Swagger/Postman MCP Server

Swagger/Postman MCP服务器

使用MCP（模型上下文协议）工具接收和提供Swagger/OpenAPI规范和Postman集合的服务器 简化战略方法.

该服务器不是为每个API端点生成数百个单独的工具，而是提供 只有4个战略工具 允许AI代理动态发现API并与之交互：

Example prompt:
Help me generate an axios call using our api mcp. I want to implement updating a user. Follow our same DDD pattern (tanstack hook -> axios service)

特性

• 战略工具方法：只有4个工具，而不是数百个，可以提高AI代理的性能
• OpenAPI/Swagger支持：从URL或本地文件加载OpenAPI 2.0/3.0规范
• 邮差收藏支持：从URL或本地文件加载Postman集合JSON文件
• 环境变量：支持Postman环境文件
• 认证：多种身份验证方法（基本、承载、API密钥、OAuth2）
• 动态API发现：用于列出、搜索和获取有关API端点的详细信息的工具
• 请求执行：通过正确的参数处理和身份验证执行API请求

安全

这是个人服务器！！不要把它暴露在公共互联网上。 如果底层API需要身份验证，则不应将MCP服务器暴露于公共互联网。

TODO

• 机密-MCP服务器应该能够使用来自用户的机密来验证对API的请求
• 全面的测试套件

先决条件

• Node.js（v18或更高版本）
• 纱线包装经理
• TypeScript

安装

# Clone the repository
git clone 
cd swag-mcp

# Install dependencies
npm install
# or
yarn install

# Build the project
npm run build
# or
yarn build

# Make the start script executable (Linux/macOS)
chmod +x start-mcp.sh

光标快速设置

1. 克隆和构建 （以上命令）
2. 配置 你的 config.json 与您的API详细信息
3. 更新路径：编辑 start-mcp.sh 并更改 cd 安装目录的路径
4. 添加到光标：编辑 ~/.cursor/mcp.json 并添加：

   {
     "mcpServers": {
       "postman-swagger-api": {
         "command": "/full/path/to/your/swag-mcp/start-mcp.sh"
       }
     }
   }

1. 重新启动游标 并开始使用4个战略性MCP工具！

配置

服务器使用 config.json 配置文件。您可以指定OpenAPI/Swagger规范或Postman集合。

OpenAPI/Swagger配置

{
  "api": {
    "type": "openapi",
    "openapi": {
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "apiBaseUrl": "https://petstore.swagger.io/v2",
      "defaultAuth": {
        "type": "apiKey",
        "apiKey": "special-key",
        "apiKeyName": "api_key",
        "apiKeyIn": "header"
      }
    }
  },
  "log": {
    "level": "info"
  }
}

邮差收集配置

{
  "api": {
    "type": "postman",
    "postman": {
      "collectionUrl": "https://www.postman.com/collections/your-collection-id",
      "collectionFile": "./examples/postman-collection.json",
      "environmentUrl": "https://www.postman.com/environments/your-environment-id",
      "environmentFile": "./examples/postman-environment.json",
      "defaultAuth": {
        "type": "bearer",
        "token": "your-api-token-here"
      }
    }
  },
  "log": {
    "level": "info"
  }
}

配置选项

API配置

• api.type：要么 "openapi" 或 "postman"
• api.openapi：OpenAPI/Swagger特定配置

- url：指向OpenAPI规范的URL - apiBaseUrl：API请求的基本URL - defaultAuth：默认身份验证配置

• api.postman：邮递员特定配置

- collectionUrl：邮递员收藏的URL（可选） - collectionFile：本地邮差收藏文件的路径（可选） - environmentUrl：Postman环境的URL（可选） - environmentFile：本地Postman环境文件的路径（可选） - defaultAuth：默认身份验证配置

验证配置

• type：身份验证类型("basic", "bearer", "apiKey", "oauth2")
• username：用户名（用于基本身份验证）
• password：密码（用于基本身份验证）
• token：令牌（用于承载/oauth2身份验证）
• apiKey：API密钥值
• apiKeyName：API关键参数名称
• apiKeyIn：将API密钥发送到何处("header" 或 "query")

日志记录配置

• log.level：日志记录级别("debug", "info", "warn", "error")

用法

启动MCP服务器

服务器通过用于MCP连接的stdio传输运行：

# Start the simplified MCP server via stdio
./start-mcp.sh

# Or directly with node
node dist/simple-stdio.js

# For development with auto-reload
npm run dev:simple
# or
yarn dev:simple

MCP集成

此服务器使用stdio传输，旨在与Claude Desktop或Cursor等MCP客户端一起使用。

在Cursor中安装

要将此MCP服务器与Cursor一起使用，您需要将其添加到Cursor MCP配置中：

1.找到您的Cursor MCP配置文件

配置文件位于：

• Linux/macOS: ~/.cursor/mcp.json
• 视窗: %APPDATA%\.cursor\mcp.json

2.添加MCP服务器配置

编辑您的 mcp.json 包含此服务器的文件：

{
  "mcpServers": {
    "postman-swagger-api": {
      "command": "/path/to/your/swag-mcp/start-mcp.sh"
    }
  }
}

⚠️ 重要提示：更改路径！

替换 /path/to/your/swag-mcp/start-mcp.sh 使用克隆存储库的实际路径。例如：

• Linux/macOS: "/home/username/Documents/swag-mcp/start-mcp.sh"
• 视窗: "C:\\Users\\username\\Documents\\swag-mcp\\start-mcp.sh"

3.完整配置示例

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "your-supabase-token"
      ]
    },
    "postman-swagger-api": {
      "command": "/home/username/Documents/swag-mcp/start-mcp.sh"
    }
  }
}

4.重新启动游标

保存配置文件后，重新启动Cursor以使更改生效。

5.验证安装

在Cursor中，您现在应该可以访问4个战略MCP工具：

• list_requests -列出所有可用请求
• get_request_details -获取详细的请求信息
• search_requests -按关键字搜索请求
• make_request -执行任何API请求

故障排除

如果MCP服务器无法启动：

1. 更新start-mcp.sh路径：编辑 start-mcp.sh 并更改 cd 路径来自 /path/to/your/swag-mcp 到您的实际安装目录
2. 检查路径：确保路径 mcp.json 指向您的实际 start-mcp.sh 文件
3. 检查权限：确保 start-mcp.sh 可执行(chmod +x start-mcp.sh)
4. 检查构建：确保你已经跑过了 npm run build 编译TypeScript文件
5. 检查日志：在Cursor的MCP日志中查找错误消息

路径更新示例

如果你克隆到 /home/username/Documents/swag-mcp/那么：

在 start-mcp.sh:

cd "/home/username/Documents/swag-mcp"

在 ~/.cursor/mcp.json:

"command": "/home/username/Documents/swag-mcp/start-mcp.sh"

运作原理

战略工具方法

该服务器不是为每个API端点生成数百个单独的工具，而是提供 4战略工具 实现动态API发现和交互：

OpenAPI/Swagger模式

4战略工具：

1. list_endpoints -列出所有可用的API端点
2. get_endpoint_details -获取特定端点的详细信息
3. search_endpoints -按关键字搜索端点
4. make_api_call -使用正确的身份验证执行任何API调用

流程：

1. 从配置的URL或文件加载OpenAPI规范
2. 分析规范以提取API端点、参数和安全方案
3. 通过4个战略工具提供端点信息
4. 动态处理身份验证和参数验证
5. 执行API请求并返回响应

邮递员收款模式

4战略工具：

1. list_requests -列出集合中所有可用的请求
2. get_request_details -获取有关特定请求的详细信息
3. search_requests -按关键字搜索请求
4. make_request -执行集合中的任何请求

流程：

1. 从配置的URL或文件加载Postman集合JSON
2. （可选）加载Postman环境文件进行变量替换
3. 解析集合中的请求、文件夹和嵌套项
4. 通过4个战略工具提供请求信息
5. 动态处理变量替换、身份验证和参数映射
6. 使用正确的标头、查询参数和正文数据执行请求

战略工具的好处

• 更好的AI性能4个工具vs数百个工具意味着更快的决策
• 动态发现：AI代理可以在不事先知道端点的情况下探索API
• 灵活的互动：任何端点都可以通过调用 make_api_call/make_request
• 减少超重：AI代理没有大量的工具选项

战略工具参考

适用于OpenAPI/Swagger API

1. list_endpoints

- 列出所有可用的API终结点及其方法和路径 - 无需参数 - 返回：端点摘要数组

1. get_endpoint_details

- 获取特定端点的详细信息 - 参数： method （GET/POST/等）， path （/users/{id}/etc） - 返回：带参数的完整端点规范、主体模式、响应

1. search_endpoints

- 按路径、摘要或描述中的关键字搜索端点 - 参数： query （搜索词） - 返回：匹配端点的筛选列表

1. make_api_call

- 对任何终结点执行API调用 - 参数： method, path, pathParams, queryParams, headers, body - 返回：带状态和数据的API响应

用于邮递员收藏

1. list_requests

- 列出集合中所有可用的请求 - 无需参数 - 返回：请求摘要数组

1. get_request_details

- 获取特定请求的详细信息 - 参数： requestId 或 requestName - 返回：完整请求规范

1. search_requests

- 按关键字搜索请求 - 参数： query （搜索词） - 返回：已筛选的匹配请求列表

1. make_request

- 执行集合中的任何请求 - 参数： requestId, variables （替换） - 返回：请求响应

认证

服务器支持多种身份验证方法：

• 基本认证：用户名/密码
• 持有者令牌：JWT或其他不记名代币
• API密钥：在标题或查询参数中
• OAuth2：基于承载令牌

身份验证可以全局配置，也可以根据请求覆盖。

配置示例

你的 config.json 应指定如上所示的OpenAPI或Postman配置。

邮差收藏结构示例

{
  "info": {
    "name": "Sample API Collection",
    "description": "A sample Postman collection"
  },
  "item": [
    {
      "name": "Get Users",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/users",
          "host": ["{{baseUrl}}"],
          "path": ["users"]
        }
      }
    }
  ]
}

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

许可证

国际协调委员会

环境变量

• PORT：服务器端口（默认值：3000）
• API_USERNAME：API身份验证的用户名（回退）
• API_PASSWORD：API身份验证的密码（回退）
• API_TOKEN：用于身份验证的API令牌（回退）
• DEFAULT_API_BASE_URL：API终结点的默认基本URL（回退）
• DEFAULT_SWAGGER_URL：默认Swagger规范URL