testhub-mcp 0.1.0__tar.gz

testhub_mcp-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Logs
+*.log
+logs/
+
+# Database
+*.db
+*.sqlite3
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build output
+frontend/dist/
+frontend/build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# Pytest
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+

testhub_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: testhub-mcp
+Version: 0.1.0
+Summary: TestHub MCP Server - 提供开发任务管理和项目文档集成
+Author: TestHub Team
+License: MIT
+Keywords: cursor,documentation,mcp,testhub
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
+Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: sse-starlette>=1.6.0; extra == 'all'
+Requires-Dist: starlette>=0.27.0; extra == 'all'
+Requires-Dist: uvicorn>=0.23.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: sse
+Requires-Dist: sse-starlette>=1.6.0; extra == 'sse'
+Requires-Dist: starlette>=0.27.0; extra == 'sse'
+Requires-Dist: uvicorn>=0.23.0; extra == 'sse'
+Description-Content-Type: text/markdown
+
+# TestHub MCP Server
+
+TestHub MCP Server 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，用于在 Cursor IDE 中集成 TestHub 开发管理系统。通过 MCP 协议，AI 助手可以直接与 TestHub 交互，实现任务管理、评审文档生成、会话同步等功能。
+
+## 功能特性
+
+- 📋 **任务管理**：获取任务详情、更新状态、查看待办列表
+- 📝 **评审文档**：自动生成设计文档、代码评审文档
+- 💾 **会话同步**：记录开发会话、关键决策、修改文件
+- 🐛 **Bug 管理**：快速创建 Bug 报告
+- 📚 **文档访问**：访问项目文档资源
+
+## 快速开始
+
+### 前置要求
+
+- Python >= 3.10
+- Cursor IDE
+- TestHub 后端服务运行中
+
+### 安装方式
+
+#### 方式一：使用 uvx（推荐）
+
+无需单独安装，直接在 Cursor 配置中使用：
+
+```json
+{
+  "mcpServers": {
+    "testhub": {
+      "command": "uvx",
+      "args": ["--from", "path/to/testhub_mcp", "testhub-mcp"],
+      "env": {
+        "TESTHUB_API_URL": "https://testhub.yourcompany.com/api/v1",
+        "TESTHUB_API_TOKEN": "your-personal-api-token",
+        "TESTHUB_TEAM_ID": "2",
+        "TESTHUB_SESSION_ID": "15"
+      }
+    }
+  }
+}
+```
+
+#### 方式二：使用 pip 安装
+
+```bash
+# 进入 testhub_mcp 目录
+cd testhub_mcp
+
+# 安装到当前环境
+pip install -e .
+
+# 或使用 uv
+uv pip install -e .
+```
+
+### 配置 Cursor
+
+1. 创建或编辑 Cursor MCP 配置文件：
+
+   **全局配置**（适用于所有项目）：
+   ```
+   ~/.cursor/mcp.json
+   ```
+
+   **项目配置**（仅适用于当前项目）：
+   ```
+   项目根目录/.cursor/mcp.json
+   ```
+
+2. 添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "testhub": {
+      "command": "testhub-mcp",
+      "env": {
+        "TESTHUB_API_URL": "https://testhub.yourcompany.com/api/v1",
+        "TESTHUB_API_TOKEN": "your-personal-api-token",
+        "TESTHUB_TEAM_ID": "2",
+        "TESTHUB_SESSION_ID": "15"
+      }
+    }
+  }
+}
+```
+
+### 配置 Cursor Rules
+
+将 `cursor_rules/testhub-integration.mdc` 文件复制到项目的 `.cursor/rules/` 目录：
+
+```bash
+mkdir -p .cursor/rules
+cp cursor_rules/testhub-integration.mdc .cursor/rules/
+```
+
+或者手动创建符号链接（推荐，便于更新）：
+
+```bash
+mkdir -p .cursor/rules
+ln -s ../../cursor_rules/testhub-integration.mdc .cursor/rules/testhub-integration.mdc
+```
+
+### 环境变量
+
+| 变量名 | 必填 | 说明 | 示例 |
+|-------|------|------|------|
+| `TESTHUB_API_URL` | ✅ | TestHub API 地址 | `https://testhub.yourcompany.com/api/v1` |
+| `TESTHUB_API_TOKEN` | ✅ | 个人 API Token | `th_xxx_xxxxx` |
+| `TESTHUB_TEAM_ID` | ✅ | 团队 ID | `2` |
+| `TESTHUB_SESSION_ID` | ⚠️ 推荐 | 默认开发会话 ID，创建任务时自动关联 | `15` |
+| `PROJECT_DOCS_PATH` | ⬜ | 项目文档路径 | `./docs` |
+
+> **💡 提示**：`TESTHUB_SESSION_ID` 虽然不是必填，但强烈建议配置。它确保所有通过 MCP 创建的任务、会话等数据都能关联到正确的开发迭代。你可以在 TestHub 前端的"开发管理"中找到活跃会话的 ID。
+
+## 使用说明
+
+### 基本工作流
+
+1. **开始任务**
+   
+   在 Cursor 中说：
+   ```
+   开始任务 TASK-042
+   ```
+   
+   AI 助手会：
+   - 调用 `testhub_get_task` 获取任务详情
+   - 显示任务标题、描述、验收标准
+   - 更新任务状态为"进行中"
+
+2. **开发完成后提交评审**
+   
+   在 Cursor 中说：
+   ```
+   功能完成了，帮我提交评审
+   ```
+   
+   AI 助手会：
+   - 分析修改的代码
+   - 自动生成评审文档（数据模型设计、API 设计、代码评审等）
+   - 上传文档到 TestHub
+   - 提交评审
+
+3. **结束会话**
+   
+   在 Cursor 中说：
+   ```
+   今天先到这，同步一下
+   ```
+   
+   AI 助手会：
+   - 整理本次会话的工作摘要
+   - 记录修改的文件、关键决策
+   - 同步到 TestHub
+
+### 可用命令
+
+| 触发语句 | 功能 |
+|---------|------|
+| "开始任务 TASK-XXX" | 获取任务详情并开始任务 |
+| "我的任务" | 查看待办任务列表 |
+| "功能完成了" | 生成评审文档并提交 |
+| "同步一下" | 同步当前会话记录 |
+| "这里有个 bug" | 创建 Bug 报告 |
+
+## 可用工具
+
+### 任务管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_get_task` | 获取任务详情 | `task_code` (必填) |
+| `testhub_update_task_status` | 更新任务状态 | `task_code`, `status` |
+| `testhub_list_my_tasks` | 获取我的待办任务 | `status`, `limit` |
+| `testhub_create_task` | 创建新任务 | `title`, `description`, `complexity` |
+| `testhub_start_task` | 开始任务 | `task_code` |
+| `testhub_complete_task` | 完成任务 | `task_code` |
+
+### 评审管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_create_review` | 创建功能评审 | `task_code` |
+| `testhub_add_review_document` | 添加评审文档 | `task_code`, `doc_type`, `title`, `content` |
+| `testhub_submit_review` | 提交评审 | `task_code` |
+
+### 会话管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_sync_dev_session` | 同步开发会话 | `session_summary`, `files_changed`, `key_decisions` |
+| `testhub_list_sessions` | 列出开发会话 | `limit` |
+| `testhub_switch_session` | 切换开发会话 | `session_id` |
+
+### Bug 管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_create_bug` | 创建 Bug | `title`, `description`, `severity`, `related_task_code` |
+
+### 上下文管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_get_context` | 获取当前上下文 | - |
+| `testhub_switch_task` | 切换当前任务 | `task_code` |
+
+## 开发
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd TestHub/testhub_mcp
+
+# 创建虚拟环境
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+```
+
+### 测试 MCP Server
+
+使用 MCP Inspector 进行测试：
+
+```bash
+# 安装 MCP Inspector
+npm install -g @modelcontextprotocol/inspector
+
+# 启动测试
+npx @modelcontextprotocol/inspector testhub-mcp
+```
+
+## 目录结构
+
+```
+testhub_mcp/
+├── __init__.py          # 包初始化
+├── server.py            # MCP Server 主入口
+├── config.py            # 配置管理
+├── api_client.py        # TestHub API 客户端
+├── tools/               # MCP 工具实现
+│   ├── __init__.py
+│   ├── task.py          # 任务管理工具
+│   ├── review.py        # 评审管理工具
+│   ├── session.py       # 会话同步工具
+│   ├── bug.py           # Bug 管理工具
+│   └── docs.py          # 文档工具
+├── resources/           # MCP 资源提供者
+│   ├── __init__.py
+│   └── docs.py          # 文档资源
+├── pyproject.toml       # 项目配置
+└── README.md            # 本文件
+```
+
+## 故障排除
+
+### MCP Server 无法启动
+
+1. 检查 Python 版本 >= 3.10
+2. 确认环境变量已正确配置
+3. 查看 Cursor 日志：`Help > Toggle Developer Tools > Console`
+
+### 无法连接 TestHub
+
+1. 检查 `TESTHUB_API_URL` 是否正确
+2. 确认 API Token 有效
+3. 确认网络可访问 TestHub 服务
+
+### 工具调用失败
+
+1. 检查必填参数是否提供
+2. 查看错误信息中的详细说明
+3. 确认对应的后端 API 已实现
+
+## 许可证
+
+MIT
+
+## 相关链接
+
+- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
+- [Cursor MCP 配置指南](https://docs.cursor.com/mcp)
+- [TestHub 项目主页](../README.md)
+

testhub_mcp-0.1.0/README.md

@@ -0,0 +1,293 @@
+# TestHub MCP Server
+
+TestHub MCP Server 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，用于在 Cursor IDE 中集成 TestHub 开发管理系统。通过 MCP 协议，AI 助手可以直接与 TestHub 交互，实现任务管理、评审文档生成、会话同步等功能。
+
+## 功能特性
+
+- 📋 **任务管理**：获取任务详情、更新状态、查看待办列表
+- 📝 **评审文档**：自动生成设计文档、代码评审文档
+- 💾 **会话同步**：记录开发会话、关键决策、修改文件
+- 🐛 **Bug 管理**：快速创建 Bug 报告
+- 📚 **文档访问**：访问项目文档资源
+
+## 快速开始
+
+### 前置要求
+
+- Python >= 3.10
+- Cursor IDE
+- TestHub 后端服务运行中
+
+### 安装方式
+
+#### 方式一：使用 uvx（推荐）
+
+无需单独安装，直接在 Cursor 配置中使用：
+
+```json
+{
+  "mcpServers": {
+    "testhub": {
+      "command": "uvx",
+      "args": ["--from", "path/to/testhub_mcp", "testhub-mcp"],
+      "env": {
+        "TESTHUB_API_URL": "https://testhub.yourcompany.com/api/v1",
+        "TESTHUB_API_TOKEN": "your-personal-api-token",
+        "TESTHUB_TEAM_ID": "2",
+        "TESTHUB_SESSION_ID": "15"
+      }
+    }
+  }
+}
+```
+
+#### 方式二：使用 pip 安装
+
+```bash
+# 进入 testhub_mcp 目录
+cd testhub_mcp
+
+# 安装到当前环境
+pip install -e .
+
+# 或使用 uv
+uv pip install -e .
+```
+
+### 配置 Cursor
+
+1. 创建或编辑 Cursor MCP 配置文件：
+
+   **全局配置**（适用于所有项目）：
+   ```
+   ~/.cursor/mcp.json
+   ```
+
+   **项目配置**（仅适用于当前项目）：
+   ```
+   项目根目录/.cursor/mcp.json
+   ```
+
+2. 添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "testhub": {
+      "command": "testhub-mcp",
+      "env": {
+        "TESTHUB_API_URL": "https://testhub.yourcompany.com/api/v1",
+        "TESTHUB_API_TOKEN": "your-personal-api-token",
+        "TESTHUB_TEAM_ID": "2",
+        "TESTHUB_SESSION_ID": "15"
+      }
+    }
+  }
+}
+```
+
+### 配置 Cursor Rules
+
+将 `cursor_rules/testhub-integration.mdc` 文件复制到项目的 `.cursor/rules/` 目录：
+
+```bash
+mkdir -p .cursor/rules
+cp cursor_rules/testhub-integration.mdc .cursor/rules/
+```
+
+或者手动创建符号链接（推荐，便于更新）：
+
+```bash
+mkdir -p .cursor/rules
+ln -s ../../cursor_rules/testhub-integration.mdc .cursor/rules/testhub-integration.mdc
+```
+
+### 环境变量
+
+| 变量名 | 必填 | 说明 | 示例 |
+|-------|------|------|------|
+| `TESTHUB_API_URL` | ✅ | TestHub API 地址 | `https://testhub.yourcompany.com/api/v1` |
+| `TESTHUB_API_TOKEN` | ✅ | 个人 API Token | `th_xxx_xxxxx` |
+| `TESTHUB_TEAM_ID` | ✅ | 团队 ID | `2` |
+| `TESTHUB_SESSION_ID` | ⚠️ 推荐 | 默认开发会话 ID，创建任务时自动关联 | `15` |
+| `PROJECT_DOCS_PATH` | ⬜ | 项目文档路径 | `./docs` |
+
+> **💡 提示**：`TESTHUB_SESSION_ID` 虽然不是必填，但强烈建议配置。它确保所有通过 MCP 创建的任务、会话等数据都能关联到正确的开发迭代。你可以在 TestHub 前端的"开发管理"中找到活跃会话的 ID。
+
+## 使用说明
+
+### 基本工作流
+
+1. **开始任务**
+   
+   在 Cursor 中说：
+   ```
+   开始任务 TASK-042
+   ```
+   
+   AI 助手会：
+   - 调用 `testhub_get_task` 获取任务详情
+   - 显示任务标题、描述、验收标准
+   - 更新任务状态为"进行中"
+
+2. **开发完成后提交评审**
+   
+   在 Cursor 中说：
+   ```
+   功能完成了，帮我提交评审
+   ```
+   
+   AI 助手会：
+   - 分析修改的代码
+   - 自动生成评审文档（数据模型设计、API 设计、代码评审等）
+   - 上传文档到 TestHub
+   - 提交评审
+
+3. **结束会话**
+   
+   在 Cursor 中说：
+   ```
+   今天先到这，同步一下
+   ```
+   
+   AI 助手会：
+   - 整理本次会话的工作摘要
+   - 记录修改的文件、关键决策
+   - 同步到 TestHub
+
+### 可用命令
+
+| 触发语句 | 功能 |
+|---------|------|
+| "开始任务 TASK-XXX" | 获取任务详情并开始任务 |
+| "我的任务" | 查看待办任务列表 |
+| "功能完成了" | 生成评审文档并提交 |
+| "同步一下" | 同步当前会话记录 |
+| "这里有个 bug" | 创建 Bug 报告 |
+
+## 可用工具
+
+### 任务管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_get_task` | 获取任务详情 | `task_code` (必填) |
+| `testhub_update_task_status` | 更新任务状态 | `task_code`, `status` |
+| `testhub_list_my_tasks` | 获取我的待办任务 | `status`, `limit` |
+| `testhub_create_task` | 创建新任务 | `title`, `description`, `complexity` |
+| `testhub_start_task` | 开始任务 | `task_code` |
+| `testhub_complete_task` | 完成任务 | `task_code` |
+
+### 评审管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_create_review` | 创建功能评审 | `task_code` |
+| `testhub_add_review_document` | 添加评审文档 | `task_code`, `doc_type`, `title`, `content` |
+| `testhub_submit_review` | 提交评审 | `task_code` |
+
+### 会话管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_sync_dev_session` | 同步开发会话 | `session_summary`, `files_changed`, `key_decisions` |
+| `testhub_list_sessions` | 列出开发会话 | `limit` |
+| `testhub_switch_session` | 切换开发会话 | `session_id` |
+
+### Bug 管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_create_bug` | 创建 Bug | `title`, `description`, `severity`, `related_task_code` |
+
+### 上下文管理
+
+| 工具 | 说明 | 参数 |
+|-----|------|------|
+| `testhub_get_context` | 获取当前上下文 | - |
+| `testhub_switch_task` | 切换当前任务 | `task_code` |
+
+## 开发
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd TestHub/testhub_mcp
+
+# 创建虚拟环境
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+```
+
+### 测试 MCP Server
+
+使用 MCP Inspector 进行测试：
+
+```bash
+# 安装 MCP Inspector
+npm install -g @modelcontextprotocol/inspector
+
+# 启动测试
+npx @modelcontextprotocol/inspector testhub-mcp
+```
+
+## 目录结构
+
+```
+testhub_mcp/
+├── __init__.py          # 包初始化
+├── server.py            # MCP Server 主入口
+├── config.py            # 配置管理
+├── api_client.py        # TestHub API 客户端
+├── tools/               # MCP 工具实现
+│   ├── __init__.py
+│   ├── task.py          # 任务管理工具
+│   ├── review.py        # 评审管理工具
+│   ├── session.py       # 会话同步工具
+│   ├── bug.py           # Bug 管理工具
+│   └── docs.py          # 文档工具
+├── resources/           # MCP 资源提供者
+│   ├── __init__.py
+│   └── docs.py          # 文档资源
+├── pyproject.toml       # 项目配置
+└── README.md            # 本文件
+```
+
+## 故障排除
+
+### MCP Server 无法启动
+
+1. 检查 Python 版本 >= 3.10
+2. 确认环境变量已正确配置
+3. 查看 Cursor 日志：`Help > Toggle Developer Tools > Console`
+
+### 无法连接 TestHub
+
+1. 检查 `TESTHUB_API_URL` 是否正确
+2. 确认 API Token 有效
+3. 确认网络可访问 TestHub 服务
+
+### 工具调用失败
+
+1. 检查必填参数是否提供
+2. 查看错误信息中的详细说明
+3. 确认对应的后端 API 已实现
+
+## 许可证
+
+MIT
+
+## 相关链接
+
+- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
+- [Cursor MCP 配置指南](https://docs.cursor.com/mcp)
+- [TestHub 项目主页](../README.md)
+