This server acts as a TAPD Data Fetcher that allows you to:
- Fetch requirements data (stories) from configured TAPD projects
- Fetch bug/defect data from configured TAPD projects
- Return formatted JSON strings of the retrieved data
- Support pagination when fetching both requirement and bug data
- Connect to AI clients (like Claude) for data analysis via the Model Context Protocol (MCP)
- Configure custom TAPD API credentials and workspace IDs for tailored data retrieval
- Automatically store fetched data in JSON files
Utilizes Python for implementation, with the project specifically requiring Python 3.10.x for compatibility.
MCP_Agent 项目指南
- 对话效果预览
- 此项目于2025年6月10日由 punkpeye (Frank Fiegel) 收录于 TAPD Data Fetcher | Glama
- 本项目 GitHub 地址 https://github.com/OneCuriousLearner/MCPAgentRE
- 本项目在 Gitee 上同步更新,镜像地址为 https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE
项目背景
MCP_Agent:RE
是一个用于从 TAPD 平台获取需求和缺陷数据并生成质量分析报告的 Python 项目,旨在为 AI 客户端提供数据支持。
可用的 MCP 服务器
本项目提供了丰富的 MCP 工具集,支持 TAPD 数据的获取、处理、分析和智能摘要功能:
数据获取工具
get_tapd_data()
- 从 TAPD API 获取需求和缺陷数据并保存到本地文件,返回数量统计【推荐】- 适用于首次获取数据或定期更新本地数据
- 包含需求和缺陷数据的完整集成
get_tapd_stories()
- 获取 TAPD 项目需求数据,支持分页并直接返回 JSON 数据,但不保存至本地,建议仅在数据量较小时使用get_tapd_bugs()
- 获取 TAPD 项目缺陷数据,支持分页并直接返回 JSON 数据,但不保存至本地,建议仅在数据量较小时使用
数据预处理工具
preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images)
- 清理TAPD数据中description字段的HTML样式,提取文字、链接、图片内容并通过DeepSeek API优化表达(需要配置 DeepSeek API 密钥),大幅压缩数据长度同时保留关键信息【仍在开发中...】preview_tapd_description_cleaning(data_file_path, item_count)
- 预览description字段清理效果,展示压缩比例和提取信息,不修改原始数据docx_summarizer.py
- 提取 .docx 文档中的文本、图片和表格信息,并生成摘要【仍在开发中...】
向量化与搜索工具
vectorize_data(data_file_path, chunk_size)
- 向量化工具,支持自定义数据源的向量化,将数据转换为向量格式,用于后续的语义搜索和分析get_vector_info()
- 获取简化版向量数据库状态和统计信息search_data(query, top_k)
- 基于语义相似度的智能搜索,支持自然语言查询,返回与查询最相关的结果
数据生成与分析工具
generate_fake_tapd_data(n_story_A, n_story_B, n_bug_A, n_bug_B, output_path)
- 生成模拟 TAPD 数据,用于测试和演示(若不指明地址,使用后可能会覆盖本地数据,若需要来自 API 的正确数据,请再次调用数据获取工具)generate_tapd_overview(since, until, max_total_tokens, model, endpoint, use_local_data)
- 使用 LLM 简要生成项目概览报告与摘要,用于了解项目概况(需要在环境中配置 DeepSeek API 密钥)analyze_word_frequency(min_frequency, use_extended_fields, data_file_path)
- 分析TAPD数据的词频分布,生成关键词词云统计,为搜索功能提供精准关键词建议
示例工具
example_tool(param1, param2)
- 示例工具,展示 MCP 工具注册方式
这些工具支持从数据获取到智能分析的完整工作流,为 AI 驱动的测试管理提供强大支持。
可用的 WorkFlow 脚本
测试用例评估
mcp_tools\test_case_rules_customer.py
- 测试用例评估规则配置脚本,用于配置测试用例的评估标准和优先级mcp_tools\test_case_require_list_knowledge_base.py
- 测试用例需求知识库生成脚本,可从 TAPD 数据中提取需求信息并生成知识库,或手动修改需求信息mcp_tools\test_case_evaluator.py
- 测试用例AI评估器脚本,用于根据配置的规则评估测试用例质量,并生成评估报告至本地文件
统一接口脚本
- 位于
mcp_tools\common_utils.py
- 提供统一的工具接口,简化 MCP 工具的注册和调用
- 包含的工具如下:
MCPToolsConfig 类
__init__()
- 初始化配置管理器,自动创建项目所需的目录结构(local_data、models、vector_data)_get_project_root()
- 获取项目根目录的绝对路径get_data_file_path(relative_path)
- 获取数据文件的绝对路径,支持相对路径自动转换get_vector_db_path(name)
- 获取向量数据库文件路径,默认为"data_vector"get_model_cache_path()
- 获取模型缓存目录路径
ModelManager 类
__init__(config)
- 初始化模型管理器,依赖MCPToolsConfig实例get_project_model_path(model_name)
- 检测本地是否存在指定模型,返回模型路径或Noneget_model(model_name)
- 获取SentenceTransformer模型实例,优先使用本地模型,支持自动下载和缓存clear_cache()
- 清除全局模型缓存,释放内存资源
TextProcessor 类
extract_text_from_item(item, item_type)
- 从TAPD数据项(需求/缺陷)中提取关键文本信息,支持不同类型的字段提取策略
FileManager 类
__init__(config)
- 初始化文件管理器,依赖MCPToolsConfig实例load_tapd_data(file_path)
- 加载TAPD JSON数据文件,支持绝对路径和相对路径load_json_data(file_path)
- 加载JSON数据文件,支持错误处理,文件不存在时返回空字典save_json_data(data, file_path)
- 保存数据为JSON格式,自动创建目录结构
APIManager 类 【2025年7月22日更新】
__init__()
- 初始化API管理器,支持DeepSeek和SiliconFlow双API配置get_headers(endpoint)
- 智能构建API请求头,根据endpoint自动选择对应的API密钥call_llm(prompt, session, model, endpoint, max_tokens)
- 兼容多API的LLM调用接口- 支持 DeepSeek API(默认):
deepseek-chat
、deepseek-reasoner
模型 - 支持 SiliconFlow API:
moonshotai/Kimi-K2-Instruct
等模型 - 自动检测API类型并适配不同的请求格式和错误处理
- 支持 DeepSeek API(默认):
全局实例管理函数
get_config()
- 获取全局MCPToolsConfig实例(单例模式)get_model_manager()
- 获取全局ModelManager实例(单例模式)get_file_manager()
- 获取全局FileManager实例(单例模式)get_api_manager()
- 获取全局APIManager实例(单例模式)
项目结构
迁移步骤
以下是将项目移植到其他 Windows 电脑的详细步骤(尚未测试 Mac 与 Linux):
一、环境准备
- 安装Python 3.10
- 从Python官网下载Python 3.10.x安装包(建议3.10.11,与原环境一致)
- 安装时勾选
Add Python to PATH
(关键!否则需手动配置环境变量) - 验证安装:终端运行
python --version
,应输出Python 3.10.11
- 安装uv工具
- 终端运行
pip install uv
(需确保pip已随Python安装): - 验证安装:运行
uv --version
,应显示版本信息
二、项目文件迁移
- 复制项目目录
- 将原项目目录
D:\MiniProject\MCPAgentRE
完整复制到目标电脑(建议路径无中文/空格,如D:\MCPAgentRE
)
三、依赖安装
- 安装项目依赖
- 终端进入项目目录:
cd D:\MCPAgentRE
(根据实际路径调整) - 运行依赖安装命令:
- 该命令会根据
pyproject.toml
安装所有依赖(包括MCP SDK、aiohttp等)
- 该命令会根据
四、配置调整
- TAPD API配置
- 在项目根目录下创建
api.txt
文件,复制下列文本,并替换配置为目标TAPD项目的真实值:- 注意:TAPD API用户名和密码需要从TAPD平台获取,具体操作请参阅开放平台文档
- WORKSPACE_ID:TAPD项目ID,可通过TAPD平台获取
- 提交Git时会根据
.gitignore
忽略api.txt
文件,确保敏感信息不被泄露
- LLM API配置(可选)
系统现已支持两种LLM API提供商,您可以根据需要选择配置:
DeepSeek API配置
如果您需要使用智能摘要功能(generate_tapd_overview
)或 description 优化功能(preprocess_tapd_description
),需要配置DeepSeek API密钥:
- 获取API密钥:访问 DeepSeek 开放平台 注册并获取API密钥
- 设置环境变量(Windows PowerShell):
SiliconFlow API配置 【🆕 2025年7月22日新增】
SiliconFlow提供多种优质模型,包括Kimi、通义千问等:
- 获取API密钥:访问 SiliconFlow 开放平台 注册并获取API密钥
- 设置环境变量(Windows PowerShell):
- 验证配置:
- 注意事项:
- 设置环境变量后需重启编辑器和MCP客户端
- 如果不配置API密钥,智能摘要工具会返回错误提示,但不影响其他功能的使用
- 详细配置说明请参考
knowledge_documents/DeepSeek API 环境变量配置指南.md
五、测试运行
- 在终端进入项目文件夹
- 终端运行:
cd D:\MCPAgentRE
(根据实际路径调整)
测试模式
- 如果需要验证
tapd_data_fetcher.py
是否正常获取数据,请运行以下指令:
- 预期输出:
- 如果需要验证
tapd_mcp_server.py
中所有 MCP工具是否正常注册,请运行以下指令:
输出结果如下:
- 快速验证向量化功能(推荐):
- 该脚本会自动运行数据获取、向量化和搜索功能,验证整体流程是否正常
- 首次使用时需要连接 VPN 以下载模型
- 预期输出:显示向量化成功和搜索演示结果
- 上下文优化器和假数据生成测试:
- 环境变量配置(在线模式):为使用上下文优化器的在线LLM功能,需要设置以下环境变量:
- 上下文优化器支持离线模式(
--offline
参数)和在线智能摘要生成 - 假数据生成器用于测试和演示,生成符合TAPD格式的模拟数据
- 词频分析工具测试:
- 该脚本会分析
local_data/msg_from_fetcher.json
中的数据,生成关键词词云统计
- 文档摘要生成测试(仍在开发中):
- 该脚本会提取指定.docx文档中的文本、图片和表格信息,并生成摘要
- 预期输出:生成的摘要JSON文件和提取的图片、表格文件
- 测试用例评估器:
- 测试用例评估器会根据配置的规则评估测试用例质量,并生成评估报告
- 首次运行时会自动生成默认规则配置文件
config/test_case_rules.json
与config/require_list_config.json
- 详细说明请参阅
knowledge_documents\AI测试用例评估器操作手册.md
- API兼容性测试 【🆕 2025年7月22日新增】:
- 该脚本会测试DeepSeek和SiliconFlow两种API的连接性和响应
- 预期输出:显示各API的调用结果和响应内容
- 用于验证多API配置是否正确
正常模式
MCP 服务器启动
- 确保
tapd_mcp_server.py
的 main 函数中没有任何 print 语句(或已注释掉),以避免在启动时输出调试信息。 - 运行MCP服务器(此操作将由AI客户端根据配置文件自动执行,无需手动操作):
WorkFlow 脚本运行
- 评分规则配置
- 运行需求单知识库
- 运行 AI 评估器
六、常见问题排查
- 依赖缺失:若提示
ModuleNotFoundError
,检查是否执行uv add
命令,或尝试uv add <缺失模块名>
- API连接失败:确认
API_USER
/API_PASSWORD
/WORKSPACE_ID
正确,且TAPD账号有对应项目的读取权限 - Python版本不匹配:确保目标电脑Python版本为3.10.x(通过
python --version
验证)
如何将项目连接到AI客户端
前提条件
- 已在本地电脑上完成项目的迁移和验证
- 已安装并运行MCP服务器
- 已在本地电脑上安装并运行AI客户端(以Claude Desktop为例)
连接步骤
- 打开Claude Desktop
- 启动Claude Desktop客户端
- 配置MCP服务器
- 使用快捷键
Ctrl + ,
打开设置页面(或者点击左上角菜单图标 - File - Settings) - 选择
Developer
选项卡 - 点击
Edit Config
按钮,将会弹出文件资源管理器 - 编辑高亮提示的
claude_desktop_config.json
文件,添加以下内容(若有其他内容,请注意层级关系):- 注意:
command
字段指定了运行MCP服务器的命令(通常为uv
)args
字段指定了运行MCP服务器的参数,包括项目目录(--directory
)和运行的脚本文件(run tapd_mcp_server.py
)- 确保
--directory
指向的是MCP服务器所在的目录,即D:\MiniProject\MCPAgentRE
(请按照实际目录修改)
- 注意:
- 保存并关闭文件
测试连接
- 点击Claude Desktop界面左上角的
+
按钮,选择New Chat
- 在新的聊天窗口中,输入以下内容测试基础功能:
- 点击发送按钮,等待MCP服务器返回数据
- 检查返回的数据是否符合预期,包括需求和缺陷的数量和内容
注意事项
- 确保MCP服务器的路径和参数配置正确
- 如果MCP服务器运行时出现错误,检查MCP服务器的日志文件(通常位于
%APPDATA%\Claude\logs
)以获取更多信息 - 如果AI客户端无法识别MCP插件,可能需要重新安装或更新AI客户端
- 您可以运行以下命令列出最近的日志并跟踪任何新日志(在 Windows 上,它只会显示最近的日志):
扩展MCP服务器功能
为了让项目目录结构更清晰,建议将MCP工具函数放在mcp_tools
文件夹中。下面是一个添加新工具函数的示例方法。
添加新工具函数
- 创建工具函数文件
- 在
mcp_tools
文件夹中创建新的Python文件(如new_tool.py
) - 编写异步函数,示例模板:
- 注册工具到服务器
- 在
tapd_mcp_server.py
中添加:- 导入语句:
from mcp_tools.new_tool import new_function
- 使用
@mcp.tool()
装饰器注册函数:
- 导入语句:
- 描述文档最佳实践
- 为AI客户端添加清晰的文档:
- 函数级文档:使用详细的中文说明,包括参数类型和返回值结构
- 参数说明:明确每个参数的数据类型和预期用途
- 返回说明:详细描述返回字典的每个字段
- 示例:提供调用示例和预期输出
相关文档或网址
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Python MCP server that retrieves requirements and bug data from TAPD platform to provide AI clients with project management information.
Related MCP Servers
- -securityAlicense-qualityA Python-based MCP server that integrates the TapTools API, enabling AI models to fetch Cardano blockchain data, including tokens, NFTs, market stats, and wallet info, through standardized tools.Last updated -PythonMIT License
- AsecurityFlicenseAqualityAn MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.Last updated -1159TypeScript
- -securityAlicense-qualityAn MCP server that enables AI assistants to access up-to-date documentation for Python libraries like LangChain, LlamaIndex, and OpenAI through dynamic fetching from official sources.Last updated -1PythonMIT License
- -securityFlicense-qualityA Python implementation of the MCP server that enables AI models to connect with external tools and data sources through a standardized protocol, supporting tool invocation and resource access via JSON-RPC.Last updated -1Python