MCP_Sgent: RE 项目指南

• 对话效果预览（项目早期阶段）

• 该项目于2025年6月10日由punkpeye (Frank Fiegel) 发起，并包含在TAPD 数据抓取器 | Glama

<a href="https://glama.ai/mcp/servers/@OneCuriousLearner/MCPAgentRE"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=1392399335,3371773907&fm=3081&app=3081&f=PNG?w=760&h=1000" alt="TAPD 数据抓取器 MCP 服务器" /> </a>

• 该项目的GitHub地址为https://github.com/OneCuriousLearner/MCPAgentRE
• 该项目同步更新到Gitee，图像地址为https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE

项目背景

MCP_Agent:RE 是一个旨在从TAPD平台获取需求和缺陷数据并生成质量分析报告的Python项目，旨在为AI客户端提供数据支持。

可用的MCP服务器

• MCP工具统一放置在tapd_mcp_server.py中间。
• 该项目提供丰富的MCP工具包，支持TAPD数据的获取、处理、分析和智能化总结。

数据获取工具

• get_tapd_data(clean_empty_fields) -从TAPD API获取需求和缺陷数据并保存到本地文件，返回数量统计。[推荐]
  • 适用于首次获取数据或定期更新本地数据
  • 完整集成包括需求和缺陷数据
• get_tapd_stories(clean_empty_fields) -获取TAPD项目需求数据，支持分页并直接返回JSON数据，但不保存到本地。建议仅在数据量较小时使用
• get_tapd_bugs(clean_empty_fields) -获取TAPD项目缺陷数据，支持分页并直接返回JSON数据，但不保存到本地。建议仅在数据量较小时使用

数据预处理工具

• preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images) -清理TAPD数据description字段的HTML样式，提取文本、链接和图像内容并通过LLM API进行表达优化（需要配置LLM API密钥），显著压缩数据长度同时保留关键信息 [仍在开发中...]
  • 遇到了腾讯文档API导出限制问题，该API每天只能导出9份文档
  • 遇到了TAPD数据详情中的图像和视频无法导出的问题，且未在文档中找到相关描述
  • 目前仅支持文本内容的提取和处理
• preview_tapd_description_cleaning(data_file_path, item_count) -预览description字段的清理效果，显示压缩比和提取的信息而不修改原始数据
• docx_summarizer.py -从.docx文档中提取文本、图像和表格信息并生成摘要 [仍在开发中...]

精确搜索工具

• precise_search_tapd_data(search_value, search_field, data_type, exact_match, case_sensitive) -TAPD数据精确搜索工具，支持需求和缺陷的精确字段匹配搜索
  • 支持任意字段的精确或模糊搜索
  • 可指定搜索需求、缺陷或两者
  • 支持大小写敏感选项
  • 提供匹配信息和统计汇总
• search_tapd_by_priority(priority_filter, data_type) -按优先级搜索TAPD数据并快速筛选高、中、低优先级项目
  • 支持高、中、低优先级预设过滤器
  • 支持特定优先级标签搜索
  • 默认搜索高优先级数据（优先级>=3或紧急/高）
• get_tapd_data_statistics(data_type) -获取TAPD数据统计信息并提供全面的数据分布分析
  • 包括数量、优先级、状态和创建者分布
  • 支持独立统计需求和缺陷
  • 提供最近项目的统计数据

时间趋势分析工具

• analyze_time_trends(data_type, chart_type, time_field, since, until, data_file_path) -分析时间趋势，支持需求和缺陷数据，可定制时间字段、时间范围和图表类型
  • Dataotype: 数据类型，可选值为"story"和"bug"
  • Chartotype: 图表类型，可选值为"count"和"line"
  • Time_field: 时间字段，可选值为"created"和"updated"
  • Since: 时间范围，格式为"YYYY-MM-DD"，可选
  • Until: 时间范围，格式为"YYYY-MM-DD"，可选
  • DataFILE Path: 数据文件路径，可选，默认值为"local_data/msg1 from _fetcher. json"

向量化和搜索工具

• vectorize_data(data_file_path, chunk_size, preserve_existing) -向量化工具，支持自定义数据源的向量化，将数据转换为向量格式以供后续语义搜索和分析
• 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数据用于测试和演示目的（如果未指定地址，使用后可能会覆盖本地数据。如需从TAPD API获取正确数据，请再次调用数据检索工具）
• generate_tapd_overview(since, until, max_total_tokens, use_local_data) -使用LLM生成简要项目概述报告和总结，以便理解项目概况（需要配置LLM API密钥）
• analyze_word_frequency(min_frequency, use_extended_fields, data_file_path) -分析TAPD数据的词频分布，生成关键词云统计，并为搜索功能提供准确的关键词建议

示例工具

• example_tool(param1, param2) -示例工具，展示MCP工具的注册方法

这些工具支持从数据获取到智能分析的完整工作流程，为AI驱动的测试管理提供了强大的支持。

可用的工作流脚本

测试用例评估

• test_case_rules_customer.py -测试用例评估规则配置脚本，用于配置测试用例的评估标准和优先级
• test_case_require_list_knowledge_base.py -测试用例需求知识库生成脚本，可以从TAPD数据中提取需求信息并生成知识库，或手动修改需求信息
• test_case_evaluator.py -测试用例AI评估器脚本，根据配置的规则评估测试用例的质量并生成评估报告到本地文件

统一接口脚本

• 位于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) -检查指定模型是否存在于本地，返回模型路径或None
• get_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格式保存数据并自动创建目录结构
• read_excel_with_mapping(excel_file_path, column_mapping, na_to_empty=True) -通用Excel读取和列映射，返回列表[dict]

传输管理器类

• __init__(file_manager) -初始化传输管理器，依赖于FileManager实例
• update_stats(success, retries) -更新传输统计信息，记录成功/失败次数和重试次数
• finalize_report() -生成最终传输报告并将统计数据保存到JSON文件

TokenCounter 类

• __init__(config) -初始化Token计数器，依赖于MCPToolsConfig实例，自动尝试加载DeepSeek分词器
• count_tokens(text) -计算文本中的token数量，优先使用Transformers库进行准确计算，在失败情况下使用改进的估算模式
• _try_load_tokenizer() -尝试加载本地DeepSeek分词器，支持精确的token计数

BatchingUtils 工具类

• split_by_token_budget(items, estimate_tokens_fn, token_threshold, start_index=0) -基于token阈值的贪婪批处理，返回（当前批次列表，下一个起点，估计的token数）

MarkdownUtils 工具类

• parse_markdown_tables(md_text) -纯解析Markdown表格为通用结构[{headers, rows}]，排除业务映射

APIManager 类

• __init__() -初始化API管理器，支持DeepSeek和SiliconFlow双API配置
• get_headers(endpoint) -智能构建API请求头，根据端点自动选择相应的API密钥
• call_llm(prompt, session, model, endpoint, max_tokens) -兼容多个API的LLM调用接口
  • 支持 DeepSeek API(默认):deepseek-chat、deepseek-reasoner模型
  • 支持 SiliconFlow API：deepseek-ai/DeepSeek-V3.1等待模型
  • 自动检测API类型并适应不同的请求格式和错误处理

全局实例管理函数

• get_config() -获取全局MCPToolsConfig实例（单例模式）
• get_model_manager() -获取全局ModelManager实例（单例模式）
• get_file_manager() -获取全局FileManager实例（单例模式）
• get_api_manager() -获取全局APIManager实例（单例模式）
• get_transmission_manager() -获取全局TransmissionManager实例（单例模式）
• get_token_counter() -获取全局TokenCounter实例（单例模式）

项目结构

• 这些目录数据可能没有及时更新，请参考实际情况

MCPAgentRE\
├─config\                     # 配置文件目录
├─knowledge_documents\        # 知识文档（Git 提交时默认忽略目录下的文件，若要提交请手动在 .gitignore 中取消忽略）
├─documents_data\             # 文档数据目录（暂时，最终将替换至 local_data）
│  ├─docx_data\                   # 存储 .docx 文档的目录
│  ├─excel_data\                  # 存储 Excel 表格的目录
│  └─pictures_data\               # 存储图片的目录
├─local_data\                 # 本地数据目录，用于存储从 TAPD 获取的数据、数据库等（Git 提交时会被忽略）
│  ├─msg_from_fetcher.json        # 从 TAPD 获取的需求和缺陷数据
│  ├─fake_tapd.json               # 假数据生成器生成的模拟 TAPD 数据
│  ├─logs\                        # 日志文件目录
│  └─vector_data\                 # 向量数据库文件目录
│     ├─data_vector.index             # 向量数据库索引文件
│     ├─data_vector.metadata.pkl      # 向量数据库元数据文件
│     └─data_vector.config.json       # 向量数据库配置文件
├─mcp_tools\                  # MCP 工具目录
│  ├─data_vectorizer.py           # 向量化工具，支持自定义数据源的向量化
│  ├─context_optimizer.py         # 上下文优化器，支持智能摘要生成
│  ├─docx_summarizer.py           # 文档摘要生成器，提取 .docx 文档内容
│  ├─fake_tapd_gen.py             # TAPD 假数据生成器，用于测试和演示
│  ├─word_frequency_analyzer.py   # 词频分析工具，生成关键词词云统计
│  ├─data_preprocessor.py         # 数据预处理工具，清理和优化 TAPD 数据
│  ├─common_utils.py              # 统一的公共工具模块
│  └─example_tool.py              # 示例工具
├─models\                     # 模型目录
├─test\                       # 测试目录
│  ├─test_data_vectorizer.py      # 完整测试 data_vectorizer 向量化脚本功能
│  ├─test_word_frequency.py       # 词频分析工具测试
│  └─vector_quick_start.py        # 向量化功能快速启动脚本
├─.gitignore                  # Git 提交时遵守的过滤规则
├─.python-version             # 记录 Python 版本（3.10）
├─提示词-TAPD平台MCP分析助手.md
├─TAPD平台MCP服务器开发指南.md
├─api.txt                     # 包含 API 密钥信息，需要自行创建（Git 提交时会被忽略）
├─main.py                     # 项目入口文件，无实际作用
├─pyproject.toml              # 现代的 Python 依赖管理文件
├─README.md                   # 项目说明文档，也就是本文档
├─tapd_data_fetcher.py        # 包含从 TAPD API 获取需求和缺陷数据的逻辑
├─tapd_mcp_server.py          # MCP 服务器启动脚本，用于提供所有 MCP 工具
└─uv.lock                     # UV 包管理器使用的锁定文件

架构图

迁移步骤

以下是详细的步骤，将项目迁移到其他Windows计算机上（尚未在Mac和Linux上测试）：

1、环境准备

1. 安装Python 3.10

• 从Python官方网站下载Python 3.10.x安装包（推荐3.10.11，与原环境一致）
• 安装过程中勾选Add Python to PATH（关键！否则需要手动配置环境变量）
• 验证安装：终端运行python --version，应输出Python 3.10.11

2. 安装UV工具

• 终端操作pip install uv（确保pip已随Python安装）：

  pip install uv
  

• 验证安装：运行uv --version，应显示版本信息

• 关于如何在UV中切换Python版本，请参阅UV - 管理Python版本、环境、第三方包 - 知乎

2、项目文件迁移

1. 复制项目目录

• 包括原始项目目录D:\MiniProject\MCPAgentRE复制完整的文件到目标计算机（推荐路径不含中文字符/空格，例如D:\MCPAgentRE）

3、依赖安装

1. 创建虚拟环境

• 终端进入项目目录：cd D:\MCPAgentRE（根据实际路径调整）

• 创建虚拟环境：

  uv venv
  

  • 此命令将创建名为.venv的虚拟环境目录

2. 安装项目依赖

• 运行依赖安装命令：

  uv sync
  

  • 此命令将基于pyproject.toml安装所有依赖（包括MCP SDK、aiohttp等）

4、配置调整

TAPD API配置

• 在项目根目录创建api.txt，从文件中复制以下文本并替换为目标TAPD项目的实际配置值：

  API_USER = '替换为你的TAPD API用户名'
  API_PASSWORD = '替换为你的TAPD API密码'
  WORKSPACE_ID = '替换为你的TAP