@rekl0w/mcp openapi发现
@rekl0w/mcp-openapi-discovery 是一个TypeScript MCP服务器，可以：
- 从URL检测OpenAPI/Swagger文档，
- 检查并总结端点，
- API中的跟踪字段和标识符使用，
- 并使用auth和payload支持对这些端点执行真正的HTTP请求。
它是为文档化的第一个API工作流而设计的，您希望MCP客户端从 “查找规格” 到 “了解端点” 到 “调用端点”.
已发布包：
释放资源：
- GitHub发布： Rekl0w/mcp openapi发现发布
为什么这个项目存在
许多API公开文档页面，但并不总是直接公开原始规范URL。该服务器通过发现文档页面后面的OpenAPI文档并将其转换为可调用的MCP工具来帮助弥合这一差距。
它特别适用于：
- Swagger UI部署
- ReDoc文档页面
- Laravel+L5 Swagger项目
- API暴露
openapi.json,swagger.json,openapi.yaml，或swagger.yaml - 通过HTML或JS配置间接引用规范的文档页面
特性
- 从文档页面或直接规范URL检测OpenAPI/Swagger规范
- 通过发送基本身份验证、承载令牌、API密钥或自定义发现头来检测受保护的文档/规范页
- 在内存中分配一个稳定
specId对于每个检测到的规范，以便以后的工具可以在不重新公开完整文档的情况下工作 - 将发现的规格保存在磁盘上，以便
specId-基于工具的程序可以在进程重启后继续运行 - 总结API元数据、服务器、标记和终结点计数
- 按方法、标记或路径片段筛选列出端点
- 在服务器端搜索端点，在方法、路径、标签、摘要、参数、模式字段名、同义词和操作意图之间进行加权匹配
- 检查特定端点的请求/响应详细信息
- 跟踪标识符所在的位置
userId,accountId，或teamId跨参数和模式显示 - 查找与另一个端点在结构上相关的端点
- 建议可能的多步骤API工作流，如登录→ 创建类别→ 创建属性→ 创造产品
- 捆绑外部
$ref在分析之前，将文件和远程模式引用保存到本地内存文档中 - 使用以下命令执行终结点：
- 路径参数 - 查询参数 - 自定义头 - JSON有效载荷 - 表单url编码的有效载荷 - 基本多部分表单数据
- 使用以下方式应用身份验证：
- 基本认证 - 持有者代币 - API密钥 - OAuth 2.0密码流 - OAuth 2.0客户端凭据流 - 基于OpenAPI安全方案的自动身份选择
可用的MCP工具
detect_openapi：检测文档页面或规范URL后面的OpenAPI文档，并返回摘要list_endpoints：列出具有可选筛选的端点search_endpoints：使用服务器端加权评分在缓存端点中搜索检测到的规范suggest_call_sequence：建议目标端点或自然语言目标的可能先决条件调用链get_endpoint_details：返回单个端点的请求/响应详细信息trace_parameter_usage：跨参数、请求体和响应体使用参数或字段的跟踪find_related_endpoints：通过共享资源、标识符和路径结构查找与源终结点相关的终结点call_endpoint：对从OpenAPI文档中发现的端点执行实际请求
需求
- Node.js 18+
- NPM9+推荐
安装
从npm安装：
npm i @rekl0w/mcp-openapi-discovery或者在从源代码工作时安装项目依赖关系：
npm install
npm run build在本地运行
构建后运行stdio MCP服务器：
node dist/index.js发展：
npm run dev从MCP客户端连接
在MCP客户端中使用已发布包的最简单方法是让客户端自动安装并运行它 npx.
使用npm自动安装 npx
如果您的MCP客户端支持 command + args stdio服务器定义，使用：
{
"command": "npx",
"args": ["-y", "@rekl0w/mcp-openapi-discovery"]
}对于VS Code和类游标MCP客户端等客户端来说，这通常是最干净的设置，因为服务器启动时会自动下载包。
VS代码(.vscode/mcp.json)
VS代码支持 mcp.json 并且可以通过以下方式运行本地MCP服务器 npx.
{
"servers": {
"openapi-discovery": {
"command": "npx",
"args": ["-y", "@rekl0w/mcp-openapi-discovery"]
}
}
}光标样式MCP配置
对于使用JSON配置的MCP客户端 mcpServers，典型的设置如下：
{
"mcpServers": {
"openapi-discovery": {
"command": "npx",
"args": ["-y", "@rekl0w/mcp-openapi-discovery"]
}
}
}本地构建而不是npm
如果你更喜欢直接运行本地构建而不是使用npm，请将你的MCP客户端指向 dist/index.js.
克劳德桌面示例（Windows）
将此添加到 %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"openapi-discovery": {
"command": "node",
"args": ["C:/absolute/path/to/project/dist/index.js"]
}
}
}使用绝对路径。在Windows上，正斜杠或转义反斜杠都有效。
示例用例
- 检测背后的规格
https://example.com/docs - 检测规格，保留返回的
specId，并仅搜索最相关的端点 - 检测规格，保留返回的
specId，并通过持久缓存在重新启动时重用它 - 列出来自的端点
https://api.example.com/openapi.json - 检查
PUT /users/{id}端点 - 仅筛选
POST标记为的端点users - 向服务器询问可能的工作流程，例如“创建具有类别和属性的产品”
- 追踪何处
userId出现在API中 - 查找与相关的端点
GET /users/{id} - 发送真实
POST /orders带有JSON有效负载的请求 - 使用用户名/密码登录，获取令牌，并调用受保护的端点
结构化跟踪
除了简单的端点列表，此服务器还可以帮助回答以下问题：
- “在哪里
userId使用？” - “哪些端点与
GET /users/{id}?” - 此标识符是来自响应体、查询参数还是路径参数
现在，它将结构化分析与轻量级的服务器端端点搜索相结合。服务器可以检查和评分，而不是只在客户端上进行自然语言相似性：
- 路径参数
- 查询参数
- 请求正文字段
- 响应体字段
- 路径中的共享资源名称
- 共享标识符模式，例如
userId,accountId,teamId，或特定实体id领域
specId + search_endpoints 流动
跑 detect_openapi 先拿回来 specId.
然后打电话 search_endpoints 说完这个 specId 以及自然语言查询，例如：
create user emailrefresh bearer tokenorder status update
服务器根据以下内容为每个端点构建可搜索的文本索引：
- HTTP方法和路径
- operationId、摘要、描述和标记
- 参数名称
- 请求正文字段名称
- 响应体字段名称
这将使端点检索保持在服务器端，并仅返回顶部匹配项。
搜索评分器还添加了意图感知奖金，因此查询如下 add order, login token，或 edit product 仍然可以匹配 createOrder、身份验证端点，以及 PATCH/PUT 没有嵌入的样式操作。
suggest_call_sequence 流动
使用 suggest_call_sequence 当最困难的部分不是找到端点，而是弄清楚依赖调用的顺序时。
它可以在两种模式下工作：
- 按精确的目标终点：
targetMethod+targetPath - 按自然语言目标：
goal
服务器分析：
- 身份验证要求
- 路径参数依赖关系
- 请求正文标识符字段，例如
categoryId,attributeId,fileId，或parentId - 响应体输出，如
id,accessToken，或资源特定标识符 - 父/子路径关系
这使得可以建议如下链：
- 登录→ 创建类别→ 创建类别属性→ 创造产品
- 登录→ 创建客户→ 创建订单
- 上传文件→ 使用返回的文件id创建实体
持久缓存
检测到的规格被缓存到磁盘上，并由规范化的输入URL和 specId.
这意味着 search_endpoints 和 suggest_call_sequence 只要缓存的规范仍在缓存TTL内，即使在进程重新启动后，也可以继续工作。
如果需要，您可以用以下命令覆盖缓存目录 MCP_OPENAPI_DISCOVERY_CACHE_DIR 环境变量。
跟踪查询示例
使用 trace_parameter_usage 当你想关注一个字段时，例如 userId 穿过API表面。
使用 find_related_endpoints 当您已经知道一个端点并希望发现附近或依赖的端点时，例如使用相同标识符的子资源或端点。
端点执行和身份验证
接受 url 也接受可选 auth 对象。当文档页面或规范URL本身受到保护时使用此选项，例如HTTP Basic auth后面的Laravel Request docs页面。
{
"url": "https://api.example.com/request-docs",
"auth": {
"strategy": "basic",
"username": "demo",
"password": "super-secret"
}
}发现身份验证仅发送到与输入URL相同的源，包括常见的回退路径，如 request-docs/api?openapi=true 同源远程 $ref 文件夹。
这 call_endpoint 该工具可以执行实际的API调用，而不仅仅是描述它们。
支持的身份验证策略：
basicbearerapiKeyoauth2-passwordoauth2-client-credentialsauto
在 auto 在模式下，该工具检查端点的有效OpenAPI安全要求，并尝试从您提供的凭据中应用最合适的身份验证策略。
支持的请求正文样式
- JSON
application/x-www-form-urlencoded- 简单
multipart/form-data - 原始弦体通过
rawBody
您还可以使用以下命令显式覆盖传出内容类型 contentType.
示例 call_endpoint 输入
JSON主体+API密钥
{
"url": "https://orders.example.com/openapi.json",
"method": "POST",
"path": "/orders",
"body": {
"productId": 42,
"quantity": 3
},
"auth": {
"apiKey": "your-api-key"
}
}OAuth密码流
{
"url": "https://auth.example.com/openapi.json",
"method": "GET",
"path": "/me",
"auth": {
"username": "demo",
"password": "super-secret",
"clientId": "client",
"clientSecret": "client-secret",
"scopes": ["profile"]
}
}路径参数+查询参数
{
"url": "https://api.example.com/openapi.json",
"method": "GET",
"path": "/users/{id}",
"pathParams": {
"id": 123
},
"query": {
"include": ["roles", "permissions"]
}
}直接持有者代币
{
"url": "https://api.example.com/openapi.json",
"method": "GET",
"path": "/profile",
"auth": {
"strategy": "bearer",
"token": "your-access-token"
}
}验证
使用以下命令运行完整的验证套件：
npm run check这运行：
- TypeScript构建
- Vitest测试套件
开发说明
- 运行时：Node.js 18+
- MCP-SDK：
@modelcontextprotocol/sdk第1版 - 规范解析：JSON/YAML+HTML发现启发式+捆绑外部
$ref支持 - 缓存：内存+磁盘支持的规范缓存，由URL和
specId - 工作流规划：跨身份验证、路径参数、请求体ID和响应输出的依赖性推理
- 请求执行：具有自动身份验证处理的真实HTTP请求
- 试运行器：
vitest
安全说明
- 不要提交真实的凭据、客户端机密或访问令牌。
- 比起硬编码的秘密，更喜欢特定于环境的客户端配置。
- 在对生产API使用此方法时要小心。
- 仔细审查来自不可信来源的OpenAPI规范，特别是在涉及身份验证和实时请求执行时。
贡献
欢迎问题和拉取请求。
如果你想做出贡献：
- fork 仓库
- 创建要素分支
- 跑
npm run check - 打开一个带有清晰描述的拉取请求
路线图
- 更广泛的Swagger UI/标量检测模式
- 更丰富的特定于拉脱维亚的API摘要
- 可选的流式HTTP传输支持
许可证
麻省理工学院