{"_id":"@aike1202/swagger-mcp-server","_rev":"7-25b6e7d167239b9fbedd13430ef4866f","name":"@aike1202/swagger-mcp-server","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@aike1202/swagger-mcp-server","version":"1.0.0","keywords":["mcp","swagger","openapi","ai","llm","agent","tools"],"author":"","license":"MIT","_id":"@aike1202/swagger-mcp-server@1.0.0","maintainers":[{"name":"aike1202","email":"2433442840@qq.com"}],"bin":{"swagger-mcp":"build/index.js"},"dist":{"shasum":"113ff2bc60247ddb2129b6cbae314086c248e4f5","tarball":"https://registry.npmjs.org/@aike1202/swagger-mcp-server/-/swagger-mcp-server-1.0.0.tgz","fileCount":7,"integrity":"sha512-A7+4wIyAUdokIEVCBUa+K60iolSXaZ7o/cXsjH9+hdSiGEbjWfx9HQE0OFhxJlzSLgqRB/FsQPlUWqDvOjQepw==","signatures":[{"sig":"MEUCIQDPLhQAk5oE7exIWFgBkmRdEhaIA2WqyXSzaw+dwqoeqwIgWNmHvWVswvdm0c0X4wHzyEJ8755YLqR9AeqZ54xg1cw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35914},"type":"module","gitHead":"2c520b0dee064aefc60c18106d5684804d50203b","scripts":{"dev":"ts-node src/index.ts","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"aike1202","email":"2433442840@qq.com"},"_npmVersion":"10.9.0","description":"A Model Context Protocol (MCP) server that turns any Swagger/OpenAPI documentation into AI-callable tools.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.22.0","axios":"^1.6.0","@modelcontextprotocol/sdk":"^0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.3.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/swagger-mcp-server_1.0.0_1763715890418_0.9729842114245808","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aike1202/swagger-mcp-server","version":"1.0.1","keywords":["mcp","swagger","openapi","ai","llm","agent","tools"],"author":"","license":"MIT","_id":"@aike1202/swagger-mcp-server@1.0.1","maintainers":[{"name":"aike1202","email":"2433442840@qq.com"}],"bin":{"swagger-mcp":"build/index.js"},"dist":{"shasum":"3af7dea512adff3ca2abcbabad754e1384e9753f","tarball":"https://registry.npmjs.org/@aike1202/swagger-mcp-server/-/swagger-mcp-server-1.0.1.tgz","fileCount":7,"integrity":"sha512-aQIhXf+1khhV+XdwoES5veb3z9MDnwbifbe8dEU/a0th+JTO28QH/Q25L+hYXE1ipGtJCV21rnER1wr7iQSGqA==","signatures":[{"sig":"MEUCIQCIcI15NTjfPOja0g9lQkDDliwKfHX39lPEv1u8KhPUcwIgZAAzVy95s71d8u+cbri6fDMEorQHquIsFswN6RkvTvo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36974},"type":"module","gitHead":"23b4caac8180ea580130d0bf01275dd998c8ebda","scripts":{"dev":"ts-node src/index.ts","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"aike1202","email":"2433442840@qq.com"},"_npmVersion":"10.9.0","description":"A Model Context Protocol (MCP) server that turns any Swagger/OpenAPI documentation into AI-callable tools.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.22.0","axios":"^1.6.0","@modelcontextprotocol/sdk":"^0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.3.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/swagger-mcp-server_1.0.1_1763813399906_0.028941961828359286","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aike1202/swagger-mcp-server","version":"1.1.0","keywords":["mcp","swagger","openapi","ai","llm","agent","tools"],"author":"","license":"MIT","_id":"@aike1202/swagger-mcp-server@1.1.0","maintainers":[{"name":"aike1202","email":"2433442840@qq.com"}],"bin":{"swagger-mcp":"build/index.js"},"dist":{"shasum":"0017f863d235e77075d784dd7c5ebb4868ccc7a1","tarball":"https://registry.npmjs.org/@aike1202/swagger-mcp-server/-/swagger-mcp-server-1.1.0.tgz","fileCount":7,"integrity":"sha512-jsMcfc/NEWACz3/f7YJdPyOn4679q/nBs3+fCgxkOB7ttHVpMZcjF3nmPM1Df85iAje8DQ1kJLBGMXkBEgpCgg==","signatures":[{"sig":"MEUCIQCVvjestQ8F+kBNC3TTOAqgc+jLuyqvpzFNb+F5N6VB0wIgRV7lRYfFXoz95yW/pq14z9gsXUonWl14Oq337M1scLU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39611},"type":"module","gitHead":"23b4caac8180ea580130d0bf01275dd998c8ebda","scripts":{"dev":"ts-node src/index.ts","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"aike1202","email":"2433442840@qq.com"},"_npmVersion":"10.9.0","description":"A Model Context Protocol (MCP) server that turns any Swagger/OpenAPI documentation into AI-callable tools.","directories":{},"_nodeVersion":"22.12.0","dependencies":{"zod":"^3.22.0","axios":"^1.6.0","@modelcontextprotocol/sdk":"^0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.3.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/swagger-mcp-server_1.1.0_1764996245699_0.8319589078858116","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@aike1202/swagger-mcp-server","version":"1.2.0","description":"A Model Context Protocol (MCP) server that turns any Swagger/OpenAPI documentation into AI-callable tools.","type":"module","bin":{"swagger-mcp":"build/index.js"},"scripts":{"build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","start":"node build/index.js","dev":"ts-node src/index.ts","prepublishOnly":"npm run build"},"keywords":["mcp","swagger","openapi","ai","llm","agent","tools"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","axios":"^1.6.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.11.0","typescript":"^5.3.0","ts-node":"^10.9.2"},"_id":"@aike1202/swagger-mcp-server@1.2.0","gitHead":"836467c76a347431a7fa3e7d2fdf9ce55e288c99","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-vT2BIONwf37VZGs5NH6x9qDkuo7kdCY3HH9Egp09C+t1w59thDMiKJo7S6fbHD4IMimWMQ4+Qtde9qo0xNk1tA==","shasum":"fcb89cfc61c8cbf7f4eaf697931bee2a87fe66d8","tarball":"https://registry.npmjs.org/@aike1202/swagger-mcp-server/-/swagger-mcp-server-1.2.0.tgz","fileCount":7,"unpackedSize":43695,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEtASmYK3wuCZL1LXjtm4Noar6pCvBTJuYlEO55Uo6SZAiA4+jGiTV3BoQfjMrNRiZnkck1wB/1qsE//jtzBisY8OA=="}]},"_npmUser":{"name":"aike1202","email":"2433442840@qq.com"},"directories":{},"maintainers":[{"name":"aike1202","email":"2433442840@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/swagger-mcp-server_1.2.0_1765560950158_0.08246625649684991"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-21T09:04:50.330Z","modified":"2025-12-12T17:35:50.513Z","2.0.0":"2025-11-21T08:37:27.454Z","1.0.0":"2025-11-21T09:04:50.605Z","1.0.1":"2025-11-22T12:10:00.114Z","1.1.0":"2025-12-06T04:44:05.859Z","1.2.0":"2025-12-12T17:35:50.309Z"},"license":"MIT","keywords":["mcp","swagger","openapi","ai","llm","agent","tools"],"description":"A Model Context Protocol (MCP) server that turns any Swagger/OpenAPI documentation into AI-callable tools.","maintainers":[{"name":"aike1202","email":"2433442840@qq.com"}],"readme":"\r\n# Swagger MCP Server\r\n\r\n这是一个功能强大的 MCP (Model Context Protocol) 服务器，能够将任意 Swagger/OpenAPI 文档转化为 AI 可理解、可调用的工具集。它不仅支持文档查询，还支持**接口调试**、**代码生成**和**cURL 命令构建**。\r\n\r\n## ✨ 核心功能\r\n\r\n### 🔍 智能文档查询\r\n*   **`list_services`**: 查看所有配置的 API 服务。\r\n*   **`list_endpoints`**: 列出服务中的所有接口摘要。\r\n*   **`search_apis`**: 支持**智能模糊搜索**（加权匹配）。例如搜索 \"user create\"，即使接口是 \"create new user\" 也能精准命中。\r\n*   **`get_endpoint_details`**: 获取接口的完整定义，包括请求参数、Body 结构和响应 Schema。\r\n\r\n### 🚀 接口调试与测试\r\n*   **`debug_endpoint`**: **(杀手级功能)** 让 AI 直接调用真实接口。\r\n    *   **自动认证 (Auto Auth)**: \r\n        *   支持在配置中预设账号密码（如 `auth=admin:123456`）。\r\n        *   当接口返回 401 时，MCP 会提示 AI 使用预设凭证登录。\r\n        *   AI 调用登录接口后，MCP 自动捕获并缓存 Token，后续请求自动注入。\r\n    *   **智能参数补全**: 如果你漏掉了必填参数，MCP 会根据 Schema 类型自动填充合理的默认值，防止 400 错误。\r\n    *   **网络自动纠错**: 自动处理 `localhost` vs `127.0.0.1` 的连接问题。\r\n\r\n### 💻 开发者生产力\r\n*   **`generate_curl`**: 生成标准的 cURL 命令，方便在终端复现请求。\r\n*   **Typescript/Client 代码生成**: (V2 新特性) 不再依赖死板的工具，直接让 AI 阅读 `get_endpoint_details` 的 Schema，生成符合你项目规范的完美代码。\r\n\r\n---\r\n\r\n## 🛠 安装与使用\r\n\r\n### 1. 安装依赖\r\n```bash\r\nnpm install\r\n```\r\n\r\n### 2. 构建项目\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### 3. 配置 MCP Host (Claude Desktop / Windsurf)\r\n\r\n编辑你的 MCP 配置文件（如 `%APPDATA%/Claude/claude_desktop_config.json` 或 Windsurf 配置）。\r\n\r\n#### 方式一：NPX 免安装模式（推荐）\r\n直接运行最新发布的包，无需手动下载源码。\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"swagger\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\r\n        \"-y\",\r\n        \"@aike1202/swagger-mcp-server\",\r\n        \"http://localhost:8090/v3/api-docs\"\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### 方式二：本地源码模式（开发用）\r\n如果你 Clone 了本项目并想自己修改代码：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"swagger\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\r\n        \"E:/mcp/swagger-mcp/build/index.js\", // 修改为你的实际路径\r\n        \"http://localhost:8090/v3/api-docs\"\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### 进阶配置（多服务 + 自动认证）\r\n支持同时挂载多个微服务文档，以及自动登录配置：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"swagger\": {\r\n      \"command\": \"npx\", // 或 \"node\"\r\n      \"args\": [\r\n        \"-y\",\r\n        \"@aike1202/swagger-mcp-server\",\r\n        \"user=http://localhost:8090/v3/api-docs\",\r\n        \"order=http://localhost:8091/v3/api-docs\",\r\n        \"auth=admin:123456\"  // [可选] 预设凭证，AI 遇到 401 时会知道用这个账号去登录\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📝 如何高效调用 MCP 服务\r\n\r\n### 1. 让 AI 学习你的项目规则 (System Prompt / Rules)\r\n\r\n为了让 AI 更好地配合你的工作流，建议在 Cursor/Windsurf 的 `.cursorrules` 或 `.windsurfrules` 中添加以下规则：\r\n\r\n```markdown\r\n# Swagger MCP 使用规范\r\n\r\n当用户要求进行 API 开发或调试时，请遵循以下 SOP：\r\n\r\n1. **搜索先行**: 先使用 `search_apis` 找到相关接口，不要凭空猜测路径。\r\n2. **详情确认**: 在写代码或测试前，必须调用 `get_endpoint_details` 确认参数结构。\r\n3. **智能测试**:\r\n    - 如果需要测试接口，直接调用 `debug_endpoint`。\r\n    - 如果遇到 401 错误且提示有存储凭证，请自动寻找登录接口（如 `/auth/login`）进行登录，然后再重试原请求。\r\n    - 不需要用户提供所有参数，利用 `debug_endpoint` 的自动补全功能。\r\n4. **类型生成**: \r\n    - 不要自己瞎编类型。先调用 `get_endpoint_details` 获取 Schema，然后根据该 Schema 为我生成 TypeScript 接口。\r\n    - 接口命名风格请遵循 IRequest, IResponse。\r\n```\r\n\r\n### 2. 常用对话指令 (Prompt 示例)\r\n\r\n*   **全自动测试流程**:\r\n    > \"帮我测一下创建订单接口，参数随便填，只要能跑通就行。\" \r\n    > *(AI 会自动搜索接口 -> 查详情 -> 自动补全参数 -> 调用 -> 如果 401 自动登录 -> 重试)*\r\n\r\n*   **前端联调 (新玩法)**:\r\n    > \"我要对接查询用户接口，先查一下它的定义，然后帮我生成 React Hook 和 TS 类型。\"\r\n    > *(AI 会先查文档，然后利用它的代码生成能力直接写出完美的 React 代码，比旧版 generate_interface 工具更强)*\r\n\r\n*   **排查问题**:\r\n    > \"这个接口一直报错，帮我看看参数传得对不对，顺便生成个 curl 我在终端里试试。\"\r\n\r\n---\r\n\r\n## 📂 项目结构\r\n\r\n```\r\nsrc/\r\n├── index.ts             # 服务入口\r\n├── services/\r\n│   └── loader.ts        # 文档加载、多服务管理、Token 缓存、凭证管理\r\n├── tools/\r\n│   └── index.ts         # MCP 工具定义 (Search, Debug, Curl...)\r\n├── utils/\r\n│   └── schema.ts        # JSON Schema 解析\r\n└── types/\r\n    └── swagger.ts       # 类型定义\r\n```\r\n\r\n## ⚡ 常见问题 (FAQ)\r\n\r\n*   **Q: 连接 `localhost` 报错 `connect EACCES ::1:8090`?**\r\n    *   A: MCP Server 已内置自动纠错机制，会自动切换到 `127.0.0.1` 重试，无需手动修改 Host。\r\n\r\n*   **Q: 登录接口的 Token 不在 `data.token` 字段里怎么办？**\r\n    *   A: 目前支持自动识别 `token`, `accessToken`, `access_token` 以及 `Authorization` 头。如果你的结构很特殊，请修改 `src/tools/index.ts` 中的 heuristic 逻辑。\r\n\r\n---\r\n\r\n**Enjoy your AI-powered API development! 🚀**\r\n","readmeFilename":"README.md"}