星战科技xingzhan.cloud
返回市场
MCP代理服务器

MCP代理服务器

作者：mozilla-ai12 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

mcpd-proxy

一个作为IDE与mcpd守护进程之间的代理的MCP（模型上下文协议）服务器，通过统一接口暴露所有由mcpd管理的MCP服务器。

概览

┌─────────────┐   STDIO/JSON-RPC    ┌──────────────┐    HTTP/REST     ┌──────────┐
│  IDE/编辑器  │ ◄─────────────────► │  mcpd-proxy  │ ◄───────────────►│   mcpd   │
│ (VS Code,   │     MCP协议        │  MCP服务器   │   使用mcpd SDK  │  守护进程│
│  Cursor)    │                     │              │                  │          │
└─────────────┘                     └──────────────┘                  └──────────┘

mcpd-proxy将多个由mcpd管理的MCP服务器中的工具、资源和提示聚合到一个单一的MCP接口中，使得IDE可以轻松访问所有功能，而无需管理单独的服务器连接。

特性

  • 统一接口：单个MCP服务器暴露所有mcpd管理的功能
  • 工具聚合：所有服务器中的工具，命名约定为server__tool
  • 资源聚合：所有服务器中的资源，命名约定为server__resource，并使用mcpd://URI
  • 提示聚合：所有服务器中的提示，命名约定为server__prompt
  • 高效缓存：利用SDK缓存进行健康检查和工具模式
  • 零配置：开箱即用，具有合理的默认设置
  • TypeScript：使用TypeScript构建，确保类型安全

先决条件

  • Node.js 22.10.0或更高版本（推荐最新22.x版本）
  • 运行并可访问的mcpd守护进程
  • mcpd SDK（作为依赖项自动安装）

安装

从npm（推荐）

# 全局安装
npm install -g @mozilla-ai/mcpd-proxy

# 或直接使用npx
npx @mozilla-ai/mcpd-proxy

从源码

# 克隆仓库
git clone https://github.com/mozilla-ai/mcpd-proxy.git
cd mcpd-proxy

# 安装依赖
npm install

# 构建项目
npm run build

配置

mcpd-proxy通过环境变量进行配置：

变量描述默认值
MCPD_ADDRmcpd守护进程地址http://localhost:8090
MCPD_API_KEY可选的mcpd认证API密钥（未设置）

使用

直接运行

# 使用npm包（推荐）
npx @mozilla-ai/mcpd-proxy

# 带自定义mcpd地址
MCPD_ADDR=http://localhost:8090 npx @mozilla--ai/mcpd-proxy

# 带API密钥
MCPD_ADDR=http://localhost:8090 MCPD_API_KEY=your-key npx @mozilla-ai/mcpd-proxy

# 从源码构建
node dist/index.mjs

# 从源码带自定义地址
MCPD_ADDR=http://localhost:8090 node dist/index.mjs

VS Code 设置

添加到你的VS Code MCP设置文件（位置因平台而异）：

{
  "servers": {
    "mcpd": {
      "type": "stdio",
      "command": "npx",
      "args": ["@mozilla-ai/mcpd-proxy"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

或者如果从源码构建：

{
  "servers": {
    "mcpd": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-mcpd-proxy>/dist/index.mjs"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

替换<path-to-mcpd-proxy>为你安装的绝对路径。

重新加载VS Code：Cmd+Shift+P → "开发者：重新加载窗口"

在MCP面板中验证连接以查看可用工具。

Cursor 设置

创建或编辑项目目录中的.cursor/mcp.json，或全局配置~/.cursor/mcp.json：

{
  "mcpServers": {
    "mcpd": {
      "command": "npx",
      "args": ["@mozilla-ai/mcpd-proxy"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

或者如果从源码构建：

{
  "mcpServers": {
    "mcpd": {
      "command": "node",
      "args": ["<path-to-mcpd-proxy>/dist/index.mjs"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

替换<path-to-mcpd-proxy>为你安装的绝对路径，或使用${workspaceFolder}表示相对路径。

重新加载Cursor以应用配置。

查看examples/文件夹以获取配置示例。

开发

项目结构

mcpd-proxy/
├── src/
│   ├── index.ts               # CLI入口点
│   ├── server.ts              # MCP服务器实现
│   ├── config.ts              # 配置加载器
│   └── apiPaths.ts            # API端点常量
├── tests/
│   └── unit/                  # 单元测试文件
│       ├── aggregation.test.ts
│       ├── apiPaths.test.ts
│       ├── config.test.ts
│       ├── parsers.test.ts
│       └── server.test.ts
├── .github/
│   └── workflows/             # GitHub Actions工作流
│       ├── tests.yaml
│       ├── lint.yaml
│       └── release.yaml
├── examples/
│   ├── vscode-config.json     # VS Code配置示例
│   └── cursor-config.json     # Cursor配置示例
├── dist/                      # 构建输出（git忽略）
├── package.json               # npm包配置
├── package-lock.json          # npm依赖锁定文件
├── tsconfig.json              # TypeScript编译配置
├── tsconfig.test.json         # TypeScript测试配置
├── vitest.config.ts           # Vitest测试配置
├── vite.config.mts            # Vite构建配置
├── eslint.config.mts          # ESLint配置
├── .prettierignore            # Prettier忽略模式
├── .gitignore                 # Git忽略模式
└── README.md                  # 本文件

开发流程

# 安装依赖
npm install

# 构建一次
npm run build

# 监控模式（更改时自动重建）
npm run dev

# 运行测试
npm test

# 在监控模式下运行测试
npm run test:watch

# 不构建的情况下进行类型检查
npm run typecheck

# 校验代码
npm run lint

# 格式化代码
npm run format

手动测试

直接使用JSON-RPC通过stdio测试MCP协议：

# 测试初始化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.mjs

# 测试列出工具
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.mjs

命名约定

工具

工具以以下格式暴露：{server}__{tool_name}

示例：

  • time__get_current_time - 来自time服务器的get_current_time工具
  • github__create_issue - 来自github服务器的create_issue工具
  • fetch__get_url - 来自fetch服务器的get_url工具

这种命名约定防止了不同服务器之间工具名称冲突，并明确指出了每个工具来自哪个服务器。

资源

资源使用自定义URI方案：mcpd://{server}/{resource_uri}

示例：

  • mcpd://filesystem/documents/file.txt
  • mcpd://database/users/123

提示

提示遵循与工具相同的命名约定：{server}__{prompt_name}

架构

单例McpdClient

mcpd-proxy在启动时创建McpdClient的单个实例，并在所有请求中重用它。这对于以下方面至关重要：

  • 缓存：健康检查缓存（10秒TTL）和工具模式缓存（60秒TTL）
  • 性能：避免为每次请求创建新的HTTP连接
  • 效率：减少对mcpd守护进程的负载
const mcpdClient = new McpdClient({
  apiEndpoint: config.mcpdAddr,
  apiKey: config.mcpdApiKey,
  healthCacheTtl: 10,
  serverCacheTtl: 60,
});

MCP协议处理器

代理实现了以下MCP协议处理器：

  • initialize - 与IDE握手，声明能力
  • tools/list - 聚合所有mcpd服务器中的工具
  • tools/call - 解析工具名称并转发给mcpd
  • resources/list - 聚合所有服务器中的资源
  • resources/read - 转发资源读取请求到mcpd
  • prompts/list - 聚合所有服务器中的提示
  • prompts/get - 转发提示请求到mcpd
  • ping - 健康检查端点

故障排除

无法连接到mcpd守护进程

原因：mcpd守护进程未运行或不可访问

解决方案：

  1. 验证mcpd正在运行：curl http://localhost:8090/api/v1/servers
  2. 检查MCPD_ADDR环境变量是否正确
  3. 确保没有防火墙阻止连接

服务器未找到

原因：请求的服务器不存在于mcpd中

解决方案：

  1. 列出可用服务器：curl http://localhost:8090/api/v1/servers
  2. 检查服务器是否已在mcpd中配置
  3. 验证服务器是否健康：curl http://localhost:8090/api/v1/health/servers/<server-name>

VS Code未显示工具

原因：VS Code可能未识别MCP服务器

解决方案：

  1. 检查VS Code开发者控制台中的错误（帮助 → 切换开发者工具）
  2. 验证dist/index.mjs的路径是否正确且为绝对路径（如果从源码构建）
  3. 重新加载VS Code：Cmd+Shift+P → "开发者：重新加载窗口"
  4. 检查mcpd守护进程是否正在运行且可访问

工具列出但执行失败

原因：服务器可能不健康或工具不存在

解决方案：

  1. 通过mcpdAPI检查服务器健康状况
  2. 验证工具是否存在于服务器上
  3. 检查mcpd日志中的错误

未来增强

  • 动态工具列表更新（notifications/tools/list_changed）
  • 通过MCPD_SERVERS环境变量过滤服务器
  • 改进不健康的服务器处理

相关项目

许可证

Apache-2.0

贡献指南

参见主mcpd仓库中的贡献指南。