# swagger-connect-mcp

[![npm version](https://img.shields.io/npm/v/swagger-connect-mcp.svg)](https://www.npmjs.com/package/swagger-connect-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

将 Swagger/OpenAPI 文档连接到 Codex、Claude Code、Qoder、Trae、Cursor、OpenCode 和 CodeBuddy。

[中文](#中文) | [English](#english)

## 中文

### 要求

- Node.js >= 20
- npm 或 pnpm

### 安装

~~~bash
npm install --save-dev swagger-connect-mcp
~~~

pnpm 项目使用：

~~~bash
pnpm add -D swagger-connect-mcp
~~~

### 初始化

在业务项目根目录执行。tool 支持：codex、claude-code、qoder、trae、cursor、opencode、codebuddy、all。

按需配置单个 Agent：

~~~bash
# Codex
npx swagger-connect-mcp init --tool codex --url https://example.com/v3/api-docs

# Claude Code
npx swagger-connect-mcp init --tool claude-code --url https://example.com/v3/api-docs

# Qoder
npx swagger-connect-mcp init --tool qoder --url https://example.com/v3/api-docs

# Trae
npx swagger-connect-mcp init --tool trae --url https://example.com/v3/api-docs

# Cursor
npx swagger-connect-mcp init --tool cursor --url https://example.com/v3/api-docs

# OpenCode
npx swagger-connect-mcp init --tool opencode --url https://example.com/v3/api-docs

# CodeBuddy
npx swagger-connect-mcp init --tool codebuddy --url https://example.com/v3/api-docs
~~~

任意命令增加 `--with-instructions` 可同时生成对应 Agent 的联调规则；使用 `all` 可生成全部配置。

同时生成所有 Agent 配置和联调规则：

~~~bash
npx swagger-connect-mcp init \
  --tool all \
  --with-instructions \
  --url https://example.com/v3/api-docs
~~~

init 会生成或合并：

- swagger-mcp.config.json
- 对应 Agent 的 MCP 配置
- 使用 --with-instructions 时生成 AGENTS.md、CLAUDE.md、CODEBUDDY.md 或对应规则文件

不会执行 postinstall，安装包不会自动修改业务项目。

### 多个 Swagger 文档

~~~bash
npx swagger-connect-mcp add billing \
  --url https://example.com/billing/v3/api-docs \
  --base-url https://example.com/billing

npx swagger-connect-mcp remove billing
~~~

配置示例：

~~~json
{
  "sources": {
    "default": {
      "url": "https://example.com/v3/api-docs"
    },
    "billing": {
      "url": "https://example.com/billing/v3/api-docs",
      "baseUrl": "https://example.com/billing"
    }
  },
  "allowRequests": false
}
~~~

支持 OpenAPI 3.x、Swagger 2.0、JSON、YAML 和 Swagger UI 地址。

### 认证

不要提交明文 token，使用环境变量引用：

~~~json
{
  "sources": {
    "private": {
      "url": "https://example.com/v3/api-docs",
      "headers": {
        "Authorization": "Bearer ${SWAGGER_TOKEN}"
      }
    }
  }
}
~~~

~~~powershell
$env:SWAGGER_TOKEN = "your-token"
~~~

### MCP 工具

默认只读：

- swagger_list_sources
- swagger_list_operations
- swagger_get_operation
- swagger_get_schema
- swagger://<source>/openapi

兼容工具：fetch_swagger_info、list_endpoints、get_endpoint_details、validate_api_response。

业务接口请求默认关闭。设置 allowRequests 为 true 后才提供 swagger_request 和 execute_api_request。

### 简洁用法

生成 AGENTS.md 后，只需要告诉 code agent：

~~~text
按 Swagger 联调结算单详情接口，接入当前页面，不要猜字段。
~~~

### 开发与发布

~~~bash
npm run build
npm test
npm pack --dry-run
npm publish --registry=https://registry.npmjs.org
~~~

## English

### Requirements

- Node.js >= 20
- npm or pnpm

### Install

~~~bash
npm install --save-dev swagger-connect-mcp
~~~

For pnpm projects:

~~~bash
pnpm add -D swagger-connect-mcp
~~~

### Initialize

Run from the target project root. Supported tools: codex, claude-code, qoder, trae, cursor, opencode, codebuddy, and all.

Configure one Agent as needed:

~~~bash
# Codex
npx swagger-connect-mcp init --tool codex --url https://example.com/v3/api-docs

# Claude Code
npx swagger-connect-mcp init --tool claude-code --url https://example.com/v3/api-docs

# Qoder
npx swagger-connect-mcp init --tool qoder --url https://example.com/v3/api-docs

# Trae
npx swagger-connect-mcp init --tool trae --url https://example.com/v3/api-docs

# Cursor
npx swagger-connect-mcp init --tool cursor --url https://example.com/v3/api-docs

# OpenCode
npx swagger-connect-mcp init --tool opencode --url https://example.com/v3/api-docs

# CodeBuddy
npx swagger-connect-mcp init --tool codebuddy --url https://example.com/v3/api-docs
~~~

Add `--with-instructions` to generate integration rules for the selected Agent. Use `all` to generate every configuration.

All agents with integration instructions:

~~~bash
npx swagger-connect-mcp init \
  --tool all \
  --with-instructions \
  --url https://example.com/v3/api-docs
~~~

init creates or merges swagger-mcp.config.json, the selected agent configuration, and—when --with-instructions is used—AGENTS.md, CLAUDE.md, CODEBUDDY.md, or native rule files.

There is no postinstall script. Installing the package does not modify the project automatically.

### Multiple Swagger documents

~~~bash
npx swagger-connect-mcp add billing \
  --url https://example.com/billing/v3/api-docs \
  --base-url https://example.com/billing

npx swagger-connect-mcp remove billing
~~~

Example:

~~~json
{
  "sources": {
    "default": { "url": "https://example.com/v3/api-docs" },
    "billing": {
      "url": "https://example.com/billing/v3/api-docs",
      "baseUrl": "https://example.com/billing"
    }
  },
  "allowRequests": false
}
~~~

Supports OpenAPI 3.x, Swagger 2.0, JSON, YAML, and Swagger UI URLs.

### Authentication

Use environment variables instead of committing tokens:

~~~json
{
  "sources": {
    "private": {
      "url": "https://example.com/v3/api-docs",
      "headers": {
        "Authorization": "Bearer ${SWAGGER_TOKEN}"
      }
    }
  }
}
~~~

~~~powershell
$env:SWAGGER_TOKEN = "your-token"
~~~

### MCP tools

Read-only tools:

- swagger_list_sources
- swagger_list_operations
- swagger_get_operation
- swagger_get_schema
- swagger://<source>/openapi

Compatibility aliases: fetch_swagger_info, list_endpoints, get_endpoint_details, validate_api_response.

Business API requests are disabled by default. Set allowRequests to true to enable swagger_request and execute_api_request.

### Short prompt

After generating AGENTS.md:

~~~text
Integrate the settlement detail API using Swagger. Do not guess fields.
~~~

### Development and publishing

~~~bash
npm run build
npm test
npm pack --dry-run
npm publish --registry=https://registry.npmjs.org
~~~

## License

[MIT](LICENSE)