麦克佩代理化

Name: 麦克佩代理化
Author: steipete

作者：steipete17 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

mcp-agentify

基于AI的MCP网关用于工具编排

概述

mcp-agentify 是一个Node.js/TypeScript应用程序，充当AI驱动的MCP（模型上下文协议）网关。此网关将：

作为MCP服务器运行，主要通过stdio进行通信。
接受来自客户端IDE（如Cursor）通过主要MCP方法agentify/orchestrateTask发送的请求。
使用OpenAI的API（特别是工具调用）来解释用户查询和上下文，选择合适的后端MCP工具，并制定MCP调用。
动态管理基于stdio的与后端MCP服务器的连接。
代理MCP调用到选定的后端并返回响应。
可以通过npx或作为依赖项运行。

特性

统一的MCP端点： 提供单个MCP服务器端点供客户端应用使用。
智能任务编排： 使用OpenAI（例如GPT-4 Turbo）理解自然语言并从配置的后端工具中选择。
动态后端管理： 通过initializationOptions配置后端MCP服务器（如@modelcontextprotocol/server-filesystem，@browserbasehq/mcp-browserbase）。
简化客户端逻辑： 集中处理工具选择和MCP调用制定。
标准I/O通信： 设计易于与IDE和其他工具集成。
可选前端UI： 用于观察日志、跟踪和状态。

安装

作为项目中的依赖项：

npm install mcp-agentify
# 或
yarn add mcp-agentify

全局使用npx运行（发布后）：

npx mcp-agentify

配置

mcp-agentify 通过环境变量（通常通过.env文件设置本地开发或IDE服务器配置中的env块）和在initialize握手期间由连接的MCP客户端提供的initializationOptions进行配置。

核心设置的优先级（针对mcp-agentify本身）：

环境变量： OPENAI_API_KEY，LOG_LEVEL，FRONTEND_PORT在mcp-agentify自身的执行环境中设置（例如，从.env或IDE的env块中的服务器进程）具有最高优先级。这允许前端服务器立即启动。
- FRONTEND_PORT="disabled"：如果FRONTEND_PORT被设置为确切字符串"disabled"，则不会启动前端服务器。
客户端的initializationOptions： 如果未在环境中设置，这些相同的键可以由客户端提供作为备用选项。
内部默认值： （例如，logLevel默认为'info'）。

1. 环境变量（`.env`文件或IDE `env`块）

这是设置OPENAI_API_KEY，LOG_LEVEL和FRONTEND_PORT给mcp-agentify自身操作的推荐方式。

示例.env文件（用于本地scripts/dev.sh或npm run dev）：

OPENAI_API_KEY=sk-YourOpenAIKeyHereFromDotEnv
LOG_LEVEL=debug
FRONTEND_PORT=3030
# 要禁用前端UI服务器，请取消注释下一行：
# FRONTEND_PORT="disabled"

# 可选：定义动态代理。逗号分隔的"Vendor/ModelName"列表。
# 示例：AGENTS="OpenAI/gpt-4.1,OpenAI/o3,Anthropic/claude-3-opus"
# 这将暴露MCP方法如：agentify/agent_OpenAI_gpt_4_1, agentify/agent_OpenAI_o3等。
AGENTS="OpenAI/gpt-4.1,OpenAI/o3"

当在IDE中配置mcp-agentify时，通常有一种指定服务器进程环境变量的方法。这就是它们应该放置的地方。

2. MCP `initialize`请求（`initializationOptions`）

连接的客户端（IDE）发送initializationOptions。这主要用于定义mcp-agentify将编排的backends。

示例initializationOptions（客户端发送的JSON）：

{
  "logLevel": "trace",
  "OPENAI_API_KEY": "sk-ClientProvidedKeyAsFallbackIfEnvNotSet",
  "FRONTEND_PORT": 3001,
  "backends": [
    {
      "id": "filesystem",
      "displayName": "本地文件系统访问",
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/Shared/Projects",
        "/tmp/agentify-work"
      ],
      "env": {
        "FILESYSTEM_LOG_LEVEL": "debug"
      }
    },
    {
      "id": "mcpBrowserbase",
      "displayName": "云浏览器（Browserbase）",
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@browserbasehq/mcp-browserbase",
        "--key", "bb_api_YOUR_KEY_AS_ARG_FOR_BROWSERBASE"
      ]
    }
  ]
}

initializationOptions中的关键字段：

logLevel，OPENAI_API_KEY，FRONTEND_PORT（可选备用设置）：如前所述，mcp-agentify为其自身的环境变量优先考虑这些。
backends（必需，数组）：定义后端MCP服务器。
- id：唯一标识符（例如，“filesystem”）。
- displayName（可选）：人类可读名称。
- type：必须是“stdio”。
- command：启动后端的命令。
- args（可选）：命令的参数。
- env（可选）：特定于此生成的后端进程的环境变量。

如何运行及配置与MCP客户端（IDE）一起使用

您的IDE（例如，Cursor，Windsurf，Claude Desktop）将启动mcp-agentify。

配置您的IDE

您需要告诉您的IDE：

如何启动mcp-agentify：这通常是command和args（如果有），以及workingDirectory。对于本地开发，这通常指向bash scripts/dev.sh或npm run dev。
mcp-agentify的环境变量：在这里设置OPENAI_API_KEY，LOG_LEVEL，FRONTEND_PORT。
initializationOptions：提供backends的JSON和任何备用设置。

概念性的IDE配置示例（例如，类似于claude_desktop_config.json文件）：

{
  "mcpServers": [
    {
      "mcp-agentify": {
        "type": "stdio",
        "command": "/Users/steipete/Projects/mcp-agentify/scripts/dev.sh",
        "env": {
          "logLevel": "trace",
          "FRONTEND_PORT": 3030,
          "OPENAI_API_KEY": "sk-YourOpenAIKeyFromIDESettingsPlaceholder"
        },
        "initializationOptions": {
          "backends": [
            {
              "id": "filesystem",
              "displayName": "本地文件系统（Agentify）",
              "type": "stdio",
              "command": "npx",
              "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "${workspaceFolder}"
              ]
            },
            {
              "id": "mcpBrowserbase",
              "displayName": "网络浏览器（通过Agentify的Browserbase）",
              "type": "stdio",
              "command": "npx",
              "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@browserbasehq/mcp-browserbase",
                "--key",
                "YOUR_BROWSERBASE_KEY_IF_NEEDED"
              ]
            }
          ]
        }
      }
    }
    // ... 其他MCP服务器配置 ...
  ]
}

IDE配置的关键点：

IDE的mcp-agentify服务器的env块对于设置其核心操作参数（如OPENAI_API_KEY，logLevel，FRONTEND_PORT）至关重要（用于立即启动前端UI）。
initializationOptions主要用于定义backends数组。
如果您的IDE支持，请使用占位符如${workspaceFolder}。

本地开发启动方法（由IDE command引用）：

bash scripts/dev.sh：
- 推荐用于IDE。
- 使用nodemon和ts-node。
- 从mcp-agentify项目根目录的.env获取OPENAI_API_KEY，LOG_LEVEL，FRONTEND_PORT。
- 如果IDE在启动脚本时设置环境变量，则IDE的env块设置（见上例）将覆盖这些设置。
npm run dev：
- 类似于bash scripts/dev.sh。
- 同样使用nodemon和ts-node。
- 同样尊重.env和IDE设置的环境变量。

前端UI

mcp-agentify包括一个可选的前端UI，也称为前端服务器。

启用前端UI

为mcp-agentify设置FRONTEND_PORT环境变量。最好通过以下方式完成：

在mcp-agentify项目根目录中运行本地时的.env文件：

FRONTEND_PORT=3030
# 要禁用，请设置FRONTEND_PORT="disabled"

您IDE的服务器配置中的env块，用于mcp-agentify。

如果在环境中的FRONTEND_PORT设置为有效数字，mcp-agentify启动时前端UI会立即启动。如果FRONTEND_PORT设置为"disabled"，则UI服务器不会启动。如果仅作为客户端在initializationOptions中的备用设置提供，它将在MCP握手之后启动（除非被环境变量禁用）。

访问前端UI

一旦mcp-agentify正在运行并且前端UI已启用（例如，环境中的FRONTEND_PORT=3030），打开： http://localhost:3030（如果不同，请替换3030为您的FRONTEND_PORT）

功能

前端UI提供了以下部分：

网关状态：
- 显示网关的整体状态（例如，运行，运行时间）。
- 列出配置的后端MCP服务器及其准备就绪状态（例如，“文件系统：就绪”，“Browserbase：未就绪”）。
网关配置：
- 显示网关当前使用的（经过清理的）配置，包括日志级别、后端定义等。敏感信息如API密钥会被删除。
实时日志：
- 通过WebSocket直接从网关流式传输实时日志。
- 允许按最低严重性级别过滤日志（跟踪、调试、信息、警告、错误、致命）。
- 提供“自动滚动”选项以保持最新日志可见。
- 显示日志时间戳、级别、消息以及任何结构化细节。
MCP跟踪：
- 流式传输网关与后端服务器之间交换的MCP消息，以及客户端IDE与网关之间的消息。
- 显示方向（向网关传入，从网关传出）、后端ID（如有）、MCP方法、请求/响应ID以及清理过的参数或结果。
- 也提供“自动滚动”选项。

工作原理

FrontendServer组件（src/frontendServer.ts）提供位于frontend/public/的静态HTML、CSS和JavaScript文件。
它提供API端点（/api/status，/api/config，/api/logs，/api/mcptrace），前端JavaScript使用这些端点来获取初始状态或分页的历史数据（尽管历史数据获取在PoC的UI脚本中尚未完全实现）。
建立了前端UI与FrontendServer之间的WebSocket连接。
网关的主要记录器（src/logger.ts）配置为将日志条目（作为JSON对象）传递给FrontendServer，如果前端UI处于活动状态。
BackendManager和主要服务器逻辑（src/server.ts）发出MCP跟踪事件。
FrontendServer接收这些日志条目和跟踪事件，并广播给所有连接的WebSocket客户端（即打开的前端UI页面）。
客户端JavaScript（frontend/src/index.tsx和组件）接收这些WebSocket消息，并动态更新HTML中的相应部分以显示信息。

本地安装和全局使用（高级）

虽然npm run dev非常适合活跃开发，而npx mcp-agentify（发布后）方便项目本地使用，但您可能希望从本地克隆安装mcp-agentify以进行更广泛的测试，或者模拟已发布的全局包的行为。

1. 从本地克隆全局安装

克隆仓库并确保安装所有依赖项（npm install）后：

导航到项目根目录：
```
cd path/to/mcp-agentify
```
构建项目（如果您想安装编译版本）：
```
npm run build
```
全局安装： 要全局安装当前本地版本，使用：
```
npm install -g .
```
此命令将当前目录（.）链接为全局包。如果您已经运行了npm run build，它通常会根据package.json中的bin和files字段链接编译版本。
运行全局安装的命令： 现在您应该能够从任何目录运行mcp-agentify：
```
mcp-agentify
```
网关将启动并监听stdio。
卸载： 要移除全局链接，通常使用package.json中定义的包名：
```
npm uninstall -g @your-scope/mcp-agentify # 替换为实际包名
```
如果您使用了不同的名称或只是链接，可能还需要从项目目录中运行npm unlink .，或者检查npm list -g --depth=0以找到链接的包名。

2. 使用`npm link`（推荐用于开发）

npm link是一种更适合开发的方式，创建到您本地项目的类似全局的符号链接。这意味着您对本地代码所做的更改（即使不重新构建，如果您通过ts-node运行链接版本或IDE指向源代码）可以在运行全局命令时立即反映出来。

导航到项目根目录：
```
cd path/to/mcp-agentify
```
创建链接：
```
npm link
```
这会在全局创建一个名为您的包名（例如mcp-agentify或@your-scope/mcp-agentify）的符号链接，该链接指向您当前的项目目录。
运行链接的命令： 您现在可以从任何终端运行mcp-agentify（或您的包名）：
```
mcp-agentify
```
如果您的package.json的bin指向dist/cli.js，则需要运行npm run build才能使src中的更改反映在链接的命令中。如果您的bin可以某种方式指向src/cli.ts的ts-node调用者（更高级的设置），那么更改可能是实时的。

解除链接： 要移除符号链接：

npm unlink --no-save @your-scope/mcp-agentify # 替换为实际包名
# 或从项目目录：
# npm unlink

关于全局安装或链接时的.env注意事项： 当运行全局安装或链接的mcp-agentify时，它会查找从您运行命令的当前工作目录中的.env文件，而不是mcp-agentify原始项目根目录中的.env文件。为了保持一致的行为，尤其是涉及API密钥时，请确保您的.env文件位于您执行mcp-agentify命令的目录中，或通过客户端工具的initializationOptions配置这些设置。

开发

克隆仓库：git clone https://github.com/steipete/mcp-agentify.git
导航到项目目录：cd mcp-agentify
安装依赖项：npm install
在项目根目录创建一个.env文件（复制自.env.example）并添加您的OPENAI_API_KEY。
```
OPENAI_API_KEY=your_openai_api_key_here
LOG_LEVEL=debug
FRONTEND_PORT=3030
```
在开发模式下运行（带有热重载）：
```
npm run dev
```
这使用nodemon和ts-node执行src/cli.ts。

测试

使用Vitest运行测试：

npm test

以监视模式运行：

npm run test:watch

获取覆盖率报告：

npm run test:coverage

（注意：单元测试和集成测试分别计划在任务11和12中进行。）

许可证

MIT

通过`AGENTS`环境变量动态代理方法

mcp-agentify可以根据AGENTS环境变量即时暴露直接代理交互方法。这对于快速测试不同的模型或直接访问特定LLM配置非常有用，而无需将其定义为完整的后端工具。

设置AGENTS环境变量为逗号分隔的"Vendor/ModelName"对的字符串。
- 格式： AGENTS="Vendor1/ModelNameA,Vendor2/ModelNameB"
- 示例： `AGENTS="OpenAI/gpt-