Openapi Directory MCP

OpenAPI Directory MCP Server

______________________________________________________________________

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

目录

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

______________________________________________________________________

致谢

他们致力于创建和维护这个全面的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. 克隆和构建:

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

1. 本地测试:

node dist/index.js

本地开发配置

克劳德桌面（本地）

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

克劳德代码（本地）

claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js

光标（本地）

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

风帆（当地）

{
  "servers": {
    "openapi-directory": {
      "command": "node /path/to/openapi-directory-mcp/dist/index.js"
    }
  }
}

NPX安装

npx -y openapi-directory-mcp

克劳德桌面（NPX）

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

克劳德代码（NPX）

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

克劳德代码MCP管理:

# 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）

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

风帆冲浪（NPX）

{
  "servers": {
    "openapi-directory": {
      "command": "npx -y openapi-directory-mcp"
    }
  }
}

______________________________________________________________________

📁 自定义OpenAPI规范

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

✨ 主要特点

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

🚀 快速开始

导入自定义规格

# 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

管理自定义规格

# 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

🛡️ 安全扫描

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

安全规则

情境感知智能

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

# ✅ 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服务器现在作为 三源系统:

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参考

导入命令

--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

管理命令

--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

常规命令

--help, -h              # Show help message with all commands

💡 使用示例

交互式导入工作流

$ 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

直接进口示例

# 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

管理实例

# 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路由和参数识别：

工具集成

// 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" });

提示集成

# 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

资源整合

// 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

🎯 最佳实践

命名约定

# 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

安全建议

# 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

版本管理

# 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

存储维护

# 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

🚨 错误处理

常见进口问题

诚信问题

# 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

🔧 环境配置

自定义规范尊重相同的环境变量：

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

# 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发现工具（上下文优化）

渐进式发现工具（推荐）

实用工具

缓存管理工具

______________________________________________________________________

📦 可用资源

上下文优化资源

分页API资源

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

______________________________________________________________________

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

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

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

核心发现与分析提示

面向动作的代码生成提示

以身份验证为重点的提示

💡 专业提示:

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

配置

服务器无需配置，但支持通过环境变量进行自定义：

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

______________________________________________________________________

🧑‍💻 示例用法

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

// 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"
});

📋 高效的资源访问

// 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!

🎯 智能提示使用

// 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"
// }

传统工具（小心使用）

// 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服务器运行

# 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

______________________________________________________________________

⚡ 演出

• npm或纱线

设置

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

开发流程

# 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之前发现它们：

# Run all pre-flight checks
npm run preflight

飞行前检查包括：

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

优点：

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

📚 完整的飞行前文件

Git挂钩设置

对于自动预推验证：

# Install git hooks
./scripts/install-hooks.sh

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

在紧急情况下绕过钩子（不建议）：

git push --no-verify

自动发布流程

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

创建发布

1. 确保主分支准备就绪:

   # 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. 更新版本并创建标签:

   # 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. 按下标签以触发释放:

   # 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版本是否已创建 - ✅ 更新包裹徽章

手动出版（后备）

# 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客户端进行测试：

# 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安装，请执行以下操作：

# Create a local package
npm pack

# Test NPX installation from local tarball
npx ./openapi-directory-mcp-1.0.0.tgz

选项1：直接使用焦油球

# 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：首先全局安装

# 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. 创建提示文件:

// src/prompts/core-discovery/my-new-prompt.ts
import { PromptTemplate } from '../types.js';

export const prompt: PromptTemplate = {
  name: "my_new_prompt",
  description: "Description of what this prompt does",
  arguments: [
    {
      name: "api_name",
      description: "Name of the API to work with",
      required: true
    }
  ],
  generateMessages: (args) => [
    {
      role: "user",
      content: {
        type: "text",
        text: `Your prompt content here using ${args.api_name}`
      }
    }
  ]
};

export default prompt;

1. 就是这样！ 该系统将：

- ✅ 启动时自动发现提示 - ✅ 使其可用 /openapi-directory:my_new_prompt - ✅ 将其纳入适当的类别 - ✅ 验证提示结构 - ✅ 处理所有MCP协议交互

添加新工具

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

1. 创建工具文件:

// src/tools/api-discovery/my-new-tool.ts
import { z } from 'zod';
import { ToolDefinition, ToolContext } from '../types.js';

export const tool: ToolDefinition = {
  name: 'my_new_tool',
  description: 'Description of what this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      api_name: {
        type: 'string',
        description: 'Name of the API to work with',
      },
    },
    required: ['api_name'],
  },
  async execute(args: any, context: ToolContext): Promise {
    const schema = z.object({
      api_name: z.string(),
    });
    const params = schema.parse(args);
    
    // Your tool logic here using:
    // - context.apiClient for API operations
    // - context.cacheManager for cache operations
    
    return { result: `Processed ${params.api_name}` };
  }
};

export default tool;

1. 就是这样！ 该系统将：

- ✅ 启动时自动发现您的工具 - ✅ 通过MCP接口使其可用 - ✅ 将其纳入适当的类别 - ✅ 验证刀具结构和参数 - ✅ 处理所有MCP协议交互

添加新类别

在下创建新文件夹 src/prompts/ 或 src/tools/ 并在其中添加文件：

# For prompts
mkdir src/prompts/my-category
# Add .ts files with prompt exports

# For tools  
mkdir src/tools/my-category
# Add .ts files with tool exports

自动加载器将自动发现并组织它们。

插件架构优势

• 单一责任：每个组件约15-70行
• 零接触扩展：新组件不需要更改代码
• 有组织的：清除基于文件夹的分类
• 可维护性：易于查找、编辑和测试单个组件
• 可扩展的：支持无限制的提示/工具和类别
• 类型安全：完整的TypeScript验证和IntelliSense
• 一致的：提示和工具的架构模式相同

______________________________________________________________________

🤝 贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改（有关添加提示，请参阅上面的插件架构）
4. 如果需要，添加测试
5. 提交拉取请求

插件贡献：由于我们的双插件架构，添加新的提示和工具非常容易！只需按照上述模式提交PR。

______________________________________________________________________

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

❤️ 支持这个项目

如果您认为此MCP服务器很有价值，特别是如果您在商业环境中使用它，请考虑通过以下方式支持其开发 .

我们的承诺

本项目的所有赞助收益与 APIs.guru 项目，以表彰他们的基础工作和维护该项目所依赖的API基础设施的持续成本。

通过赞助这个项目，您不仅支持这个MCP服务器，还帮助维持整个生态系统，使全面的API发现成为可能。APIs.guru维护超过3000个API规范，并为开发者社区提供免费的API访问。您的支持有助于让每个人都能获得这一宝贵的资源。

支持

______________________________________________________________________

🙏 学分

• 内置于 模型上下文协议
• API数据来自 APIs.guru
• 由OpenAPI目录MCP团队维护