specmill (Flipbitsnotburgers)

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）

1. 发出实际的HTTP请求 到API服务器
2. 返回响应 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}）

1. 发出真正的HTTP请求 当LLM使用这些工具时
2. 返回实际API响应 LLM

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

VSCode集成

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

设置

1. 构建服务器

   make build

1. 创建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