使用说明
MCP Swagger搜索
MCP（模型上下文协议）服务器，用于搜索和探索Swagger/OpenAPI文档。
支持两者 标准 （当地）和 可流式传输的HTTP （远程）运输。
特性
- 🔍 按关键字搜索API端点
- 📖 获取详细的API规范
- 🌐 多种传输模式（stdio和HTTP）
- 🚀 MSA环境的无状态架构
- 🔄 支持多个Swagger源
安装
npm install
npm run build
用法
1.标准传输（本地/Claude代码CLI）
对于使用Claude Code CLI的本地执行：
# Development
npm run dev
# Production
npm start
Claude代码配置 (~/.config/claude/claude_desktop_config.json):
{
"mcpServers": {
"mcp-swagger-search": {
"command": "node",
"args": ["/path/to/mcp-swagger-search/dist/index.js"]
}
}
}
2.可流式HTTP传输（远程/MSA）
对于远程部署和微服务架构：
# Development with HTTP transport (default port: 3000)
npm run dev:http
# Production with HTTP transport
npm run start:http
# Custom port
npm run start:http:custom-port
# or
node dist/index.js --http --port=8080
# or
MCP_TRANSPORT=http MCP_PORT=8080 node dist/index.js
HTTP端点：
POST /mcp-主MCP端点（JSON-RPC 2.0）GET /health-健康检查GET /mcp/stream-SSE端点（未来使用）
HTTP请求示例：
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_api",
"arguments": {
"query": "pet"
}
},
"id": 1
}'
可用工具
1. search_api
按关键字搜索API端点。
参数：
query（string）：搜索关键字（例如“宠物”、“用户”、“订单”）
例子：
{
"name": "search_api",
"arguments": {
"query": "pet"
}
}
2. get_api_detail
获取有关特定API终结点的详细信息。
参数：
service（string）：服务名称（例如“petstore”）path（字符串）：API路径（例如，“/pet/｛petId｝”）method（string）：HTTP方法（例如，“GET”、“POST”）
例子：
{
"name": "get_api_detail",
"arguments": {
"service": "petstore",
"path": "/pet/{petId}",
"method": "GET"
}
}
3. list_services
列出所有可用的Swagger服务。
例子：
{
"name": "list_services",
"arguments": {}
}
配置
添加Swagger源
编辑 src/index.ts 添加您的Swagger/OpenAPI网址：
const SWAGGER_SOURCES: SwaggerSource[] = [
{
name: 'petstore',
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
},
{
name: 'your-api',
url: 'https://your-api.com/swagger.json',
},
];
运输选择
优先级顺序：
- CLI标志：
--http - 环境变量：
MCP_TRANSPORT=http - 违约：
stdio
端口选择：
- CLI标志：
--port=8080 - 环境变量：
MCP_PORT=8080 - 违约：
3000
建筑
┌─────────────────────────────────────┐
│ SwaggerMCPServer │
│ (Transport-agnostic core logic) │
└──────────────┬──────────────────────┘
│
┌───────┴───────┐
│ │
┌──────▼─────┐ ┌─────▼──────┐
│ Stdio │ │ HTTP │
│ Transport │ │ Transport │
└────────────┘ └────────────┘
│ │
│ │
┌────▼─────┐ ┌─────▼──────────┐
│ Claude │ │ Remote Client │
│ Code │ │ (MSA/Cloud) │
└──────────┘ └────────────────┘
为什么是流式HTTP？
流式HTTP传输（MCP规范2025-03-26）是微服务架构的理想选择：
- ✅ 无状态：90%以上的用例不需要会话管理
- ✅ 可扩展的：使用负载平衡器轻松实现水平扩展
- ✅ 灵活的：需要时提供可选会话支持
- ✅ 云原生：适用于Kubernetes、无服务器等。
- ✅ 简单：单端点，无粘性会话
发展
# Install dependencies
npm install
# Run in development mode (stdio)
npm run dev
# Run in development mode (HTTP)
npm run dev:http
# Build
npm run build
# Run production build
npm start
部署
码头工人
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js", "--http"]
Kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-swagger-search
spec:
replicas: 3
selector:
matchLabels:
app: mcp-swagger-search
template:
metadata:
labels:
app: mcp-swagger-search
spec:
containers:
- name: mcp-swagger-search
image: mcp-swagger-search:latest
env:
- name: MCP_TRANSPORT
value: "http"
- name: MCP_PORT
value: "3000"
ports:
- containerPort: 3000
---
apiVersion: v1
kind: Service
metadata:
name: mcp-swagger-search
spec:
selector:
app: mcp-swagger-search
ports:
- port: 80
targetPort: 3000
type: LoadBalancer
许可证
ISC
贡献
欢迎投稿！请随时提交拉取请求。