npm package: @funfe-dev/swagger-mcp-client
Description: Swagger MCP Client for Cursor Integration
Author: funfe
Latest version: 1.0.9

# @funfe-dev/swagger-mcp-client

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

## 安装

```bash
# 使用 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]
```

## 命令行使用

```bash
# 直接使用（使用默认 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配置示例：

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

##### Windows配置示例：

```json
{
  "mcpServers": {
    "swagger-api": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@funfe-dev/swagger-mcp-client@1.0.7",
        "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服务器返回如下格式的数据：

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

错误响应格式：

```json
{
  "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客户端是否正常工作

## 代码中使用

```typescript
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 交互。

#### 构造函数

```typescript
constructor(config: SwaggerMCPConfig)
```

配置参数：
- \`swaggerUrl\`: Swagger/OpenAPI 文档的 URL（必需）
- \`serverUrl\`: API 服务器 URL（可选，默认从 Swagger 文档获取）

#### 方法

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

```typescript
async initialize(): Promise<void>
```

##### getTools()
获取可用的工具列表。

```typescript
async getTools(): Promise<Tool[]>
```

返回值类型：
```typescript
interface Tool {
  name: string;        // 工具名称
  description: string; // 工具描述
  parameters: {        // 参数定义
    type: string;
    properties: Record<string, any>;
    required: string[];
  };
}
```

##### executeTool()
执行指定的工具。

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

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

返回值类型：
```typescript
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 块处理可能的错误：

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

## 示例

### 基本使用

```typescript
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);
```

### 批量操作

```typescript
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