内容
# OpenAPI Contract MCP
MCP 服务器从本地（或远程）后端读取 **OpenAPI 契约**，以便代理可以针对真实的 API 形状构建前端和移动应用。默认情况下，它是 **只读** 的（仅检查 OpenAPI 文档）。当设置 `OPENAPI_MCP_ENABLE_CALLS` 时，可选的 HTTP 执行通过 `call_endpoint` 提供。后端按需注册；没有后端环境变量列表。
[](https://www.npmjs.com/package/@fqueis/openapi-contract)
[](https://github.com/fqueis/openapi-contract/actions/workflows/pr-checks.yml)
[](LICENSE.md)
---
## 功能描述
大多数 LLMs 通过猜测构建 API：发明路径、请求体和响应字段，这些可能与后端不匹配。OpenAPI Contract MCP 为代理提供了一个 **结构化接口**，以访问真实的 OpenAPI 文档，而在编写任何 UI 或客户端代码之前。
使用 [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) 构建，它提供了：
- **按需后端注册**：使用 `baseUrl` 调用 `use_backend`；不需要在静态后端列表中存储敏感信息
- **契约浏览**：概览、标签、操作、安全方案和来自实时规范的组件模式
- **解除引用操作**：`get_operation` 返回本地 `$ref` 解析和可能的请求示例
- **默认只读**：除非设置了 `OPENAPI_MCP_ENABLE_CALLS`，否则 API 执行关闭（然后注册 `call_endpoint`）
---
## 要求
- Node.js >= 18
- 暴露 OpenAPI 的后端（Nest Swagger：`/docs-json` 等）
- [pnpm](https://pnpm.io/) — 如果您开发或贡献此仓库
---
## 与 MCP 客户端一起使用
在 MCP 客户端的配置（stdio）中注册服务器。形状略有不同；下面的示例使用常见的 `mcpServers` 布局。
**推荐（npm）：**
```json
{
"mcpServers": {
"openapi-contract": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@fqueis/openapi-contract"]
}
}
}
```
您可以从本地克隆运行服务器进行开发，但对于正常使用，请优先使用上述已发布的软件包。
**可选：启用 HTTP 调用**（注册 `call_endpoint`）：
```json
{
"mcpServers": {
"openapi-contract": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@fqueis/openapi-contract"],
"env": {
"OPENAPI_MCP_ENABLE_CALLS": "1"
}
}
}
}
```
优先使用 `headerEnv`（环境变量名称）而不是将机密粘贴到 `headers` 中，以便令牌不太可能出现在代理记录中。
---
## 本地开发 / 贡献者
```bash
cd /path/to/openapi-contract
pnpm install
pnpm build
pnpm test
```
**构建的 JS：**
```json
{
"mcpServers": {
"openapi-contract": {
"type": "stdio",
"command": "node",
"args": ["/path/to/openapi-contract/dist/index.js"]
}
}
}
```
**开发（TypeScript via tsx）：**
```json
{
"mcpServers": {
"openapi-contract": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "/path/to/openapi-contract/src/index.ts"]
}
}
}
```
---
## 典型代理流程
1. 使用 `baseUrl`（例如 `http://localhost:3000`）和可选的 `id` / `specPath` 调用 `use_backend`
2. `get_api_overview` / `list_tags` / `list_operations` / `search_operations`
3. 为解除引用的模式 + 请求示例获取 `get_operation`
4. 根据需要获取 `get_schema` / `get_security`
5. 启用 `OPENAPI_MCP_ENABLE_CALLS=1`：使用 `call_endpoint` 执行操作（通过 `headers` / `headerEnv` 进行身份验证）
6. 使用 `forget_backend` 或 `clear_backends` 删除磁盘注册表；使用 `refresh_backend` 重新获取 OpenAPI
如果缺少 `baseUrl`，则工具返回清晰的错误，以便代理可以询问用户。
---
## 工具
| 工具 | 目的 |
| --- | --- |
| `use_backend` | 注册/更新后端（磁盘，1天 TTL）并获取 OpenAPI |
| `list_backends` | 列出未过期的后端 |
| `forget_backend` | 删除后端 |
| `clear_backends` | 清除注册表 |
| `refresh_backend` | 重新获取 OpenAPI（绕过 60 秒缓存） |
| `get_api_overview` | 信息、服务器、计数、全局安全 |
| `list_tags` | 标签 |
| `get_security` | 方案 + 要求（按操作可选） |
| `list_operations` | 按标签/方法/路径过滤 |
| `search_operations` | 文本搜索 |
| `get_operation` | 完整操作（解除引用 + 示例） |
| `get_schema` | 按名称或 `$ref` 获取组件模式 |
| `call_endpoint` | 对操作执行 HTTP（仅限 ENABLE_CALLS） |
---
## 规范发现
默认路径：`/docs-json`。备用路径：`/docs-yaml` → `/openapi.json` → `/v3/api-docs`。接受绝对文档 URL。
---
## 可选环境变量
MCP 客户端配置（`mcp.json` 等）将 `env` 传递给服务器进程。这些值始终是 **字符串**（与 OS/`process.env` 相同）。写入 `"1"` 或 `"30000"`，而不是裸 JSON 布尔值或数字。
| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `OPENAPI_MCP_CACHE_TTL_MS` | `60000` | 内存 OpenAPI 文档 TTL |
| `OPENAPI_MCP_REGISTRY_TTL_MS` | `86400000` | 磁盘后端注册表 TTL（1 天） |
| `OPENAPI_MCP_REGISTRY_PATH` | `%USERPROFILE%\.openapi-contract-mcp\backends.json` | 注册表文件路径 |
| `OPENAPI_MCP_ENABLE_CALLS` | 未设置（关闭） | 当 `"1"` / `"true"` / `"yes"` 时，注册 `call_endpoint` |
| `OPENAPI_MCP_CALL_TIMEOUT_MS` | `30000` | `call_endpoint` 请求中止超时 |
| `OPENAPI_MCP_CALL_MAX_BODY_BYTES` | `102400` | `call_endpoint` 返回的最大响应体字节（然后截断） |
---
## 架构
有关 MCP 客户端、服务层、注册表/缓存和 OpenAPI 后端（包括 Mermaid 图）之间的通信流程，请参阅 [ARCHITECT.md](ARCHITECT.md)。
发行历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。GitHub 版本说明取自匹配的版本部分（如果存在）。
---
## 许可证
MIT © [fqueis](https://github.com/fqueis)。参见 [LICENSE.md](LICENSE.md)。
