MCP_Agent:RE

Obtiene datos de requisitos y defectos de la plataforma TAPD para proporcionar soporte de datos a clientes de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Guía del Proyecto MCP_Agent:RE

Vista previa del efecto de conversación (etapa inicial del proyecto)

对话效果预览

Este proyecto fue incluido el 10 de junio de 2025 por punkpeye (Frank Fiegel) en TAPD Data Fetcher | Glama

Dirección de GitHub de este proyecto: https://github.com/OneCuriousLearner/MCPAgentRE
Este proyecto se sincroniza en Gitee, la dirección del espejo es https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE

Antecedentes del Proyecto

MCP_Agent:RE es un proyecto de Python que se utiliza para obtener datos de requisitos y defectos de la plataforma TAPD y generar informes de análisis de calidad, con el objetivo de proporcionar soporte de datos para clientes de IA.

Servidores MCP Disponibles

Las herramientas MCP se encuentran unificadas en tapd_mcp_server.py.
Este proyecto proporciona un completo conjunto de herramientas MCP que admite la obtención, procesamiento, análisis y resumen inteligente de datos de TAPD:

Herramientas de Obtención de Datos

get_tapd_data(clean_empty_fields) - Obtiene datos de requisitos y defectos de la API de TAPD y los guarda en un archivo local, devolviendo estadísticas de cantidad【Recomendado】
- Adecuado para la primera obtención de datos o para actualizar periódicamente los datos locales
- Incluye la integración completa de datos de requisitos y defectos
get_tapd_stories(clean_empty_fields) - Obtiene datos de requisitos del proyecto TAPD, admite paginación y devuelve directamente datos JSON, pero no los guarda localmente; se recomienda usarlo solo cuando el volumen de datos sea pequeño
get_tapd_bugs(clean_empty_fields) - Obtiene datos de defectos del proyecto TAPD, admite paginación y devuelve directamente datos JSON, pero no los guarda localmente; se recomienda usarlo solo cuando el volumen de datos sea pequeño

Herramientas de Preprocesamiento de Datos

preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images) - Limpia los estilos HTML del campo description en los datos de TAPD, extrae texto, enlaces e imágenes, y optimiza la expresión mediante la API de LLM (requiere configurar la clave de API de LLM), comprimiendo significativamente la longitud de los datos mientras conserva la información clave【Aún en desarrollo...】
- Se encontró el problema del límite de exportación de la API de Documentos de Tencent: la API solo permite exportar 9 documentos por día
- Se encontró el problema de que las imágenes y videos en los detalles de los datos de TAPD no se pueden exportar; aún no se ha encontrado una descripción relevante en la documentación
- Actualmente solo admite la extracción y procesamiento de contenido de texto
preview_tapd_description_cleaning(data_file_path, item_count) - Previsualiza el efecto de limpieza del campo description, muestra la proporción de compresión y la información extraída, sin modificar los datos originales
docx_summarizer.py - Extrae texto, imágenes e información de tablas de documentos .docx y genera un resumen【Aún en desarrollo...】

Herramientas de Búsqueda Precisa

precise_search_tapd_data(search_value, search_field, data_type, exact_match, case_sensitive) - Herramienta de búsqueda precisa de datos de TAPD, admite búsqueda por coincidencia de campos exactos en requisitos y defectos
- Admite búsqueda exacta o difusa por cualquier campo
- Puede especificar buscar en requisitos, defectos o ambos
- Admite opción de distinción entre mayúsculas y minúsculas
- Proporciona información de coincidencia y resumen estadístico
search_tapd_by_priority(priority_filter, data_type) - Busca datos de TAPD por prioridad, filtra rápidamente proyectos de prioridad alta, media y baja
- Admite filtros predefinidos de prioridad alta, media y baja
- Admite búsqueda por etiquetas de prioridad específicas
- Por defecto busca datos de prioridad alta (priority >= 3 o urgent/high)
get_tapd_data_statistics(data_type) - Obtiene información estadística de datos de TAPD, proporciona un análisis completo de la distribución de datos
- Incluye distribución por cantidad, prioridad, estado y creador
- Admite estadísticas independientes para requisitos y defectos
- Proporciona estadísticas de proyectos recientes y estado de finalización

Herramientas de Análisis de Tendencias Temporales

analyze_time_trends(data_type, chart_type, time_field, since, until, data_file_path) - Analiza tendencias temporales, admite datos de requisitos y defectos, y permite personalizar el campo de tiempo, el rango de tiempo y el tipo de gráfico
- data_type: tipo de datos, valores opcionales "story" y "bug"
- chart_type: tipo de gráfico, valores opcionales "count" y "line"
- time_field: campo de tiempo, valores opcionales "created" y "updated"
- since: rango de tiempo, formato "YYYY-MM-DD", opcional
- until: rango de tiempo, formato "YYYY-MM-DD", opcional
- data_file_path: ruta del archivo de datos, opcional, valor predeterminado "local_data/msg_from_fetcher.json"

Herramientas de Vectorización y Búsqueda

vectorize_data(data_file_path, chunk_size, preserve_existing) - Herramienta de vectorización, admite la vectorización de fuentes de datos personalizadas, convierte los datos a formato vectorial para su posterior búsqueda semántica y análisis
get_vector_info() - Obtiene el estado simplificado y las estadísticas de la base de datos vectorial
search_data(query, top_k) - Búsqueda inteligente basada en similitud semántica, admite consultas en lenguaje natural y devuelve los resultados más relevantes para la consulta

Herramientas de Generación y Análisis de Datos

generate_fake_tapd_data(n_story_A, n_story_B, n_bug_A, n_bug_B, output_path) - Genera datos simulados de TAPD para pruebas y demostraciones (si no se especifica la dirección, su uso puede sobrescribir los datos locales; si necesita datos correctos de la API de TAPD, vuelva a llamar a la herramienta de obtención de datos)
generate_tapd_overview(since, until, max_total_tokens, use_local_data) - Genera brevemente un informe de visión general y un resumen del proyecto usando LLM, para comprender la situación general del proyecto (requiere configurar la clave de API de LLM)
analyze_word_frequency(min_frequency, use_extended_fields, data_file_path) - Analiza la distribución de frecuencia de palabras en los datos de TAPD, genera estadísticas de nube de palabras clave y proporciona sugerencias precisas de palabras clave para la función de búsqueda

Herramientas de Ejemplo

example_tool(param1, param2) - Herramienta de ejemplo que muestra cómo registrar herramientas MCP

Estas herramientas admiten un flujo de trabajo completo desde la obtención de datos hasta el análisis inteligente, proporcionando un sólido soporte para la gestión de pruebas impulsada por IA.

Scripts de WorkFlow Disponibles

Evaluación de Casos de Prueba

test_case_rules_customer.py - Script de configuración de reglas de evaluación de casos de prueba, utilizado para configurar los estándares de evaluación y prioridades de los casos de prueba
test_case_require_list_knowledge_base.py - Script de generación de base de conocimiento de requisitos de casos de prueba, puede extraer información de requisitos de los datos de TAPD y generar una base de conocimiento, o modificar manualmente la información de requisitos
test_case_evaluator.py - Script de evaluador de IA de casos de prueba, utilizado para evaluar la calidad de los casos de prueba según las reglas configuradas y generar un informe de evaluación en un archivo local

Script de Interfaz Unificada

Ubicado en common_utils.py
Proporciona una interfaz de herramientas unificada, simplificando el registro y la invocación de herramientas MCP
Las herramientas incluidas son las siguientes:

Clase MCPToolsConfig

__init__() - Inicializa el administrador de configuración, crea automáticamente la estructura de directorios necesaria para el proyecto (local_data, models, vector_data)
_get_project_root() - Obtiene la ruta absoluta del directorio raíz del proyecto
get_data_file_path(relative_path) - Obtiene la ruta absoluta del archivo de datos, admite la conversión automática de rutas relativas
get_vector_db_path(name) - Obtiene la ruta del archivo de la base de datos vectorial, el valor predeterminado es "data_vector"
get_model_cache_path() - Obtiene la ruta del directorio de caché de modelos

Clase ModelManager

__init__(config) - Inicializa el administrador de modelos, depende de la instancia de MCPToolsConfig
get_project_model_path(model_name) - Detecta si el modelo especificado existe localmente, devuelve la ruta del modelo o None
get_model(model_name) - Obtiene la instancia del modelo SentenceTransformer, prioriza el uso del modelo local, admite descarga automática y caché
clear_cache() - Limpia la caché global de modelos, libera recursos de memoria

Clase TextProcessor

extract_text_from_item(item, item_type) - Extrae información de texto clave de los elementos de datos de TAPD (requisitos/defectos), admite diferentes estrategias de extracción de campos

Clase FileManager

__init__(config) - Inicializa el administrador de archivos, depende de la instancia de MCPToolsConfig
load_tapd_data(file_path) - Carga archivos de datos JSON de TAPD, admite rutas absolutas y relativas
load_json_data(file_path) - Carga archivos de datos JSON, admite manejo de errores, devuelve un diccionario vacío si el archivo no existe
save_json_data(data, file_path) - Guarda datos en formato JSON, crea automáticamente la estructura de directorios
read_excel_with_mapping(excel_file_path, column_mapping, na_to_empty=True) - Lectura genérica de Excel y mapeo de columnas, devuelve list[dict]

Clase TransmissionManager

__init__(file_manager) - Inicializa el administrador de transmisión, depende de la instancia de FileManager
update_stats(success, retries) - Actualiza la información estadística de transmisión, registra el número de éxitos/fallos y reintentos
finalize_report() - Genera el informe final de transmisión, guarda los datos estadísticos en un archivo JSON

Clase TokenCounter

__init__(config) - Inicializa el contador de tokens, depende de la instancia de MCPToolsConfig, intenta cargar automáticamente el tokenizador de DeepSeek
count_tokens(text) - Calcula el número de tokens de un texto, prioriza el cálculo preciso con la biblioteca transformers, y usa un modo de estimación mejorado en caso de fallo
_try_load_tokenizer() - Intenta cargar el tokenizador local de DeepSeek, admite el conteo preciso de tokens

Clase de Utilidades BatchingUtils

split_by_token_budget(items, estimate_tokens_fn, token_threshold, start_index=0) - Agrupación codiciosa basada en umbral de tokens, devuelve (lista del lote actual, siguiente punto de inicio, tokens estimados)

Clase de Utilidades MarkdownUtils

parse_markdown_tables(md_text) - Analiza puramente tablas Markdown en una estructura genérica [{headers, rows}], sin mapeo de negocio

Clase APIManager

__init__() - Inicializa el administrador de API, admite configuración dual de API DeepSeek y SiliconFlow
get_headers(endpoint) - Construye inteligentemente los encabezados de solicitud de API, selecciona automáticamente la clave de API correspondiente según el endpoint
call_llm(prompt, session, model, endpoint, max_tokens) - Interfaz de invocación de LLM compatible con múltiples API
- Admite API DeepSeek (predeterminada): modelos deepseek-chat, deepseek-reasoner
- Admite API SiliconFlow: modelos como deepseek-ai/DeepSeek-V3.1
- Detecta automáticamente el tipo de API y adapta diferentes formatos de solicitud y manejo de errores

Funciones Globales de Gestión de Instancias

get_config() - Obtiene la instancia global de MCPToolsConfig (patrón singleton)
get_model_manager() - Obtiene la instancia global de ModelManager (patrón singleton)
get_file_manager() - Obtiene la instancia global de FileManager (patrón singleton)
get_api_manager() - Obtiene la instancia global de APIManager (patrón singleton)
get_transmission_manager() - Obtiene la instancia global de TransmissionManager (patrón singleton)
get_token_counter() - Obtiene la instancia global de TokenCounter (patrón singleton)

Estructura del Proyecto

Estos datos de directorio pueden no estar actualizados; consulte la situación real

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 包管理器使用的锁定文件

Diagrama de Arquitectura

项目架构图

Pasos de Migración

Los siguientes son los pasos detallados para trasladar el proyecto a otra computadora con Windows (aún no probado en Mac y Linux):

1. Preparación del Entorno

Instalar Python 3.10

Descargue el paquete de instalación de Python 3.10.x desde el sitio oficial de Python (se recomienda 3.10.11, consistente con el entorno original)
Durante la instalación, marque Add Python to PATH (¡clave! De lo contrario, deberá configurar manualmente las variables de entorno)
Verifique la instalación: ejecute python --version en la terminal; debería mostrar Python 3.10.11

Instalar la herramienta uv

Ejecute pip install uv en la terminal (asegúrese de que pip se haya instalado con Python):
```
pip install uv
```
Verifique la instalación: ejecute uv --version; debería mostrar información de versión
Para saber cómo cambiar la versión de Python en UV, consulte UV - Gestión de versiones de Python, entornos y paquetes de terceros - Zhihu

2. Migración de Archivos del Proyecto

Copie el directorio del proyecto

Copie completamente el directorio original del proyecto D:\MiniProject\MCPAgentRE a la computadora de destino (se recomienda una ruta sin caracteres chinos ni espacios, como D:\MCPAgentRE)

3. Instalación de Dependencias

Cree un entorno virtual

Entre al directorio del proyecto en la terminal: cd D:\MCPAgentRE (ajuste según la ruta real)
Cree el entorno virtual:
```
uv venv
```
- Este comando creará un directorio de entorno virtual llamado .venv en el directorio del proyecto

Instale las dependencias del proyecto

Ejecute el comando de instalación de dependencias:
```
uv sync
```
- Este comando instalará todas las dependencias según pyproject.toml (incluyendo MCP SDK, aiohttp, etc.)

4. Ajustes de Configuración

Configuración de la API de TAPD

Cree el archivo api.txt en el directorio raíz del proyecto, copie el siguiente texto y reemplace la configuración con los valores reales del proyecto TAPD de destino:
```
API_USER = '替换为你的TAPD API用户名'
API_PASSWORD = '替换为你的TAPD API密码'
WORKSPACE_ID = '替换为你的TAPD项目ID'
```
- Nota: El nombre de usuario y la contraseña de la API de TAPD deben obtenerse de la plataforma TAPD; consulte la documentación de la plataforma abierta para más detalles
- WORKSPACE_ID: ID del proyecto TAPD, se puede obtener a través de la plataforma TAPD
- Al enviar a Git, el archivo api.txt se ignorará según .gitignore, asegurando que la información sensible no se filtre

Configuración de la API de LLM

Advertencia especial: si sus datos de TAPD requieren un alto nivel de confidencialidad, no configure esta opción, o agregue una API de LLM que cumpla con los requisitos de confidencialidad en class APIManager de common_utils.py
El sistema ahora admite dos proveedores de API de LLM; puede elegir configurar según sus necesidades:

Configuración de la API de DeepSeek

Si necesita usar la función de resumen inteligente (generate_tapd_overview) o la función de optimización description (preprocess_tapd_description), debe configurar la clave de API de DeepSeek o SiliconFlow:

Obtener la clave de API: visite la plataforma abierta de DeepSeek, regístrese y obtenga la clave de API

Configurar la variable de entorno (Windows PowerShell):

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

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

Configuración de la API de SiliconFlow

SiliconFlow ofrece varios modelos de alta calidad, incluidos DeepSeek, Kimi, Qwen, etc.:

Obtener la clave de API: visite la plataforma abierta de SiliconFlow, regístrese y obtenga la clave de API
Si es su primer registro, en la página de registro puede ingresar mi código de invitación nYbojgoI; después de un registro exitoso, ambas partes recibirán un crédito de RMB 14, equivalente a una prueba gratuita de 1 millón de tokens