OpenAPI到MCP代理服务

Specmill

一个MCP（模型上下文协议）代理服务器，将任何符合OpenAPI的REST API公开为用于LLM的MCP工具。

它做什么

Specmill充当 LLM和REST API之间的代理:

1. 读取OpenAPI规范 （YAML格式）描述REST API
2. 生成MCP工具 从规范中的每个API操作
3. 当LLM调用工具时，Specmill向API发出实际的HTTP请求
4. 返回API响应 回到LLM

这允许任何兼容MCP的LLM与具有OpenAPI规范的REST API交互，而无需编写自定义MCP服务器代码。

特性

• API代理 -向API端点发出真实的HTTP请求
• 自动生成刀具 -从OpenAPI操作创建MCP工具
• 参数映射 -将函数参数转换为HTTP参数
• 架构验证 -将OpenAPI模式用于参数类型
• 多个API -为不同的API运行多个实例

快速开始

构建项目

make build

使用OpenAPI规范运行

./specmill-server -spec examples/petstore.yaml

与Claude或其他MCP客户端一起使用

# Initialize the server
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}' | ./specmill-server -spec examples/petstore.yaml

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' | ./specmill-server -spec examples/petstore.yaml

# Call a tool
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"getPetById","arguments":{"petId":1}},"id":3}' | ./specmill-server -spec examples/petstore.yaml

项目结构

• parser/ -OpenAPI规范解析器
  • openapi.go -YAML解析和模式定义
• generator/ -MCP服务器生成器
  • types.go -MCP协议类型定义
  • mcp.go -OpenAPI到MCP转换逻辑
• server/ -MCP服务器实现
  • server.go -JSON-RPC服务器和请求处理
• examples/ -OpenAPI规范示例
  • petstore.yaml -用于测试的标准Petstore API
• main.go -CLI入口点

运作原理

当LLM调用工具（例如。， getPetById（Specmill:

1. 接收MCP工具调用 与法学硕士的论点
2. 将其映射到OpenAPI操作 （例如。， GET /pet/{petId})
3. 构造HTTP请求:
   • 使用OpenAPI中的基本URL servers 章节
   • 替换路径参数
   • 添加查询参数
   • 设置请求正文（用于POST/PUT）
4. 发出实际的HTTP请求 到API服务器
5. 返回响应 LLM

示例流程

LLM: "Get pet with ID 123"
  ↓
MCP: tools/call { name: "getPetById", arguments: { petId: 123 } }
  ↓
Specmill: GET [servers.url]/pet/123
  ↓
API: { "id": 123, "name": "Fluffy", "status": "available" }
  ↓
LLM: "The pet with ID 123 is named Fluffy and is available"

OpenAPI到MCP映射

发展

先决条件

• 达到1.21或更高
• Make（可选，用于使用Makefile）

测试

# Run all tests
make test

# Run with verbose output
make test-verbose

# Run with coverage
make test-coverage

可用生成目标

• build -构建服务器二进制文件
• test -运行单元测试
• test-verbose -运行具有详细输出的测试
• test-coverage -使用覆盖率报告运行测试
• clean -删除构建工件
• fmt -设置Go代码格式
• lint -绒毛（需要golangci绒毛）
• help -显示可用目标

用例

Specmill非常适合：

1. 测试API -让LLM与您的开发API交互
2. API集成 -允许LLM访问第三方API（GitHub、Stripe等）
3. 内部工具 -将内部REST API暴露给LLM，而无需编写代码
4. API勘探 -使用LLM探索和理解新的API
5. 自动化 -让LLM基于自然语言执行API操作

示例：Petstore API

在运行Petstore示例时，Specmill：

1. 连接到 现场API宠物店 https://petstore3.swagger.io
2. 生成MCP工具 比如：
   • addPet -创建新宠物（POST/pet）
   • getPetById -取宠物（GET/pet/{petId}）
   • updatePet -更新宠物（PUT/pet）
   • deletePet -删除宠物（删除/pet/{petId}）
3. 发出真正的HTTP请求 当LLM使用这些工具时
4. 返回实际API响应 LLM

注意：Petstore规范使用相对URL(/api/v3)，因此您需要一个OpenAPI规范，其中包含用于实际API调用的绝对URL。

VSCode集成

Specmill可以作为MCP服务器与VSCode集成，以便与Claude一起使用基于OpenAPI的工具。

设置

1. 构建服务器

   复制

   make build
   

2. 创建MCP配置

   创建 .vscode/mcp.json 在项目根目录中：

   复制

   {
     "mcpServers": {
       "petstore": {
         "command": "/absolute/path/to/specmill-server",
         "args": ["-spec", "/absolute/path/to/examples/petstore.yaml"],
         "env": {},
         "disabled": false
       }
     }
   }
   

文档

• VSCode设置 -VSCode快速配置指南
• 使用指南 -详细的使用说明和故障排除
• 例子 -示例配置和OpenAPI规范

全部

• []支持身份验证方案（API密钥、OAuth等）
• []处理非JSON请求/响应内容类型
• []添加响应解析和格式化
• []支持OpenAPI 3.1功能
• []基本URL和默认值的配置
• []更好的错误消息和验证

参考

• 模型上下文协议
• OpenAPI规范
• JSON-RPC 2.0