Matfejbat MCP

MCP HTTP 封装器

具有IBM WatsonX Orchestrate集成的模型上下文协议（MCP）服务器的HTTP REST API封装器


🚀 概述

这个项目填补了（或连接了）……之间的鸿沟/差距 模型上下文协议（MCP） 服务器和云编排平台，如IBM WatsonX Orchestrate。它将本地MCP服务器（通过stdin/stdout进行通信）封装在一个可通过HTTP调用的REST API中。

为何此现象存在

• Claude Desktop（可译为“Claude桌面版”或根据具体语境简化为“Claude桌面”） 在本地作为进程运行MCP服务器（通过stdin/stdout进行通信）
• WatsonX Orchestrate（可译为“WatsonX 交响乐”或根据具体语境简化为“WatsonX 协调平台/系统”，但通常“Orchestrate”在技术语境下可能指一种协调、整合或调度多个系统/服务的能力，因此更贴切的翻译可能需要结合具体应用背景） 在云端运行，需要HTTP API（REST通信）
• 这个封装程序在两者之间进行转换，使您的MCP工具能够被云平台访问

✨ 特点

• 🔌 表示电源插头或插座的符号，可翻译为“电源插头”或“插座”。 通用MCP支持 - 与任何MCP服务器兼容 claude_desktop_config.json
• 🔒（锁形图标，常用于表示安全、保密或锁定状态） 默认安全 API密钥认证、速率限制、CORS保护
• 📊 表格/数据图表 OpenAPI 生成 - 自动生成OpenAPI 3.0规范以集成WatsonX
• 🐳 表示“海豚”或“海豚脸”。 Docker 准备就绪 - 使用docker-compose进行容器化部署
• 🔄 翻译成中文是：🔄（这个符号本身没有直接的中文翻译，但在中文语境中，它常被用来表示“循环”、“重复”或“刷新”的意思，具体含义需结合上下文理解。）如果仅从符号本身来看，可以简单地将其描述为“循环箭头”或“旋转箭头”。 自动启动服务器 - 启动时自动启动已配置的MCP服务器
• 📝（笔记或记录的符号，可译为“笔记”或“记录”） 详细日志记录 - 记录所有请求、响应和错误
• ⚡（闪电符号，常用于表示速度、活力、能量或紧急情况） 准备就绪，可投入生产 - 错误处理、超时、优雅关闭

📋 前提条件

• Node.js 18+（或 Docker）
• 你的 claude_desktop_config.json 文件
• 您想要暴露的MCP服务器

🛠️ 快速入门

选项1：本地开发

# Clone the repository
git clone https://github.com/Matfejbat/mcp-http-wrapper.git
cd mcp-http-wrapper

# Install dependencies
npm install

# Copy your Claude Desktop config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ./config/

# Set up environment variables
cp .env.example .env
# Edit .env and set your API_KEY

# Start the server
npm start

选项2：Docker

# Copy your config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ./config/

# Start with docker-compose
docker-compose up -d

📡 API 使用

健康检查

curl http://localhost:3000/health

列出可用工具

curl -H "X-API-Key: your-secret-key" \
  http://localhost:3000/servers/filesystem/tools

调用工具

curl -X POST \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/documents"}' \
  http://localhost:3000/servers/filesystem/tools/read_file

🔧 配置

环境变量

创建一个 .env 文件：

API_KEY=your-super-secret-key-here
PORT=3000
ALLOWED_ORIGINS=https://watsonx.cloud.ibm.com,http://localhost:3000
NODE_ENV=production

MCP服务器配置

将您的 claude_desktop_config.json 在……中 config/ 目录：

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/path/to/filesystem-server.js"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

🎯 WatsonX 集成

看见 docs/WATSONX_SETUP.md（文件名可译为“文档/WATSONX安装设置.md”） 关于以下内容的详细说明：

1. 生成OpenAPI规范
2. 部署包装器
3. 配置 WatsonX Orchestrate
4. 测试集成

快速OpenAPI生成

# Generate OpenAPI spec
node src/openapi-generator.js > openapi.json

# Or generate from running servers (more accurate)
curl -H "X-API-Key: your-secret-key" \
  http://localhost:3000/openapi > openapi.json

🚢 部署

见 docs/DEPLOYMENT.md 翻译为中文是：docs/部署指南.md（或“部署说明文件.md”，具体翻译可能根据上下文有所调整，但基本意思是“部署相关的文档文件”） 对于部署指南：

• Docker / Docker Compose（保持原名，不翻译）
• Railway.app（可译为“铁路应用”或保持原样作为专有名词）
• Fly.io（可直接保留原名，或根据上下文译为“飞.io”等，但通常技术平台名保持原样）
• AWS ECS/Fargate（亚马逊网络服务 - 任务容器服务/无服务器容器引擎）
• Google Cloud Run（谷歌云运行服务）
• 传统VPS（虚拟专用服务器）

📚 项目结构

mcp-http-wrapper/
├── src/
│   ├── server.js              # Main HTTP wrapper server
│   ├── openapi-generator.js   # OpenAPI spec generator
│   └── mcp-manager.js         # MCP server process manager
├── config/
│   └── claude_desktop_config.json  # Your MCP server config
├── docs/
│   ├── WATSONX_SETUP.md      # WatsonX integration guide
│   ├── DEPLOYMENT.md         # Deployment instructions
│   └── API.md                # API documentation
├── examples/
│   ├── claude_desktop_config.json
│   └── test-requests.http
├── .env.example              # Environment variables template
├── .gitignore
├── package.json
├── Dockerfile
├── docker-compose.yml
└── README.md

🔒 安全

• 认证所有端点（健康端点除外）均需API密钥
• 速率限制每个IP每15分钟100次请求
• CORS（跨源资源共享）可配置的允许来源
• 输入验证所有输入在处理前均经过验证
• 超时保护MCP操作的30秒超时
• Helmet.js安全头部已启用

🧪 测试

# Run tests
npm test

# Test with example requests
npm run test:integration

🤝 贡献

欢迎投稿！请：

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支
3. 提交您的更改
4. 推送至分支
5. 提交一个拉取请求

📄 许可证

MIT 许可证 - 详见 许可证 文件中有详细信息

🙏 致谢

• Anthropic（公司名，可译为“安萨提克”或根据具体语境保留原名） 为克劳德和MCP（注：MCP可能代表某个特定的人名、组织名或项目名，具体需根据上下文确定）
• 模型上下文协议 社区
• IBM WatsonX团队

📞 支持

• 问题:
• 讨论:
• MCP 文档https://modelcontextprotocol.io/（该网址可译为：“模型上下文协议.io”）

🗺️ 路线图/发展蓝图

• \[ \] 对流式响应的WebSocket支持
• \[ \] 内置身份验证提供程序（OAuth，JWT）
• \[ \] 指标和监控仪表板
• \[ \] 多服务器负载均衡
• \[ \] 自动更新OpenAPI规范
• \[ \] WatsonX 技能模板
• \[ \] 集成测试套件

______________________________________________________________________

为MCP社区倾心打造