6.0 KiB

Raw Blame History

🎉 MCP Swagger Server - 发布完成使用指南

恭喜！您的 mcp-swagger-server 已经成功发布到 NPM！以下是完整的使用指南。

📦 安装

全局安装（推荐）

npm install -g mcp-swagger-server

验证安装

# 检查版本
mcp-swagger-server --help

# 应该显示完整的帮助信息

🚀 快速开始

1. 基础使用

# 从 GitHub API 启动 streamable 服务器
mcp-swagger-server --transport streamable --port 3322 --openapi https://api.github.com/openapi.json

# 从 Petstore API 启动 STDIO 模式（适合 AI 客户端）
mcp-swagger-server --transport stdio --openapi https://petstore.swagger.io/v2/swagger.json

# 从本地文件启动并监控变化
mcp-swagger-server --transport http --openapi ./my-api.yaml --watch

2. 与 Claude Desktop 集成

编辑 Claude Desktop 配置文件：

Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github-api": {
      "command": "mcp-swagger-server",
      "args": [
        "--transport", "stdio",
        "--openapi", "https://api.github.com/openapi.json"
      ]
    },
    "petstore-api": {
      "command": "mcp-swagger-server", 
      "args": [
        "--transport", "stdio",
        "--openapi", "https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

重启 Claude Desktop，现在您可以让 Claude 调用这些 API！

3. VS Code MCP Extension 集成

如果您使用 VS Code MCP 扩展，可以这样配置：

{
  "mcp.servers": [
    {
      "name": "GitHub API",
      "command": "mcp-swagger-server",
      "args": [
        "--transport", "stdio",
        "--openapi", "https://api.github.com/openapi.json"
      ]
    }
  ]
}

🔧 高级用法

环境变量配置

# 设置默认配置
export MCP_PORT=3322
export MCP_TRANSPORT=streamable
export MCP_OPENAPI_URL=https://api.github.com/openapi.json
export MCP_ENDPOINT=/mcp
export MCP_AUTO_RELOAD=true

# 直接运行（使用环境变量）
mcp-swagger-server

进程管理

# 托管模式 - 自动重启
mcp-swagger-server --transport streamable --openapi https://api.example.com/openapi.json --auto-restart

# 使用 PM2 管理
pm2 start "mcp-swagger-server --transport http --openapi https://api.example.com/openapi.json" --name "my-mcp-server"

文件监控

# 监控本地 OpenAPI 文件变化
mcp-swagger-server --transport streamable --openapi ./api.yaml --watch

# 适合开发环境，API 规范变化时自动重载

📋 实际使用场景

场景 1: 内部 API 集成

# 让 AI 助手访问公司内部 API
mcp-swagger-server --transport stdio --openapi https://internal-api.company.com/openapi.json

现在 Claude 可以：

查询用户信息
创建和更新订单
执行业务逻辑操作
获取报表数据

场景 2: API 开发调试

# 开发环境自动同步
mcp-swagger-server --transport http --port 3322 --openapi ./dev-api.yaml --watch

访问 http://localhost:3322 进行交互式 API 测试。

场景 3: 微服务集成

# 为每个微服务启动独立的 MCP 服务器
mcp-swagger-server --transport streamable --port 3001 --openapi https://user-service.com/openapi.json
mcp-swagger-server --transport streamable --port 3002 --openapi https://order-service.com/openapi.json
mcp-swagger-server --transport streamable --port 3003 --openapi https://payment-service.com/openapi.json

🔍 故障排除

常见问题

1. 端口占用

# 检查端口使用
netstat -an | findstr :3322  # Windows
lsof -i :3322                # macOS/Linux

# 使用其他端口
mcp-swagger-server --port 3323

2. OpenAPI 解析失败

# 验证 OpenAPI URL 可访问性
curl -I https://api.github.com/openapi.json

# 检查本地文件格式
mcp-swagger-server --openapi ./api.yaml --validate-only

3. 权限问题（Windows）

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

调试模式

# 启用详细日志
set DEBUG=mcp-swagger:*        # Windows
export DEBUG=mcp-swagger:*     # macOS/Linux

mcp-swagger-server --openapi ./api.yaml

📚 更多资源

🎯 最佳实践

生产环境部署

# 使用 PM2 进程管理
npm install -g pm2
pm2 start "mcp-swagger-server --transport http --openapi https://api.prod.com/openapi.json" --name "mcp-api"
pm2 save
pm2 startup

安全考虑

# 限制访问地址
mcp-swagger-server --transport http --host 127.0.0.1 --openapi ./internal-api.yaml

# 使用环境变量存储敏感 URL
export API_URL="https://api.company.com/openapi.json?token=SECRET"
mcp-swagger-server --openapi $API_URL

性能优化

# 使用本地缓存的 OpenAPI 文件避免网络延迟
curl -o cached-api.json https://api.github.com/openapi.json
mcp-swagger-server --openapi ./cached-api.json

🚀 下一步

尝试不同的传输协议，找到最适合您用例的方式
集成到您的 AI 工作流程中，提升开发效率
为您的内部 API 创建 MCP 服务器，让 AI 助手更智能
参与社区贡献，帮助改进项目

🎉 恭喜！您现在已经掌握了 MCP Swagger Server 的完整使用方法。开始让您的 API 与 AI 无缝集成吧！

6.0 KiB Raw Blame History Unescape Escape