Mcpd Proxy

mcpd代理

MCP（模型上下文协议）服务器，充当IDE和 mcpd 守护进程，暴露所有 mcpd-通过统一接口管理MCP服务器。

概述

┌─────────────┐   STDIO/JSON-RPC    ┌──────────────┐    HTTP/REST     ┌──────────┐
│  IDE/Editor │ ◄─────────────────► │  mcpd-proxy  │ ◄───────────────►│   mcpd   │
│ (VS Code,   │     MCP Protocol    │  MCP Server  │   Uses mcpd SDK  │  daemon  │
│  Cursor)    │                     │              │                  │          │
└─────────────┘                     └──────────────┘                  └──────────┘

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

特性

• 统一接口：单个MCP服务器暴露所有 mcpd-管理能力
• 工具聚合：来自所有服务器的工具 server__tool 命名规范
• 资源聚合：来自所有服务器的资源 server__resource 命名和 mcpd:// 统一资源标识符
• 提示聚合：来自所有服务器的提示 server__prompt 命名规范
• 高效缓存：利用SDK缓存进行健康检查和工具模式
• 零配置：使用合理的默认值即可开箱即用
• TypeScript：内置 TypeScript 用于类型安全

先决条件

• Node.js 22.10.0或更高（建议使用最新的22.x）
• mcpd 守护进程正在运行且可访问
• mcpd SDK（作为依赖项自动安装）

安装

来自npm（推荐）

# Global installation
npm install -g @mozilla-ai/mcpd-proxy

# Or use directly with npx
npx @mozilla-ai/mcpd-proxy

来源

# Clone the repository
git clone https://github.com/mozilla-ai/mcpd-proxy.git
cd mcpd-proxy

# Install dependencies
npm install

# Build the project
npm run build

配置

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

用法

直接运行

# Using npm package (recommended)
npx @mozilla-ai/mcpd-proxy

# With custom mcpd address
MCPD_ADDR=http://localhost:8090 npx @mozilla-ai/mcpd-proxy

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

# From source build
node dist/index.mjs

# From source with custom address
MCPD_ADDR=http://localhost:8090 node dist/index.mjs

VS代码设置

添加到您的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": ["
/dist/index.mjs"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

替换 带有安装的绝对路径。

重新加载VS代码： Cmd+Shift+P → “开发人员：重新加载窗口”

验证MCP面板中的连接，查看可用工具。

光标设置

创建或编辑 .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": ["
/dist/index.mjs"],
      "env": {
        "MCPD_ADDR": "http://localhost:8090"
      }
    }
  }
}

替换 使用安装的绝对路径，或使用 ${workspaceFolder} 相对路径。

重新加载游标以应用配置。

看 examples/ 用于配置示例的文件夹。

发展

项目结构

mcpd-proxy/
├── src/
│   ├── index.ts               # CLI entry point
│   ├── server.ts              # MCP server implementation
│   ├── config.ts              # Configuration loader
│   └── apiPaths.ts            # API endpoint constants
├── tests/
│   └── unit/                  # Unit test files
│       ├── aggregation.test.ts
│       ├── apiPaths.test.ts
│       ├── config.test.ts
│       ├── parsers.test.ts
│       └── server.test.ts
├── .github/
│   └── workflows/             # GitHub Actions workflows
│       ├── tests.yaml
│       ├── lint.yaml
│       └── release.yaml
├── examples/
│   ├── vscode-config.json     # VS Code configuration example
│   └── cursor-config.json     # Cursor configuration example
├── dist/                      # Build output (gitignored)
├── package.json               # npm package configuration
├── package-lock.json          # npm dependency lock file
├── tsconfig.json              # TypeScript compiler configuration
├── tsconfig.test.json         # TypeScript test configuration
├── vitest.config.ts           # Vitest test configuration
├── vite.config.mts            # Vite build configuration
├── eslint.config.mts          # ESLint configuration
├── .prettierignore            # Prettier ignore patterns
├── .gitignore                 # Git ignore patterns
└── README.md                  # This file

开发工作流程

# Install dependencies
npm install

# Build once
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check without building
npm run typecheck

# Lint code
npm run lint

# Format code
npm run format

手动测试

使用直接测试MCP协议 JSON-RPC 超过 stdio:

# Test initialize
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

# Test list tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.mjs

命名规范

工具

工具以以下格式公开： {server}__{tool_name}

示例：

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

这种命名约定可以防止服务器之间的工具名称冲突，并明确哪个服务器提供每个工具。

资源

资源使用自定义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,
});

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/

VS代码未显示工具

原因：VS代码可能无法识别MCP服务器

解决方案：

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

列出了工具，但执行失败

原因：服务器可能不正常或工具不存在

解决方案：

1. 通过以下方式检查服务器运行状况 mcpd API
2. 验证服务器上是否存在工具
3. 检查 mcpd 错误日志

未来的增强功能

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

相关项目

• mcpd -此代理连接到的MCP守护进程
• mcpd-sdk-javascript - TypeScript SDK用于 mcpd
• mcpd-sdk-python -Python SDK mcpd

许可证

阿帕奇-2.0

贡献

查看主 mcpd 仓库 关于贡献指南。