@funfe-dev/swagger-mcp-client

基于 Swagger/OpenAPI 的 MCP（Model Context Protocol）客户端工具，用于自动生成和执行 API 工具集。

安装

# 使用 npm
npm install @funfe-dev/swagger-mcp-client

# 使用 yarn
yarn add @funfe-dev/swagger-mcp-client

# 直接通过 npx 使用
npx @funfe-dev/swagger-mcp-client [swagger-url]

命令行使用

# 直接使用（使用默认 Swagger URL）
npx @funfe-dev/swagger-mcp-client

# 指定 Swagger URL
npx @funfe-dev/swagger-mcp-client https://api.example.com/swagger.json

# 通过环境变量指定 Swagger URL
SWAGGER_URL=https://api.example.com/swagger.json npx @funfe-dev/swagger-mcp-client

在Cursor编辑器中使用 (重要！)

重要提示： Cursor要求MCP服务器通信时严格遵循JSON-RPC 2.0格式！这意味着所有输出必须是有效的JSON-RPC 2.0格式，包含jsonrpc: "2.0"等必要字段。

在Cursor中配置MCP服务器

有两种方法配置Swagger MCP客户端：

方法1: 通过Cursor界面配置

1. 打开Cursor编辑器
2. 进入Settings > Features > MCP Servers
3. 添加您的服务器，使用以下命令格式

方法2: 通过配置文件配置（推荐）

创建或编辑以下任一文件：

• 全局配置：~/.cursor/mcp.json
• 项目级配置：.cursor/mcp.json（在您的项目目录中）

Mac/Linux配置示例：

{
  "mcpServers": {
    "swagger-api": {
      "command": "npx",
      "args": [
        "-y",
        "@funfe-dev/[email protected]",
        "https://your-api.com/swagger.json"
      ],
      "env": {
        "CURSOR_INTEGRATION": "1"
      }
    }
  }
}

Windows配置示例：

{
  "mcpServers": {
    "swagger-api": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@funfe-dev/[email protected]",
        "https://your-api.com/swagger.json"
      ],
      "env": {
        "CURSOR_INTEGRATION": "1"
      }
    }
  }
}

完成配置后，重启Cursor以应用更改。

常见问题排查

如果遇到JSON验证错误(例如："Invalid literal value, expected "2.0"")，这表明MCP客户端没有返回正确的JSON-RPC 2.0格式数据。确保您：

1. 使用最新版本 (1.0.7+) 的客户端，它已修复此问题
2. 不要修改代码添加额外的控制台输出
3. 如果您使用的是自定义版本，确保所有输出都是有效的JSON-RPC 2.0格式
4. 确保已正确设置CURSOR_INTEGRATION环境变量为1

JSON-RPC 2.0格式要求

Cursor期望MCP服务器返回如下格式的数据：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

错误响应格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "错误信息"
  }
}

在Windows上使用

在Windows上，由于Cursor处理命令的方式，请使用以下命令格式在Cursor的MCP设置中注册:

cmd /c npx @funfe-dev/swagger-mcp-client https://your-api.com/swagger.json

或者使用完整路径:

cmd /c node C:\完整路径\到\node_modules\@funfe-dev\swagger-mcp-client\build\index.js https://your-api.com/swagger.json

注意事项:

1. 在Windows上必须使用cmd /c前缀
2. 可以在命令末尾添加Swagger URL
3. 不要添加任何会输出额外日志的参数

在Mac/Linux上使用

在Mac/Linux上，使用以下命令格式:

npx @funfe-dev/swagger-mcp-client https://your-api.com/swagger.json

或者使用完整路径:

node /完整路径/到/node_modules/@funfe-dev/swagger-mcp-client/build/index.js https://your-api.com/swagger.json

故障排除

如果遇到连接问题:

1. 确保使用最新版本(1.0.5+)
2. 尝试关闭并重新打开Cursor编辑器
3. 验证Swagger URL是否可访问
4. 检查 swagger.json 是否有效
5. 在命令行中先测试MCP客户端是否正常工作

代码中使用

import { SwaggerMCPClient } from '@funfe-dev/swagger-mcp-client';

async function main() {
  // 创建客户端实例
  const client = new SwaggerMCPClient({
    swaggerUrl: 'https://api.example.com/swagger.json'
  });

  try {
    // 初始化客户端
    await client.initialize();
    
    // 获取可用工具列表
    const tools = await client.getTools();
    console.log('可用工具:', tools);

    // 执行特定工具
    const result = await client.executeTool({
      toolId: 'get_users',  // 工具 ID 格式：method_path
      parameters: {
        // 工具所需参数
        limit: 10,
        offset: 0
      }
    });

    console.log('执行结果:', result);
  } catch (error) {
    console.error('发生错误:', error);
  }
}

API 参考

SwaggerMCPClient

主客户端类，用于与 Swagger API 交互。

构造函数

constructor(config: SwaggerMCPConfig)

配置参数：

• `swaggerUrl`: Swagger/OpenAPI 文档的 URL（必需）
• `serverUrl`: API 服务器 URL（可选，默认从 Swagger 文档获取）

方法

initialize()

初始化客户端，获取 Swagger 文档并生成工具集。

async initialize(): Promise<void>

getTools()

获取可用的工具列表。

async getTools(): Promise<Tool[]>

返回值类型：

interface Tool {
  name: string;        // 工具名称
  description: string; // 工具描述
  parameters: {        // 参数定义
    type: string;
    properties: Record<string, any>;
    required: string[];
  };
}

executeTool()

执行指定的工具。

async executeTool(params: ExecuteToolParams): Promise<ExecuteToolResponse>

参数类型：

interface ExecuteToolParams {
  toolId: string;                 // 工具 ID
  parameters: Record<string, any>; // 工具参数
}

返回值类型：

interface ExecuteToolResponse {
  success: boolean; // 执行是否成功
  data?: any;      // 成功时的返回数据
  error?: string;  // 失败时的错误信息
}

工具 ID 格式

工具 ID 的格式为：`{method}_{path}`，其中：

• `method`: HTTP 方法（小写）
• `path`: API 路径，将 "/" 替换为 "_"

例如：

• GET /users 的工具 ID 为：`get_users`
• POST /users/{id}/update 的工具 ID 为：`post_users_{id}_update`

错误处理

客户端会在以下情况抛出错误：

1. 初始化失败（无法获取 Swagger 文档）
2. 工具不存在
3. API 调用失败

建议使用 try-catch 块处理可能的错误：

try {
  await client.initialize();
} catch (error) {
  console.error('初始化失败:', error);
}

示例

基本使用

import { SwaggerMCPClient } from '@funfe-dev/swagger-mcp-client';

const client = new SwaggerMCPClient({
  swaggerUrl: 'https://petstore.swagger.io/v2/swagger.json'
});

await client.initialize();

// 获取宠物信息
const result = await client.executeTool({
  toolId: 'get_pet_findbyid',
  parameters: {
    petId: 1
  }
});

console.log(result.data);

批量操作

import { SwaggerMCPClient } from '@funfe-dev/swagger-mcp-client';

async function batchOperation() {
  const client = new SwaggerMCPClient({
    swaggerUrl: 'https://api.example.com/swagger.json'
  });

  await client.initialize();
  const tools = await client.getTools();

  // 过滤出所有 GET 请求
  const getTools = tools.filter(tool => tool.name.startsWith('get_'));
  
  // 批量执行
  const results = await Promise.all(
    getTools.map(tool => 
      client.executeTool({
        toolId: tool.name,
        parameters: {}
      })
    )
  );

  return results;
}

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT