YApi MCP Tools

一个基于 Model Context Protocol (MCP) 的 YApi 接口文档查询工具，允许 AI 助手通过 MCP 协议访问和查询 YApi 平台的 API 文档。

🚀 功能特性

• 🔍 YApi 接口查询: 支持查询 YApi 项目中的 API 接口文档
• 🤖 MCP 协议支持: 完全兼容 Model Context Protocol 标准
• 🔐 LDAP 自动登录: 支持通过 LDAP 凭据自动获取和刷新 YApi token
• 📝 TypeScript 支持: 使用 TypeScript 开发，提供类型安全
• 💬 详细注释: 代码包含完整的中文注释
• 📦 npm 包: 已发布到 npm，支持全局安装和项目依赖
• 🛠️ CLI 支持: 提供命令行接口，方便集成到各种工具中

📋 可用工具

1. sayHello

简单的问候工具，用于测试 MCP 服务器连接。

参数:

• name (string, 必需): 要问候的姓名

示例:

{
  "name": "张三"
}

返回:

Hello, 张三! 👋

2. get_yapi_api

查询 YApi 平台的 API 接口文档。

参数:

• projectId (string, 必需): YApi 项目 ID
• apiId (string, 可选): 具体的 API 接口 ID

示例:

{
  "projectId": "12345",
  "apiId": "67890"
}

注意: YApi 服务器地址和 LDAP 凭据通过环境变量配置，无需在参数中传递。系统会自动通过 LDAP 登录获取访问令牌。

返回: 详细的 API 接口信息，包括请求参数、响应参数、接口描述等。

🛠️ 安装和配置

方法一：全局安装（推荐）

# 全局安装
npm install -g @zhangmengtao/yapi-mcp

# 验证安装
yapi-mcp --help

方法二：项目依赖

# 安装到项目
npm install @zhangmengtao/yapi-mcp

# 在 package.json 中添加脚本
{
  "scripts": {
    "mcp": "yapi-mcp"
  }
}

方法三：从源码安装

# 克隆项目
git clone <your-repo-url>
cd yapi_mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（开发模式）
npm link

🔧 配置

1. 获取 LDAP 凭据

1. 联系系统管理员获取 LDAP 用户名和密码
2. 确保你的 LDAP 账户有访问 YApi 的权限

2. 设置环境变量

必需的环境变量：

• YAPI_URL：YApi 服务器地址

可选的环境变量（有默认值）：

• YAPI_LDAP_EMAIL：LDAP 邮箱（默认：yapi）
• YAPI_LDAP_PASSWORD：LDAP 密码（默认：your_ldap_password）

方法一：使用默认凭据（最简单）

export YAPI_URL=https://yapi.yourcompany.com

方法二：使用自定义凭据

export YAPI_URL=https://yapi.yourcompany.com
export [email protected]
export YAPI_LDAP_PASSWORD=your_password

方法三：创建 .env 文件（推荐）

# 创建 .env 文件
echo "YAPI_URL=https://yapi.yourcompany.com" > .env
echo "[email protected]" >> .env
echo "YAPI_LDAP_PASSWORD=your_password" >> .env

方法三：在系统环境变量中设置（永久）

• macOS/Linux: 在 ~/.bashrc 或 ~/.zshrc 中添加
• Windows: 在系统环境变量中设置

🚀 使用方法

在 Cursor 中配置 MCP

1. 打开 Cursor 设置 (Cmd+, 或 Ctrl+,)
2. 搜索 "MCP" 或 "Model Context Protocol"
3. 添加以下配置：

使用默认凭据（推荐）：

{
  "mcpServers": {
    "yapi-mcp": {
      "command": "yapi-mcp",
      "env": {
        "YAPI_URL": "https://yapi.yourcompany.com"
      }
    }
  }
}

使用自定义凭据：

{
  "mcpServers": {
    "yapi-mcp": {
      "command": "yapi-mcp",
      "env": {
        "YAPI_URL": "https://yapi.yourcompany.com",
        "YAPI_LDAP_EMAIL": "[email protected]",
        "YAPI_LDAP_PASSWORD": "your_password"
      }
    }
  }
}

在 Claude Desktop 中配置

1. 打开 Claude Desktop 设置
2. 在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "yapi-mcp": {
      "command": "yapi-mcp",
      "env": {
        "YAPI_URL": "https://yapi.yourcompany.com",
        "YAPI_LDAP_EMAIL": "[email protected]",
        "YAPI_LDAP_PASSWORD": "your_password"
      }
    }
  }
}

使用示例

在 AI 助手中，你可以这样使用：

请使用 get_yapi_api 工具查询项目 22 中 ID 为 123214 的接口

或者：

请使用 sayHello 工具向张三问好

🧪 测试

安装完成后，你可以通过以下方式测试：

# 测试 CLI 命令
yapi-mcp --help

# 在 Cursor 中测试工具调用
请使用 get_yapi_api 工具查询项目 22 中 ID 为 123214 的接口

📁 项目结构

yapi_mcp/
├── src/
│   ├── index.ts          # MCP 服务器主文件
│   └── cli.ts            # CLI 入口文件
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
├── .gitignore           # Git 忽略规则
├── LICENSE              # MIT 许可证
├── README.md            # 项目说明文档
├── QUICKSTART.md        # 快速开始指南
├── PUBLISH.md           # 发布指南
└── env-config.md        # 环境配置说明

🔧 开发

添加新工具

1. 在 src/index.ts 中的 tools 数组中添加工具定义
2. 在 setRequestHandler 中添加对应的处理逻辑

示例：

// 添加工具定义
{
  name: "your_tool_name",
  description: "工具描述",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "参数描述" }
    },
    required: ["param1"]
  }
}

// 添加处理逻辑
if (name === "your_tool_name") {
  const { param1 } = args as { param1: string };
  // 处理逻辑
  return {
    content: [{ type: "text", text: "处理结果" }]
  };
}

构建项目

# 开发模式
npm run dev

# 构建项目
npm run build

# 验证构建
npm run validate

发布新版本

# 发布补丁版本
npm run publish:patch

# 发布小版本
npm run publish:minor

# 发布大版本
npm run publish:major

🔒 安全注意事项

⚠️ 重要安全警告

• 绝不要将真实密码提交到版本控制系统
• 不要在文档或代码中硬编码真实密码
• 使用 .env 文件时，确保将其添加到 .gitignore
• 定期更换 LDAP 密码和访问令牌
• 在生产环境中使用强密码和环境变量
• 确保 YApi 服务器使用 HTTPS 协议
• 限制 LDAP 账户的访问权限，只授予必要的最小权限

🔐 最佳实践

1. 环境变量配置：

   # 生产环境推荐使用环境变量
   export YAPI_URL=https://your-secure-yapi-server.com
   export [email protected]
   export YAPI_LDAP_PASSWORD=your_strong_password_here

2. .env 文件配置：

   # 创建 .env 文件（确保 .gitignore 包含 .env）
   echo "YAPI_URL=https://your-secure-yapi-server.com" > .env
   echo "[email protected]" >> .env
   echo "YAPI_LDAP_PASSWORD=your_strong_password_here" >> .env

3. 权限控制：

   • 使用专门的服务账户，不要使用个人账户
   • 定期轮换密码
   • 监控账户活动

🐛 故障排除

常见问题

1. MCP 服务器无法启动

   • 检查 Node.js 版本是否 >= 18.0.0
   • 确认所有依赖已正确安装

2. YApi API 调用失败

   • 检查 YAPI_URL、YAPI_LDAP_EMAIL 和 YAPI_LDAP_PASSWORD 环境变量是否正确设置
   • 确认 LDAP 凭据是否有效
   • 检查 YApi 服务器地址是否正确
   • 确认 LDAP 账户是否有访问 YApi 的权限

3. 工具调用返回错误

   • 查看服务器日志输出
   • 确认参数格式是否正确
   • 检查网络连接

调试模式

# 启用详细日志
DEBUG=* yapi-mcp

# 或者设置环境变量
export DEBUG=*
yapi-mcp

📝 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📞 支持

如果你遇到任何问题，请：

1. 检查 YAPI_URL、YAPI_LDAP_USERNAME 和 YAPI_LDAP_PASSWORD 环境变量是否正确设置
2. 确认 LDAP 凭据是否有效
3. 查看服务器日志输出
4. 查看 故障排除 部分
5. 提交 Issue 描述问题

🔗 相关链接

• Model Context Protocol 官方文档
• YApi 官方文档
• npm 包页面

注意: 这是一个开源项目，实际使用时请根据你的 YApi 平台配置进行相应调整。