Torna MCP Server

# Torna MCP Server [](https://pypi.org/project/torna-mcp/) [](https://pypi.org/project/torna-mcp/) [](https://github.com/li7hai26/torna-mcp/blob/main/LICENSE) [](https://github.com/li7hai26/torna-mcp) <<<<<<< HEAD 一个用于与 Torna 接口文档管理平台交互的 MCP（模型上下文协议）服务器。该服务器基于真实的 Torna OpenAPI 规范，提供了5个完整工具，允许 LLM 通过标准化的接口来管理 Torna 中的 API 文档。 **基于真实 Torna API 规范**: http://localhost:7700/api ======= 一个用于与 Torna 接口文档管理平台交互的 MCP（模型上下文协议）服务器。该服务器基于真实的 Torna OpenAPI 规范，提供了2个核心工具，允许 LLM 通过标准化的接口来管理 Torna 中的 API 文档。 **基于真实 Torna API 规范**: http://localhost:7700/api ## 🎉 发布状态 **项目已成功发布到PyPI！** - **包名**: `torna-mcp` - **版本**: `1.0.0` - **PyPI页面**: https://pypi.org/project/torna-mcp/ - **许可证**: MIT - **Python支持**: >=3.8 >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ## 🚀 快速开始 ### 安装 <<<<<<< HEAD #### 方法1：通过 uv 安装（推荐） ```bash # 安装 uv（如果尚未安装） curl -LsSf https://astral.sh/uv/install.sh | sh # 安装包 uv add toma-mcp # 或使用 pip pip install toma-mcp ======= #### 方法1：通过PyPI安装（推荐） ```bash # 使用 pip pip install toma-mcp # 或使用 uv（推荐） uv pip install toma-mcp >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ``` #### 方法2：从源码安装 ```bash <<<<<<< HEAD # 使用 uv uv pip install -e . # 或使用 pip pip install -e . ======= git clone https://github.com/li7hai26/torna-mcp.git cd torna-mcp pip install -e . # 或使用 uv uv pip install -e . >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ``` ### 配置环境变量 ```bash # 设置Torna服务器地址 export TORNA_URL="http://localhost:7700/api" # 设置模块访问令牌 export TORNA_TOKEN="your-module-token-here" ``` **获取Token方法:** 1. 登录 Torna 管理后台 2. 选择项目 3. 选择模块 4. 点击 OpenAPI 标签 5. 复制 token **环境变量文件:** 如果您使用环境变量文件： ```bash cp .env.example .env # 编辑 .env 文件，设置您的 TORNA_URL 和 TORNA_TOKEN ``` <<<<<<< HEAD ======= >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ### 启动MCP服务器 ```bash torna-mcp ``` 启动后，服务器将在标准输出显示连接信息，您可以将其配置到MCP客户端中使用。 ## 📚 功能特性 <<<<<<< HEAD ### 核心 API 接口 (5个工具) ======= ### 核心 API 接口 (2个工具) >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea 基于真实的 Torna OpenAPI 规范实现： - **推送文档** (`torna_push_document`) - 向 Torna 推送 API 文档 - 支持创建分类/文件夹 - 支持请求/响应参数定义 - 支持错误码配置 - 支持调试环境设置 <<<<<<< HEAD - **获取单个文档详情** (`torna_get_document_detail`) - 获取单个文档详细信息 ======= - **获取文档** (`torna_get_document`) - 获取单个文档详细信息 >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea - 获取文档完整信息 - 包括请求/响应参数 - 包括错误码信息 <<<<<<< HEAD - **获取模块信息** (`torna_get_module`) - 获取应用模块基本信息 - 模块名称和描述 - 模块状态信息 - **列出所有文档** (`torna_list_documents`) - 获取完整文档列表 - 获取所有文档和文件夹 - 支持分类结构 - 解决“获取所有文档详情”问题 - **批量获取文档详情** (`torna_get_document_detail_batch`) - 批量获取多个文档详情 - 一次性获取多个文档详细信息 - 高效处理大量文档 - 完整参数列表 ======= >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea **API 规范**: 基于 [Torna 官方 OpenAPI](https://torna.cn/dev/openapi.html) 实现 ## 🛠️ MCP客户端配置 ### Cursor 1. 打开Cursor设置 2. 找到MCP Servers配置 3. 添加新服务器： ```json { "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服务器配置： ```json { "mcpServers": { "torna-mcp": { "command": "torna-mcp" } } } ``` 3. 重启Claude Desktop <<<<<<< HEAD ### VS Code 1. 安装MCP相关扩展 2. 配置服务器连接 3. 使用MCP工具 ======= ### IFlow CLI ```bash # 添加到MCP配置 iflow mcp add toma-mcp ``` 详细的客户端配置说明请参见 [MCP_CLIENTS.md](./MCP_CLIENTS.md) >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ## 📝 使用示例 ### 推送 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": "张三" } ``` ### 获取文档详情 ``` <<<<<<< HEAD 工具: torna_get_document_detail ======= 工具: toma_get_document >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea 参数: { "doc_id": "doc_123" } ``` <<<<<<< HEAD ### 批量获取文档详情 ``` 工具: torna_get_document_detail_batch 参数: { "doc_ids": ["doc_123", "doc_456", "doc_789"] } ``` ### 获取模块信息 ``` 工具: torna_get_module 参数: {} ``` ### 列出所有文档 ``` 工具: torna_list_documents 参数: {} ``` ======= >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ### 创建分类（文件夹） ``` 工具: 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" } ``` ## 🔧 系统要求 ### 环境要求 <<<<<<< HEAD - **Python**: 3.11 或更高版本 - **Torna**: 私有化部署版本 - **MCP客户端**: Cursor、Claude Desktop、VS Code等 ### 开发工具 - **uv**: 现代 Python 包管理器 - **pytest**: 测试框架 - **black**: 代码格式化 - **isort**: 导入排序 - **mypy**: 类型检查 ## 🧪 开发 ### 安装开发依赖 ```bash uv sync --dev ``` ### 运行测试 ```bash uv run pytest ``` ### 代码格式化 ```bash uv run black src/ tests/ uv run isort src/ tests/ ``` ### 类型检查 ```bash uv run mypy src/ ``` ======= - **Python**: 3.8 或更高版本 - **Torna**: 私有化部署版本 - **MCP客户端**: Cursor、Claude Desktop、VS Code等 ### 安装Python环境 - **pip** (标准Python安装) - **uv** (推荐 - 更快更现代的包管理器) ```bash # 安装uv curl -LsSf https://astral.sh/uv/install.sh | sh ``` ## 📖 详细文档 - **[快速开始](./QUICKSTART.md)** - 详细的快速入门指南 - **[安装指南](./INSTALL.md)** - 多种安装方法 - **[MCP客户端配置](./MCP_CLIENTS.md)** - 各种MCP客户端的配置方法 - **[部署指南](./DEPLOYMENT.md)** - 生产环境部署说明 ## 🐛 问题反馈 如果您在使用过程中遇到问题，请： 1. 查看 [GitHub Issues](https://github.com/li7hai26/torna-mcp/issues) 2. 在PyPI页面提交反馈 3. 发送邮件至: li7hai26@gmail.com >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea ## 📄 许可证 本项目采用 MIT 许可证，详情请参见 [LICENSE](./LICENSE) 文件。 ## 👨‍💻 开发者 - **作者**: 阿拉丁神灯 - **邮箱**: li7hai26@gmail.com - **GitHub**: [@li7hai26](https://github.com/li7hai26) <<<<<<< HEAD ## 📋 变更日志 详细变更日志请查看 [CHANGELOG.md](./CHANGELOG.md) ### v0.1.0 (2025-11-12) - Beta版本 - ✨ 初始版本发布 - ✅ 基于真实 Torna OpenAPI 规范实现 (5个工具) - ✅ 解决"获取所有文档详情"的核心问题 - 📦 使用 uv 进行现代化包管理 - 🧪 添加完整测试套件 - 🔧 遵循 MCP 开发通用规范 - 🌏 支持国内镜像加速 ======= >>>>>>> 55eee9a1cddd378865fe2faccee51a0c205a87ea --- **🔗 相关链接** - [PyPI包](https://pypi.org/project/torna-mcp/) - [GitHub仓库](https://github.com/li7hai26/torna-mcp) - [Torna项目](https://gitee.com/dromara/Torna)