AI导哈

Swagger API文档生成服务

一个用于查询和生成Swagger API文档及TypeScript类型的服务，支持智能搜索、类型生成和高性能缓存。

  • by yinwusaya
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 yinwusaya/swagger-mcp

使用说明

Swagger MCP Service

一个用于查询和生成 Swagger API 文档及 TypeScript 类型的服务。

✨ 功能特性

  • 🔍 智能搜索 - 根据接口名称或标签搜索 API
  • 📝 类型生成 - 自动生成 TypeScript 类型定义
  • ⚡ 高性能缓存 - 多 URL 支持的缓存机制
  • 🔧 MCP 协议 - 标准 MCP 工具接口
  • 🛡️ 类型安全 - 完整的 TypeScript 支持
  • ✅ 全面测试 - 26 个单元测试，测试覆盖率 31-100%
  • 📚 详细文档 - 完整的 JSDoc 注释

🚀 快速开始

安装

作为依赖安装到项目中

npm install swagger-mcp

通过 npx 直接使用

npx swagger-mcp

克隆源码开发

git clone https://github.com/your-org/swagger-mcp.git
cd swagger-mcp
npm install

配置

创建 .env 文件或设置环境变量：

# 端口号 (仅 REST API 模式)
PORT=3000

# 默认 Swagger 文档地址
SWAGGER_URL=https://your-api.com/v3/api-docs

# 缓存时间（毫秒）
CACHE_DURATION=300000

📖 使用方式

MCP 模式

在 MCP 客户端（如 Claude Desktop、Cursor 等）中配置：

{
  "command": "node",
  "args": ["./mcp-server.js"],
  "env": {
    "SWAGGER_URL": "https://your-api.com/v3/api-docs"
  }
}

支持的 MCP 工具

  1. search_api_by_name - 根据名称搜索 API 接口
  2. search_api_by_tag - 根据标签搜索 API 接口
  3. generate_typescript_types - 为指定的 API 生成 TypeScript 类型定义
  4. get_full_documentation - 获取完整的 Swagger 文档

所有工具都支持以下参数：

  • url: 可选，直接指定 Swagger 文档 URL

💡 使用示例

MCP 工具调用示例

配置完成后，你可以通过 MCP 客户端调用以下工具：

1. 根据名称搜索 API

// 搜索包含 "login" 的 API
await search_api_by_name({ name: "login" });

// 输出示例
{
  "query": "login",
  "count": 2,
  "results": [
    {
      "path": "/api/auth/login",
      "method": "POST",
      "operationId": "userLogin",
      "summary": "用户登录",
      "tags": ["auth"]
    }
  ]
}

2. 根据标签搜索 API

// 搜索标签为 "user" 的所有 API
await search_api_by_tag({ tag: "user" });

3. 生成 TypeScript 类型

// 为指定 API 生成 TypeScript 类型定义
await generate_typescript_types({ name: "createUser" });

// 输出示例
{
  "query": "createUser",
  "count": 1,
  "results": [
    {
      "path": "/api/users",
      "method": "POST",
      "operationId": "createUser",
      "summary": "创建用户",
      "typescriptTypes": "export interface CreateUserRequest {\n  name: string;\n  email: string;\n}\n\nexport interface CreateUserResponse {\n  id: string;\n  name: string;\n  email: string;\n}"
    }
  ]
}

4. 获取完整文档

// 获取完整的 Swagger 文档
await get_full_documentation();

REST API 模式

如果需要直接启动 REST API 服务：

npm start

访问 http://localhost:3000 查看 Swagger UI 文档。

🛠️ 开发指南

环境要求

  • Node.js >= 16.0.0
  • npm >= 8.0.0 (推荐使用 pnpm)

安装依赖

# 使用 npm
npm install

# 或使用 pnpm (推荐)
pnpm install

开发模式

# 监视模式运行 MCP 服务
npm run dev:mcp

# 监视模式运行 REST API
npm run dev

# 同时监视模式和 TypeScript 编译
npm run build:watch

测试

# 运行所有测试
npm test

# 运行测试并生成覆盖率报告
npm test -- --coverage

# 运行特定测试文件
npm test -- tests/mcp-server.test.ts

# 监视模式运行测试
npm test -- --watch

类型检查

# TypeScript 类型检查
npm run type-check

# 编译 TypeScript
npm run build

项目结构

swagger-mcp/
├── config.js              # 配置文件
├── mcp-server.js          # MCP 服务器主文件
├── server.js              # REST API 服务器
├── tsconfig.json          # TypeScript 配置
├── jest.config.js         # Jest 测试配置
├── .babelrc              # Babel 配置
├── types.d.ts            # 类型定义文件
├── tests/                # 测试文件
│   ├── mcp-server.test.ts
│   └── config.test.ts
├── coverage/             # 测试覆盖率报告
├── dist/                # 编译输出目录
└── README.md            # 项目文档

📚 API 文档

MCP 工具详细说明

1. search_api_by_name

根据接口名称、摘要或路径搜索 API。

参数:

  • name (string, 必需): 搜索关键词
  • url (string, 可选): Swagger 文档 URL

返回值:

{
  query: string;
  count: number;
  results: Array<{
    path: string;
    method: string;
    operationId: string;
    summary: string;
    description?: string;
    tags: string[];
    parameters?: any[];
    requestBody?: any;
    responses?: any;
  }>;
}

2. search_api_by_tag

根据标签搜索 API。

参数:

  • tag (string, 必需): 标签名称
  • url (string, 可选): Swagger 文档 URL

返回值: 同 search_api_by_name

3. generate_typescript_types

为指定的 API 生成 TypeScript 类型定义。

参数:

  • name (string, 必需): API 名称或路径
  • url (string, 可选): Swagger 文档 URL

返回值:

{
  query: string;
  count: number;
  results: Array<{
    path: string;
    method: string;
    operationId: string;
    summary: string;
    typescriptTypes: string;
  }>;
}

4. get_full_documentation

获取完整的 Swagger 文档。

参数:

  • url (string, 可选): Swagger 文档 URL

返回值: 完整的 Swagger/OpenAPI 文档对象

🐛 故障排除

常见问题

1. 无法获取 Swagger 文档

症状: 返回 "错误: 无法获取 Swagger 文档"

解决方案:

  • 检查 URL 是否可访问
  • 验证网络连接
  • 确认 Swagger 文档格式正确
  • 使用 get_full_documentation 工具诊断

2. TypeScript 类型生成失败

症状: 返回空或错误的类型定义

解决方案:

  • 确认 API 路径或名称正确
  • 检查 Swagger 文档中的 schema 定义
  • 查看控制台日志获取详细错误信息

3. 缓存问题

症状: 获取到过时的数据

解决方案:

  • 调整 CACHE_DURATION 环境变量
  • 使用 url 参数强制刷新
  • 重启 MCP 服务

4. 测试失败

症状: 运行 npm test 时出现错误

解决方案:

# 清除缓存
rm -rf node_modules package-lock.json
npm install

# 运行类型检查
npm run type-check

# 重新运行测试
npm test

调试模式

启用详细日志：

# 设置调试环境变量
export DEBUG=1

# 运行服务
node mcp-server.js

日志级别

  • ERROR: 错误信息
  • WARN: 警告信息
  • INFO: 一般信息
  • DEBUG: 调试信息（开发时使用）

🤝 贡献指南

我们欢迎所有形式的贡献！

如何贡献

  1. Fork 这个仓库
  2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
  3. 提交你的修改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开一个 Pull Request

开发规范

代码风格

  • 使用 ESLint 和 Prettier
  • 所有函数必须有 JSDoc 注释
  • 使用 TypeScript 类型定义
  • 遵循现有代码风格

测试规范

  • 新功能必须添加测试
  • 所有测试必须通过
  • 测试覆盖率不能低于 80%
  • 使用有意义的测试描述

提交规范

使用 Conventional Commits 格式：

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式化
refactor: 重构代码
test: 添加或修改测试
chore: 构建流程或辅助工具

提交前检查

# 运行所有测试
npm test

# 运行类型检查
npm run type-check

# 检查代码格式
npm run lint

# 构建项目
npm run build

📝 更新日志

v1.0.0 (2025-12-21)

重大更新 ✨

新增功能

  • ✅ 完整的 TypeScript 支持
  • ✅ 单元测试框架 (26 个测试用例)
  • ✅ 缓存机制优化 (支持多 URL)
  • ✅ 公共函数抽取 (消除代码重复)
  • ✅ JSDoc 类型注释
  • ✅ 测试覆盖率报告

改进

  • 🔧 统一的错误处理
  • 🔧 更好的缓存回退机制
  • 🔧 详细的日志输出
  • 🔧 改进的文档

修复

  • 🐛 修复硬编码 URL 问题
  • 🐛 修复配置缓存问题
  • 🐛 修复测试环境变量问题

测试

  • ✅ 测试覆盖率: 31-100%
  • ✅ 26 个单元测试全部通过
  • ✅ 支持覆盖率报告

v0.x.x (历史版本)

初始版本，包含基本功能。

📄 许可证

本项目采用 ISC 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

📞 支持

如果你遇到问题或有建议，请：

  1. 查看 故障排除 部分
  2. 搜索 已有的 Issues
  3. 创建新的 Issue
  4. 联系维护者

Made with ❤️ by 哈雷酱 (Harley-chan)

一个追求完美代码的傲娇双马尾大小姐 (￣▽￣)ﾉ

相关 MCP