Torna MCP

🚀 Torna MCP Server

一个用于与 Torna 接口文档管理平台交互的 MCP（模型上下文协议）服务器。该服务器基于真实的 Torna OpenAPI 规范，提供了 2 个核心工具，允许 LLM 通过标准化的接口来管理 Torna 中的 API 文档。

🚀 快速开始

📦 安装指南

项目已成功发布到 PyPI！

• 包名：torna-mcp
• 版本：1.0.0
• PyPI 页面：https://pypi.org/project/torna-mcp/
• 许可证：MIT
• Python 支持：>=3.8

以下为您提供两种安装方式：

• 方法 1：通过 PyPI 安装（推荐）

# 使用 pip
pip install toma-mcp

# 或使用 uv（推荐）
uv pip install toma-mcp

• 方法 2：从源码安装

git clone https://github.com/li7hai26/torna-mcp.git
cd torna-mcp
pip install -e .
# 或使用 uv
uv pip install -e .

配置环境变量

# 设置 Torna 服务器地址
export TORNA_URL="http://localhost:7700/api"

# 设置模块访问令牌
export TORNA_TOKEN="your-module-token-here"

获取 Token 方法：

1. 登录 Torna 管理后台
2. 选择项目
3. 选择模块
4. 点击 OpenAPI 标签
5. 复制 token

环境变量文件：如果您使用环境变量文件：

cp .env.example .env
# 编辑 .env 文件，设置您的 TORNA_URL 和 TORNA_TOKEN

启动 MCP 服务器

torna-mcp

启动后，服务器将在标准输出显示连接信息，您可以将其配置到 MCP 客户端中使用。

✨ 主要特性

核心 API 接口 (2 个工具)

基于真实的 Torna OpenAPI 规范实现：

• 推送文档 (torna_push_document) - 向 Torna 推送 API 文档
  • 支持创建分类/文件夹
  • 支持请求/响应参数定义
  • 支持错误码配置
  • 支持调试环境设置
• 获取文档 (torna_get_document) - 获取单个文档详细信息
  • 获取文档完整信息
  • 包括请求/响应参数
  • 包括错误码信息

API 规范：基于 Torna 官方 OpenAPI 实现

💻 使用示例

基础用法

• 推送 API 文档

工具: toma_push_document
参数:
{
  "name": "用户登录",
  "description": "用户登录接口",
  "url": "/api/auth/login",
  "http_method": "POST",
  "content_type": "application/json",
  "request_params": [
    {
      "name": "username",
      "type": "string",
      "description": "用户名",
      "required": true,
      "example": "john_doe"
    },
    {
      "name": "password", 
      "type": "string",
      "description": "密码",
      "required": true,
      "example": "123456"
    }
  ],
  "response_params": [
    {
      "name": "token",
      "type": "string",
      "description": "访问令牌"
    },
    {
      "name": "userId",
      "type": "string", 
      "description": "用户ID"
    }
  ],
  "author": "张三"
}

• 获取文档详情

工具: toma_get_document
参数:
{
  "doc_id": "doc_123"
}

高级用法

• 创建分类（文件夹）

工具: toma_push_document
参数:
{
  "name": "用户管理",
  "description": "用户相关的 API 接口",
  "url": "",
  "http_method": "GET",
  "is_folder": true
}

• 带调试环境的文档

工具: toma_push_document
参数:
{
  "name": "商品查询",
  "description": "查询商品信息",
  "url": "/api/products/{id}",
  "http_method": "GET",
  "content_type": "application/json",
  "path_params": [
    {
      "name": "id",
      "type": "int",
      "description": "商品 ID",
      "required": true,
      "example": "123"
    }
  ],
  "debug_env_name": "测试环境",
  "debug_env_url": "http://localhost:8080"
}

📚 详细文档

• 快速开始 - 详细的快速入门指南
• 安装指南 - 多种安装方法
• MCP 客户端配置 - 各种 MCP 客户端的配置方法
• 部署指南 - 生产环境部署说明

🔧 技术细节

系统要求

• 环境要求
  • Python：3.8 或更高版本
  • Torna：私有化部署版本
  • MCP 客户端：Cursor、Claude Desktop、VS Code 等
• 安装 Python 环境
  • pip (标准 Python 安装)
  • uv (推荐 - 更快更现代的包管理器)

  # 安装 uv
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

开发

• 安装开发依赖

uv sync --dev

• 运行测试

uv run pytest

• 代码格式化

uv run black src/ tests/
uv run isort src/ tests/

• 类型检查

uv run mypy src/

🛠️ MCP 客户端配置

Cursor

1. 打开 Cursor 设置
2. 找到 MCP Servers 配置
3. 添加新服务器：

{
  "mcpServers": {
    "torna-mcp": {
      "command": "torna-mcp",
      "env": {
        "TORNA_URL": "http://localhost:7700/api",
        "TORNA_TOKEN": "your-module-token-here"
      }
    }
  }
}

Claude Desktop

1. 编辑 Claude 配置文件
2. 添加 MCP 服务器配置：

{
  "mcpServers": {
    "torna-mcp": {
      "command": "torna-mcp"
    }
  }
}

3. 重启 Claude Desktop

IFlow CLI

# 添加到 MCP 配置
iflow mcp add toma-mcp

详细的客户端配置说明请参见 MCP_CLIENTS.md

🐛 问题反馈

如果您在使用过程中遇到问题，请：

1. 查看 GitHub Issues
2. 在 PyPI 页面提交反馈
3. 发送邮件至：li7hai26@gmail.com

📄 许可证

本项目采用 MIT 许可证，详情请参见 LICENSE 文件。

👨‍💻 开发者

• 作者：阿拉丁神灯
• 邮箱：li7hai26@gmail.com
• GitHub：@li7hai26

🔗 相关链接

• PyPI 包
• GitHub 仓库
• Torna 项目