MCP Agent Server

MCP Agent 服务

一个模型上下文协议（MCP）中枢，可无缝连接 AI 客户端与智能 Agent，实现多个 AI 生态系统之间强大的跨平台通信。

概述

MCP Agent Server 在兼容 MCP 的客户端（如 Claude Desktop、VS Code、Cursor 等）与专用 AI Agent 之间搭建桥梁。它支持你：

• 创建和配置具备不同能力的多个专用 Agent
• 将这些 Agent 连接到 MCP 客户端
• 将多个 Agent 组合成主 Agent，以处理复杂工作流
• 使用高级功能构建 AI 应用和 MCP 服务

此项目利用 mcp-ai-agent 框架，简化 Agent 的创建和管理。

功能

• 多 Agent 支持：创建和管理不同的专用 Agent
• Agent 组合：将多个专用 Agent 组合成主 Agent
• 自定义工具集成：创建自己的工具或使用现有 MCP 服务
• 预配置服务：轻松使用 Sequential Thinking、Brave Search 和 Memory 等热门 MCP 服务
• AI SDK 集成：通过 Vercel AI SDK v5 支持 17+ 个大模型提供商，包括 OpenAI、Anthropic、Google（Generative AI 和 Vertex）、Amazon Bedrock、Azure、Cohere、Mistral、Fireworks、Groq、Perplexity、Together AI、xAI、DeepSeek、Cerebras、DeepInfra 和 Replicate

先决条件

• 已安装 Node.js（v16+）
• 所选 AI 模型提供商的 API 密钥（OpenAI、Anthropic、Google 等）
• 要使用的特定 MCP 服务所需的任何 API 密钥

安装

选项 1：使用 npx（推荐）

无需安装，即可直接使用 npx 运行 MCP Agent Server：

# Start the server with default configuration
npx mcp-agent-server

# Start with custom configuration
npx mcp-agent-server --config my-config.json

# Test an agent
npx mcp-agent-server test-agent --name "Sequential Thinker" --prompt "What is 2+2?"

选项 2：全局安装

全局安装后，可在任何位置使用 mcp-agent-server 命令：

npm install -g mcp-agent-server

# Then use it
mcp-agent-server --config my-config.json

选项 3：本地开发

1. 克隆仓库：

   git clone <repository-url>
   cd mcp-agent-server
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

配置

配置你的 Agent

MCP Agent Server 现在使用基于 JSON 的配置，以便更轻松地管理和部署。你可以在项目根目录中创建名为 my-agents-config.json 的个性化 Agent 配置文件。如果该文件存在，服务会自动检测并使用它。

创建自定义配置的步骤：

1. 在项目根目录中创建名为 my-agents-config.json 的新文件
2. 使用 JSON 格式定义 Agent、工具、模型和配置
3. 服务会自动加载并使用你的配置

JSON 配置架构

以下是自定义 Agent 配置示例：

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Code Context Agent",
      "description": "Use this agent to analyze and understand code in your projects",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "mcpServers": {
            "codeContext": {
              "command": "node",
              "args": ["/path/to/code-context-mcp/dist/index.js"]
            }
          }
        }
      ]
    },
    {
      "name": "Web Search Agent",
      "description": "Use this agent to search the web",
      "systemPrompt": "Prefer to use brave search to search the web for information.",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        {
          "prebuilt": "sequentialThinking"
        },
        {
          "prebuilt": "braveSearch"
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Code Context Agent"
        },
        {
          "agentRef": "Web Search Agent"
        }
      ]
    }
  ]
}

配置选项

模型配置

• provider：要使用的 AI 提供商。支持的提供商包括：
  • "openai" - OpenAI 模型（GPT-4、GPT-4o 等）
  • "anthropic" - Anthropic Claude 模型
  • "google" - Google Generative AI（Gemini 模型）
  • "vertex" - Google Vertex AI
  • "bedrock" - Amazon Bedrock
  • "azure" - Azure OpenAI Service
  • "cohere" - Cohere 模型
  • "mistral" - Mistral AI 模型
  • "fireworks" - Fireworks AI
  • "groq" - Groq（超高速推理）
  • "perplexity" - Perplexity AI
  • "togetherai" - Together AI
  • "xai" - xAI（Grok 模型）
  • "deepseek" - DeepSeek 模型
  • "cerebras" - Cerebras 推理
  • "deepinfra" - DeepInfra
  • "replicate" - Replicate（开源模型）
• model：具体的模型名称（例如 "gpt-4o-mini"、"claude-3-5-haiku-20241022"、"gemini-2.0-flash-exp"）
• apiKey：（可选）提供商的 API 密钥。也可以通过环境变量设置

工具配置类型

1. 预置服务（推荐）：

   {
     "prebuilt": "sequentialThinking"
   }
   

   可用的预置服务：sequentialThinking、memory、braveSearch、firecrawlMcp、fetch、awsKbRetrieval、everart、fileSystem、sqlite

2. 自定义 MCP 服务：

   {
     "mcpServers": {
       "serverName": {
         "command": "node",
         "args": ["/path/to/server.js"],
         "env": {
           "API_KEY": "your-api-key"
         }
       }
     }
   }
   

3. Agent 引用（用于主 Agent）：

   {
     "agentRef": "Other Agent Name"
   }
   

4. 导入的 Agent（用于使用外部 Agent 文件）：

   {
     "type": "import",
     "importPath": "/path/to/your/agent-file.js",
     "exportName": "createResearchAgent",
     "factoryArgs": {
       "modelProvider": "anthropic",
       "modelName": "claude-3-5-haiku-20241022",
       "includeMemory": true
     }
   }
   

   这允许你从使用 mcp-ai-agent 库创建的 TypeScript/JavaScript 文件中导入 Agent。导入的文件可以导出：

   • 预配置的 Agent 实例
   • 用于创建 Agent 的工厂函数（可选参数）
   • 用于复杂初始化的异步工厂函数

选择性公开 Agent

你可以使用每个 Agent 上的 expose 布尔字段，控制向 MCP 客户端公开哪些 Agent。如果你希望设置仅供其他 Agent 内部使用的辅助 Agent，这会很有用：

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Web Search Helper",
      "description": "Internal web search capabilities",
      "model": { "provider": "openai", "model": "gpt-4o-mini" },
      "toolsConfigs": [{ "prebuilt": "braveSearch" }],
      "expose": false
    },
    {
      "name": "Master Assistant",
      "description": "Public-facing assistant with web search",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-haiku-20241022"
      },
      "toolsConfigs": [
        { "prebuilt": "sequentialThinking" },
        { "agentRef": "Web Search Helper" }
      ],
      "expose": true
    }
  ]
}

• expose: true（默认）：Agent 可作为工具供 MCP 客户端使用
• expose: false：Agent 仅供其他 Agent 内部使用

指定配置文件

你可以使用 --config 参数指定自定义配置文件：

# Using CLI
npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Test prompt"

# When starting the server (multiple formats supported)
node dist/index.js --config=path/to/config.json
node dist/index.js -c path/to/config.json
node dist/index.js --config path/to/config.json

你可以根据需要包含任意数量的专用 Agent，例如：

• 代码分析 Agent
• 开发环境 Agent
• 知识库 Agent（Obsidian 等）
• 项目管理 Agent（Jira 等）
• Google Drive/Workspace Agent
• 网页搜索 Agent
• 设计工具 Agent（Figma 等）

重要：创建或更新自定义配置后，请记得：

1. 运行 npm run build 以重新构建项目
2. 重启 MCP 客户端以应用更改

默认配置

该服务附带一个默认的 agents-config.json，其中包括：

1. Sequential Thinking Agent：用于解决复杂问题
2. Brave Search Agent：用于网页搜索
3. Memory Agent：用于存储和检索信息
4. 主 Agent：组合多个 Agent

重要：更改 Agent 配置后，请记得：

1. 运行 npm run build 以重新构建项目
2. 重启 Claude 客户端以应用更改
3. 在 Windows 上，你可能需要使用任务管理器（Ctrl+Alt+Del）完全关闭 Claude，因为它可能会继续在后台运行

Agent 配置示例

{
  "version": "1.0.0",
  "agents": [
    {
      "name": "Sequential Thinker",
      "description": "Use this agent to think sequentially and resolve complex problems",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "sequentialThinking": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
            }
          }
        }
      ]
    },
    {
      "name": "Claude Assistant",
      "description": "A powerful AI assistant using Claude's capabilities",
      "model": {
        "provider": "anthropic",
        "model": "claude-3-5-sonnet-20241022"
      },
      "toolsConfigs": [
        {
          "mcpServers": {
            "memory": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-memory"]
            }
          }
        }
      ]
    },
    {
      "name": "Master Agent",
      "description": "An agent that can manage other agents",
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      },
      "toolsConfigs": [
        {
          "agentRef": "Sequential Thinker"
        },
        {
          "agentRef": "Memory Agent"
        },
        {
          "agentRef": "Brave Search Agent"
        }
      ]
    }
  ]
}

注意：mcp-ai-agent 框架通过 AI SDK 支持多种 AI 模型。你可以使用 OpenAI、Anthropic、Google Generative AI、Mistral、Groq 等提供商的模型。请查看 AI SDK 提供商文档，了解支持的模型及其功能的完整列表。

连接到 MCP 客户端

将 MCP Agent Server 添加到 MCP 客户端配置中：

Claude Desktop

编辑你的 claude_desktop_config.json：

使用 npx（推荐）

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "npx",
      "args": ["mcp-agent-server", "--config", "/path/to/your/config.json"]
    }
  }
}

使用全局安装

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "mcp-agent-server",
      "args": ["--config", "/path/to/your/config.json"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

使用本地构建

{
  "mcpServers": {
    "mcp-agent-server": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-agent-server/dist/index.js",
        "--config",
        "/path/to/your/config.json"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "BRAVE_API_KEY": "your-brave-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

重要：更改 claude_desktop_config.json 后，请记得：

1. 重启 Claude 客户端以应用更改
2. 在 Windows 上，你可能需要使用任务管理器（Ctrl+Alt+Del）完全关闭 Claude，因为它可能会继续在后台运行

VS Code / Cursor / 其他 MCP 客户端

按照相应客户端关于添加 MCP 服务的说明，使用：

• 命令：node
• 参数：["/full/path/to/mcp-agent-server/dist/index.js"]

使用你的 Agent

配置完成后，你的 Agent 会以工具的形式显示在 MCP 客户端中。例如，在 Claude Desktop 中，你可以通过以下步骤使用它们：

1. 输入 / 查看可用工具
2. 选择一个已配置的 Agent
3. 按照提示提供上下文和具体任务

高级配置

自定义工具

对于自定义功能，你有几种选择：

1. 使用预构建服务（推荐）：从可用的预构建服务中选择，例如 sequentialThinking、memory、braveSearch、fetch 等。

2. 创建自定义 MCP 服务：构建自己的 MCP 服务并集成：

{
  "name": "Calculator Agent",
  "description": "A calculator agent with custom math operations",
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  },
  "toolsConfigs": [
    {
      "mcpServers": {
        "calculator": {
          "command": "node",
          "args": ["/path/to/your/calculator-mcp-server.js"]
        }
      }
    }
  ]
}

3. 组合多个预构建服务：混合搭配现有服务，实现复杂功能：

{
  "name": "Multi-Tool Agent",
  "description": "An agent with multiple capabilities",
  "model": {
    "provider": "anthropic",
    "model": "claude-3-5-haiku-20241022"
  },
  "toolsConfigs": [
    {
      "prebuilt": "sequentialThinking"
    },
    {
      "prebuilt": "memory"
    },
    {
      "prebuilt": "fetch"
    }
  ]
}

导入外部 Agent

你可以从外部文件导入 Agent。请参阅示例： @fkesheh/mcp-ai-agent-example/exportable-agent.ts

1. 创建 Agent 文件

// my-agent.ts
import { AIAgent, Servers } from "mcp-ai-agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new AIAgent({
  name: "My Custom Agent",
  description: "A custom agent",
  model: openai("gpt-4o-mini"),
  toolsConfigs: [Servers.sequentialThinking],
});

2. 构建为 JavaScript

npx tsc  # Creates my-agent.js in dist/ folder

3. 在配置中使用

{
  "type": "import",
  "importPath": "/full/path/to/dist/my-agent.js",
  "exportName": "myAgent"
}

重要：始终使用已编译 .js 文件的绝对路径。

使用 MCP 服务

mcp-ai-agent 框架支持各种 MCP 服务：

• Sequential Thinking：用于拆解复杂问题
• Memory：用于持久化存储信息
• Brave Search：用于网页搜索
• 还有更多……

故障排除

• 如果 Agent 初始化失败，请检查 MCP 服务是否配置正确
• 对于“npx”命令，如有需要，请确保指定完整路径
• 确认环境中提供了所有必需的 API 密钥
• 检查 MCP 客户端是否已正确配置为使用 MCP Agent Server

开发

1. 修改 TypeScript 文件
2. 使用 npm run build 重新构建
3. 重启 MCP 客户端以加载更改

CLI 用法

MCP Agent Server 附带一个命令行界面（CLI），可用于处理 Agent。

测试 Agent

你可以直接从命令行测试单个 Agent，无需连接 MCP 客户端，这有助于调试。

使用 npx（推荐）

npx mcp-agent-server test-agent --config="/path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

例如，要测试 Brave Search Agent：

npx mcp-agent-server test-agent --config="./agents-config.json" --name="Brave Search" --prompt="What is the capital of France?" --context="I need geographical information"

或者测试组合多个专用 Agent 的 Master Agent：

npx mcp-agent-server test-agent --config="./my-agents-config.json" --name="Master Agent" --prompt="Store this information: Claude is an AI assistant by Anthropic" --context="I need to test the memory capabilities"

注意：如果未指定 --config，服务端会在当前目录中查找 agents-config.json 或 my-agents-config.json。

使用本地开发环境

npm run test-agent -- --config="path/to/config.json" --name="Agent Name" --prompt="Your test prompt" --context="Optional context"

或者直接运行命令：

node dist/cli.js test-agent --config="./agents-config.json" --name="Sequential Thinker" --prompt="How would I approach solving a complex math problem?"

测试命令将：

1. 按名称查找指定的 Agent
2. 初始化 Agent
3. 发送你的提示词和上下文
4. 显示 Agent 的响应

这适用于：

• 测试新的 Agent 配置
• 调试 Agent 问题
• 在连接 MCP 客户端之前验证 Agent 功能

如果你提供的 Agent 名称无效，测试命令会列出所有可用的 Agent。

许可证

本项目采用 MIT 许可证。