Specmill
一个MCP(模型上下文协议)代理服务器,将任何符合OpenAPI的REST API公开为用于LLM的MCP工具。
它做什么
Specmill充当 LLM和REST API之间的代理:
- 读取OpenAPI规范 (YAML格式)描述REST API
- 生成MCP工具 从规范中的每个API操作
- 当LLM调用工具时,Specmill向API发出实际的HTTP请求
- 返回API响应 回到LLM
这允许任何兼容MCP的LLM与具有OpenAPI规范的REST API交互,而无需编写自定义MCP服务器代码。
特性
- API代理 -向API端点发出真实的HTTP请求
- 自动生成刀具 -从OpenAPI操作创建MCP工具
- 参数映射 -将函数参数转换为HTTP参数
- 架构验证 -将OpenAPI模式用于参数类型
- 多个API -为不同的API运行多个实例
快速开始
构建项目```bash
make build
### 使用OpenAPI规范运行```bash
./specmill-server -spec examples/petstore.yaml
与Claude或其他MCP客户端一起使用```bash
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工具调用** 与法学硕士的论点
1. **将其映射到OpenAPI操作** (例如。, `GET /pet/{petId}`)
1. **构造HTTP请求**:
- 使用OpenAPI中的基本URL `servers` 章节
- 替换路径参数
- 添加查询参数
- 设置请求正文(用于POST/PUT)
1. **发出实际的HTTP请求** 到API服务器
1. **返回响应** 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映射
| OpenAPI | MCP | HTTP |
|---|---|---|
| 操作 | 工具 | HTTP方法 |
| 操作ID | 工具名称 | - |
| 路径+参数 | - | URL构造 |
| RequestBody | 工具参数 | 请求正文 |
| 响应 | 工具响应 | 响应正文 |
发展
先决条件
- 达到1.21或更高
- Make(可选,用于使用Makefile)
测试```bash
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交互
1. **API集成** -允许LLM访问第三方API(GitHub、Stripe等)
1. **内部工具** -将内部REST API暴露给LLM,而无需编写代码
1. **API勘探** -使用LLM探索和理解新的API
1. **自动化** -让LLM基于自然语言执行API操作
## 示例:Petstore API
在运行Petstore示例时,Specmill:
1. **连接到** 现场API宠物店 `https://petstore3.swagger.io`
1. **生成MCP工具** 比如:
- `addPet` -创建新宠物(POST/pet)
- `getPetById` -取宠物(GET/pet/{petId})
- `updatePet` -更新宠物(PUT/pet)
- `deletePet` -删除宠物(删除/pet/{petId})
1. **发出真正的HTTP请求** 当LLM使用这些工具时
1. **返回实际API响应** LLM
注意:Petstore规范使用相对URL(`/api/v3`),因此您需要一个OpenAPI规范,其中包含用于实际API调用的绝对URL。
## VSCode集成
Specmill可以作为MCP服务器与VSCode集成,以便与Claude一起使用基于OpenAPI的工具。
### 设置
1. **构建服务器**```bash
make build
- 创建MCP配置
创建 .vscode/mcp.json 在项目根目录中: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
