Model Context Protocol (MCP) Server

Model Context Protocol (MCP) 服务

一个简单的 Model Context Protocol 实现，为多个 AI 模型提供商提供统一的 API。

功能

• 为多个 AI 提供商（Anthropic、OpenAI）提供统一的 API
• 支持聊天补全和旧版补全
• 支持工具调用
• 上下文／系统消息处理
• 基于环境的配置
• 使用 MongoDB 数据库实现持久化和状态管理
• 工具执行历史记录和分析

安装

# Clone the repository
git clone <repository-url>
cd testmcp

# Install dependencies
npm install

# Run the interactive setup
npm run setup

设置脚本将引导你配置所需的 API 密钥：

• ANTHROPIC_API_KEY - 用于 Claude 模型
• OPENAI_API_KEY - 用于 GPT 模型和 DALL-E 图像生成
• STABILITY_API_KEY - 用于 Stable Diffusion 图像生成
• GOOGLE_CSE_API_KEY 和 GOOGLE_CSE_ID - 用于网页搜索功能
• BING_SEARCH_API_KEY - 用于备用网页搜索

如果你愿意，也可以手动编辑 .env 文件。

MongoDB 设置

MCP 服务使用 MongoDB 持久化数据。你有多种设置 MongoDB 的选择：

选项 1：自动设置（推荐）

运行 MongoDB 设置脚本，该脚本将引导你完成整个流程：

# Run the MongoDB setup script
npm run setup-mongodb

此脚本将：

1. 检查 Docker 是否可用
2. 使用 Docker Compose 启动 MongoDB（如果可用）
3. 在 .env 文件中配置连接
4. 验证 MongoDB 连接

选项 2：手动使用 Docker 设置

开始使用 MongoDB 最简单的方式是使用随附的 Docker Compose 配置：

# Start MongoDB and Mongo Express in Docker
docker compose up -d

# Update your .env file with the connection string
echo "MONGODB_URI=mongodb://mcpuser:mcppassword@localhost:27017/mcp-server" >> .env

MongoDB 可通过 mongodb://mcpuser:mcppassword@localhost:27017/mcp-server 访问
Mongo Express（Web 管理界面）可通过 http://localhost:8081 访问

选项 3：本地安装 MongoDB

如果你更愿意在本地安装 MongoDB：

1. 从 https://www.mongodb.com/try/download/community 安装 MongoDB
2. 启动 MongoDB 服务
3. 更新 .env 文件，添加以下内容：

   MONGODB_URI=mongodb://localhost:27017/mcp-server
   

选项 4：MongoDB Atlas（云端）

对于生产环境，推荐使用 MongoDB Atlas：

1. 在 https://www.mongodb.com/cloud/atlas 创建账户
2. 创建新集群
3. 设置数据库用户并将你的 IP 地址加入白名单
4. 获取连接字符串并更新 .env 文件：

   MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/mcp-server?retryWrites=true&w=majority
   

数据库迁移

将现有数据迁移到 MongoDB：

# Run the migration script
npm run migrate-mongodb

此脚本将：

1. 将工具定义迁移到 MongoDB
2. 将配置（如 API 密钥）迁移到 MongoDB
3. 如果有备份数据，则将其导入

使用方法

启动服务

# Interactive startup (checks for API keys)
npm start

# Development mode with auto-reload
npm run dev

# Quick start (skips environment checks)
npm run quick-start

# Start server with PM2 process manager
npm run pm2:start

# Start server with PM2 in production mode
npm run pm2:start:prod

服务将在 http://localhost:3000 上运行（或运行在你在 .env 中指定的端口）。

启动选项

1. 标准启动（npm start）：

   • 检查是否已配置 API 密钥
   • 如果未找到密钥，则提示进行设置
   • 推荐首次使用时采用

2. 开发模式（npm run dev）：

   • 使用 nodemon 在代码更改时自动重新加载
   • 仍会执行环境检查
   • 最适合开发

3. 快速启动（npm run quick-start）：

   • 跳过所有环境检查
   • 立即启动服务
   • 适用于你确认配置正确的情况

4. PM2 生产模式（npm run pm2:start:prod）：

   • 使用 PM2 进程管理器运行服务
   • 服务崩溃时自动重启
   • 针对生产环境进行了优化
   • 跳过环境检查

使用 PM2 进程管理器

可以使用 PM2 运行服务。PM2 是 Node.js 应用的生产级进程管理器，提供以下功能：

• 进程管理（崩溃时重启）
• 日志管理
• 性能监控
• 负载均衡（用于多个实例）

PM2 命令

# Start the server with PM2
npm run pm2:start

# Start in production mode
npm run pm2:start:prod

# View logs
npm run pm2:logs

# Monitor performance
npm run pm2:monit

# Restart the server
npm run pm2:restart

# Stop the server
npm run pm2:stop

# Remove the server from PM2
npm run pm2:delete

PM2 配置存储在 ecosystem.config.js 中。你可以修改此文件以更改：

• 进程名称
• 环境变量
• 内存限制
• 部署配置
• 实例数量（用于负载均衡）

API 端点

POST /mcp/:provider

通过统一 API 向 AI 模型发送请求。

URL 参数：

• provider：要使用的 AI 提供商（anthropic 或 openai）

请求正文：

{
  "messages": [
    { "role": "user", "content": "Your prompt here" }
  ],
  "model": "claude-3-opus-20240229",  // Optional, provider-specific model name
  "tools": [...],  // Optional, tools for function calling
  "context": "System message or context"  // Optional
}

或（旧版格式）：

{
  "prompt": "Your prompt here",
  "model": "claude-3-opus-20240229",  // Optional
  "context": "System message or context"  // Optional
}

响应： 返回提供商 API 的原始响应。

GET /tools/available

获取所有可用工具的完整列表及详细信息。

查询参数：

• format - 响应格式：json（默认）、yaml、table 或 html
• category - 按类别筛选工具（可选）
• enabled - 按启用状态筛选：true（默认）或 false
• search - 按名称、描述或标签搜索工具
• provider - 按提供商筛选工具（例如，openai、google）
• limit - 返回工具的最大数量（用于分页）
• offset - 分页偏移量（默认值：0）

响应（JSON 格式）：

{
  "success": true,
  "count": 10,
  "metadata": {
    "categories": ["web", "image", "utility"],
    "providers": ["openai", "anthropic", "internal"],
    "totalCount": 24,
    "offset": 0,
    "limit": 10
  },
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web for information",
      "category": "web",
      "version": "1.0.0",
      "provider": "google",
      "enabled": true,
      "parameters": {
        "query": {
          "type": "string",
          "description": "The search query",
          "required": true
        },
        "limit": {
          "type": "number",
          "description": "Maximum number of results",
          "required": false,
          "default": 5
        }
      },
      "usage": {
        "endpoint": "/tools/web/search",
        "method": "POST",
        "parameters": { /* same as above */ }
      },
      "metadata": {
        "createdAt": "2023-10-15T12:00:00Z",
        "updatedAt": "2024-04-20T09:30:00Z",
        "usageCount": 1245
      }
    }
    // ... more tools
  ]
}

GET /health

健康检查端点；服务器运行时返回状态码 200。

数据管理

数据库备份

你可以创建和管理数据库备份：

# Create a full backup
npm run backup-mongodb

# Create a backup with execution history
npm run backup-mongodb -- --with-executions

# List existing backups
npm run backup-mongodb -- --list

测试数据库连接

验证 MongoDB 配置：

# Run the database test script
npm run test-mongodb

示例客户端

命令行客户端

src/client.js 中包含一个测试客户端。运行方法：

node src/client.js

Web 客户端

服务器运行时，可通过 http://localhost:3000 使用一个简单的 Web 界面。你可以直接在浏览器中使用它测试 API。

可用工具

MCP 服务提供了一个工具发现端点，允许用户和 AI Agent 以编程方式列出所有可用工具：

工具发现

GET /tools/available - 列出所有可用工具及详细信息。

• 支持多种格式：JSON、YAML、HTML 和 ASCII 表格
• 支持按类别、提供商和搜索词筛选
• 包含每种工具的详细元数据和使用示例

示例用法：

# Get all tools in JSON format
curl http://localhost:3000/tools/available

# Get tools in a specific category
curl http://localhost:3000/tools/available?category=web

# Search for image-related tools
curl http://localhost:3000/tools/available?search=image

# Get a formatted HTML page of all tools
curl http://localhost:3000/tools/available?format=html > tools.html

Web 搜索工具

该服务包含内置的 Web 搜索和内容检索工具：

1. Web 搜索（/tools/web/search）

   • 搜索 Web，查找给定查询的信息
   • 参数：query（必需）、limit（可选）
   • 需要：GOOGLE_CSE_API_KEY 和 GOOGLE_CSE_ID 环境变量
   • 如果 Google 搜索失败，则回退到 BING_SEARCH_API_KEY

2. Web 内容（/tools/web/content）

   • 从指定 URL 检索并提取内容
   • 参数：url（必需）、useCache（可选）

3. Web 批量检索（/tools/web/batch）

   • 并行检索多个 URL 的内容
   • 参数：urls（必需数组）、useCache（可选）

图像生成工具

该服务还包含图像生成、编辑和变体工具：

1. 生成图像（/tools/image/generate）

   • 根据文本提示词生成图像
   • 参数：
     • prompt（必需）：图像的详细描述
     • provider（可选）：openai 或 stability（默认值为 openai）
     • options（可选）：提供商特定选项

2. 编辑图像（/tools/image/edit）

   • 使用文本提示词编辑现有图像
   • 参数：
     • imagePath（必需）：要编辑的图像路径
     • prompt（必需）：要进行的编辑说明
     • maskPath（可选）：蒙版图像的路径

3. 创建图像变体（/tools/image/variation）

   • 创建现有图像的变体
   • 参数：
     • imagePath（必需）：要生成变体的图像路径

注意： 要使用这些工具，需要在 .env 文件中设置 API 密钥：

• 对于 OpenAI 图像：OPENAI_API_KEY
• 对于 Stability AI 图像：STABILITY_API_KEY
• 对于 Web 搜索：GOOGLE_CSE_API_KEY 和 GOOGLE_CSE_ID

与 AI 模型集成工具

MCP 服务会自动处理与 AI 模型的工具调用和执行。当模型决定使用某个工具时，服务会：

1. 使用提供的参数执行请求的工具
2. 将工具的响应返回给模型
3. 模型随后可以将工具的响应融入最终答案

为 AI 模型发现工具

AI 模型可以使用 /tools/available 端点来发现可用工具及其使用方法。这对于以下场景尤其有用：

• 在运行时动态发现工具
• 为 AI Agent 提供自我文档
• 使 AI 系统能够适应可用功能

AI 模型的系统提示词示例：

You have access to external tools through the MCP server. 
Before using any tools, you should check what tools are available by calling:
GET /tools/available

This will return a list of all available tools with their parameters and usage instructions.
You can then use these tools by following the provided usage patterns.

工具使用示例

请参阅 /examples 目录中的示例代码，了解工具用法。

添加新的提供方或工具

添加新的 AI 提供方

要添加新的 AI 提供方：

1. 将提供方的 SDK 添加到项目中
2. 在 server.js 中创建新的处理函数
3. 在主路由处理程序中添加新的 case

添加新工具

要向服务添加新工具：

1. 在 /src/tools 目录中创建新的工具实现
2. 将工具定义添加到 tool-definitions.js
3. 更新 server.js 中的工具执行函数
4. 添加用于直接使用工具的新 API 端点（如有需要）

许可证

GNU MIT