开放API目录-MCP
项目介绍
技术文档摘要
<h1 align="center">OpenAPI 目录 MCP 服务器</h1> <p align="center"> <a href="https://www.npmjs.com/package/openapi-directory-mcp"><img src="https://img.shields.io/npm/v/openapi-directory-mcp.svg?style=flat-square&aaa=1" alt="NPM 版本"></a> <a href="https://github.com/rawveg/openapi-directory-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rawveg/openapi-directory-mcp.svg?style=flat-square&aaa=1" alt="许可证"></a> <a href="https://github.com/rawveg/openapi-directory-mcp"><img src="https://img.shields.io/github/stars/rawveg/openapi-directory-mcp?style=flat-square&aaa=1" alt="GitHub 星数"></a> <a href="https://github.com/sponsors/rawveg"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-lightgrey?style=flat-square&aaa=1" alt="赞助"></a> </p>一个模型上下文协议（MCP）服务器，提供对 APIs.guru 目录的访问——这是世界上最大的 OpenAPI 规范存储库，包含来自 600 多个提供商的超过 3,000 个 API 规范。现在支持自定义 OpenAPI 规范导入——无缝集成您自己的 API 并与公共目录一起使用。
目录
致谢
该项目基于 APIs.guru 的出色工作及其全面的 OpenAPI 目录。APIs.guru 项目维护了最大的机器可读 API 定义存储库，并通过其免费 API 服务 https://api.apis.guru/v2 向开发者社区提供了宝贵的资源。
他们致力于创建和维护这个全面的 OpenAPI 规范目录，使得像这样的项目成为可能。我们非常感谢他们对开源生态系统做出的贡献以及他们致力于让 API 发现对所有人开放。
源数据在 Creative Commons Zero v1.0 Universal 许可证下提供，反映了他们慷慨的知识共享方法。
功能
| 功能 | 描述 |
|---|---|
| 零配置 | 使用合理的默认设置即可开箱即用 |
| 全面的 API 覆盖 | 访问来自 APIs.guru 的 3,000 多个 API 规范 |
| 自定义 OpenAPI 导入 | 零接触集成导入和管理您自己的 API |
| 上下文感知安全 | 智能的安全扫描，具有合法模式识别 |
| 上下文优化 | 渐进式发现减少上下文使用约 95% |
| 智能搜索结果 | 相关性排名 + 最新版本优先 + 提供商优先级 |
| 智能缓存 | 带有管理工具的 24 小时 TTL 持久缓存 |
| 丰富的工具集 | 22 个专门用于 API 发现和端点分析的工具 |
| 斜杠命令 | 所有提示自动暴露为 Claude Code 斜杠命令 |
| 分页资源 | 支持分页的高效数据访问 |
| NPX 就绪 | 单一命令安装和运行 |
| 类型安全 | 使用 TypeScript 构建以确保可靠性 |
🎯 上下文优化及渐进式发现
此 MCP 服务器实现了渐进式发现方法，该方法显著减少了上下文使用，允许您在达到上下文限制之前探索更多 API。
问题
传统的 API 发现工具返回大量数据，这些数据会迅速饱和 LLM 上下文窗口。例如，搜索“社交媒体 API”并获取它们的完整规范可能会在提供有用答案之前耗尽您的上下文。
我们的解决方案：95% 上下文减少
我们已将发现工作流程重新设计为三个高效的阶段：
🔍 第一阶段：初步发现
search_apis返回最小的、分页的结果（每页 20 条）openapi://apis/summary提供目录概览- 快速浏览 1,000 多个 API 而不会出现上下文过载
📋 第二阶段：基本评估
get_api_summary提供没有端点的基本详细信息- 认证、文档、类别和提供商信息
- 高效比较多个 API
⚙️ 第三阶段：详细分析
get_endpoints显示分页的端点列表（每页 30 条）get_endpoint_details获取特定端点的信息get_endpoint_schema和get_endpoint_examples用于实现
智能提示引导您
所有 22 个内置提示自动使用这种渐进式方法：
api_discovery引导您进行高效的 API 探索api_integration_guide使用渐进式端点发现- 每个提示防止上下文饱和同时最大化有用信息
🚀 快速开始
本地开发环境设置
- 克隆并构建：
git clone https://github.com/rawveg/openapi-directory-mcp.git
cd openapi-directory-mcp
npm install
npm run build
- 本地测试：
node dist/index.js
本地开发配置
Claude Desktop (本地)
{
"mcpServers": {
"openapi-directory": {
"command": "node",
"args": ["/path/to/openapi-directory-mcp/dist/index.js"],
"cwd": "/path/to/openapi-directory-mcp"
}
}
}
Claude Code (本地)
claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js
Cursor (本地)
{
"mcpServers": {
"openapi-directory": {
"command": "node",
"args": ["/path/to/openapi-directory-mcp/dist/index.js"],
"cwd": "/path/to/openapi-directory-mcp"
}
}
}
Windsurf (本地)
{
"servers": {
"openapi-directory": {
"command": "node /path/to/openapi-directory-mcp/dist/index.js"
}
}
}
NPX 安装
npx -y openapi-directory-mcp
Claude Desktop (NPX)
{
"mcpServers": {
"openapi-directory": {
"command": "npx",
"args": ["-y", "openapi-directory-mcp"]
}
}
}
Claude Code (NPX)
claude mcp add openapi-directory -- npx -y openapi-directory-mcp
Claude Code MCP 管理：
# 列出所有配置的 MCP 服务器
claude mcp list
# 获取有关服务器的详细信息
claude mcp get openapi-directory
# 移除服务器
claude mcp remove openapi-directory
# 在聊天中检查服务器状态
/mcp
🎯 Claude Code 斜杠命令：所有 22 个 MCP 提示都自动作为斜杠命令可用！
核心发现与分析：
/openapi-directory:api_discovery- 发现特定用途的 API/openapi-directory:api_integration_guide- 生成集成指南/openapi-directory:api_comparison- 比较多个 API/openapi-directory:authentication_guide- 了解 API 认证/openapi-directory:code_generation- 生成代码示例/openapi-directory:api_documentation_analysis- 分析 API 能力/openapi-directory:troubleshooting_guide- 调试集成问题
面向行动的代码生成：
/openapi-directory:retrofit_api_client- 使用类型化的 API 客户端重构现有代码库/openapi-directory:api_type_generator- 根据规范生成 TypeScript/语言类型/openapi-directory:api_test_suite- 创建全面的测试套件/openapi-directory:api_error_handler- 构建带有重试逻辑的强大错误处理程序/openapi-directory:api_migration_assistant- 在不同 API 版本/提供商之间迁移/openapi-directory:api_sdk_wrapper- 生成自定义 SDK 包装器/openapi-directory:api_webhook_scaffold- 构建 webhook 处理程序/openapi-directory:api_rate_limiter- 实现智能速率限制/openapi-directory:api_graphql_wrapper- 为 REST API 创建 GraphQL 包装器/openapi-directory:api_batch_processor- 构建批处理系统
认证聚焦：
/openapi-directory:api_auth_implementation- 完整的认证实现/openapi-directory:api_auth_flow_generator- 生成 OAuth2/OIDC 流程/openapi-directory:api_auth_middleware- 为框架构建认证中间件/openapi-directory:api_auth_test_harness- 创建认证测试工具/openapi-directory:api_auth_debugger- 调试认证问题
Cursor (NPX)
{
"mcpServers": {
"openapi-directory": {
"command": "npx",
"args": ["-y", "openapi-directory-mcp"]
}
}
}
Windsurf (NPX)
{
"servers": {
"openapi-directory": {
"command": "npx -y openapi-directory-mcp"
}
}
}
📁 自定义 OpenAPI 规范
导入并管理您自己的 OpenAPI 规范，与公共 API 目录一起使用。自定义规范被视为第一公民，并在所有工具和提示中完全集成。
✨ 关键特性
- 🎯 无摩擦导入：单命令从文件或 URL 导入
- 🔒 上下文感知安全扫描：通过合法模式识别智能检测安全问题
- ⚡ 零接触集成：与所有 22 个现有工具和提示无缝协作
- 🏆 自定义始终优先：自定义规范在任何冲突中优先
- 📊 交互式管理：完整的 CLI 用于列出、删除和维护规范
- 🔄 YAML/JSON 支持：自动转换和验证
- 📂 层次结构存储：组织在
custom/name/version结构中
🚀 快速开始
导入自定义规范
# 交互式引导导入（推荐首次使用）
openapi-directory-mcp --import
# 从本地文件直接导入
openapi-directory-mcp --import ./my-api.yaml --name my-api --version v1
# 从 URL 导入并进行严格的安全部署
openapi-directory-mcp --import https://api.example.com/openapi.json --name example-api --version v2 --strict-security
# 使用自定义安全部署选项导入
openapi-directory-mcp --import ./internal-api.yaml --name internal-api --version v1 --skip-security
管理自定义规范
# 列出所有导入的自定义规范
openapi-directory-mcp --list-custom
# 删除自定义规范
openapi-directory-mcp --remove-custom my-api:v1
# 对现有规范重新执行安全扫描
openapi-directory-mcp --rescan-security my-api:v1
# 验证所有自定义规范的完整性
openapi-directory-mcp --validate-integrity
# 修复任何完整性问题
openapi-directory-mcp --repair-integrity
🛡️ 安全扫描
内置的上下文感知安全扫描程序能够区分合法代码模式和实际安全风险：
安全规则
| 规则 | 严重程度 | 描述 |
|---|---|---|
| 代码注入 | 严重 | 检测 eval()、exec()、脚本注入模式 |
| 路径遍历 | 高 | 识别 ../、目录遍历尝试 |
| SQL 注入 | 高 | 查找 SQL 注入模式和关键字 |
| XSS 模式 | 高 | 检测跨站脚本漏洞 |
| 硬编码的秘密 | 中 | 识别 API 密钥、令牌、密码 |
| 不安全的 URL | 中 | 标记可疑的域和协议 |
| 命令执行 | 严重 | 检测系统命令执行模式 |
上下文感知智能
扫描程序理解示例中的合法模式：
# ✅ 这是安全的 - 扫描程序识别这是一个示例
paths:
/logs/analyze:
post:
examples:
datadog_query:
value:
query: "eval(sum:system.cpu.usage{*})" # Datadog 查询语法
安全模式
- 正常（默认）：扫描并报告问题，允许导入
- 严格：如果发现任何高/严重问题，则阻止导入
- 跳过：完全绕过安全扫描
📂 存储架构
自定义规范存储在与 API 目录格式匹配的层次结构中：
~/.cache/openapi-directory-mcp/custom-specs/
├── manifest.json # 所有自定义规范的主索引
└── custom/ # 所有自定义规范使用 "custom" 提供者
├── my-api/
│ ├── v1.json # 规范化的 OpenAPI 规范
│ └── v2.json
├── internal-api/
│ └── v1.json
└── third-party-api/
└── v1.json
🔄 三源架构
MCP 服务器现在作为一个三源系统运行：
graph TD
A[MCP 客户端请求] --> B[三源 API 客户端]
B --> C[自定义规范 - 最高优先级]
B --> D[次要 API - 中等优先级]
B --> E[APIs.guru - 基础优先级]
C --> F{在自定义中找到？}
F -->|是| G[返回自定义结果]
F -->|否| H{在次要中找到？}
H -->|是| I[返回次要结果]
H -->|否| J[返回主要结果]
优先级规则：自定义 > 次要 > 主要（自定义始终优先）
🔧 CLI 参考
导入命令
--import [PATH/URL] # 导入规范（如果没有提供路径则交互式）
--name NAME # 为导入的规范指定名称
--version VERSION # 为导入的规范指定版本
--skip-security # 导入期间跳过安全扫描
--strict-security # 导入时在任何中等及以上安全问题上阻止
管理命令
--list-custom # 列出所有导入的自定义规范及其详细信息
--remove-custom ID # 删除自定义规范（格式：name:version）
--rescan-security ID # 对现有规范重新执行安全扫描
--validate-integrity # 检查自定义规范存储的完整性
--repair-integrity # 自动修复完整性问题
通用命令
--help, -h # 显示包含所有命令的帮助消息
💡 使用示例
交互式导入工作流
$ openapi-directory-mcp --import
📋 自定义 OpenAPI 规范导入向导
==================================================
📂 输入您的 OpenAPI 规范的路径或 URL：./company-api.yaml
🔍 验证规范...
✅ 检测到有效的 OpenAPI 规范
📝 为此 API 输入名称：company-api
🏷️ 输入版本标识符：v1.2.0
🔒 安全扫描？（严格/正常/跳过）[正常]：正常
📦 准备导入：
源：./company-api.yaml
名称：company-api
版本：v1.2.0
安全：正常
继续导入？(Y/n)：y
📥 正在从：./company-api.yaml 导入 OpenAPI 规范
📝 名称：company-api，版本：v1.2.0
🔍 处理和验证规范...
🔒 安全扫描完成：
✅ 未发现安全问题
💾 存储规范...
✅ 成功导入自定义规范：custom:company-api:v1.2.0
直接导入示例
# 导入内部 API 并禁用安全扫描
openapi-directory-mcp --import ./internal-api.yaml --name internal --version v1 --skip-security
# 导入公共 API 并要求