OpenAPI Directory MCP Server

一个模型上下文协议（MCP）服务器，提供对APIs.guru目录的访问，该目录是世界上最大的OpenAPI规范库，拥有来自600多家供应商的3000多个API规范。 现在使用自定义OpenAPI规范导入 -将您自己的API与公共目录无缝集成。

目录

• 致谢
• 特性
• 上下文优化和渐进式发现
• 快速开始
• 自定义OpenAPI规范
• 可用工具
• 可用资源
• 可用提示
• 配置
• 示例用法
• 建筑
• 演出
• 发展
• 贡献
• 许可证
• 支持这个项目
• 支持
• 学分

致谢

该项目建立在以下杰出工作的基础上 APIs.guru 及其全面 OpenAPI目录。APIs.guru项目维护了最大的机器可读API定义存储库，通过其位于https://api.apis.guru/v2.

他们致力于创建和维护这个全面的OpenAPI规范目录，这使得这样的项目成为可能。我们非常感谢他们对开源生态系统的贡献，以及他们致力于让每个人都能访问API发现。

源数据是根据知识共享零v1.0通用许可证提供的，反映了他们对知识共享的慷慨态度。

特性

🎯 上下文优化和渐进式发现

此MCP服务器实现了 渐进式发现方法 这大大减少了上下文的使用，允许您在达到上下文限制之前探索更多的API。

问题

传统的API发现工具会返回大量数据，使LLM上下文窗口迅速饱和。例如，搜索“社交媒体API”并获取其完整规范可能会在提供有用答案之前耗尽您的上下文。

我们的解决方案：95%上下文缩减

我们将发现工作流程重新设计为三个高效阶段：

🔍 第一阶段：初步发现

• search_apis 返回最小的分页结果（每页20个）
• openapi://apis/summary 提供目录概述
• 快速浏览1000多个API，无需上下文重载

📋 第二阶段：基本评估

• get_api_summary 提供没有端点的基本细节
• 身份验证、文档、类别和提供商信息
• 高效比较多个API

⚙️ 第三阶段：详细分析

• get_endpoints 显示分页端点列表（每页30个）
• get_endpoint_details 获取特定端点信息
• get_endpoint_schema 和 get_endpoint_examples 用于实施

智能提示指导您

所有22个内置提示都自动使用这种渐进式方法：

• api_discovery 指导您进行高效的API勘探
• api_integration_guide 使用渐进式端点发现
• 每个提示都可以防止上下文饱和，同时最大限度地利用有用信息

🚀 快速开始

地方发展设置

1. 克隆和构建:```bash
   git clone https://github.com/rawveg/openapi-directory-mcp.git
   cd openapi-directory-mcp
   npm install
   npm run build

2. **本地测试**:```bash
node dist/index.js

本地开发配置

克劳德桌面（本地）```json

{
"mcpServers": {
"openapi-directory": {
"command": "node",
"args": ["/path/to/openapi-directory-mcp/dist/index.js"],
"cwd": "/path/to/openapi-directory-mcp"
}
}
}

#### 克劳德代码（本地）```bash
claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js

光标（本地）```json

{
"mcpServers": {
"openapi-directory": {
"command": "node",
"args": ["/path/to/openapi-directory-mcp/dist/index.js"],
"cwd": "/path/to/openapi-directory-mcp"
}
}
}

#### 风帆（当地）```json
{
"servers": {
"openapi-directory": {
"command": "node /path/to/openapi-directory-mcp/dist/index.js"
}
}
}

NPX安装```bash

npx -y openapi-directory-mcp

#### 克劳德桌面（NPX）```json
{
"mcpServers": {
"openapi-directory": {
"command": "npx",
"args": ["-y", "openapi-directory-mcp"]
}
}
}

克劳德代码（NPX）```bash

claude mcp add openapi-directory -- npx -y openapi-directory-mcp

**克劳德代码MCP管理**:```bash
# List all configured MCP servers
claude mcp list

# Get details about the server
claude mcp get openapi-directory

# Remove the server
claude mcp remove openapi-directory

# Check server status in chat
/mcp

🎯 Claude代码Slash命令：所有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 -调试身份验证问题

光标（NPX）```json

{
"mcpServers": {
"openapi-directory": {
"command": "npx",
"args": ["-y", "openapi-directory-mcp"]
}
}
}

#### 风帆冲浪（NPX）```json
{
"servers": {
"openapi-directory": {
"command": "npx -y openapi-directory-mcp"
}
}
}

📁 自定义OpenAPI规范

在公共API目录中导入并管理您自己的OpenAPI规范。自定义规格被视为 一等公民 与所有工具和提示完全集成。

✨ 主要特点

• 🎯 无摩擦进口：从文件或URL导入单个命令
• 🔒 上下文感知安全扫描：通过合法模式识别智能检测安全问题
• ⚡ 零接触集成：与所有22个现有工具和提示无缝协作
• 🏆 定制总是赢：自定义规格优先于任何冲突
• 📊 互动管理：用于列出、删除和维护规范的完整CLI
• 🔄 YAML/JSON支持：自动转换和验证
• 📂 分级存储：组织于 custom/name/version 结构

🚀 快速开始

导入自定义规格```bash

Interactive guided import (recommended for first time)

openapi-directory-mcp --import

Direct import from local file

openapi-directory-mcp --import ./my-api.yaml --name my-api --version v1

Import from URL with strict security scanning

openapi-directory-mcp --import https://api.example.com/openapi.json --name example-api --version v2 --strict-security

Import with custom security options

openapi-directory-mcp --import ./internal-api.yaml --name internal-api --version v1 --skip-security

#### 管理自定义规格```bash
# List all imported custom specs
openapi-directory-mcp --list-custom

# Remove a custom spec
openapi-directory-mcp --remove-custom my-api:v1

# Re-run security scan on existing spec
openapi-directory-mcp --rescan-security my-api:v1

# Validate integrity of all custom specs
openapi-directory-mcp --validate-integrity

# Repair any integrity issues
openapi-directory-mcp --repair-integrity

🛡️ 安全扫描

内置上下文感知安全扫描程序，了解合法代码模式和实际安全风险之间的区别：

安全规则

情境感知智能

扫描仪理解 示例中的合法模式:```yaml

✅ This is SAFE - Scanner recognizes it's in an example

paths:
/logs/analyze:
post:
examples:
datadog_query:
value:
query: "eval(sum:system.cpu.usage{*})" # Datadog query syntax

#### 安全模式

- **正常** （默认）：扫描和报告问题，允许导入
- **严格**：如果发现任何高/关键问题，则阻止导入
- **跳过**：完全绕过安全扫描

### 📂 存储体系结构

自定义规范存储在与API目录格式匹配的分层结构中：```
~/.cache/openapi-directory-mcp/custom-specs/
├── manifest.json                    # Master index of all custom specs
└── custom/                          # All custom specs use "custom" provider
├── my-api/
│   ├── v1.json                  # Normalized OpenAPI spec
│   └── v2.json
├── internal-api/
│   └── v1.json
└── third-party-api/
└── v1.json

🔄 三源架构

MCP服务器现在作为 三源系统:```mermaid
graph TD
A[MCP Client Request] --> B[Triple-Source API Client]
B --> C[Custom Specs - Highest Priority]
B --> D[Secondary APIs - Medium Priority]
B --> E[APIs.guru - Base Priority]

C --> F{Found in Custom?}
F -->|Yes| G[Return Custom Result]
F -->|No| H{Found in Secondary?}
H -->|Yes| I[Return Secondary Result]
H -->|No| J[Return Primary Result]

**优先级规则**：自定义>次要>主要(**定制总是赢**)

### 🔧 CLI参考

#### 导入命令```bash
--import [PATH/URL]     # Import spec (interactive if no path provided)
--name NAME             # Specify name for the imported spec
--version VERSION       # Specify version for the imported spec
--skip-security         # Skip security scanning during import
--strict-security       # Block import on any medium+ security issues

管理命令```bash

--list-custom # List all imported custom specs with details
--remove-custom ID # Remove a custom spec (format: name:version)
--rescan-security ID # Re-run security scan on existing spec
--validate-integrity # Check integrity of custom spec storage
--repair-integrity # Repair integrity issues automatically

#### 常规命令```bash
--help, -h              # Show help message with all commands

💡 使用示例

交互式导入工作流```bash

$ openapi-directory-mcp --import

📋 Custom OpenAPI Spec Import Wizard

📂 Enter the path or URL to your OpenAPI spec: ./company-api.yaml
🔍 Validating specification...
✅ Valid OpenAPI specification detected
📝 Enter a name for this API: company-api
🏷️ Enter a version identifier: v1.2.0
🔒 Security scanning? (strict/normal/skip) [normal]: normal

📦 Ready to import:
Source: ./company-api.yaml
Name: company-api
Version: v1.2.0
Security: normal

Proceed with import? (Y/n): y

📥 Importing OpenAPI spec from: ./company-api.yaml
📝 Name: company-api, Version: v1.2.0
🔍 Processing and validating specification...
🔒 Security scan completed:
✅ No security issues found
💾 Storing specification...
✅ Successfully imported custom spec: custom:company-api:v1.2.0

#### 直接进口示例```bash
# Import internal API with security scanning disabled
openapi-directory-mcp --import ./internal-api.yaml --name internal --version v1 --skip-security

# Import public API with strict security requirements
openapi-directory-mcp --import https://api.github.com/openapi.json --name github --version v3 --strict-security

# Import development API with normal security scanning
openapi-directory-mcp --import ./dev-api.json --name dev-api --version latest

管理实例```bash

List all custom specifications

$ openapi-directory-mcp --list-custom

📚 Custom OpenAPI Specifications (3)

1. company-api:v1.2.0
   📋 Company Internal API
   📄 Internal API for company services and data access
   📅 Imported: 12/15/2024 | 📊 156KB YAML
   🔒 Security: ✅ 0 issues | 📦 Source: file

2. github:v3
   📋 GitHub REST API
   📄 GitHub's REST API for repository and user management
   📅 Imported: 12/14/2024 | 📊 2.1MB JSON
   🔒 Security: ⚠️ 2 issues | 📦 Source: url

3. dev-api:latest
   📋 Development API
   📄 Development environment API for testing
   📅 Imported: 12/13/2024 | 📊 45KB JSON
   🔒 Security: ✅ 0 issues | 📦 Source: file

💾 Total: 3 specs, 2.3MB

### 🔌 无缝集成

导入后，自定义规格将自动与 **所有现有功能** 通过智能API路由和参数识别：

#### 工具集成```javascript
// All 22 tools work with custom specs automatically with intelligent routing

// Search automatically prioritizes custom specs
const results = await search_apis({ query: "company" });
// Returns: custom:company-api:v1.2.0 first (if matches), then public APIs

// Get details works with automatic parameter recognition
const details = await get_api_summary({ api_id: "custom:company-api:v1.2.0" });

// Endpoint analysis works identically with smart routing
const endpoints = await get_endpoints({ api_id: "custom:company-api:v1.2.0" });

提示集成```bash

All 22 prompts work with custom specs automatically

API discovery finds custom specs first

/openapi-directory:api_discovery

Arguments: { use_case: "internal data access" }

Result: Discovers and recommends custom:company-api:v1.2.0

Integration guides work seamlessly

/openapi-directory:api_integration_guide

Arguments: { api_name: "custom:company-api:v1.2.0", language: "Python" }

Result: Complete integration guide using your custom spec

Code generation uses custom specs

/openapi-directory:code_generation

Arguments: { api_id: "custom:company-api:v1.2.0", endpoint: "/users" }

Result: Generated code for your custom API endpoints

#### 资源整合```javascript
// Resources automatically include custom specs with priority handling

// Providers list dynamically includes "custom" when specs exist
const providers = await readResource("openapi://providers");
// Returns: [..., "custom"] (only when custom specs are imported)

// Paginated APIs automatically prioritize custom specs
const apis = await readResource("openapi://apis/page/1");
// Custom specs appear first, then public APIs

// Summary automatically aggregates custom specs in metrics
const summary = await readResource("openapi://apis/summary");
// Directory counts and popular lists seamlessly include custom specs

🎯 最佳实践

命名约定```bash

Use semantic versioning

--name my-api --version v1.0.0
--name my-api --version v1.1.0-beta

Use descriptive names

--name user-management-api --version v2
--name payment-gateway-api --version production
--name analytics-api --version latest

#### 安全建议```bash
# For production APIs, use strict scanning
--strict-security

# For internal/development APIs, use normal scanning
# (default behavior)

# Only skip security for trusted, internal-only APIs
--skip-security

版本管理```bash

Import new versions as separate entries

openapi-directory-mcp --import ./api-v1.yaml --name my-api --version v1
openapi-directory-mcp --import ./api-v2.yaml --name my-api --version v2

Remove old versions when no longer needed

openapi-directory-mcp --remove-custom my-api:v1

#### 存储维护```bash
# Regular integrity checks
openapi-directory-mcp --validate-integrity

# Automatic repairs when needed
openapi-directory-mcp --repair-integrity

# Clean up unused specs
openapi-directory-mcp --list-custom  # Review list
openapi-directory-mcp --remove-custom old-api:v1

🚨 错误处理

常见进口问题

诚信问题```bash

Check for issues

$ openapi-directory-mcp --validate-integrity
❌ Found 2 integrity issues:
• Missing spec file: custom:old-api:v1
• Orphaned file: custom/unknown-api/v1.json

Repair automatically

$ openapi-directory-mcp --repair-integrity
✅ Repaired 2 issues:
• Removed orphaned manifest entry: custom:old-api:v1
• Cleaned up orphaned file: custom/unknown-api/v1.json

### 🔧 环境配置

自定义规范尊重相同的环境变量：```bash
# Change cache directory for custom specs
export OPENAPI_DIRECTORY_CACHE_DIR=/custom/cache/path

# Custom specs will be stored at:
# /custom/cache/path/custom-specs/

⚡ 自动缓存无效

该系统使用 标志文件方法 为了在CLI操作和正在运行的MCP服务器之间实现无缝缓存同步：

运作原理

1. 导入/删除操作：当您通过CLI导入或删除自定义规范时 .invalidate 标志文件已创建
2. 自动检测：MCP服务器在每次缓存访问时检查此标志
3. 立即失效：如果该标志存在，则清除缓存并删除该标志
4. 无需重新启动：更改立即可见，无需重新启动Claude Desktop或MCP服务器

技术优势

• 跨进程通信：CLI和MCP服务器通过文件系统标志进行通信
• 立即一致性：导入新规范时没有过时的缓存问题
• 性能优化：仅在实际发生更改时无效
• 防弹：适用于所有操作系统和流程架构```bash

This workflow now works seamlessly:

openapi-directory-mcp --import ./new-api.yaml --name new-api --version v1

↑ Creates .invalidate flag

Immediately available in Claude Desktop (no restart needed)

↑ MCP server detects flag, clears cache, removes flag

______________________________________________________________________

## 🛠️ 可用工具

**所有22个工具无缝支持自定义导入的API，无需任何配置。** 自定义API在搜索结果和工具响应中会自动按优先级排列。

### 核心API发现工具（上下文优化）

|工具|说明|
|-----------------------|------------------------------------------------|
| `get_providers` |列出所有API提供程序|
| `get_provider_apis` |获取特定提供商的API|
| `get_provider_services`|为提供商获取服务|
| `get_api` |获取API详细信息|
| `list_all_apis` | ⚠️ **谨慎使用** -返回大量数据|
| `get_metrics` |目录统计|
| `search_apis` | 🎯 **智能搜索**：自定义API优先+相关性排名+最新版本（20/页）|

### 渐进式发现工具（推荐）

|工具|说明|
|---------------------|--------------------------------------------------|
| `get_api_summary` | 📋 **第2阶段** -没有终结点的API基本信息|
| `get_endpoints` | ⚙️ **第三期** -分页端点列表（每页30个）|
| `get_endpoint_details`| ⚙️ **第三期** -详细的端点信息|
| `get_endpoint_schema`| ⚙️ **第三期** -请求/响应模式|
| `get_endpoint_examples`| ⚙️ **第三期** -请求/响应示例|

### 实用工具

|工具|说明|
|---------------------|----------------------------|
| `get_popular_apis` |获取流行的API|
| `get_recently_updated`|获取最近更新的API|
| `get_provider_stats`|提供商统计信息|
| `get_openapi_spec` |获取OpenAPI规范|
| `analyze_api_categories`|分析API类别|

### 缓存管理工具

|工具|说明|
|---------------------|----------------------------|
| `cache_stats` |获取缓存统计信息和使用情况信息|
| `list_cache_keys` |列出所有缓存密钥及其总计数|
| `clear_cache` |清除所有缓存条目|
| `clear_cache_key` |清除特定缓存密钥|
| `cache_info` |获取缓存配置和设置|

______________________________________________________________________

## 📦 可用资源

### 上下文优化资源

|资源|描述|
|---------------------------|--------------------------------------------------|
| `openapi://providers` |完整的提供商列表|
| `openapi://metrics` |目录指标|
| `openapi://apis/summary` | 🎯 **推荐** -使用流行API的目录概述|

### 分页API资源

|资源|描述|
|---------------------------|--------------------------------------------------|
| `openapi://apis/page/1` | 🔍 **第一阶段** -API 1-50，数据量最小|
| `openapi://apis/page/2` | 🔍 **第一阶段** -API 51-100，数据量最小|
| `...` |第1-20页可用（每页50个API）|
| `openapi://apis/page/20` | 🔍 **第一阶段** -API 951-1000，数据量最小|

**备注**：上一篇 `openapi://list` 资源已被删除，因为它超过了大量数据的上下文限制。使用分页 `openapi://apis/page/N` 资源或 `openapi://apis/summary` 相反。

______________________________________________________________________

## 💡 可用提示（上下文优化）

所有提示都会自动使用渐进式发现工作流来防止上下文饱和。

**🎯 Claude代码用户**：以下所有提示都可以作为斜线命令使用！只需键入 `/openapi-directory:` 您将看到所有可用的命令及其描述。

### 核心发现与分析提示

|提示|目的|工作流程|
|------------------------------|----------------------------------------------|-------------------------|
| `api_discovery` | 🎯 **最受欢迎** -发现用例的API |三阶段渐进式发现|
| `api_integration_guide` |API分步集成指南|渐进式端点探索|
| `api_comparison` |比较多个API的功能|高效的API摘要|
| `authentication_guide` |了解API身份验证方法|重点身份验证分析|
| `code_generation` |生成API使用的代码示例|特定于端点的示例|
| `api_documentation_analysis` |分析API功能和限制|渐进式功能映射|
| `troubleshooting_guide` |调试API集成问题|有针对性的问题分析|

### 面向动作的代码生成提示

|提示|目的|用例|
|------------------------------|----------------------------------------------|-------------------------|
| `retrofit_api_client` |使用类型化的API客户端改造现有代码库|使传统集成现代化|
| `api_type_generator` |从OpenAPI规范生成TypeScript/语言类型|类型安全和IDE支持|
| `api_test_suite` |为API集成创建全面的测试套件|质量保证和CI/CD|
| `api_error_handler` |使用重试逻辑构建稳健的错误处理|生产可靠性|
| `api_migration_assistant` |在不同的API版本/提供程序之间迁移| API现代化|
| `api_sdk_wrapper` |围绕API生成自定义SDK包装|开发人员体验|
| `api_webhook_scaffold` |脚手架webhook处理程序和验证|事件驱动架构|
| `api_rate_limiter` |实施智能限速| API额度管理|
| `api_graphql_wrapper` |为REST API创建GraphQL包装器|现代API接口|
| `api_batch_processor` |为API调用构建批处理系统|高批量操作|

### 以身份验证为重点的提示

|提示|目的|身份验证类型|
|------------------------------|----------------------------------------------|-------------------------|
| `api_auth_implementation` |任何API的完整身份验证实现|OAuth2，Bearer，API Key，Basic|
| `api_auth_flow_generator` |生成OAuth2/OIDC授权流|OAuth2、OIDC、PKCE|
| `api_auth_middleware` |为框架构建身份验证中间件| Express、FastAPI、Spring|
| `api_auth_test_harness` |创建身份验证测试和验证工具|单元和集成测试|
| `api_auth_debugger` |调试身份验证问题和流程|令牌检查、流程跟踪|

**💡 专业提示**:

- 从开始 `api_discovery` 对于任何用例-引导您进行有效的探索
- 使用 `retrofit_api_client` 通过适当的API客户端实现现有代码库的现代化
- 尝试 `api_auth_implementation` 用于任何API的完整身份验证解决方案

## 配置

服务器无需配置，但支持通过环境变量进行自定义：```bash
export CACHE_TTL=86400000  # Cache TTL in milliseconds (default: 24 hours)
export DISABLE_CACHE=false  # Disable caching (default: false)
export OPENAPI_DIRECTORY_CACHE_DIR=~/.cache/openapi-directory-mcp  # Cache directory
export PRIMARY_API_BASE_URL=https://api.apis.guru/v2  # Primary API URL
export SECONDARY_API_BASE_URL=https://api.openapidirectory.com  # Secondary API URL

🧑‍💻 示例用法

🎯 渐进式发现工作流（推荐）```javascript

// Phase 1: Initial Discovery (Context-efficient search with relevance ranking)
const searchResults = await search_apis({
query: "payment",
page: 1,
limit: 20
});
// Note: Smart search shows provider APIs first + newest versions first within same relevance!

// Phase 2: Basic Evaluation (Get summaries for promising APIs)
const stripeInfo = await get_api_summary({ api_id: "stripe.com" });
const paypalInfo = await get_api_summary({ api_id: "paypal.com" });

// Phase 3: Detailed Analysis (Only for chosen API)
const endpoints = await get_endpoints({
api_id: "stripe.com",
page: 1,
limit: 30
});

// Get specific endpoint details for implementation
const paymentEndpoint = await get_endpoint_details({
api_id: "stripe.com",
method: "POST",
path: "/v1/charges"
});

// Get schemas and examples for coding
const schemas = await get_endpoint_schema({
api_id: "stripe.com",
method: "POST",
path: "/v1/charges"
});

const examples = await get_endpoint_examples({
api_id: "stripe.com",
method: "POST",
path: "/v1/charges"
});

### 📋 高效的资源访问```javascript
// Get directory overview (recommended starting point)
const summary = await readResource("openapi://apis/summary");

// Browse APIs in pages (50 per page)
const page1 = await readResource("openapi://apis/page/1");
const page2 = await readResource("openapi://apis/page/2");

// ⚠️ Avoid this - returns massive data
// const allApis = await list_all_apis(); // Can saturate context!

🎯 智能提示使用```javascript

// Best practice: Use api_discovery prompt for any use case
// Prompt: api_discovery
// Arguments: {
// use_case: "send emails",
// requirements: "free tier available, good documentation"
// }

// The prompt automatically guides through:
// 1. Efficient search with pagination
// 2. API summaries for comparison
// 3. Progressive endpoint discovery
// 4. Implementation details only when needed

// Integration guide with progressive approach
// Prompt: api_integration_guide
// Arguments: {
// api_name: "Gmail API",
// programming_language: "JavaScript",
// use_case: "send automated notifications"
// }

### 传统工具（小心使用）```javascript
// These work but can consume lots of context:
const metrics = await get_metrics();
const providerStats = await get_provider_stats({ provider: "amazonaws.com" });
const popularApis = await get_popular_apis({ limit: 10 });

🏗️ 建筑

服务器使用模块化、上下文优化的架构：

• 三源API客户端：处理与APIs.guru、辅助API和自定义导入规范的通信
• 增强双源路由：具有自定义的第一优先级和回退处理的智能API解析
• 定制规格管理：为用户提供的OpenAPI规范完成导入、存储和生命周期管理
• 上下文感知安全扫描程序：具有合法模式识别的智能安全分析
• 基于标志的缓存无效：使用文件系统标志自动跨进程缓存同步
• 持久缓存管理器：实现24小时TTL文件系统缓存，实时失效
• CLI接口：功能齐全的命令行工具，带有交互式向导和批处理操作
• 工具生成器：创建具有分页和上下文限制的MCP工具
• 资源处理器：管理分页资源流（20页，每页50个API）
• 渐进式发现：智能工作流程指南，防止上下文饱和
• 提示系统：22个使用高效发现模式的上下文感知提示
• 缓存管理：5个缓存检查和维护工具

v1.3.0中的新功能

混合CLI/MCP架构

应用程序现在运行在 双模式:

• 命令行接口命令模式：提供参数后，将作为用于规范管理的命令行工具运行
• MCP模式：当没有提供参数时，作为Claude Desktop的MCP服务器运行```bash

CLI Mode - Import management

openapi-directory-mcp --import ./api.yaml --name my-api --version v1

MCP Mode - Service for Claude Desktop

openapi-directory-mcp # Starts MCP server

#### 增强的API客户端体系结构```
DualSourceClient
├── Custom API Detection & Routing
├── Parameter Pattern Recognition
├── Fallback Chain Management
└── Cache-Aware Resolution

Custom Provider Handling:
provider="custom" + service="APIName"
→ Routes to: customClient.getAPI("custom", "APIName")
→ Bypasses standard provider:service:version pattern

⚡ 演出

发展

先决条件

• Node.js>=18.0.0
• npm或纱线

设置```bash

git clone https://github.com/rawveg/openapi-directory-mcp.git
cd openapi-directory-mcp
npm install

### 开发流程```bash
# Build the project
npm run build

# Run locally for testing
node dist/index.js

# Run tests
npm test
npm run test:coverage

# Development with auto-rebuild
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Run pre-flight checks (recommended before pushing)
npm run preflight

飞行前检查

该项目包括一个全面的飞行前检查系统，可以在常见问题到达CI/CD之前发现它们：```bash

Run all pre-flight checks

npm run preflight

飞行前检查包括：

- **构建输出** -确保项目建成
- **工具曝光** -验证所有工具文件是否已公开（根据文件数量自动调整）
- **快速曝光** -验证所有提示文件是否公开（根据文件数量自动调整）
- **模拟验证** -确保测试模拟实现所需的方法
- **TypeScript** -验证TypeScript编译
- **ESLint** -验证代码风格和质量

#### 优点：

- ⚡ **快速故障** -在几秒钟内而不是几分钟内捕获问题
- 💰 **节省成本** -避免为注定失败的构建运行昂贵的CI/CD
- 🎯 **特定错误** -提供精确的修复说明
- 🔄 **自我调节** -无硬编码计数，源自文件系统

📚 **完整的飞行前文件**

### Git挂钩设置

对于自动预推验证：```bash
# Install git hooks
./scripts/install-hooks.sh

# This installs:
# - pre-push: Runs pre-flight checks before pushing

在紧急情况下绕过钩子（不建议）：```bash
git push --no-verify

### 自动发布流程

此项目使用由版本标记触发的自动发布工作流：

#### 创建发布

1. **确保主分支准备就绪**:```bash
# Make sure you're on main and up to date
git checkout main
git pull origin main

# Ensure all tests pass
npm run validate

1. 更新版本并创建标签:```bash

Update version in package.json (choose one)

npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0

Or for pre-releases

npm version prerelease --preid=beta # 1.0.0 -> 1.0.1-beta.0

1. **按下标签以触发释放**:```bash
# Push the tag (this triggers the automated workflow)
git push origin --tags

# Also push the commit
git push origin main

CI/CD管道

所有推送和拉取请求都通过我们全面的CI/CD管道运行：

1. 飞行前检查 （先运行，快速失败）：

• 构建验证
• 插件暴露验证
• 模拟完整性检查
• TypeScript编译
• 代码检查

1. 主管道 （仅在飞行前通过时运行）：

• 代码质量检查
• 多节点版本测试（18、20、22）
• 插件架构验证
• 安全扫描
• 测试套件（单元、功能、集成、回归）

这种分阶段的方法通过及早发现常见问题来节省CI/CD资源。

自动发生的事情

GitHub Actions工作流将：

1. 预发布验证:

• ✅ 验证版本是否与标记匹配
• ✅ 检查更改日志条目（可选）
• ✅ 运行完整的测试套件（lint、类型检查、测试）
• ✅ 构建项目并验证包内容

1. NPM出版:

• ✅ 构建生产版本
• ✅ 配置NPM身份验证
• ✅ 发布到NPM（基于版本的稳定或测试标签）
• ✅ 验证发布和测试安装

1. GitHub发布创建:

• ✅ 从提交生成更改日志
• ✅ 创建带有安装说明的GitHub版本
• ✅ 上传构建工件
• ✅ 如果是beta/alpha/rc版本，则标记为预发布

1. 发布后验证:

• ✅ 验证NPM包是否可访问
• ✅ 验证GitHub版本是否已创建
• ✅ 更新包裹徽章

手动出版（后备）```bash

Only use if automated process fails

npm login
npm run build
npm test
npm publish

#### 分支保护

这 `main` 分支受到保护，需要：

- ✅ 拉取所有更改的请求
- ✅ 通过所有CI检查
- ✅ 合并前的最新分支
- ✅ 没有直接推到main

#### 发布要求

- 所有测试必须通过
- package.json中的版本必须与git标签匹配
- 可选但建议：更新CHANGELOG.md
- NPM发布所需：已配置NPM_TOKEN机密

### 使用MCP客户端进行本地测试

构建后，您可以使用绝对路径使用任何MCP客户端进行测试：```bash
# Get absolute path
pwd
# Example: /Users/yourname/projects/openapi-directory-mcp

# Use in client config:
node /Users/yourname/projects/openapi-directory-mcp/dist/index.js

本地测试NPX包

要在发布之前测试NPX安装，请执行以下操作：```bash

Create a local package

npm pack

Test NPX installation from local tarball

npx ./openapi-directory-mcp-1.0.0.tgz

#### 选项1：直接使用焦油球```bash
# Claude Code with local tarball
claude mcp add openapi-directory -- npx -y ./openapi-directory-mcp-1.0.0.tgz

# Claude Desktop with local tarball
{
"mcpServers": {
"openapi-directory": {
"command": "npx",
"args": ["-y", "./openapi-directory-mcp-1.0.0.tgz"],
"cwd": "/Users/yourname/projects/openapi-directory-mcp"
}
}
}

选项2：首先全局安装```bash

Install globally for testing

npm install -g ./openapi-directory-mcp-1.0.0.tgz

Find the installed binary path

which openapi-directory-mcp

Use direct path (NPX still tries to fetch from registry)

claude mcp add openapi-directory -- /path/to/openapi-directory-mcp

For Claude Desktop, use direct path

{
"mcpServers": {
"openapi-directory": {
"command": "/path/to/openapi-directory-mcp"
}
}
}

Uninstall when done testing

npm uninstall -g openapi-directory-mcp

**备注**：即使全球安装， `npx openapi-directory-mcp` 将首先尝试从NPM注册表中获取，并以404失败。请改用直接二进制路径。

______________________________________________________________________

## 🔧 插件架构

此MCP服务器具有 **双插件架构** 这为提示和工具提供了零接触的可扩展性。所有组件都会在启动时从有组织的类别文件夹中自动发现和加载。

### 架构概述

#### 提示插件系统```
src/prompts/
├── core-discovery/         # API discovery and analysis prompts
│   ├── api-discovery.ts
│   ├── api-integration-guide.ts
│   ├── api-comparison.ts
│   ├── authentication-guide.ts
│   ├── code-generation.ts
│   ├── api-documentation-analysis.ts
│   ├── troubleshooting-guide.ts
│   └── api-performance-analyzer.ts
├── action-oriented/        # Code generation and automation prompts
│   ├── retrofit-api-client.ts
│   ├── api-type-generator.ts
│   ├── api-test-suite.ts
│   ├── api-error-handler.ts
│   ├── api-migration-assistant.ts
│   ├── api-sdk-wrapper.ts
│   ├── api-webhook-scaffold.ts
│   ├── api-rate-limiter.ts
│   ├── api-graphql-wrapper.ts
│   └── api-batch-processor.ts
├── authentication/         # Authentication-focused prompts
│   ├── api-auth-implementation.ts
│   ├── api-auth-flow-generator.ts
│   ├── api-auth-middleware.ts
│   ├── api-auth-test-harness.ts
│   └── api-auth-debugger.ts
├── loader.ts              # Auto-discovery system
├── types.ts               # Prompt type definitions
└── templates.ts           # Main prompt interface

工具插件系统```

src/tools/
├── api-discovery/ # Core API discovery tools
│ ├── get-providers.ts
│ ├── get-provider-services.ts
│ ├── list-all-apis.ts
│ └── get-metrics.ts
├── api-details/ # Detailed API information tools
│ ├── get-api.ts
│ ├── get-api-summary.ts
│ ├── get-openapi-spec.ts
│ ├── get-provider-stats.ts
│ └── search-apis.ts
├── endpoint-tools/ # API endpoint analysis tools
│ ├── get-endpoints.ts
│ ├── get-endpoint-details.ts
│ ├── get-endpoint-schema.ts
│ └── get-endpoint-examples.ts
├── cache-tools/ # Cache management tools
│ ├── cache-stats.ts
│ ├── cache-info.ts
│ ├── list-cache-keys.ts
│ ├── clear-cache.ts
│ └── clear-cache-key.ts
├── provider-tools/ # Provider-specific tools
│ └── get-provider-apis.ts
├── utility-tools/ # Analysis and utility tools
│ ├── analyze-api-categories.ts
│ ├── get-popular-apis.ts
│ └── get-recently-updated.ts
├── loader.ts # Auto-discovery system
├── registry.ts # Tool organization
├── handler.ts # MCP integration
└── types.ts # Tool type definitions

### 添加新提示

**零开发开销**：只需创建一个新 `.ts` 将文件放在相应的类别文件夹中：

1. **创建提示文件**:```typescript

…（正文过长，页面只展示前面部分，完整内容见仓库）