MCP Swagger Search

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',
  },
];

运输选择

优先级顺序：

1. CLI标志： --http
2. 环境变量： MCP_TRANSPORT=http
3. 违约： stdio

端口选择：

1. CLI标志： --port=8080
2. 环境变量： MCP_PORT=8080
3. 违约： 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

贡献

欢迎投稿！请随时提交拉取请求。