使用说明

改进的Swagger MCP

一个高性能MCP服务器，用于高效Swagger/OpenAPI API探索，具有动态会话管理和轻量级搜索功能。

🚀 主要改进（v2.0）

✅ 基于会话的动态配置

运行时配置：在不使用环境变量的情况下，在现场配置API会话
会话隔离：每个会话都维护独立的设置和缓存
自动清理：过期的会话会自动删除，以防止内存泄漏
内存监控：实时内存使用跟踪和优化

✅ 闪电般的快速搜索性能

内存减少90%：搜索大型API而不加载完整文档
亚毫秒搜索：智能索引提供即时结果
多维搜索：关键字、标签、模式和HTTP方法筛选
智能缓存：多层缓存策略减少了冗余请求

✅ 企业级可扩展性

5000+会话/秒：经过数百个并发会话的测试
每个会话<50KB内存：高效的内存利用率
自动资源管理：智能清理和垃圾收集
生产就绪：全面的错误处理和监控

🛠️ 增强功能

核心MCP工具

原始工具：保留所有现有功能
configure_swagger_session：动态会话配置
search_swagler_endpoints：高效的端点搜索，无需满载
get_endpoint_details：按需提供详细的端点信息
get_session_stats：实时会话和系统监控
clear_swaker_cache：智能缓存管理
get_search_建议：智能搜索建议

性能优化

增量索引：仅加载必要的元数据
按需加载：需要时获取端点详细信息
LRU缓存：自动缓存清除和内存管理
并发处理：同时处理多个会话

高级搜索功能

基于标签的分组：按API端点类别搜索
模式匹配：基于正则表达式的智能路径搜索
关键字扩展：同义词感知模糊搜索
相关性评分：智能结果排名

先决条件

Node.js（v14或更高版本）
npm或纱线

安装

克隆存储库：

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

安装依赖项：

npm install

创建 .env 文件基于 .env.example 文件：

cp .env.example .env

更新 .env 文件。

配置

编辑 .env 配置应用程序的文件：

PORT：服务器将运行的端口（默认值：3000）
NODE_ENV：环境（开发、生产、测试）
LOG_LEVEL：日志记录级别（信息、错误、调试）

用法

构建应用程序

构建应用程序：

npm run build

这将编译TypeScript代码，准备用作MCP服务器

作为MCP服务器运行

要作为MCP服务器运行以与Cursor和其他应用程序集成，请执行以下操作：

node build/index.js

使用MCP检查器

要运行MCP检查器进行调试：

npm run inspector

添加到光标

要将此MCP服务器添加到游标，请执行以下操作：

打开光标设置>功能>MCP
点击“+添加新MCP服务器”
输入服务器的名称（例如“Swagger MCP”）
选择“stdio”作为传输类型
输入运行服务器的命令： node path/to/swagger-mcp/build/index.js 然后，如果需要，如上所述添加命令行参数。
点击“添加”

Swagger MCP工具现在将可用于Composer中的光标代理。

可用的MCP工具

原始工具（增强）

getSwaggerDefinition：从URL下载Swagger定义
- 新功能 （v2.1+）：
  - 🌐 微服务支持：自动检测弹簧启动 /swagger-resources 端点
  - 🔍 URL自动检测：自动在公共路径中查找Swagger/OpenAPI文档
  - 📄 YAML格式支持：解析JSON和YAML Swagger文档
  - 🔑 自定义头：内置对经过身份验证的API的支持
```
{
  "url": "https://api-gateway.example.com",
  "saveLocation": "./",
  "service": "auth-service",
  "autoDetect": true,
  "sessionConfig": {
    "custom_headers": { "Authorization": "Bearer token" }
  }
}
```
listEndpoints：列出Swagger定义中的所有端点
listEndpointModels：列出特定端点使用的所有模型
generateModelCode：为模型生成TypeScript代码
generateEndpointToolCode：为MCP工具定义生成TypeScript代码

微服务架构支持

对于Spring Boot微服务，使用 /swagger-resources:

步骤1：获取可用服务

{
  "tool": "getSwaggerDefinition",
  "arguments": {
    "url": "https://api-gateway.example.com",
    "saveLocation": "./"
  }
}

回应：列出所有可用的微服务

步骤2：获取特定的服务文档

{
  "tool": "getSwaggerDefinition",
  "arguments": {
    "url": "https://api-gateway.example.com",
    "saveLocation": "./",
    "service": "auth-service"
  }
}

URL自动检测

该工具会自动尝试常见的Swagger路径：

/swagger.json, /swagger.yaml
/openapi.json, /openapi.yaml
/api-docs, /api-docs/swagger.json
/docs/api, /v1/swagger.json
10多条常见路径

如果直接URL失败，它会自动尝试这些路径。

新型高性能工具

configure_swagger_session：不带环境变量的动态会话配置

{
  "session_id": "my-api-session",
  "swagger_urls": ["https://api.example.com/swagger.json"],
  "custom_headers": {"Authorization": "Bearer token"},
  "cache_ttl": 600000
}

search_swagger_endpoints：无需加载完整文档即可快速搜索

{
  "swagger_url": "https://api.example.com/swagger.json",
  "session_id": "my-api-session",
  "search_type": "keywords",
  "query": "user profile management",
  "limit": 20
}

get_endpoint_details：按需提供详细的端点信息

{
  "swagger_url": "https://api.example.com/swagger.json",
  "session_id": "my-api-session",
  "endpoint_paths": ["/users/{id}", "/users"],
  "methods": ["GET", "POST"]
}

get_session_stats：实时会话和系统监控
```
{
  "session_id": "my-api-session"
}
```

clear_swagger_cache：智能缓存管理

{
  "swagger_url": "https://api.example.com/swagger.json",
  "session_id": "my-api-session"
}

get_search_suggestions：智能搜索建议和流行端点

{
  "swagger_url": "https://api.example.com/swagger.json",
  "session_id": "my-api-session",
  "partial": "user",
  "limit": 5
}

可用的Swagger MCP提示

服务器还提供MCP提示，指导AI助手完成常见的工作流程：

add-endpoint：使用Swagger MCP工具添加新端点的分步指南

要使用提示，客户端可以 prompts/get 带有提示名称和可选参数的请求：

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

提示将返回一系列消息，指导AI助手完成添加新端点所需的确切过程。

设置新项目

首先让代理获取Swagger文件，确保你给了它Swagger文件的URL，或者至少给你一种找到它的方法，这将下载文件并用哈希文件名保存在本地，这个文件名将自动添加到 .claude/swagger-mcp.json 中的设置文件 .claude 当前解决方案的文件夹。

自动生成.claude/swagger-mcp.json配置文件

{
  "sessionId": "session_abc123...",
  "swaggerUrl": "https://api.example.com/swagger.json"
}

此JSON配置文件将当前项目与特定的Swagger API相关联。

配置后，MCP将能够找到您的Swagger定义，并将其与您当前的解决方案相关联，从而减少获取与您正在处理的解决方案相关的项目和任务所需的API调用次数。

改进的MCP工具代码生成器

MCP工具代码生成器已得到增强，可提供更完整和可用的工具定义：

关键改进

完整的架构信息：生成器现在直接在inputSchema中包含所有模型的完整模式信息，包括嵌套对象。
更好的参数命名：参数名称现在更具语义，避免了点等有问题的字符（例如。， taskRequest 而不是 task.Request).
语义工具名称：工具名称现在更具描述性，并遵循基于HTTP方法和资源路径的一致命名约定。
支持YAML Swagger文件：生成器现在支持JSON和YAML Swagger定义文件。
改进文档：生成的工具定义包括对所有参数和属性的全面描述。
无外部依赖关系：生成的代码不需要导入外部模型文件，使其更加自包含且易于使用。
AI特定说明工具描述现在包括针对AI代理的特殊说明，帮助他们了解如何有效地使用工具。

示例用法

要为端点生成MCP工具定义，请执行以下操作：

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

这将生成一个完整的MCP工具定义，其中包含POST/pets端点的完整模式信息。

许可证

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

📊 性能基准

基于广泛的测试，以下是您可以期待的性能改进：

会话管理

创建速度：每秒5 937次会议
内存效率：每个会话<50KB
并发处理：100多个活动会话同时进行
自动清理：延长使用时间后无内存泄漏

搜索性能

索引创建：大型API为亚秒级
搜索速度：平均响应时间<100ms
内存减少：内存比满载文档少90%
缓存命中率：重复搜索率>95%

资源使用情况

基本内存：约13MB，可容纳160多个会话
可扩展性：线性内存增长，无指数级增长
网络效率：智能缓存将API调用减少80%以上

🚀 快速入门指南

步骤1：配置会话

{
  "tool": "configure_swagger_session",
  "arguments": {
    "session_id": "my-project-api",
    "swagger_urls": ["https://api.example.com/v1/swagger.json"],
    "custom_headers": {
      "Authorization": "Bearer your-api-token"
    },
    "cache_ttl": 600000
  }
}

步骤2：高效搜索端点

{
  "tool": "search_swagger_endpoints",
  "arguments": {
    "swagger_url": "https://api.example.com/v1/swagger.json",
    "session_id": "my-project-api",
    "search_type": "keywords",
    "query": "user authentication profile",
    "methods": ["GET", "POST"],
    "limit": 10
  }
}

步骤3：获取详细信息

{
  "tool": "get_endpoint_details",
  "arguments": {
    "swagger_url": "https://api.example.com/v1/swagger.json",
    "session_id": "my-project-api",
    "endpoint_paths": ["/auth/login", "/users/{id}"],
    "methods": ["POST", "GET"]
  }
}

步骤4：监控性能

{
  "tool": "get_session_stats",
  "arguments": {
    "session_id": "my-project-api"
  }
}

💡 代币使用指南

概述

此MCP服务器旨在最大限度地减少代币使用，同时提供全面的API探索功能。了解代币成本有助于优化您的工作流程。

工具令牌成本

工具	典型响应	代币成本	风险水平
`search_swagger_endpoints`	10-20个结果	~1000-2000	🟢 低
`get_endpoint_details`	1-5个端点	~1000-3000	🟡 中等
`listEndpoints` （summary=true）	50个端点	~400-600	🟢 低
`listEndpoints` （摘要=假）	50个端点	~1000-1500	🟡 中等
`get_session_stats`	会话信息	~500-1000	🟢 低
`get_search_suggestions`	5-10条建议	~500-800	🟢 低
`generateEndpointToolCode`	工具代码	~1000-3000	🟡 中等

最佳实践

1.适用于大型API（100+端点）

❌ 避免：

// Getting all endpoints at once - HIGH TOKEN COST
listEndpoints({ swaggerFilePath, limit: 1000 })

✅ 推荐：

// Step 1: Get overview in summary mode
listEndpoints({ swaggerFilePath, summary: true, limit: 100 })

// Step 2: Use search for specific endpoints
search_swagger_endpoints({
  swagger_url,
  session_id,
  search_type: "keywords",
  query: "user management",
  limit: 20
})

// Step 3: Get details only for needed endpoints
get_endpoint_details({
  swagger_url,
  session_id,
  endpoint_paths: ["/users/{id}", "/users/create"],
  methods: ["GET"]
})

2.使用子代理执行复杂任务

为了进行全面的API分析，委托具有特定说明的子代理：

// Main context: Get overview
const overview = await listEndpoints({
  swaggerFilePath,
  summary: true,
  limit: 50
});

// Sub-agent: Detailed analysis with filtered results
await analyzeEndpoints({
  task: "Find authentication-related endpoints",
  useSubAgent: true,
  filter: { tags: ["auth", "security"] }
});

3.分页策略

// Page through large APIs efficiently
const pageSize = 50;
let offset = 0;

while (true) {
  const page = await listEndpoints({
    swaggerFilePath,
    summary: true,
    limit: pageSize,
    offset
  });

  if (page.endpoints.length === 0) break;

  // Process page...
  offset += pageSize;
}

代币优化提示

策略	代币节省	用例
使用 `summary=true`	70-80%	API快速概述
设置 `limit` 参数	比例	大型API
使用搜索而不是列表	50-90%	有针对性的发现
子代理委托	90%+	复杂分析
分页控制	可变	渐进式加载

示例工作流

工作流程1：快速API概述（约500个令牌）

1. listEndpoints({ summary: true, limit: 50 })  // ~400 tokens

工作流程2：目标端点发现（约1500个令牌）

1. search_swagger_endpoints({ query: "user auth", limit: 10 })  // ~1,000 tokens
2. get_endpoint_details({ endpoint_paths: ["/auth/login"] })    // ~500 tokens

工作流程3：综合分析（子代理，主约2000个令牌）

1. listEndpoints({ summary: true, limit: 100 })  // ~600 tokens
2. Delegate to sub-agent for detailed analysis    // ~1,400 tokens in sub-agent

🏢 用例

API文档团队

即时搜索大型API文档
生成全面的API概述
在单独的会话中维护多个API版本

开发团队

在开发过程中快速发现API端点
生成具有准确类型定义的客户端代码
缓存常用的API规范

DevOps和SRE团队

监控API性能和可用性
自动化API文档更新
管理多个API环境（dev/tstaging/prod）

人工智能集成平台

为人工智能助手提供高效的API访问
通过有针对性的搜索减少上下文使用
启用多对映API探索

🧪 测试

运行基本测试

node test-basic.js

运行性能测试

node test-performance.js

集成测试

该项目包括全面的测试套件，涵盖：

会话生命周期管理
内存使用优化
搜索性能验证
并发会话处理
缓存效率验证

📋 迁移指南

来自原始Swagger MCP

保留所有原始功能。要升级，请执行以下操作：

无重大变更：现有工具继续工作
可选增强功能：使用新工具提高性能
逐步采用：根据需要混合新旧工具

最佳实践

使用会话管理多个API
利用搜索而不是加载完整文档
监控会话统计数据以获得最佳性能
在生产中定期清除缓存

📝 架构概述

┌─────────────────────────────────────────────────────────────┐
│                    Improved Swagger MCP                      │
├─────────────────────────────────────────────────────────────┤
│  Dynamic Session Layer                                       │
│  ├─ SessionConfigManager  ├─ MemoryOptimizedCache           │
│  └─ Auto-Cleanup System  └─ Resource Monitoring             │
├─────────────────────────────────────────────────────────────┤
│  Search & Indexing Layer                                    │
│  ├─ IndexedSwaggerLoader   ├─ LightweightAPIRetriever      │
│  └─ Multi-Dimensional Search └─ Relevance Scoring           │
├─────────────────────────────────────────────────────────────┤
│  MCP Tool Layer                                              │
│  ├─ Original Tools (Preserved)                              │
│  └─ Enhanced Tools (New)                                     │
└─────────────────────────────────────────────────────────────┘

🔧 高级配置

会话管理

// Custom session configuration
const sessionConfig = {
  maxSessions: 200,              // Maximum concurrent sessions
  sessionCleanupInterval: 300000, // Cleanup every 5 minutes
  memoryThreshold: 1024,         // 1GB memory limit
  defaultCacheTTL: 1800000       // 30 minutes default TTL
};

缓存优化

// Cache configuration
const cacheConfig = {
  maxSize: 200,                 // Maximum cached items
  ttl: 1800000,                // 30 minutes TTL
  memoryThreshold: 512,        // 512MB limit
  checkPeriod: 60000           // Cleanup check interval
};

📈 监测和可观察性

内置指标

活动会话计数
内存使用跟踪
缓存命中率
搜索性能指标
资源利用率

健康检查

{
  "tool": "get_session_stats",
  "arguments": {
    "session_id": "health-check"
  }
}

🔒 安全考虑

会话隔离：每个会话都保持单独的配置
标题管理：安全处理身份验证标头
缓存加密：缓存数据的可选加密
资源限制：可配置的限制可防止资源耗尽

MCP提示AI助手

为了帮助人工智能助手有效地使用Swagger MCP工具，我们创建了一组提示，指导他们完成常见任务。这些提示为添加新端点、使用生成的模型等过程提供了分步说明。

看看 PROMPTS.md 文件以获取完整的提示集合。

示例用例：当要求AI助手向您的项目添加新端点时，您可以参考“添加新端点”提示，以确保助手按照正确的顺序遵循正确的流程。

使用说明

改进的Swagger MCP

🚀 主要改进（v2.0）

✅ 基于会话的动态配置

✅ 闪电般的快速搜索性能

✅ 企业级可扩展性

🛠️ 增强功能

核心MCP工具

性能优化

高级搜索功能

先决条件

安装

配置

用法

构建应用程序

作为MCP服务器运行

使用MCP检查器

添加到光标

可用的MCP工具

原始工具 （增强）

微服务架构支持

URL自动检测

新型高性能工具

可用的Swagger MCP提示

设置新项目

自动生成.claude/swagger-mcp.json配置文件

改进的MCP工具代码生成器

关键改进

示例用法

许可证

📊 性能基准

会话管理

搜索性能

资源使用情况

🚀 快速入门指南

步骤1：配置会话

步骤2：高效搜索端点

步骤3：获取详细信息

步骤4：监控性能

💡 代币使用指南

概述

工具令牌成本

最佳实践

1.适用于大型API（100+端点）

2.使用子代理执行复杂任务

3.分页策略

代币优化提示

示例工作流

工作流程1：快速API概述（约500个令牌）

工作流程2：目标端点发现（约1500个令牌）

工作流程3：综合分析（子代理，主约2000个令牌）

🏢 用例

API文档团队

开发团队

DevOps和SRE团队

人工智能集成平台

🧪 测试

运行基本测试

运行性能测试

集成测试

📋 迁移指南

来自原始Swagger MCP

最佳实践

📝 架构概述

🔧 高级配置

会话管理

缓存优化

📈 监测和可观察性

内置指标

健康检查

🔒 安全考虑

MCP提示AI助手

相关 MCP

GraphQL模式分析工具

Swagger API测试工具

OpenAPI解析服务

OpenAPI模式解析服务

Swagger API解析工具

OpenAPI规范搜索服务

原始工具（增强）