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 項目