转换端点到MCP工具

作者：nissynicolas0 星标更新：2025-10-15

安装使用来源：spider==github.com

项目介绍

OpenAPI 到 MCP 服务器生成器

🚀 将任何 OpenAPI JSON 规范转换为完整的 C# MCP（模型上下文协议）服务器！

此工具自动生成完整的 C# MCP 服务器应用程序，其中每个 OpenAPI 端点都成为 MCP 工具，使 REST API 即刻可供 AI 代理和兼容 MCP 的客户端访问。

✨ 特性

🔄 自动转换：将 OpenAPI 3.0+ 规范转换为 MCP 服务器
🛠️ 完整项目生成：创建可运行的 C# 项目
📡 MCP 兼容：生成的服务器与 Cursor IDE、VS Code、Claude Desktop 兼容
🎯 智能命名：根据端点和操作 ID 智能命名工具
🔧 类型映射：将 OpenAPI 类型转换为适当的 C# 类型
📚 文档：自动生成 README 和使用示例
🧪 测试：包括验证测试脚本

🚀 快速开始

预备条件

.NET 9.0 SDK 或更高版本
OpenAPI 3.0+ JSON 规范文件

安装及使用

# 克隆或下载此生成器
git clone <repository-url>
cd OpenApiToMcpGenerator

# 构建生成器
dotnet build

# 从 OpenAPI 规范生成 MCP 服务器
dotnet run -- --openapi petstore.json --output ./Generated-PetStore-Server --name PetStoreMMcpServer

# 运行生成的服务器
cd Generated-PetStore-Server
dotnet run

📋 命令行选项

dotnet run -- [选项]

选项:
  --openapi, -o     OpenAPI JSON 文件路径或 URL（必需）
                    示例：
                    • ./petstore.json
                    • https://petstore3.swagger.io/api/v3/openapi.json
                    • https://localhost:56733/swagger/v1/swagger.json
  --output, -out    生成的 MCP 服务器输出目录（必需）
  --name, -n        生成项目的名称（默认：GeneratedMcpServer）
  --base-url, -b    API 的基础 URL（覆盖 OpenAPI 服务器 URL）
  --namespace, -ns  生成代码的根命名空间（默认：GeneratedMcpServer）
  --verbose, -v     启用详细输出
  --help           显示帮助信息

🎯 使用示例

从 Swagger Petstore（URL）生成

# 直接从 URL 生成 - 不需要先下载！
dotnet run -- --openapi https://petstore3.swagger.io/api/v3/openapi.json --output ./PetStore-MCP --name PetStoreMcpServer --base-url https://petstore3.swagger.io/api/v3

# 测试生成的服务器
cd PetStore-MCP
dotnet run

从本地开发服务器生成

# 从你的本地 API 的 swagger 端点生成
dotnet run -- --openapi https://localhost:56733/swagger/v1/swagger.json --output ./MyApi-MCP --name MyApiMcpServer --base-url https://localhost:56733

# 或从本地文件生成
dotnet run -- --openapi ./my-api-spec.json --output ./MyApi-MCP --name MyApiMcpServer

与 Cursor IDE 集成

{
  "mcpServers": {
    "petstore": {
      "command": "dotnet",
      "args": ["run", "--project", "./PetStore-MCP", "--no-build"],
      "cwd": "./PetStore-MCP"
    }
  }
}

🏗️ 生成项目结构

Generated-MCP-Server/
├── 📄 Program.cs              # MCP 服务器入口点（与参考相同）
├── 📄 ProjectName.csproj      # 包含 MCP 依赖项的项目文件
├── 📄 ApiTools.cs             # 从 OpenAPI 端点生成的 MCP 工具
├── 📄 README.md               # 生成的文档
└── 📄 test-mcp.bat           # 测试脚本

🔄 转换示例

OpenAPI 端点 → MCP 工具

OpenAPI:

{
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "getUserById",
        "summary": "通过 ID 获取用户",
        "parameters": [
          {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}
        ]
      }
    }
  }
}

生成的 MCP 工具:

[McpServerTool, Description("通过 ID 获取用户")]
public static async Task<string> GetUserById(
    [Description("要检索的用户 ID")] string id)
{
    try
    {
        using var client = new HttpClient();
        var url = $"{BaseUrl}/users/{id}";
        var response = await client.GetAsync(url);
        response.EnsureSuccessStatusCode();
        var responseContent = await response.Content.ReadAsStringAsync();
        
        return JsonSerializer.Serialize(new
        {
            success = true,
            data = JsonSerializer.Deserialize<object>(responseContent),
            method = "GET",
            url = url
        }, new JsonSerializerOptions { WriteIndented = true });
    }
    catch (Exception ex)
    {
        return JsonSerializer.Serialize(new
        {
            success = false,
            error = ex.Message,
            method = "GET",
            endpoint = "/users/{id}"
        }, new JsonSerializerOptions { WriteIndented = true });
    }
}

🎯 支持的功能

✅ HTTP 方法

GET, POST, PUT, PATCH, DELETE
自定义 HTTP 方法

✅ 参数

路径参数 (/users/{id})
查询参数 (?limit=10&offset=0)
请求体（JSON, form-data 等）
头部参数

✅ OpenAPI 功能

操作 ID 用于工具命名
参数描述
请求/响应模式
多种内容类型
服务器 URL

✅ 生成代码功能

异步/等待模式
正确的错误处理
JSON 序列化
类型安全的参数处理
全面的文档

🔧 架构

生成器由几个关键组件组成：

OpenApiParser：解析 OpenAPI 规范并提取端点信息
CodeGenerator：从端点生成 C# MCP 工具方法
ProjectGenerator：创建完整的项目结构
NameGenerator：工具和参数的智能命名
TypeMapper：将 OpenAPI 类型映射到 C# 类型

🧪 测试生成的服务器

手动测试

# 测试工具列表
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | dotnet run

# 测试特定工具
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "GetUsers", "arguments": {}}}' | dotnet run

使用测试脚本

# Windows
test-mcp.bat

# 脚本测试基本功能和工具调用

🎯 兼容的 MCP 客户端

生成的服务器与支持通过标准输入/输出进行 JSON-RPC 的任何 MCP 客户端兼容：

✅ Cursor IDE（原生 MCP 支持）
✅ VS Code（带有 MCP 扩展）
✅ Claude Desktop（带有配置）
✅ 自定义 MCP 客户端

📚 示例

查看 examples/ 目录中的样本 OpenAPI 规范及其生成的 MCP 服务器：

Petstore API → 管理宠物工具
JSONPlaceholder → 管理博客文章和用户
GitHub API → 管理仓库和问题

🤝 贡献

欢迎贡献！请随时提交问题、功能请求或拉取请求。

📄 许可证

该项目在 MIT 许可证 下提供。

🔗 参考资料

利用 MCP 的力量将您的 REST API 转变为可供 AI 访问的工具！🚀