Skip to main content
Glama

TAPD Data Fetcher

MCP_Agent 项目指南

  • 对话效果预览

对话效果预览

项目背景

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) - 检测本地是否存在指定模型,返回模型路径或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格式,自动创建目录结构
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-chatdeepseek-reasoner 模型
    • 支持 SiliconFlow APImoonshotai/Kimi-K2-Instruct 等模型
    • 自动检测API类型并适配不同的请求格式和错误处理
全局实例管理函数
  • get_config() - 获取全局MCPToolsConfig实例(单例模式)
  • get_model_manager() - 获取全局ModelManager实例(单例模式)
  • get_file_manager() - 获取全局FileManager实例(单例模式)
  • get_api_manager() - 获取全局APIManager实例(单例模式)

项目结构

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 数据 │ ├─preprocessed_data.json # 预处理后的 TAPD 数据 │ └─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_comprehensive.py # 综合向量化功能测试 │ ├─test_vectorization.py # 基础向量化功能测试 │ ├─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工具
  • 终端运行pip install uv(需确保pip已随Python安装):
    pip install uv
  • 验证安装:运行uv --version,应显示版本信息

二、项目文件迁移

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

三、依赖安装

  1. 安装项目依赖
  • 终端进入项目目录:cd D:\MCPAgentRE(根据实际路径调整)
  • 运行依赖安装命令:
    uv sync
    • 该命令会根据pyproject.toml安装所有依赖(包括MCP SDK、aiohttp等)

四、配置调整

  1. 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文件,确保敏感信息不被泄露
  1. LLM API配置(可选)

系统现已支持两种LLM API提供商,您可以根据需要选择配置:

DeepSeek API配置

如果您需要使用智能摘要功能(generate_tapd_overview)或 description 优化功能(preprocess_tapd_description),需要配置DeepSeek 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配置 【🆕 2025年7月22日新增】

SiliconFlow提供多种优质模型,包括Kimi、通义千问等:

  • 获取API密钥:访问 SiliconFlow 开放平台 注册并获取API密钥
  • 设置环境变量(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密钥,智能摘要工具会返回错误提示,但不影响其他功能的使用
  • 详细配置说明请参考 knowledge_documents/DeepSeek API 环境变量配置指南.md

五、测试运行

  1. 在终端进入项目文件夹
  • 终端运行:cd D:\MCPAgentRE(根据实际路径调整)
测试模式
  1. 如果需要验证tapd_data_fetcher.py是否正常获取数据,请运行以下指令:
uv run tapd_data_fetcher.py
  • 预期输出:
    成功加载配置: 用户=********, 工作区=******** ===== 开始获取需求数据 ===== 需求数据获取完成,共获取X条 ===== 开始获取缺陷数据 ===== 缺陷数据获取完成,共获取Y条 数据已成功保存至msg_from_fetcher.json文件。
  1. 如果需要验证tapd_mcp_server.py 中所有 MCP工具是否正常注册,请运行以下指令:
uv run check_mcp_tools.py

输出结果如下:

成功加载配置: 用户=4ikoesFM, 工作区=37857678 ✅ MCP服务器启动成功! 📊 已注册工具数量: 14 🛠️ 已注册的工具列表: 1. example_tool - 示例工具函数(用于演示MCP工具注册方式) 功能描述: ... 2. get_tapd_data - 从TAPD API获取需求和缺陷数据并保存到本地文件 功能描述: ...
  1. 快速验证向量化功能(推荐):
uv run test\vector_quick_start.py
  • 该脚本会自动运行数据获取、向量化和搜索功能,验证整体流程是否正常
  • 首次使用时需要连接 VPN 以下载模型
  • 预期输出:显示向量化成功和搜索演示结果
  1. 上下文优化器和假数据生成测试
# 生成模拟TAPD数据(用于测试) uv run mcp_tools\fake_tapd_gen.py # 使用上下文优化器生成数据概览(离线模式) uv run mcp_tools\context_optimizer.py -f local_data\msg_from_fetcher.json --offline --debug # 生成详细摘要(需要配置API密钥) uv run mcp_tools\context_optimizer.py -f local_data\msg_from_fetcher.json --debug
  • 环境变量配置(在线模式):为使用上下文优化器的在线LLM功能,需要设置以下环境变量:
    set DS_KEY=your_deepseek_api_key # DeepSeek API密钥 set DS_EP=https://api.deepseek.com/v1 # API端点URL(可选,默认为DeepSeek) set DS_MODEL=deepseek-chat # 模型名称(可选,默认为deepseek-chat)
  • 上下文优化器支持离线模式(--offline参数)和在线智能摘要生成
  • 假数据生成器用于测试和演示,生成符合TAPD格式的模拟数据
  1. 词频分析工具测试
uv run mcp_tools\word_frequency_analyzer.py
  • 该脚本会分析local_data/msg_from_fetcher.json中的数据,生成关键词词云统计
  1. 文档摘要生成测试(仍在开发中):
uv run mcp_tools\docx_summarizer.py
  • 该脚本会提取指定.docx文档中的文本、图片和表格信息,并生成摘要
  • 预期输出:生成的摘要JSON文件和提取的图片、表格文件
  1. 测试用例评估器
# 运行自定义规则演示 uv run test\demo_custom_rules.py # 运行需求单知识库初始化 uv run test\init_requirement_kb.py # 运行测试用例评估器 uv run mcp_tools\test_case_evaluator.py
  • 测试用例评估器会根据配置的规则评估测试用例质量,并生成评估报告
  • 首次运行时会自动生成默认规则配置文件 config/test_case_rules.jsonconfig/require_list_config.json
  • 详细说明请参阅 knowledge_documents\AI测试用例评估器操作手册.md
  1. API兼容性测试 【🆕 2025年7月22日新增】:
uv run test\test_api_compatibility.py
  • 该脚本会测试DeepSeek和SiliconFlow两种API的连接性和响应
  • 预期输出:显示各API的调用结果和响应内容
  • 用于验证多API配置是否正确
正常模式
MCP 服务器启动
  1. 确保tapd_mcp_server.py的 main 函数中没有任何 print 语句(或已注释掉),以避免在启动时输出调试信息。
  2. 运行MCP服务器(此操作将由AI客户端根据配置文件自动执行,无需手动操作):
uv run tapd_mcp_server.py
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 评估器
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为例)

连接步骤

  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(请按照实际目录修改)
  • 保存并关闭文件

测试连接

  • 点击Claude Desktop界面左上角的+按钮,选择New Chat
  • 在新的聊天窗口中,输入以下内容测试基础功能:
    请使用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文件夹中。下面是一个添加新工具函数的示例方法。

添加新工具函数

  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客户端添加清晰的文档:
    • 函数级文档:使用详细的中文说明,包括参数类型和返回值结构
    • 参数说明:明确每个参数的数据类型和预期用途
    • 返回说明:详细描述返回字典的每个字段
    • 示例:提供调用示例和预期输出

相关文档或网址

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

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.

  1. 项目背景
    1. 可用的 MCP 服务器
    2. 可用的 WorkFlow 脚本
    3. 统一接口脚本
  2. 项目结构
    1. 迁移步骤
      1. 一、环境准备
      2. 二、项目文件迁移
      3. 三、依赖安装
      4. 四、配置调整
      5. 五、测试运行
      6. 六、常见问题排查
    2. 如何将项目连接到AI客户端
      1. 前提条件
      2. 连接步骤
      3. 测试连接
      4. 注意事项
    3. 扩展MCP服务器功能
      1. 添加新工具函数
    4. 相关文档或网址

      Related MCP Servers

      • -
        security
        A
        license
        -
        quality
        A 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 -
        Python
        MIT License
      • A
        security
        F
        license
        A
        quality
        An 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 -
        11
        59
        TypeScript
        • Linux
        • Apple
      • -
        security
        A
        license
        -
        quality
        An 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 -
        1
        Python
        MIT License
      • -
        security
        F
        license
        -
        quality
        A 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 -
        1
        Python

      View all related MCP servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/OneCuriousLearner/MCPAgentRE'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server