specrun

SpecRun

一个将 OpenAPI 规范转换为 MCP 工具的 MCP 服务。扫描文件夹中的 OpenAPI 规范文件，并自动生成相应工具。随后可在任何 MCP 客户端中使用这些工具，与规范中定义的 API 交互；还内置了通过简单的 `.env` 文件管理身份验证和服务 URL 的支持。

使用 FastMCP 为 TypeScript 构建。

✨ 功能

• 零配置：文件系统就是操作界面——只需将 OpenAPI 规范文件放入文件夹
• 支持 OpenAPI 3.0 和 2.0：兼容 OpenAPI 3.x 和 Swagger 2.0 规范
• 命名空间隔离：多个 API 可以共存，彼此清晰隔离
• 全面支持 OpenAPI：处理参数、请求正文、身份验证和响应
• 运行任意工具与 API 交互：例如，运行 cars_addCar 调用 cars.json 规范中的 POST /cars 来创建新车，或运行 github_get_user_repos 调用 github.yaml 规范中的 GET /user/repos 来列出仓库。
• 运行任意工具并提供自定义输入：传入结构化 JSON 输入，用于设置参数和请求正文
• 运行任意工具查看规范详情：获取任意工具对应的原始 OpenAPI 规范详情，包括参数、请求正文架构和响应架构
• 运行任意工具并将 API 响应作为资源获取：每次工具调用都会返回一个 JSON 资源，其中包含请求 URL、请求正文和响应
• 批量运行任意工具：一个 specrun_batch 工具即可通过多个输入执行任意工具，并返回汇总的 JSON 资源
• 自动身份验证：使用简单的 .env 文件，并遵循 {API_NAME}_API_KEY 模式
• 自动添加 .env 占位项：缺少 {API_NAME}_SERVER_URL 和 {API_NAME}_BEARER_TOKEN 时自动添加
• 多种传输方式：支持 stdio 和 HTTP 流式传输
• 内置调试功能：使用 list 命令查看已加载的规范和工具
• MCP 提示词：内置提示词，用于列出工具、生成输入和解释架构
• Agent：已配置用于以引导方式使用 SpecRun 工具探索和操作 API 的 Agent（.github/agents/specrun.agent.md）

快速开始

要求

• Node.js 22 或更高版本

1️⃣ 安装（可选）

npm install -g specrun

2️⃣ 创建一个供服务读取 OpenAPI 规范文件的文件夹。例如：

mkdir ~/specs

3️⃣ 添加 OpenAPI 规范

将任意 .json、.yaml 或 .yml OpenAPI 规范文件放入规范文件夹

4️⃣ 配置身份验证（可选）

在规范文件夹中创建 .env 文件：

# ~/specs/.env
CARS_API_KEY=your_api_key_here

SpecRun 还会确保每个规范都存在 {API_NAME}_SERVER_URL 和 {API_NAME}_BEARER_TOKEN 条目；如果缺少，则添加空占位项。 当 {API_NAME}_SERVER_URL 有值时，SpecRun 会在加载时更新规范文件：

• OpenAPI 3.0：更新第一个 servers 条目。
• OpenAPI 2.0（以前称为 Swagger 2.0）：更新 host、schemes 和 basePath（OpenAPI 2.0 中没有 servers 部分）。

SpecRun 还会监视 .env 文件，并在文件发生更改后自动刷新服务 URL 和身份验证配置。

5️⃣ 添加到 MCP 客户端配置

将以下内容添加到 MCP 配置中：

如果已安装到计算机上：

{
  "mcpServers": {
    "specrun": {
      "command": "specrun",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

否则：

{
  "mcpServers": {
    "specrun": {
      "command": "npx",
      "args": ["-y", "specrun", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}

或指定 Node 版本：

{
  "mcpServers": {
    "specrun": {
      "command": "/Users/YOUR_USER_NAME/.local/bin/mcp-npx-node22",
      "args": ["specrun@latest", "--specs", "/absolute/path/to/your/specs"],
      "type": "stdio"
    }
  }
}

mcp-npx-node22 脚本文件使用 nvm 以 Node.js 22.14.0 运行 specrun，确保其不受系统默认 Node 版本影响，始终保持兼容：

#!/bin/bash
# Set the PATH to include NVM's Node.js v22.14.0 installation
export PATH="/Users/YOUR_USER_NAME/.nvm/versions/node/v22.14.0/bin:$PATH"

# Execute npx with all passed arguments
exec npx "$@"

💻 命令行用法

🚀 启动服务

# Default: stdio transport, current directory
specrun

# Custom specs folder
specrun --specs ~/specs

# HTTP transport mode
specrun --transport httpStream --port 8080

使用 npx 以 Node 22 运行

如果默认的 node 版本低于 22，可直接使用 Node 22 运行 SpecRun：

• npx -y node@22 ... 运行 Node.js 运行时，因此下一个参数必须是脚本路径（例如 ./node_modules/.bin/specrun）。
• specrun@latest 是一个 npm 包规范，只有当当前 Node 版本已满足 SpecRun 的要求时，才能直接与 npx 搭配使用。

# Or list tools
npx -y node@22 ./node_modules/.bin/specrun list --specs ~/specs

# If your default Node is already 22+, this also works
npx -y specrun@latest --specs ~/specs

📋 列出已加载的规范和工具

# List all loaded specifications and their tools
specrun list

# List specs from custom folder
specrun list --specs ~/specs

🔑 身份验证模式

服务器会使用以下模式自动检测环境变量中的身份验证信息：

模式	身份验证类型	用法
{API_NAME}_API_KEY	🗝️ API Key	X-API-Key 标头
{API_NAME}_TOKEN	🎫 Bearer Token	Authorization: Bearer {token}
{API_NAME}_BEARER_TOKEN	🎫 Bearer Token	Authorization: Bearer {token}
{API_NAME}_USERNAME + {API_NAME}_PASSWORD	👤 Basic Auth	Authorization: Basic {base64}

SpecRun 还会为以下变量创建 .env 占位符：

模式	用途
{API_NAME}_SERVER_URL	API 的基础 URL
{API_NAME}_BEARER_TOKEN	缺少令牌时使用的占位符

如果设置了 {API_NAME}_SERVER_URL，SpecRun 会在生成工具前将该值写入规范：

• OpenAPI 3.0：写入第一个 servers 条目。
• OpenAPI 2.0（原名 Swagger 2.0）：写入 host、schemes 和 basePath。

.env 的更新会自动应用，无需重启 MCP 服务。

{API_NAME} 根据 OpenAPI 规范的文件名生成：

• cars.json → CARS_API_KEY
• github-api.yaml → GITHUB_TOKEN
• my_custom_api.yml → MY_CUSTOM_API_KEY

🏷️ 工具命名

工具会按照以下模式自动命名：

• 带有 operationId：{operation_id}
• 不带 operationId：{method}_{path_segments}

名称规范化规则：

• 转换为 snake_case
• 转换为小写
• 将非字母数字字符规范化为 _
• 超过 52 个字符时从末尾截断。（为兼容 VS Code/Copilot，名称保持在实用的 64 字符内部限制以内。）
• 仅在需要解决名称冲突时添加短后缀

示例：

• get_car_by_id（来自 operationId）
• get_user_repos（根据 GET /user/repos 生成）

使用共享批处理工具，通过一组输入运行任意工具：

{
  "toolName": "cars_getCarById",
  "items": [{ "id": "123" }, { "id": "456" }],
  "failFast": false
}

批处理响应会返回一个整合后的 JSON 资源，其中包含每个项目的输出。

对于超过 200 个项目的批处理，SpecRun 需要明确确认，以防意外的大规模运行造成性能问题或意料之外的后果。服务器会返回要求确认的消息；你可以使用 confirmLargeBatch: true 和提供的 confirmLargeBatchToken 重试以继续。

📦 资源输出

工具响应会以 MCP 资源的形式返回，内容类型为 application/json。每个资源包含：

1. 请求 URL
2. 请求正文
3. 响应状态和正文

资源载荷示例：

{
  "requestUrl": "https://api.example.com/v1/users/123",
  "requestBody": null,
  "response": {
    "status": 200,
    "body": {
      "id": "123",
      "name": "Jane Doe"
    }
  }
}

批处理运行会返回一个包含所有项目结果的整合资源。

📁 文件结构

your-project/
── specs/           # Your OpenAPI specs folder
   ├── .env            # Authentication credentials
   └── custom-api.yml  # Your OpenAPI spec files

🧭 MCP 提示词

SpecRun 提供适用于常见工作流的 MCP 提示词：

详细的提示词指南和示例：PROMPTS_README.md

• list_apis：列出已加载的 API/工具，并让用户选择一个端点
• generate_api_call：为工具生成可直接运行的 JSON 输入载荷
• explain_api_schema：解释参数和请求正文架构，并提供示例
• generate_random_data：为工具生成可直接运行的随机 JSON 载荷示例

📄 OpenAPI 规范示例

以下是一个创建两个工具的最简示例：

# ~/specs/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api-server.placeholder
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        "201":
          description: User created

此示例会创建以下名称的工具：

• example_getUser
• example_createUser

🔧 故障排除

❌ 没有显示工具？

1. 检查 OpenAPI 规范是否有效：

   specrun list --specs /path/to/specs
   

2. 确保文件扩展名正确（.json、.yaml、.yml）

3. 检查服务日志中是否有解析错误

⚠️ 注意： 使用绝对路径（且不含空格）作为 --specs 参数和其他文件路径时，SpecRun 的效果最佳。相对路径或包含空格的路径可能会在某些平台或 MCP 客户端上导致问题。

🔐 身份验证无法正常工作？

1. 确认 .env 文件位于规范目录中
2. 检查命名模式是否与规范文件名匹配
3. 使用 list 命令验证身份验证配置：

   specrun list
   

🔄 规范更改后工具没有更新？

1. 重启 MCP 服务以重新加载规范
2. 检查文件权限
3. 如有需要，重启 MCP 客户端

🛠️ 开发

# Clone and install
git clone [email protected]:Pavel-Piha/specrun.git
cd specrun
npm install

# Build
npm run build

npm run dev -- list --specs ./specs

🤝 贡献

欢迎贡献！请随时提交问题和拉取请求。