OpenAPI Directory MCP Server：为AI编码助手构建渐进式API发现与集成平台

1. 项目概述一个为AI编码助手打造的OpenAPI“超级目录”如果你和我一样日常重度依赖Claude Code、Cursor或者Windsurf这类AI编码助手那你肯定遇到过这个痛点想让它帮你调用某个外部API比如发个邮件、查个天气或者处理个支付结果它要么不知道这个API的存在要么对API的细节一问三不知。你不得不手动去翻找官方文档复制粘贴接口定义整个过程繁琐又割裂。OpenAPI Directory MCP Server就是为了解决这个“最后一公里”问题而生的。简单来说它是一个模型上下文协议MCP服务器为你的AI助手装上了一本全球API的“黄页”和“说明书”。它接入了APIs.guru这个目前全球最大的OpenAPI规范仓库里面包含了来自600多家服务商的超过3000个API的机器可读定义。从Stripe、GitHub到Twilio、Spotify主流的、小众的API基本都涵盖在内。但这还不是全部。这个项目的杀手锏在于它的**“渐进式发现”** 工作流和**“自定义API导入”** 功能。前者解决了LLM上下文窗口有限无法一次性加载海量API数据的难题后者则让你能把自己公司内部、或者正在开发的私有API规范无缝集成进去让AI助手像了解公开API一样了解你的私有接口。想象一下这个场景你在Claude Code里直接输入/openapi-directory:api_discovery然后告诉它“我想找一个能发邮件、有免费额度、并且文档友好的API”。AI助手会通过这个MCP服务器智能地搜索、筛选、并分步为你呈现结果最终生成调用代码。整个过程你不需要离开编辑器也不需要手动拼接任何URL或参数。2. 核心设计思路为什么是“渐进式发现”与“三重数据源”2.1 直面LLM的上下文瓶颈传统的API目录工具思路很简单给你一个巨大的JSON列表里面包含所有API的所有信息。这在网页上浏览没问题但一旦塞进AI助手的上下文立刻就会引发“上下文灾难”。一个完整的OpenAPI规范动辄几MB哪怕只是元数据列表几千个API的信息也足以瞬间挤占宝贵的Token导致AI无法处理你后续的真正问题。这个项目的设计者显然深谙此道。他们没有选择“暴力全量”的路线而是设计了一套精密的渐进式发现Progressive Discovery流程。这套流程将探索过程分解为三个资源消耗逐级递增但目标性越来越强的阶段 第一阶段轻量级搜索与浏览。使用search_apis工具或openapi://apis/page/N资源每次只获取20-50个API的最简信息如名称、提供商、简短描述。这就像在图书馆的电子目录里输入关键词先看看有哪些相关的书而不需要把每本书都搬下来。 第二阶段基础评估。对第一阶段筛选出的几个候选API使用get_api_summary获取其摘要信息。这包括认证方式、官方文档链接、所属分类等关键决策信息但仍然不包含具体的端点Endpoint列表。这相当于把几本候选书的简介和目录页翻给你看。⚙️ 第三阶段深度分析。只有当你确定了要使用哪个API后才通过get_endpoints、get_endpoint_details等工具按需、分页地获取具体的端点详情、请求响应模式和示例代码。这才相当于翻开你选定的那本书仔细阅读你需要的那几个章节。据项目文档称这种策略能将上下文使用量减少约95%。我实际测试下来在探索一个包含数十个相关API的领域时AI助手的响应速度和连贯性确实有质的提升不会再因为“吃得太撑”而“胡言乱语”。2.2 自定义API作为一等公民另一个极具前瞻性的设计是三重数据源架构并且确立了“自定义优先”的原则。系统按以下优先级查询数据自定义规范Custom Specs用户自己导入的私有或第三方API。次要源Secondary APIs项目可能配置的其他公共目录源。主要源Primary APIs默认的APIs.guru公共目录。这意味着如果你导入了自己公司的internal-payment-api那么在任何搜索和查询中它都会优先于公共的Stripe或PayPal API出现。这种设计完美契合了企业开发场景既能让AI助手利用庞大的公共API知识库又能确保其首要理解和操作的是内部系统接口避免了信息混淆和安全隐患。实操心得这个“自定义优先”的设定非常实用。我们在内部推广时首先就把所有微服务的OpenAPI规范都导入了进去。当开发者在AI助手中询问“如何调用用户服务”时AI会直接引用我们内部的v1.2版规范来生成代码而不是去搜索一个毫不相干的公共API极大提升了准确性和效率。3. 从零开始部署与配置详解3.1 两种核心安装方式项目提供了两种主流的安装方式适用于不同场景方式一NPX直接运行推荐用于快速体验这是最简单快捷的方式无需克隆代码或构建。它直接从npm注册表运行最新版本的服务器。# 一行命令启动服务器 npx -y openapi-directory-mcp-y参数会自动对任何提示回答“是”实现非交互式运行。启动后服务器会在后台运行等待MCP客户端连接。方式二本地开发模式适合定制与二次开发如果你需要修改代码、添加功能或者希望固定在某个版本可以选择本地安装。# 1. 克隆仓库 git clone https://github.com/rawveg/openapi-directory-mcp.git cd openapi-directory-mcp # 2. 安装依赖并构建 npm install npm run build # 这会编译TypeScript代码到dist目录 # 3. 运行编译后的服务器 node dist/index.js3.2 配置你的AI编码助手服务器运行起来后需要告诉你的AI助手去哪里找到它。以下是主流工具的配置方法请务必将/path/to/替换为你项目的实际绝对路径。Claude Desktop (本地模式)编辑Claude Desktop的MCP配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json或%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { openapi-directory: { command: node, args: [/absolute/path/to/openapi-directory-mcp/dist/index.js], cwd: /absolute/path/to/openapi-directory-mcp } } }cwd参数设置了工作目录对于资源加载很重要。Claude Code (命令行配置)Claude Code通过命令行管理MCP服务器更为灵活# 添加服务器本地模式 claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js # 添加服务器NPX模式 claude mcp add openapi-directory -- npx -y openapi-directory-mcp # 查看已配置的服务器列表 claude mcp list # 获取某个服务器的详细信息 claude mcp get openapi-directory # 移除服务器 claude mcp remove openapi-directory在Claude Code聊天界面中你也可以输入/mcp来快速查看所有已连接服务器的状态。Cursor 编辑器在Cursor中进入设置找到MCP Servers部分进行配置格式与Claude Desktop类似{ mcpServers: { openapi-directory: { command: npx, args: [-y, openapi-directory-mcp] } } }Windsurf 编辑器Windsurf的配置也大同小异{ servers: { openapi-directory: { command: npx -y openapi-directory-mcp } } }注意事项配置完成后通常需要重启你的AI助手应用如Claude Desktop、Cursor才能使新的MCP服务器配置生效。之后你就能在助手界面中直接使用相关的工具和提示词了。3.3 环境变量高级配置虽然开箱即用但项目也支持通过环境变量进行深度定制满足高级需求# 调整缓存生存时间TTL默认为24小时86400000毫秒 # 如果你的API目录更新频繁可以适当调低 export CACHE_TTL3600000 # 1小时 # 禁用缓存仅用于调试会严重影响性能 export DISABLE_CACHEfalse # 自定义缓存目录默认在用户缓存文件夹下 export OPENAPI_DIRECTORY_CACHE_DIR~/.my-custom-cache/openapi-mcp # 指定主要和次要API目录的源地址高级用户使用 export PRIMARY_API_BASE_URLhttps://api.apis.guru/v2 export SECONDARY_API_BASE_URLhttps://your-custom-directory.com4. 核心功能实战自定义API导入与管理这是我认为该项目最亮眼的功能。它让你私有的API规范与庞大的公共目录平起平坐甚至拥有更高优先级。4.1 导入自定义API规范导入过程设计得非常人性化支持交互式向导和直接命令两种方式。交互式导入推荐初学者运行以下命令会启动一个步步引导的向导openapi-directory-mcp --import向导会依次询问OpenAPI规范路径或URL可以是本地的./api.yaml或./api.json文件也可以是远程的https://api.example.com/openapi.json。API名称给你要导入的API起个名字如company-user-service。版本标识遵循语义化版本如v1.0.0、v2.1.0-beta。安全扫描模式选择normal默认扫描并报告、strict发现中高危问题则阻止导入或skip跳过扫描。直接命令导入适合自动化脚本# 从本地文件导入并指定名称和版本 openapi-directory-mcp --import ./internal-api.yaml --name internal-api --version v1.2.0 # 从URL导入并启用严格安全扫描 openapi-directory-mcp --import https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml --name petstore --version v3.0 --strict-security # 跳过安全扫描仅用于完全信任的内部规范 openapi-directory-mcp --import ./trusted-spec.json --name legacy-system --version v1 --skip-security4.2 智能安全扫描解析安全扫描不是简单的关键字匹配而是上下文感知Context-Aware的。它能区分真正的安全威胁和API示例中出现的合法模式。例如一个监控API的示例中可能包含eval(sum:system.cpu.usage{*})这样的字符串。笨拙的扫描器会将其标记为危险的“代码注入”。但本项目的扫描器能识别到这段内容位于examples字段下是Datadog查询语句的合法示例从而不会误报。它主要检查以下几类问题关键级代码注入eval,exec、命令执行、路径遍历../。高危级SQL注入模式、XSS跨站脚本模式。中危级硬编码的密钥、令牌、密码不安全的URL如http://内网地址。避坑指南对于从互联网获取的第三方API规范强烈建议使用--strict-security模式。我曾导入一个开源项目的API文档扫描器立刻提示其中包含一个硬编码的测试用API Key。这虽然可能只是文档示例但若被AI助手误用也可能导致信息泄露。严格模式能帮你把好第一道关。4.3 管理已导入的规范项目提供了完整的CLI工具集来管理你的自定义API库。列出所有自定义规范openapi-directory-mcp --list-custom这个命令会以清晰的表格形式列出所有导入的规范包括名称、版本、描述、导入时间、文件大小和安全状态一目了然。移除不再需要的规范# 移除特定版本 openapi-directory-mcp --remove-custom my-api:v1.0.0 # 如果同一个API有多个版本需要分别移除 openapi-directory-mcp --remove-custom my-api:v1.0.0 openapi-directory-mcp --remove-custom my-api:v2.0.0维护与修复# 重新扫描某个已有规范的安全问题比如在更新规范后 openapi-directory-mcp --rescan-security my-api:v2.1.0 # 验证存储完整性检查是否有损坏或孤立的文件 openapi-directory-mcp --validate-integrity # 自动修复发现的完整性问题 openapi-directory-mcp --repair-integrity4.4 无缝集成与缓存魔法导入自定义API后最令人称道的是零配置无缝集成。你不需要任何额外操作所有22个工具和提示词都能自动识别并优先使用你的自定义API。其背后的技术关键在于一个巧妙的标志文件Flag File缓存失效机制当你通过CLI导入或删除一个自定义规范时系统会在缓存目录创建一个.invalidate标志文件。正在运行的MCP服务器会在每次处理请求前检查这个标志文件。如果标志存在服务器会清空相关缓存然后删除该标志。结果你的更改在几秒内就能在AI助手中生效无需重启MCP服务器或AI助手应用。这意味着你可以一边在终端里导入新的API规范一边在Claude Code里继续聊天很快AI就能基于新API给你建议了。这种体验非常流畅。5. 工具与资源全解析如何高效“驾驭”API宇宙MCP服务器通过“工具Tools”和“资源Resources”两种方式向AI助手暴露能力。理解它们的用途和最佳组合是高效使用的关键。5.1 核心发现工具像专家一样搜索search_apis- 你的智能搜索起点这是最常用、也最强大的工具。它不仅仅是简单的关键字匹配而是实现了智能排序自定义API优先如果你导入了相关的自定义API它们会排在最前面。相关性排名在公共API中会综合标题、描述、标签进行相关性打分。版本优先对于同一API的多个版本默认返回最新的稳定版。// 示例搜索支付相关API只取第一页最多20条结果 const results await search_apis({ query: payment processing, page: 1, limit: 20 });返回的结果是轻量级的只包含API ID、名称、提供者、简短描述和版本完美契合“渐进式发现”的第一阶段。get_api_summary- 决策的关键信息当你从搜索结果中圈定几个候选API比如Stripe和PayPal后用这个工具获取它们的“简历”。const stripeSummary await get_api_summary({ api_id: stripe.com });返回的信息包括认证方式OAuth2, API Key等、官方文档链接、所属分类金融、企业等、服务条款链接以及提供者信息。这些是决定“用哪个API”的核心依据但依然不包含会撑爆上下文的端点列表。5.2 深度分析工具按需获取精准打击只有当你决定使用某个API后才进入第三阶段使用以下工具进行深度挖掘。这些工具都支持分页避免一次性加载过多数据。get_endpoints- 浏览API的“菜单”获取指定API的所有端点列表分页返回默认每页30条。const endpointsPage1 await get_endpoints({ api_id: stripe.com, page: 1, limit: 30 });你可以看到端点的路径如/v1/charges和方法GET, POST等从而快速定位你需要的功能。get_endpoint_details- 查看“菜品”详情锁定某个端点后用这个工具获取其完整详情。const chargeDetails await get_endpoint_details({ api_id: stripe.com, method: POST, path: /v1/charges });返回的信息非常详尽完整的参数描述查询参数、请求头、路径参数、请求体、可能的响应状态码、安全要求需要哪些权限等。这是编写调用代码的蓝图。get_endpoint_schema与get_endpoint_examples- 获取“食谱”与“样例”这两个工具是编码的加速器。get_endpoint_schema给出请求和响应的JSON Schema让你明确数据结构get_endpoint_examples则提供实际的请求/响应示例让你可以快速模仿。实操心得不要一上来就尝试获取整个API的所有端点。我见过有新手直接对GitHub API调用get_endpoints结果返回了数百个端点瞬间耗尽了上下文。正确的做法一定是先search_apis再get_api_summary比较最后针对选定的1-2个核心端点使用get_endpoint_details和get_endpoint_examples。这才是“渐进式发现”的精髓。5.3 实用工具与资源辅助工具get_popular_apis/get_recently_updated帮你发现热门或最新的API寻找灵感。analyze_api_categories分析整个目录的API分类构成了解某个领域如“机器学习”有多少可用资源。cache_stats/clear_cache管理本地缓存。如果你发现API信息过时了可以清空缓存强制刷新。高效资源Resources资源是另一种数据暴露方式更适合AI助手以“阅读文档”的形式获取信息。openapi://apis/summary强烈推荐作为起点。它返回目录的概览包括API总数、热门API列表等信息量适中。openapi://apis/page/1...openapi://apis/page/20分页浏览所有API的最简信息每页50个。这是替代已被移除的、会返回海量数据的openapi://list资源的安全方式。6. 提示词Prompts的威力从探索到实现的自动化工作流对于Claude Code用户来说提示词以/开头的命令是最高效的交互方式。该项目将22个工具封装成了智能提示词每个都内嵌了“渐进式发现”的最佳实践。6.1 核心发现与分析提示词/openapi-directory:api_discovery- 万能探索助手这是我最常用的提示词。你只需要描述你的用例和需求。/openapi-directory:api_discovery然后在后续对话中提供参数例如use_case: 发送交易通知邮件 requirements: 需要有免费额度集成要简单支持PythonAI助手会自动执行“搜索 - 评估 - 深度分析”的流程最终可能向你推荐SendGrid或Mailgun的API并给出选择理由和初步的集成思路。/openapi-directory:api_integration_guide- 手把手集成教程当你确定了使用哪个API后这个提示词能生成一份完整的集成指南。/openapi-directory:api_integration_guide参数示例api_name: stripe.com programming_language: Node.js use_case: 在网站上接受一次性付款它会生成从安装SDK、配置认证、到编写核心业务代码和错误处理的一站式指南。/openapi-directory:api_comparison- 理性决策支持在几个相似的API间犹豫不决用它。/openapi-directory:api_comparison参数示例api_list: [stripe.com, paypal.com, squareup.com] criteria: 费用结构开发者体验支付方式支持文档质量它会生成一个详细的对比表格帮你从多个维度做出客观选择。6.2 面向行动的代码生成提示词这类提示词直接产出可用的代码或工程化解决方案价值极高。/openapi-directory:retrofit_api_client- 旧代码现代化如果你有一堆直接使用fetch或axios调用API的散落代码这个提示词能帮你生成一个类型安全、可复用的API客户端。/openapi-directory:retrofit_api_client参数示例api_id: github.com existing_code_snippet: 粘贴你现有的调用GitHub API的代码 target_language: TypeScript/openapi-directory:api_test_suite- 构建测试保障为指定的API端点生成完整的单元测试和集成测试套件。/openapi-directory:api_test_suite参数示例api_id: slack.com endpoints: [/api/chat.postMessage, /api/users.info] testing_framework: Jest/openapi-directory:api_error_handler- 打造鲁棒性生成包含重试逻辑、断路器模式、降级策略的健壮错误处理模块。/openapi-directory:api_error_handler参数示例api_id: twilio.com failure_scenarios: [网络超时, 速率限制, 认证失效] programming_language: Python6.3 认证专项提示词API集成中认证往往是最复杂的一环。这套专项提示词能极大简化这个过程。/openapi-directory:api_auth_implementation- 全栈认证实现根据OpenAPI规范中定义的安全方案生成从前端到后端的完整认证代码。/openapi-directory:api_auth_implementation参数示例api_id: spotify.com # 使用OAuth 2.0 application_type: Web Server App/openapi-directory:api_auth_flow_generator- OAuth流程生成专门生成OAuth 2.0或OIDC的授权码流程、PKCE流程等。/openapi-directory:api_auth_flow_generator参数示例api_id: googleapis.com:gmail flow_type: Authorization Code with PKCE/openapi-directory:api_auth_debugger- 认证问题排查当认证失败时提供一套诊断步骤和工具代码帮你定位是配置错误、令牌过期还是范围不足。/openapi-directory:api_auth_debugger参数示例api_id: microsoft.com:graph error_description: 获取用户信息时返回401错误个人体会这些提示词的价值在于它们封装了最佳实践。比如api_error_handler生成的代码通常会包含指数退避重试和简单的熔断器这些都是我在生产环境中踩过坑后才总结出来的模式。现在AI能直接给出一个不错的起点我只需要根据具体业务微调即可节省了大量设计和编码时间。7. 性能、架构与最佳实践7.1 性能考量与缓存策略项目默认开启了24小时TTL的持久化缓存这对性能至关重要。APIs.guru的目录数据量巨大每次请求都实时拉取是不现实的。缓存机制保证了首次加载后的后续操作极其迅速。缓存存储在~/.cache/openapi-directory-mcp/或你自定义的目录下结构清晰。你可以通过cache_stats工具查看缓存命中率和大小。如果你怀疑数据过时比如某个API刚刚发布了新版本可以使用clear_cache工具强制刷新。缓存失效的精细控制clear_cache_key只清除某个特定API的缓存比如clear_cache_key(stripe.com)这样不会影响其他API的缓存。自定义API的导入/删除会自动触发相关缓存失效如前所述。7.2 项目架构浅析虽然作为用户无需深究但了解其架构有助于理解其稳定性和扩展性。从代码和文档看它是一个典型的TypeScript构建的Node.js MCP服务器。数据层通过三重数据源客户端统一代理对自定义目录、次要源和主要源APIs.guru的请求。自定义API的存储采用了与公共目录类似的层级结构 (custom/{name}/{version}.json)保证了处理逻辑的一致性。业务逻辑层实现了所有MCP工具和资源的处理函数。核心是“渐进式发现”的逻辑编排确保每个工具都按最优路径获取数据。接口层遵循Model Context Protocol标准通过stdin/stdout与AI助手客户端如Claude Desktop进行JSON-RPC通信。工具层提供了丰富的CLI命令用于管理自定义API和缓存这些CLI与运行的MCP服务器通过文件系统标志进行通信。这种分层架构使得代码清晰也便于社区贡献新的工具或数据源。7.3 避坑指南与常见问题问题1AI助手找不到或无法连接MCP服务器。检查首先确保服务器进程正在运行执行npx -y openapi-directory-mcp后应有持续输出或无错误退出。然后仔细核对配置文件中路径的拼写和绝对路径。最后重启你的AI助手应用。问题2搜索返回结果很少或没有自定义API。检查确认自定义API已成功导入使用--list-custom。检查搜索关键词是否匹配。记住自定义API在搜索中优先级最高如果没出现可能是名称或描述不匹配。问题3工具调用超时或返回错误。检查可能是网络问题导致无法访问APIs.guru。可以尝试运行clear_cache后重试。如果问题持续检查是否能直接访问https://api.apis.guru/v2/list.json。问题4导入自定义API时安全扫描报错。决策仔细阅读扫描报告。如果确认是误报如示例代码中的字符串可以使用--skip-security参数跳过。如果是真实的硬编码密钥务必在规范中移除或替换为占位符如{{API_KEY}}。最佳实践总结始于探索对新需求先用/openapi-directory:api_discovery。精于评估用get_api_summary和api_comparison做决策。终于细节只为你最终选定的1-2个端点获取完整详情和示例。善用提示词直接使用内建的提示词它们封装了最优工作流。管理好自定义库定期用--list-custom和--validate-integrity维护你的私有API库。信任缓存但知道如何更新在集成新发布的API版本时主动使用clear_cache_key。这个项目本质上是一个“知识增强”工具。它没有取代开发者而是将查找、理解、整合API文档这类繁琐且耗时的“上下文切换”工作极大地简化了让开发者能更专注于业务逻辑和创新本身。无论是探索未知的API领域还是将内部系统快速赋能给AI助手它都提供了一个极其优雅和高效的解决方案。