RAP2 MCP Server - API Documentation for LLMs and AI Code Editors
RAP2 MCP Server - 将 RAP2 API 文档和接口管理能力无缝集成到 AI 编程助手中，让 LLM 能够直接访问和操作 RAP2 接口文档。
⚡ 快速开始
方式一：直接使用 npx（推荐，无需安装）
# 直接运行，无需安装
npx -y rap2-mcp-tool@latest
方式二：在 AI 编程助手中集成（最推荐）
直接在您的 AI 编程助手（如 Cursor、Claude Desktop）中配置 MCP 服务器，无需手动启动：
{
"mcpServers": {
"rap2": {
"command": "npx",
"args": ["-y", "rap2-mcp-tool@latest"],
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
配置完成后，AI 助手将自动启动 RAP2 MCP 服务器，您可以直接在对话中使用 RAP2 接口文档功能。
🚀 特性
- 🔗 无缝集成 - 标准 MCP 协议，支持所有主流 AI 编程助手
- 📚 接口文档访问 - 直接获取 RAP2 接口详情和文档
- 🔍 智能搜索 - 按关键字搜索接口，支持跨仓库查询
- 🔐 灵活认证 - 支持账号密码和 Cookie 两种认证方式
- 📊 结构化日志 - 完整的请求日志记录，便于调试和监控
- ⚡ 高性能 - 基于 undici 的高性能 HTTP 客户端
- 🛡️ 安全可靠 - 支持多种认证方式，确保数据安全
- 🎯 精准匹配 - 智能接口搜索，快速定位所需 API
- 🔄 实时同步 - 与 RAP2 实例实时同步，确保数据最新
- 📱 跨平台 - 支持 Windows、macOS、Linux 等主流操作系统
- 🔧 易于配置 - 简单的环境变量配置，快速上手
- 📈 可扩展 - 模块化设计，易于扩展新功能
📦 安装方式
推荐方式：使用 npx（无需安装）
# 直接使用最新版本，无需安装
npx -y rap2-mcp-tool@latest
可选方式：全局安装
如果您需要频繁使用命令行工具，可以选择全局安装：
# 使用 npm
npm install -g rap2-mcp-tool
# 使用 pnpm
pnpm add -g rap2-mcp-tool
# 使用 yarn
yarn global add rap2-mcp-tool
开发方式：从源码安装
git clone https://github.com/MarveleE/rap2-mcp.git
cd rap2-mcp
npm install
⚙️ 配置
环境变量
| 变量名 | 必需 | 描述 | 示例 |
|---|---|---|---|
RAP2_BASE_URL | ✅ | RAP2 实例地址 | http://rap2.example.com |
RAP2_EMAIL | 🔄 | 登录邮箱（与密码配对使用） | user@example.com |
RAP2_PASSWORD | 🔄 | 登录密码（与邮箱配对使用） | yourpassword |
RAP2_SID | 🔄 | 已登录的 Cookie SID | koa.sid 值 |
RAP2_SID_SIG | 🔄 | 已登录的 Cookie 签名 | koa.sid.sig 值 |
认证方式说明：支持两种认证方式，二选一即可：
- 账号密码：使用
RAP2_EMAIL+RAP2_PASSWORD- Cookie 认证：使用
RAP2_SID+RAP2_SID_SIG
手动启动服务器（可选）
如果您需要手动启动服务器进行测试或调试：
使用账号密码认证
# 使用 npx（推荐，无需安装）
RAP2_BASE_URL="http://rap2.example.com" \
RAP2_EMAIL="you@example.com" \
RAP2_PASSWORD="yourpass" \
npx -y rap2-mcp-tool@latest
# 或全局安装后使用命令
RAP2_BASE_URL="http://rap2.example.com" \
RAP2_EMAIL="you@example.com" \
RAP2_PASSWORD="yourpass" \
rap2-mcp
使用 Cookie 认证
# 使用 npx（推荐，无需安装）
RAP2_BASE_URL="http://rap2.example.com" \
RAP2_SID="your_sid_value" \
RAP2_SID_SIG="your_sig_value" \
npx -y rap2-mcp-tool@latest
# 或全局安装后使用命令
RAP2_BASE_URL="http://rap2.example.com" \
RAP2_SID="your_sid_value" \
RAP2_SID_SIG="your_sig_value" \
rap2-mcp
🔧 与 AI 编程助手集成
🎯 这是最推荐的使用方式！ 直接在 AI 编程助手中集成，无需手动启动服务器。
通用配置模板（推荐）
{
"mcpServers": {
"rap2": {
"command": "npx",
"args": ["-y", "rap2-mcp-tool@latest"],
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
Cursor 配置
在 Cursor 的 MCP 配置中添加：
{
"mcpServers": {
"rap2": {
"command": "npx",
"args": ["-y", "rap2-mcp-tool@latest"],
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
Claude Desktop 配置
在 Claude Desktop 的配置文件中添加：
{
"mcpServers": {
"rap2": {
"command": "npx",
"args": ["-y", "rap2-mcp-tool@latest"],
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
其他 MCP 客户端
任何支持 MCP 协议的客户端都可以使用此服务器，只需配置相应的启动命令和环境变量。
推荐配置（npx 方式，无需安装）
{
"mcpServers": {
"rap2": {
"command": "npx",
"args": ["-y", "rap2-mcp-tool@latest"],
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
可选配置（全局安装方式）
{
"mcpServers": {
"rap2": {
"command": "rap2-mcp",
"env": {
"RAP2_BASE_URL": "http://rap2.example.com",
"RAP2_EMAIL": "your@email.com",
"RAP2_PASSWORD": "yourpassword"
}
}
}
}
🛠️ 可用工具
RAP2 MCP Server 提供以下工具供 LLM 使用：
rap2_test_connection
测试与 RAP2 服务器的连接状态
- 功能：探测服务器连通性，必要时自动登录
- 用途：验证配置和网络连接
rap2_ensure_session
确保有效的登录会话
- 功能：使用环境变量登录并保存 Cookie 到会话缓存
- 用途：建立和维护认证状态
rap2_debug_login_info
输出当前登录配置摘要
- 功能：显示登录配置信息（不包含明文密码）
- 用途：调试和验证配置
rap2_get_interface_by_id
通过接口 ID 获取接口详情
- 参数：
interfaceId(必需) - RAP2 中的接口 ID - 返回：接口的详细信息，包括 URL、方法、参数和响应数据结构
rap2_get_repository_interfaces
获取指定仓库中的所有接口列表
- 参数：
repositoryId(必需) - RAP2 中的仓库 ID - 返回：仓库中的所有接口列表
rap2_search_interfaces_by_keyword
通过关键字搜索接口
- 参数：
keyword(必需) - 搜索关键字repositoryId(可选) - 限制搜索范围的仓库 ID
- 返回：匹配的接口列表
rap2_search_interfaces_by_path
通过请求路径搜索接口
- 参数：
path(必需) - 请求路径（如：/api/users）repositoryId(可选) - 限制搜索范围的仓库 ID
- 返回：匹配的接口列表
📝 使用示例
在 AI 对话中使用（自然语言触发）
用户：获取接口id123的信息
AI：我来获取接口 123 的详情...
[调用 rap2_nl_get_interface_by_text 工具]
- 识别到接口ID：123
- 已自动登录并获取详情
结果：
方法：GET
路径：/api/demo
...
您也可以直接说：接口456、查看接口789
获取特定接口详情
用户：请告诉我创建用户的接口详情
AI：[调用 rap2_get_interface_by_id 工具]
创建用户接口详情：
- 方法：POST
- URL：/api/users
- 请求参数：
- name (string, 必需) - 用户姓名
- email (string, 必需) - 用户邮箱
- role (string, 可选) - 用户角色
- 响应示例：
{
"id": 123,
"name": "张三",
"email": "zhangsan@example.com",
"role": "user",
"createdAt": "2024-01-01T00:00:00Z"
}
📊 日志和监控
日志文件位置
- 路径：
/tmp/rap-mcp.log - 格式：结构化 JSON 日志
- 内容：服务器请求、响应、错误信息
查看日志
# 实时查看日志
tail -f /tmp/rap-mcp.log
# 查看最近的日志
tail -n 100 /tmp/rap-mcp.log
# 搜索特定内容
grep "ERROR" /tmp/rap-mcp.log
🔧 开发
本地开发
# 克隆仓库
git clone https://github.com/MarveleE/rap2-mcp.git
cd rap2-mcp
# 安装依赖
npm install
# 启动开发服务器
npm run mcp
项目结构
rap2-mcp/
├── src/
│ ├── mcp-server.js # MCP 服务器主文件
│ └── rap2Client.js # RAP2 API 客户端
├── package.json # 项目配置
├── README.md # 项目说明
└── .gitignore # Git 忽略规则
测试
# 运行测试
npm test
# 测试 MCP 连接（开发模式）
npm run mcp
# 测试已发布的包
npx -y rap2-mcp-tool@latest --help
🚨 故障排除
常见问题
1. 连接失败或未登录自动跳转HTML
- 检查
RAP2_BASE_URL是否正确 - 确认网络连接正常
- 验证 RAP2 服务器是否可访问
- 已内置自动登录重试：若遇到 401/403 或返回 HTML 登录页，客户端会尝试一次自动登录并重试请求
2. 认证失败
- 确认邮箱和密码正确
- 检查 Cookie 是否过期
- 验证 RAP2 实例是否支持当前认证方式
- 可在对话中先说“确保已登录”触发
rap2_ensure_session
3. 模块未找到错误
# 使用 npx（推荐，无需安装）
npx -y rap2-mcp-tool@latest
# 或使用全局安装（可选）
npm install -g rap2-mcp-tool
# 验证安装
rap2-mcp --help
4. 权限问题
# 确保有写入日志文件的权限
sudo chmod 666 /tmp/rap-mcp.log
📋 系统要求
- 🟢 Node.js: >= 18.0.0
- 💻 操作系统: Windows, macOS, Linux
- 🧠 内存: 最少 128MB
- 🌐 网络: 需要访问 RAP2 实例的网络连接
- 📦 包管理器: npm, pnpm, yarn
- 🔧 开发工具: 支持 MCP 协议的 AI 编程助手
📄 许可证
本项目采用 MIT 许可证。
🤝 贡献
欢迎贡献代码！请遵循以下步骤：
- 🍴 Fork 本仓库 - 创建您的项目副本
- 🌿 创建特性分支 (
git checkout -b feature/AmazingFeature) - 为您的功能创建分支 - 💾 提交更改 (
git commit -m 'Add some AmazingFeature') - 提交您的改进 - 📤 推送到分支 (
git push origin feature/AmazingFeature) - 推送您的更改 - 🔄 开启 Pull Request - 创建合并请求
贡献类型
- 🐛 Bug 修复 - 修复现有问题
- ✨ 新功能 - 添加新特性
- 📚 文档改进 - 完善文档
- 🎨 代码优化 - 提升代码质量
- 🧪 测试用例 - 增加测试覆盖
📞 支持
如果您遇到问题或有建议，请：
- 🐛 提交 Issue - 报告 Bug 或提出功能请求
- 📖 查看 Wiki - 详细文档和教程
- 💬 联系维护者 - 直接沟通和技术支持
- ⭐ 给项目点赞 - 支持项目发展
- 🍴 Fork 项目 - 参与开源贡献
- 📝 提交 PR - 贡献代码改进
⭐ Star History
如果这个项目对您有帮助，请给我们一个 ⭐！
RAP2 MCP Server - 让 AI 编程助手更智能地处理 API 文档！