mcp-server-orchestrator

用途

MCP Server Orchestrator 用于管理面向 AI 开发工作流的 MCP（Model Context Protocol）服务器基础设施，帮助完成 MCP 服务器的配置、部署与故障排查。

MCP 架构概览

MCP 采用客户端—服务器—外部 API 的三层结构：

MCP Client（如 Claude 等）通过 JSON-RPC 与 MCP Server 通信；
MCP Server（工具提供方）再调用外部 API（服务）。

关键概念：

Server：通过 MCP 协议提供工具、资源和提示；
Client：消费服务器能力（Claude Desktop、Claude Code 等）；
Transport：通信层（stdio、SSE、WebSocket）。

配置文件位置

不同客户端的配置文件位置不同：

Claude Desktop：claude_desktop_config.json；macOS 位于 ~/Library/Application Support/Claude/，Windows 位于 %APPDATA%\Claude\；
Claude Code：settings.json 或 MCP 配置，项目级或用户设置；
Cline：cline_mcp_settings.json，VS Code 扩展设置。

服务器配置 Schema

配置采用如下结构：

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "value"
      },
      "disabled": false
    }
  }
}

常见服务器类型

Python 服务器（uvx）：

{
  "my-python-server": {
    "command": "uvx",
    "args": ["--from", "package-name", "server-command"]
  }
}

Node 服务器（npx）：

{
  "my-node-server": {
    "command": "npx",
    "args": ["-y", "@scope/package-name"]
  }
}

本地开发服务器：

{
  "dev-server": {
    "command": "python",
    "args": ["-m", "my_server"],
    "env": {
      "DEBUG": "true"
    }
  }
}

排查工作流

连接问题

先独立验证服务器能否启动：

# 测试 Python 服务器
python -m my_server

# 测试 Node 服务器
npx -y @scope/package-name

检查日志：

Claude Desktop：~/Library/Logs/Claude/mcp*.log
关注 JSON-RPC 错误、连接超时

校验 JSON 配置：

python -c "import json; json.load(open('config.json'))"

常见修复方式：

命令使用绝对路径；
确保依赖安装在正确的环境中；
检查 API 密钥/环境变量是否已设置；
修改配置后重启客户端。

认证问题

OAuth 流程：确保重定向 URI 配置正确；
API 密钥：确认服务器进程可访问环境变量；
Token 刷新：检查 token 存储位置与权限。

构建自定义服务器

Python 服务器（FastMCP）

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """Tool description for the AI."""
    return f"Result: {param}"

@mcp.resource("resource://my-data")
def get_data() -> str:
    """Provide data as a resource."""
    return "Resource content"

if __name__ == "__main__":
    mcp.run()

Node 服务器（MCP SDK）

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "my_tool",
    description: "Tool description",
    inputSchema: { type: "object", properties: { param: { type: "string" } } }
  }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);

多服务器编排

模块化架构

按领域组织服务器：

{
  "mcpServers": {
    "filesystem": { "command": "...", "args": ["--allowed-dirs", "/projects"] },
    "database": { "command": "...", "env": { "DB_URL": "..." } },
    "api-integrations": { "command": "...", "env": { "API_KEYS": "..." } },
    "custom-tools": { "command": "python", "args": ["-m", "my_tools"] }
  }
}

服务器选择策略

可将服务器视为合成器中的模块，按工作流需求进行组合：

开发工作流：filesystem + git + code-analysis 服务器；
研究工作流：web-search + document + note-taking 服务器；
数据工作流：database + visualization + export 服务器。

性能优化

懒加载：仅启用当前任务所需的服务器；
缓存：对开销较大的操作实现响应缓存；
超时调优：为较慢的外部 API 调整超时；
连接池：在数据库服务器中复用连接。

参考资料

references/server-templates.md：常见服务器类型的样板；
references/debugging-guide.md：详细的排查流程。