specwise-mcp

Specwise MCP 服务

让你的编码 Agent 检查 API 契约：验证 OpenAPI 文档、查找两个版本之间的破坏性变更（也支持对比 git），并验证 JSON Schema 和数据。

该服务开源（MIT）。它会调用付费的 Specwise API，该 API 提供免费套餐。

• 使用你自己的密钥，可从 RapidAPI 或 api.market 获取。
• 每次工具调用都会消耗套餐中的一次请求。
• 免费 Basic 套餐每月提供 15 次请求，并设有硬性限额，因此不会产生额外账单。

1. 获取密钥

marketplace
RapidAPI	套餐
api.market	商店

2. 将服务添加到 MCP 客户端

该服务通过 uv 在本地使用 stdio 运行。将密钥放入其环境变量中。

JSON 配置（Claude Desktop、Cursor、VS Code 和大多数客户端）：

{
  "mcpServers": {
    "specwise": {
      "command": "uvx",
      "args": ["--from", "bytestay-specwise-mcp", "specwise-mcp"],
      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
    }
  }
}

Claude Code：

claude mcp add specwise --env RAPIDAPI_KEY=your-rapidapi-key -- uvx --from bytestay-specwise-mcp specwise-mcp

环境变量

变量	含义
RAPIDAPI_KEY	你的 RapidAPI 密钥
API_MARKET_KEY	你的 api.market 密钥；未设置 RAPIDAPI_KEY 时使用
HFL_MARKETPLACE	两个密钥都已设置时，使用 rapidapi 或 apimarket

即使没有密钥，服务仍会启动。首次调用工具时，它会说明如何获取密钥。

也已收录在 Glama：

3. 工具

工具	功能
validate_openapi(spec=… | spec_path=…)	列出所有错误及其 JSON Pointer、行号和列号，并提供 lint 警告（OpenAPI 3.x 和 Swagger 2.0）
diff_openapi(...)	将两个 OpenAPI 3.x 版本之间的每项变更标记为破坏性、警告、非破坏性或信息提示，并给出 semver 建议
validate_json_schema(schema=… | schema_path=…, instance=… | instance_path=…, draft=None)	根据元模式检查模式；如果提供了数据，也会根据模式检查数据

diff_openapi 支持以下三种方式之一来指定两个版本：

• 将 base 和 revision 指定为文本；
• 将 base_path 和 revision_path 指定为文件；
• 使用 revision_path 和 base_git_ref。例如，编辑规范后：revision_path="openapi.yaml", base_git_ref="main"。

每个工具都会返回 API 的 JSON 响应。

• 如果 marketplace 提供此信息，响应中会添加 quota_remaining：表示本月套餐还剩余的请求次数。
• 错误会用通俗易懂的文字说明，并告知接下来该怎么做：
  • 密钥被拒绝，并提供订阅链接；
  • 已达到配额，并提供套餐信息；
  • API 无法处理输入，并说明原因。

隐私

• 只有在工具收到本地文件路径时才会读取文件。文件会随该次请求发送到 API。
• API 会在内存中处理输入，不会存储。请参阅隐私政策。
• 你的密钥只会发送到你选择的 marketplace。

限制

• 每份文档最大约为 900 KiB。
• 不会获取外部 $ref。请先打包多文件规范（redocly bundle）。
• 差异比较需要 OpenAPI 3.x；可以验证 Swagger 2.0，但不能进行差异比较。
• 服务需要 Python 3.10+（uv 会为你安装）。

开发

uv venv && uv pip install -e ".[dev]"
.venv/bin/pytest            # unit tests, no network; 100% coverage required
.venv/bin/ruff check src tests scripts

scripts/e2e_stdio.py specwise 会像客户端一样通过 stdio 运行服务，并调用其工具访问真实 API。它需要 RAPIDAPI_KEY 或 API_MARKET_KEY。

许可证

MIT。Specwise 本身是由 ByteStay 运营的付费 API，提供免费套餐。