JUHE API Marketplace
OneCuriousLearner avatar
MCP Server

TAPD Data Fetcher

A Python MCP server that retrieves requirements and bug data from TAPD platform to provide AI clients with project management information.

5
GitHub Stars
10/8/2025
Last Updated
MCP Server Configuration
1{
2 "name": "tapd_mcp_server",
3 "command": "uv",
4 "args": [
5 "--directory",
6 "D:\\MiniProject\\MCPAgentRE",
7 "run",
8 "tapd_mcp_server.py"
9 ]
10}
JSON10 lines

README Documentation

MCP_Agent:RE 项目指南

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

对话效果预览

Ask DeepWiki

TAPD Data Fetcher MCP server

项目背景

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 数据，快速筛选高中低优先级项目
    • 支持高中低优先级预设过滤器
    • 支持具体优先级标签搜索
    • 默认查找高优先级数据（priority >= 3 或 urgent/high）
  • get_tapd_data_statistics(data_type) - 获取 TAPD 数据统计信息，提供全面的数据分布分析
    • 包含数量、优先级、状态、创建者分布
    • 支持需求和缺陷的独立统计
    • 提供最近项目和完成情况统计

时间趋势分析工具

  • analyze_time_trends(data_type, chart_type, time_field, since, until, data_file_path) - 分析时间趋势，支持需求和缺陷数据，可自定义时间字段、时间范围和图表类型
    • data_type : 数据类型，可选值为 "story" 和 "bug"
    • chart_type : 图表类型，可选值为 "count" 和 "line"
    • time_field : 时间字段，可选值为 "created" 和 "updated"
    • since : 时间范围，格式为 "YYYY-MM-DD"，可选
    • until : 时间范围，格式为 "YYYY-MM-DD"，可选
    • data_file_path : 数据文件路径，可选，默认值为 "local_data/msg_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 驱动的测试管理提供强大支持。

可用的 WorkFlow 脚本

测试用例评估

  • 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 读取与列映射，返回 list[dict]

TransmissionManager 类

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

TokenCounter 类

  • __init__(config) - 初始化 Token 计数器，依赖 MCPToolsConfig 实例，自动尝试加载 DeepSeek tokenizer
  • count_tokens(text) - 计算文本的 token 数量，优先使用 transformers 库精确计算，失败时使用改进的预估模式
  • _try_load_tokenizer() - 尝试加载本地 DeepSeek tokenizer，支持精确 token 计数

BatchingUtils 工具类

  • split_by_token_budget(items, estimate_tokens_fn, token_threshold, start_index=0) - 基于 token 阈值的贪心分批，返回(本批列表, 下一起点, 估算 tokens)

MarkdownUtils 工具类

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

APIManager 类

  • __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：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. 安装Python 3.10
  • 从 Python官网 下载 Python 3.10.x 安装包（建议 3.10.11，与原环境一致）
  • 安装时勾选 Add Python to PATH（关键！否则需手动配置环境变量）
  • 验证安装：终端运行 python --version，应输出 Python 3.10.11
  1. 安装uv工具

二、项目文件迁移

  1. 复制项目目录
  • 将原项目目录 D:\MiniProject\MCPAgentRE 完整复制到目标电脑（建议路径无中文/空格，如 D:\MCPAgentRE）

三、依赖安装

  1. 创建虚拟环境

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

  • 创建虚拟环境：

    uv venv
    • 该命令会在项目目录下创建一个名为 .venv 的虚拟环境目录
  1. 安装项目依赖

  • 运行依赖安装命令：

    uv sync
    • 该命令会根据 pyproject.toml 安装所有依赖（包括 MCP SDK、aiohttp 等）

四、配置调整

TAPD API配置

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

    API_USER = '替换为你的TAPD API用户名'
API_PASSWORD = '替换为你的TAPD API密码'
WORKSPACE_ID = '替换为你的TAPD项目ID'
    • 注意：TAPD API 用户名和密码需要从 TAPD 平台获取，具体操作请参阅开放平台文档
    • WORKSPACE_ID：TAPD 项目 ID，可通过 TAPD 平台获取
    • 提交 Git 时会根据 .gitignore 忽略 api.txt 文件，确保敏感信息不被泄露

LLM API配置

  • 特别提醒：若您的 TAPD 数据需要较高的保密等级，请不要配置此项，或自行在 common_utils.py 的 class APIManager 中添加满足保密需求的 LLM API
  • 系统现已支持两种 LLM API 提供商，您可以根据需要选择配置：
DeepSeek API配置

如果您需要使用智能摘要功能（generate_tapd_overview）或 description 优化功能（preprocess_tapd_description），需要配置 DeepSeek 或 SiliconFlow API 密钥：

  • 获取API密钥：访问 DeepSeek 开放平台 注册并获取 API 密钥

  • 设置环境变量（Windows PowerShell）：

    # 临时设置（仅当前会话有效）
$env:DS_KEY = "your-deepseek-api-key-here"

# 永久设置（推荐）
[Environment]::SetEnvironmentVariable("DS_KEY", "your-deepseek-api-key-here", "User")
SiliconFlow API配置

SiliconFlow 提供多种优质模型，包括 DeepSeek、Kimi、Qwen 等：

  • 获取API密钥：访问 SiliconFlow 开放平台 注册并获取 API 密钥

  • 如果这是你的首次注册，在 注册页面 可以填写我的邀请码 nYbojgoI，成功注册后双方均可获得 RMB 14 额度，等价于 100w tokens 的免费试用额度

  • 设置环境变量（Windows PowerShell）：

    # 临时设置（仅当前会话有效）
$env:SF_KEY = "your-siliconflow-api-key-here"

# 永久设置（推荐）
[Environment]::SetEnvironmentVariable("SF_KEY", "your-siliconflow-api-key-here", "User")

  • 验证配置：

    echo $env:DS_KEY
echo $env:SF_KEY

  • 注意事项：

  • 设置环境变量后需重启编辑器和 MCP 客户端

  • 如果不配置 API 密钥，智能摘要工具会返回错误提示，但不影响其他功能的使用

  • 若需要使用 SiliconFlow 的其他模型，可在 common_utils.py 文件头部修改 SF_DEFAULT_MODEL 变量，或在环境变量中配置 SF_DEFAULT_MODEL

  • 详细配置说明请参考 SiliconFlow API Docs 与 DeepSeek API Docs

五、测试运行

  1. 在终端进入项目文件夹
  • 终端运行：cd D:\MCPAgentRE（根据实际路径调整）

测试模式

这部分已被移动至 测试模式.md

正常模式

MCP 服务器启动

  1. 确保tapd_mcp_server.py的 main 函数中没有任何 print 语句（或已注释掉），以避免在启动时输出调试信息。

  2. 运行 MCP 服务器（此操作将由 AI 客户端根据配置文件自动执行，无需手动操作）：

uv run tapd_mcp_server.py
MCP 服务调试

  1. 确保 tapd_mcp_server.py 的 main 函数中没有任何 print 语句（或已注释掉），以避免在启动时输出调试信息。

  2. 运行MCP调试器：

npx -y @modelcontextprotocol/inspector uv --directory . run tapd_mcp_server.py

操作文档：调试器 Inspector - MCP 官方文档中文版

WorkFlow 脚本运行
  1. 评分规则配置
# 查看规则配置
uv run mcp_tools/test_case_rules_customer.py

# 修改规则配置
uv run mcp_tools/test_case_rules_customer.py --config

# 重置为默认配置
uv run mcp_tools/test_case_rules_customer.py --reset

# 查看帮助信息
uv run mcp_tools/test_case_rules_customer.py --help
  1. 运行需求单知识库
uv run mcp_tools/test_case_require_list_knowledge_base.py
  1. 运行 AI 评估器
  • 运行前，请将需要处理的集成用例 Excel 文件放置于 local_data 文件夹中
uv run mcp_tools/test_case_evaluator.py

六、常见问题排查

  • 依赖缺失：若提示 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 为例）

连接步骤

配置 Chatbox 以使用 MCP 服务器

  1. 打开 Chatbox

  2. 配置 MCP 服务器

  • 在 Chatbox 的 设置 中，找到 MCP 标签页
  • 在 自定义 MCP 服务器 栏，点击 添加服务器：

    • 复制以下 JSON 配置：

      {
  "mcpServers": {
    "tapd_mcp_server": {
      "command": "uv",
      "args": [
        "--directory",
        "D:\\MiniProject\\MCPAgentRE",
        "run",
        "tapd_mcp_server.py"
      ]
    }
  }
}

    • 确保 --directory 指向的是MCP服务器所在的目录，即 D:\MiniProject\MCPAgentRE（请按照实际目录修改）

  • 点击 从剪贴板中的JSON导入

配置 Claude Desktop 以使用 MCP 服务器

  1. 打开Claude Desktop
  • 启动Claude Desktop客户端
  1. 配置MCP服务器

  • 使用快捷键 Ctrl + , 打开设置页面（或者点击左上角菜单图标 - File - Settings）

  • 选择 Developer 选项卡

  • 点击 Edit Config 按钮，将会弹出文件资源管理器

  • 编辑高亮提示的 claude_desktop_config.json 文件，添加以下内容（若有其他内容，请注意层级关系）：

    {
  "mcpServers": {
    "tapd_mcp_server": {
      "command": "uv",
      "args": [
        "--directory",
        "D:\\MiniProject\\MCPAgentRE",
        "run",
        "tapd_mcp_server.py"
      ]
    }
  }
}
    • 注意：
      • command 字段指定了运行MCP服务器的命令（通常为 uv）
      • args 字段指定了运行MCP服务器的参数，包括项目目录（--directory）和运行的脚本文件（run tapd_mcp_server.py）
      • 确保 --directory 指向的是MCP服务器所在的目录，即 D:\MiniProject\MCPAgentRE（请按照实际目录修改）

  • 保存并关闭文件

设置LLM提示词【推荐】

  • 将 提示词-TAPD平台MCP分析助手.md 文件中的内容复制到 Chatbox 的提示词设置中。
  • 除 Chatbox 外，其他 AI 客户端也可以使用相同的提示词内容。
  • 此功能将帮助您更好地与 MCP 服务器进行交互。根据实际需求调整提示词内容，以提高交互效果。

测试连接

  • 开启一条新对话（若使用 Chatbox，需要点击对话框底部的锤子图标，勾选 tapd_mcp_server）

  • 在新的聊天窗口中，输入以下内容测试基础功能：

    请使用 tapd_mcp_server 插件获取 TAPD 项目的需求和缺陷数据

  • 点击发送按钮，等待 MCP 服务器返回数据

  • 检查返回的数据是否符合预期，包括需求和缺陷的数量和内容

注意事项

  • 确保 MCP 服务器的路径和参数配置正确

  • 如果 MCP 服务器运行时出现错误，检查 MCP 服务器的日志文件（通常位于 %APPDATA%\Claude\logs）以获取更多信息

  • 如果 AI 客户端无法识别 MCP 插件，可能需要重新安装或更新 AI 客户端

  • 您可以运行以下命令列出最近的日志并跟踪任何新日志（在 Windows 上，它只会显示最近的日志）：

    type "%APPDATA%\Claude\logs\mcp*.log"

扩展MCP服务器功能

  • 为了让项目目录结构更清晰，建议将 MCP 工具函数放在 mcp_tools 文件夹中。下面是一个添加新工具函数的示例方法。
  • 拓展阅读: TAPD平台MCP服务器开发指南.md

添加新 MCP 函数脚本

  1. 创建工具函数文件

  • 在 mcp_tools 文件夹中创建新的 Python 文件（如 new_tool.py）

  • 编写异步函数，示例模板：

    async def new_function(param1: str, param2: int) -> dict:
    """
    新工具函数说明
    
    参数:
        param1: 参数说明
        param2: 参数说明
        
    返回:
        返回数据结构说明
    """
    # 函数实现
    return {"result": "处理结果"}
  1. 注册工具到服务器
  • 在 tapd_mcp_server.py 中添加：

    • 导入语句：from mcp_tools.new_tool import new_function

    • 使用 @mcp.tool() 装饰器注册函数：

      @mcp.tool()
async def new_tool(param1: str, param2: int) -> dict:
    """
    工具功能详细说明
    
    参数:
        param1 (str): 参数详细说明
        param2 (int): 参数详细说明
        
    返回:
        dict: 返回数据结构详细说明
    """
    return await new_function(param1, param2)
  1. 描述文档最佳实践
  • 为AI客户端添加清晰的文档：
    • 函数级文档：使用详细的中文说明，包括参数类型和返回值结构
    • 参数说明：明确每个参数的数据类型和预期用途
    • 返回说明：详细描述返回字典的每个字段
    • 示例：提供调用示例和预期输出

相关文档或网址

Quick Install

Quick Actions

View on GitHubView All Servers

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source

Boost your projects with Wisdom Gate LLM API

Supporting GPT-5, Claude-4, DeepSeek v3, Gemini and more.

Enjoy a free trial and save 20%+ compared to official pricing.

Learn More