MCP Agentify

mcp代理

用于工具编排的AI驱动MCP网关

概述

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

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

特性

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

安装

作为项目中的依赖项：

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

要使用npx全局运行（一旦发布）：

npx mcp-agentify

配置

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

核心设置的优先级（适用于 mcp-agentify 自身）：

1. 环境变量： OPENAI_API_KEY, LOG_LEVEL, FRONTEND_PORT 开始 mcp-agentify自己的执行环境（例如，来自 .env 或IDE env 服务器进程的块）具有最高优先级。这允许前端服务器立即启动。

- FRONTEND_PORT="disabled"：如果 FRONTEND_PORT 设置为精确的字符串 "disabled"，前端服务器将不会启动。

1. initializationOptions 来自客户： 如果没有在环境中设置，客户端可以提供这些相同的密钥作为回退。
2. 内部默认值： （例如。， 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
# To disable the Frontend UI server, uncomment the next line:
# FRONTEND_PORT="disabled"

# Optional: Define dynamic agents. Comma-separated list of "Vendor/ModelName".
# Example: AGENTS="OpenAI/gpt-4.1,OpenAI/o3,Anthropic/claude-3-opus"
# This will expose MCP methods like: agentify/agent_OpenAI_gpt_4_1, agentify/agent_OpenAI_o3, etc.
AGENTS="OpenAI/gpt-4.1,OpenAI/o3"

配置时 mcp-agentify 在IDE中，您通常可以为服务器进程指定环境变量。这就是这些应该去的地方。

2.MCP initialize 请求(initializationOptions)

连接客户端（IDE）发送 initializationOptions这是 主要用于定义 backends 那 mcp-agentify 将协调。

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

{
  "logLevel": "trace",
  "OPENAI_API_KEY": "sk-ClientProvidedKeyAsFallbackIfEnvNotSet",
  "FRONTEND_PORT": 3001,
  "backends": [
    {
      "id": "filesystem",
      "displayName": "Local Filesystem Access",
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/Shared/Projects",
        "/tmp/agentify-work"
      ],
      "env": {
        "FILESYSTEM_LOG_LEVEL": "debug"
      }
    },
    {
      "id": "mcpBrowserbase",
      "displayName": "Cloud Browser (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：唯一标识符（例如“文件系统”）。 - displayName （可选）：人类可读的名称。 - type：必须是 "stdio". - command：启动后端的命令。 - args （可选）：命令的参数。 - env （可选）：专门用于 *这催生了后端进程*.

如何使用MCP客户端（IDE）运行和配置

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

配置IDE

你需要告诉你的IDE：

1. 如何开始 mcp-agentify：这通常是 command 和 args （如有），以及 workingDirectory对于地方发展而言，这往往意味着 bash scripts/dev.sh 或 npm run dev.
2. 环境变量 mcp-agentify：设置 OPENAI_API_KEY, LOG_LEVEL, FRONTEND_PORT 在这里。
3. initializationOptions：提供JSON backends 以及任何回退设置。

概念性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": "Local Filesystem (Agentify)",
              "type": "stdio",
              "command": "npx",
              "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "${workspaceFolder}"
              ]
            },
            {
              "id": "mcpBrowserbase",
              "displayName": "Web Browser (Browserbase via Agentify)",
              "type": "stdio",
              "command": "npx",
              "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@browserbasehq/mcp-browserbase",
                "--key",
                "YOUR_BROWSERBASE_KEY_IF_NEEDED"
              ]
            }
          ]
        }
      }
    }
    // ... other MCP server configurations ...
  ]
}

IDE配置要点：

• IDE env 块为 mcp-agentify 服务器对于设置其核心操作参数至关重要，例如 OPENAI_API_KEY, logLevel，以及 FRONTEND_PORT （用于即时前端UI）。
• initializationOptions 主要用于定义 backends 阵列。
• 使用占位符，如 ${workspaceFolder} 如果你的IDE支持它们。

本地开发启动方法（由IDE引用 command):

• bash scripts/dev.sh:

- 建议用于IDE。 - 用途 nodemon 和 ts-node. - 拿起 .env 从 mcp-agentify 项目根 OPENAI_API_KEY, LOG_LEVEL, FRONTEND_PORT. - IDE env 如果IDE在启动脚本时设置了环境变量，块设置（见上面的示例）将覆盖这些设置。

• npm run dev:

- 类似于 bash scripts/dev.sh. - 还使用 nodemon 和 ts-node. - 也尊重 .env 以及IDE设置的环境变量。

前端用户界面

mcp-agentify 包括可选的前端UI（也称为前端服务器）。

启用前端UI

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

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

   FRONTEND_PORT=3030
   # To disable, set FRONTEND_PORT="disabled"

1. 这 env IDE服务器配置中的块 mcp-agentify.

前端UI将在以下情况下立即启动 mcp-agentify 发射如果 FRONTEND_PORT 在其环境中设置为有效数字。如果 FRONTEND_PORT 设置为 "disabled"，UI服务器将不会启动。如果仅作为后备方案提供 initializationOptions 对于客户端，它将在MCP握手后启动（除非被环境变量禁用）。

访问前端UI

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

特性

前端UI提供以下部分：

• 网关状态：

- 显示网关的整体状态（例如，运行、正常运行时间）。 - 列出已配置的后端MCP服务器及其就绪状态（例如，“文件系统：就绪”、“浏览器基础：未就绪”）。

• 网关配置：

- 显示网关正在使用的当前（经过净化的）配置，包括日志级别、后端定义等。API密钥等敏感信息将被编辑。

• 实时日志：

- 通过WebSockets直接从网关实时流式日志。 - 允许按最低严重级别（跟踪、调试、信息、警告、错误、致命）过滤日志。 - 提供“自动滚动”选项，以查看最新日志。 - 显示日志时间戳、级别、消息和任何结构化详细信息。

• MCP迹线：

- 流化网关和后端服务器之间以及客户端IDE和网关之间交换的MCP消息。 - 显示方向（传入网关、传出网关）、后端ID（如适用）、MCP方法、请求/响应ID以及经过净化的参数或结果。 - 还提供“自动滚动”选项。

原理

• 这 FrontendServer 组件(src/frontendServer.ts)提供位于以下位置的静态HTML、CSS和JavaScript文件 frontend/public/.
• 它提供了API端点(/api/status, /api/config, /api/logs, /api/mcptrace)前端JavaScript用来获取初始状态或分页历史数据（尽管历史数据获取在PoC的UI脚本中没有完全实现）。
• 在前端UI和 FrontendServer.
• 网关的主记录器(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):

1. 导航到项目根目录：

   cd path/to/mcp-agentify

1. 构建项目（如果要安装编译版本）：

   npm run build

1. 全局安装：

要全局安装当前本地版本，请使用：

   npm install -g .

此命令链接当前目录(.)作为一个全球性的一揽子计划。如果你跑过 npm run build，它通常会根据您的 package.jsons bin 和 files 领域。

1. 运行全局安装命令：

现在你应该可以跑了 mcp-agentify 从任何目录：

   mcp-agentify

网关将启动并继续监听 stdio.

1. 卸载：

要删除全局链接，您通常会使用中定义的包名称 package.json:

   npm uninstall -g @your-scope/mcp-agentify # Replace with actual package name

如果你使用了不同的名称，或者它只是一个链接， npm unlink . 可能还需要从项目目录中获取，或检查 npm list -g --depth=0 查找链接的包名称。

2.使用 npm link （建议开发）

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

1. 导航到项目根目录：

   cd path/to/mcp-agentify

1. 创建链接：

   npm link

这将创建一个以您的包名命名的全局符号链接（例如。， mcp-agentify 或 @your-scope/mcp-agentify)它指向您当前的项目目录。

1. 运行链接命令：

你现在可以跑了 mcp-agentify （或您的包裹名称）从任何终端：

   mcp-agentify

如果你 package.json bin 指向 dist/cli.js，你需要跑 npm run build 对于更改 src 以反映在链接的命令中。如果你 bin 可以以某种方式指向 ts-node 发票人 src/cli.ts （更高级的设置），则更改可能是实时的。

1. 取消链接：

要删除符号链接，请执行以下操作：

   npm unlink --no-save @your-scope/mcp-agentify # Replace with actual package name
   # or from the project directory:
   # npm unlink

关于的注释 .env 全球安装： 运行全局安装或链接的 mcp-agentify，它将寻找 .env 文件在 *当前工作目录* 从哪里运行命令，不一定是从 mcp-agentify 项目的原始根。对于一致的行为，尤其是使用API密钥时，请确保 .env 文件位于执行 mcp-agentify 命令，或通过以下方式配置这些设置 initializationOptions 从您的客户端工具。

发展

1. 克隆存储库： git clone https://github.com/steipete/mcp-agentify.git
2. 导航到项目目录： cd mcp-agentify
3. 安装依赖项： npm install
4. 创建一个 .env 项目根目录中的文件（复制自 .env.example)并添加您的 OPENAI_API_KEY.

   OPENAI_API_KEY=your_openai_api_key_here
   LOG_LEVEL=debug
   FRONTEND_PORT=3030

1. 在开发模式下运行（热重新加载）：

   npm run dev

这使用 nodemon 和 ts-node 执行 src/cli.ts.

测试

使用Vitest运行测试：

npm test

要在监视模式下运行：

npm run test:watch

要获取覆盖率报告：

npm run test:coverage

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

许可证

麻省理工学院

动态代理方法 AGENTS 环境变量

mcp-agentify 可以基于 AGENTS 环境变量。这对于快速测试不同的模型或提供对特定LLM配置的直接访问非常有用，而无需将其定义为完整的后端工具。

• 设置 AGENTS 环境变量以逗号分隔的字符串表示 "Vendor/ModelName" 对。

- 格式： AGENTS="Vendor1/ModelNameA,Vendor2/ModelNameB" - 例子： AGENTS="OpenAI/gpt-4.1,OpenAI/o3" - 关于“OpenAI”供应商的说明： 供应商名称“OpenAI”不区分大小写，将标准化为小写 openai （例如，“OPENAI/gpt-4.1”变为“OPENAI/gpt-4.1”）。其他供应商名称区分大小写。 - （确保型号名称对指定供应商有效，例如，根据OpenAI API文档 gpt-4.1, o3等等）

• 对于每个条目， mcp-agentify 将注册一个MCP方法：

- 这 Vendor/ModelName 字符串被净化（非字母数字，包括 /，成为 _). - 该方法将被命名 agentify/agent_. - 例子： AGENTS="OpenAI/gpt-4.1" 创造 agentify/agent_OpenAI_gpt_4_1.

• 这些方法目前接受 { query: string, context?: OrchestrationContext } payload并返回占位符响应。

未来将实现这些动态代理的完整LLM交互逻辑。