Torna Mcp

torna-mcp

将 Torna API 文档系统与 AI 助手（Cursor、Claude Desktop 等）连接起来的 MCP 服务。通过自然语言查询、搜索和探索 Torna API 文档。

功能介绍

此服务将 Torna API 文档作为 MCP 工具、资源和提示词提供。你的 AI 助手可以：

• 按关键字或自然语言需求搜索 API
• 获取详细的 API 定义
• 生成 curl 命令示例
• 切换项目
• 访问项目元数据

特性

• 零配置身份验证：按连接缓存凭据，无需重复输入
• 批量操作：并发获取多个 API 详情
• 智能匹配：自然语言需求 → 匹配的 API
• 项目切换：随时切换 Torna 项目

快速开始

安装

git clone https://github.com/chenqi146/torna-mcp.git
cd torna-mcp
npm install
npm run build

运行

npm start
# Server runs on http://localhost:3000

也可以使用 Docker：

docker build -t torna-mcp .
docker run -p 3000:3000 torna-mcp

在 Cursor 中配置

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "torna": {
      "transport": "http",
      "url": "http://localhost:3000/mcp",
      "heartbeat": true,
      "headers": {
        "username": "your_torna_username",
        "password": "your_torna_password",
        "projectid": "your_project_id",
        "torna-base-url": "http://your-torna-server:7700"
      }
    }
  }
}

重启 Cursor 并选择 torna MCP 服务。

使用示例

按需求查找 API

你：“我需要一个查询用户信息的 API”

**AI：**使用 torna-find-apis-by-need 匹配 API，并返回：

• 用户详情 API（/api/user/detail）
• 用户列表 API（/api/user/list）

按关键字搜索

你：“查找所有与‘停车’相关的 API”

**AI：**使用关键字“parking”调用 torna-search-docs，并返回匹配的 API。

获取 API 详情

你：“获取以下三个 API 的详情：JzAM4Mzp,AbC123Xy,Def456Za”

**AI：**使用逗号分隔的 docIds 调用 torna-get-doc-detail，并发获取全部详情。

切换项目

你：“有哪些可用项目？切换到 user-center 项目”

**AI：**通过 torna-list-projects 列出项目，并通过 torna-select-project 切换项目。

生成 curl 命令

你：“为用户详情 API 生成一个 curl 命令”

**AI：**使用 torna-generate-request 生成可直接使用的 curl 命令。

MCP 工具

所有工具都会自动使用连接标头中的缓存身份验证信息。

工具	说明
torna-project-info	获取当前会话信息（用户名、项目 ID/名称、令牌状态、文档数量）
torna-search-docs	按关键字搜索 API。关键字为空时返回完整树
torna-get-doc-detail	获取 API 详情。支持单个或逗号分隔的 docIds（批量、并发）
torna-list-projects	列出所有可访问的空间/项目
torna-select-project	切换当前项目，供后续操作使用

MCP 资源

• config://settings - 服务配置示例
• torna://session/project - 当前会话的项目信息
• torna://projects - 实时项目列表

MCP 提示词

• torna-find-apis-by-need - 查找符合自然语言需求的 API。对于 API 数量 ≤30 的项目，会自动获取详情以实现更好的匹配。
• torna-generate-request - 根据 API 定义生成 curl 命令

开发

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Production
npm start

环境变量

• PORT - 服务端口（默认：3000）
• MCP_URL - MCP 服务基础 URL（默认：http://localhost:3000）

日志

• [TornaExternal] - 实际的 Torna API 请求/响应
• [TornaAPI] - MCP 对客户端的响应
• [MCPAuth] - 身份验证事件
• [MCPCapture] - MCP 请求捕获

架构

AI Assistant (Cursor/Claude) 
    ↓ MCP Protocol
torna-mcp Server (this project)
    ↓ HTTP Proxy
Torna API Server

该服务充当 MCP 客户端与 Torna 之间的代理，负责：

• 身份验证（登录、令牌缓存）
• 请求路由（MCP 工具 → Torna 端点）
• 响应转换（Torna 格式 → MCP 格式）

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行更改
4. 提交 pull request

保持简单。不要引入不必要的抽象。

许可证

MIT