MCP_Agent:RE

Obtém dados de requisitos e defeitos da plataforma TAPD para fornecer suporte de dados para clientes de IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Guia do Projeto MCP_Agent:RE

Prévia do efeito da conversa (fase inicial do projeto)

对话效果预览

Este projeto foi incluído em 10 de junho de 2025 por punkpeye (Frank Fiegel) no TAPD Data Fetcher | Glama

Endereço do GitHub deste projeto: https://github.com/OneCuriousLearner/MCPAgentRE
Este projeto é sincronizado no Gitee, com espelho em https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE

Contexto do Projeto

MCP_Agent:RE é um projeto Python usado para obter dados de requisitos e defeitos da plataforma TAPD e gerar relatórios de análise de qualidade, com o objetivo de fornecer suporte de dados para clientes de IA.

Servidores MCP disponíveis

As ferramentas MCP estão centralizadas em tapd_mcp_server.py.
Este projeto oferece um conjunto robusto de ferramentas MCP, com suporte para obtenção, processamento, análise e resumo inteligente de dados do TAPD:

Ferramentas de obtenção de dados

get_tapd_data(clean_empty_fields) - Obtém dados de requisitos e defeitos da API do TAPD e salva em arquivos locais, retornando estatísticas de contagem【Recomendado】
- Adequado para a primeira obtenção de dados ou atualização periódica de dados locais
- Inclui integração completa de dados de requisitos e defeitos
get_tapd_stories(clean_empty_fields) - Obtém dados de requisitos do projeto TAPD, com suporte a paginação e retorno direto de dados JSON, sem salvar localmente; recomendado apenas para volumes pequenos de dados
get_tapd_bugs(clean_empty_fields) - Obtém dados de defeitos do projeto TAPD, com suporte a paginação e retorno direto de dados JSON, sem salvar localmente; recomendado apenas para volumes pequenos de dados

Ferramentas de pré-processamento de dados

preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images) - Limpa os estilos HTML do campo description nos dados do TAPD, extrai texto, links e imagens e otimiza a expressão via API de LLM (requer chave de API de LLM), reduzindo significativamente o tamanho dos dados enquanto preserva informações essenciais【Ainda em desenvolvimento...】
- Enfrentou limitações de exportação da API do Tencent Docs, que permite exportar apenas 9 documentos por dia
- Enfrentou problemas ao exportar imagens e vídeos dos detalhes dos dados do TAPD; ainda não há descrição relevante na documentação
- Atualmente, suporta apenas extração e processamento de conteúdo textual
preview_tapd_description_cleaning(data_file_path, item_count) - Pré-visualiza o efeito da limpeza do campo description, exibindo a taxa de compressão e as informações extraídas, sem modificar os dados originais
docx_summarizer.py - Extrai texto, imagens e tabelas de documentos .docx e gera resumos【Ainda em desenvolvimento...】

Ferramentas de busca precisa

precise_search_tapd_data(search_value, search_field, data_type, exact_match, case_sensitive) - Ferramenta de busca precisa nos dados do TAPD, com suporte a correspondência exata de campos em requisitos e defeitos
- Suporta busca exata ou difusa por qualquer campo
- Permite especificar busca em requisitos, defeitos ou ambos
- Suporta opção de diferenciação entre maiúsculas e minúsculas
- Fornece informações de correspondência e resumo estatístico
search_tapd_by_priority(priority_filter, data_type) - Busca dados do TAPD por prioridade, filtrando rapidamente itens de prioridade alta, média e baixa
- Suporta filtros predefinidos de prioridade alta, média e baixa
- Suporta busca por rótulos de prioridade específicos
- Por padrão, busca dados de prioridade alta (priority >= 3 ou urgent/high)
get_tapd_data_statistics(data_type) - Obtém estatísticas dos dados do TAPD, fornecendo análise abrangente da distribuição dos dados
- Inclui distribuição por quantidade, prioridade, status e criador
- Suporta estatísticas independentes para requisitos e defeitos
- Fornece estatísticas de projetos recentes e conclusão

Ferramentas de análise de tendência temporal

analyze_time_trends(data_type, chart_type, time_field, since, until, data_file_path) - Analisa tendências temporais, com suporte a dados de requisitos e defeitos, permitindo personalizar campo de tempo, intervalo de tempo e tipo de gráfico
- data_type: tipo de dado, valores possíveis: "story" e "bug"
- chart_type: tipo de gráfico, valores possíveis: "count" e "line"
- time_field: campo de tempo, valores possíveis: "created" e "updated"
- since: intervalo de tempo, formato "YYYY-MM-DD", opcional
- until: intervalo de tempo, formato "YYYY-MM-DD", opcional
- data_file_path: caminho do arquivo de dados, opcional, padrão "local_data/msg_from_fetcher.json"

Ferramentas de vetorização e busca

vectorize_data(data_file_path, chunk_size, preserve_existing) - Ferramenta de vetorização, com suporte a fontes de dados personalizadas, convertendo dados em formato vetorial para busca semântica e análise posteriores
get_vector_info() - Obtém status e estatísticas simplificados do banco de dados vetorial
search_data(query, top_k) - Busca inteligente baseada em similaridade semântica, com suporte a consultas em linguagem natural, retornando os resultados mais relevantes

Ferramentas de geração e análise de dados

generate_fake_tapd_data(n_story_A, n_story_B, n_bug_A, n_bug_B, output_path) - Gera dados simulados do TAPD para testes e demonstrações (se o endereço não for especificado, pode sobrescrever dados locais; para dados corretos da API do TAPD, chame novamente a ferramenta de obtenção de dados)
generate_tapd_overview(since, until, max_total_tokens, use_local_data) - Gera relatório de visão geral e resumo do projeto usando LLM, para entender o panorama do projeto (requer chave de API de LLM)
analyze_word_frequency(min_frequency, use_extended_fields, data_file_path) - Analisa a distribuição de frequência de palavras nos dados do TAPD, gerando estatísticas de nuvem de palavras-chave, fornecendo sugestões precisas de palavras-chave para a função de busca

Ferramentas de exemplo

example_tool(param1, param2) - Ferramenta de exemplo que demonstra como registrar ferramentas MCP

Essas ferramentas suportam um fluxo de trabalho completo, desde a obtenção de dados até a análise inteligente, fornecendo suporte robusto para gerenciamento de testes orientado por IA.

Scripts de WorkFlow disponíveis

Avaliação de casos de teste

test_case_rules_customer.py - Script de configuração de regras de avaliação de casos de teste, usado para configurar critérios de avaliação e prioridades
test_case_require_list_knowledge_base.py - Script de geração de base de conhecimento de requisitos de casos de teste, que extrai informações de requisitos dos dados do TAPD e gera a base de conhecimento, ou permite modificação manual
test_case_evaluator.py - Script de avaliador de IA para casos de teste, usado para avaliar a qualidade dos casos de teste com base nas regras configuradas e gerar relatório de avaliação em arquivo local

Scripts de interface unificada

Localizados em common_utils.py
Fornecem interface unificada de ferramentas, simplificando o registro e a chamada de ferramentas MCP
Ferramentas incluídas:

Classe MCPToolsConfig

__init__() - Inicializa o gerenciador de configuração, criando automaticamente a estrutura de diretórios necessária ao projeto (local_data, models, vector_data)
_get_project_root() - Obtém o caminho absoluto do diretório raiz do projeto
get_data_file_path(relative_path) - Obtém o caminho absoluto do arquivo de dados, com conversão automática de caminhos relativos
get_vector_db_path(name) - Obtém o caminho do arquivo do banco de dados vetorial, padrão "data_vector"
get_model_cache_path() - Obtém o caminho do diretório de cache de modelos

Classe ModelManager

__init__(config) - Inicializa o gerenciador de modelos, dependente da instância MCPToolsConfig
get_project_model_path(model_name) - Detecta se o modelo especificado existe localmente, retornando o caminho do modelo ou None
get_model(model_name) - Obtém instância do modelo SentenceTransformer, priorizando modelos locais, com suporte a download automático e cache
clear_cache() - Limpa o cache global de modelos, liberando recursos de memória

Classe TextProcessor

extract_text_from_item(item, item_type) - Extrai informações textuais essenciais de itens de dados do TAPD (requisitos/defeitos), com suporte a diferentes estratégias de extração por tipo de campo

Classe FileManager

__init__(config) - Inicializa o gerenciador de arquivos, dependente da instância MCPToolsConfig
load_tapd_data(file_path) - Carrega arquivos de dados JSON do TAPD, com suporte a caminhos absolutos e relativos
load_json_data(file_path) - Carrega arquivos de dados JSON, com tratamento de erros; retorna dicionário vazio se o arquivo não existir
save_json_data(data, file_path) - Salva dados em formato JSON, criando automaticamente a estrutura de diretórios
read_excel_with_mapping(excel_file_path, column_mapping, na_to_empty=True) - Leitura genérica de Excel e mapeamento de colunas, retornando list[dict]

Classe TransmissionManager

__init__(file_manager) - Inicializa o gerenciador de transmissão, dependente da instância FileManager
update_stats(success, retries) - Atualiza estatísticas de transmissão, registrando contagens de sucesso/falha e tentativas
finalize_report() - Gera relatório final de transmissão, salvando dados estatísticos em arquivo JSON

Classe TokenCounter

__init__(config) - Inicializa o contador de tokens, dependente da instância MCPToolsConfig, com carregamento automático do tokenizer DeepSeek
count_tokens(text) - Calcula a quantidade de tokens de um texto, priorizando cálculo preciso com a biblioteca transformers e usando modo de estimativa aprimorado em caso de falha
_try_load_tokenizer() - Tenta carregar o tokenizer DeepSeek local, com suporte a contagem precisa de tokens

Classe de utilitários BatchingUtils

split_by_token_budget(items, estimate_tokens_fn, token_threshold, start_index=0) - Divisão em lotes gananciosa baseada em limite de tokens, retornando (lista do lote atual, próximo ponto de início, tokens estimados)

Classe de utilitários MarkdownUtils

parse_markdown_tables(md_text) - Analisa tabelas Markdown em estrutura genérica [{headers, rows}], sem mapeamento de negócio

Classe APIManager

__init__() - Inicializa o gerenciador de API, com suporte a configuração dupla de API DeepSeek e SiliconFlow
get_headers(endpoint) - Constrói cabeçalhos de requisição de API de forma inteligente, selecionando automaticamente a chave de API correspondente ao endpoint
call_llm(prompt, session, model, endpoint, max_tokens) - Interface de chamada LLM compatível com múltiplas APIs
- Suporta API DeepSeek (padrão): modelos deepseek-chat, deepseek-reasoner
- Suporta API SiliconFlow: modelos como deepseek-ai/DeepSeek-V3.1
- Detecta automaticamente o tipo de API e adapta formatos de requisição e tratamento de erros

Funções globais de gerenciamento de instâncias

get_config() - Obtém instância global de MCPToolsConfig (padrão singleton)
get_model_manager() - Obtém instância global de ModelManager (padrão singleton)
get_file_manager() - Obtém instância global de FileManager (padrão singleton)
get_api_manager() - Obtém instância global de APIManager (padrão singleton)
get_transmission_manager() - Obtém instância global de TransmissionManager (padrão singleton)
get_token_counter() - Obtém instância global de TokenCounter (padrão singleton)

Estrutura do Projeto

Esses dados de diretórios podem não estar atualizados; considere a situação 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 arquitetura

项目架构图

Etapas de migração

A seguir estão as etapas detalhadas para migrar o projeto para outro computador Windows (ainda não testado em Mac e Linux):

1. Preparação do ambiente

Instalar Python 3.10

Baixe o instalador do Python 3.10.x no site oficial do Python (recomendado 3.10.11, consistente com o ambiente original)
Durante a instalação, marque Add Python to PATH (crítico! Caso contrário, será necessário configurar variáveis de ambiente manualmente)
Verifique a instalação: execute python --version no terminal; deve exibir Python 3.10.11

Instalar a ferramenta uv

Execute pip install uv no terminal (garanta que o pip foi instalado junto com o Python):
```
pip install uv
```
Verifique a instalação: execute uv --version; deve exibir informações de versão
Para saber como alternar versões do Python no UV, consulte UV - Gerenciando versões do Python, ambientes e pacotes de terceiros - Zhihu

2. Migração dos arquivos do projeto

Copiar o diretório do projeto

Copie o diretório original do projeto D:\MiniProject\MCPAgentRE completamente para o computador de destino (recomenda-se caminho sem caracteres chineses/espaços, como D:\MCPAgentRE)

3. Instalação de dependências

Criar ambiente virtual

No terminal, entre no diretório do projeto: cd D:\MCPAgentRE (ajuste conforme o caminho real)
Crie o ambiente virtual:
```
uv venv
```
- Esse comando criará um diretório de ambiente virtual chamado .venv no diretório do projeto

Instalar dependências do projeto

Execute o comando de instalação de dependências:
```
uv sync
```
- Esse comando instalará todas as dependências conforme pyproject.toml (incluindo MCP SDK, aiohttp etc.)

4. Ajustes de configuração

Configuração da API TAPD

Crie o arquivo api.txt no diretório raiz do projeto, copie o texto abaixo e substitua a configuração pelos valores reais do projeto TAPD de destino:
```
API_USER = '替换为你的TAPD API用户名'
API_PASSWORD = '替换为你的TAPD API密码'
WORKSPACE_ID = '替换为你的TAPD项目ID'
```
- Observação: o nome de usuário e a senha da API TAPD devem ser obtidos na plataforma TAPD; consulte a documentação da plataforma aberta para detalhes
- WORKSPACE_ID: ID do projeto TAPD, obtido pela plataforma TAPD
- Ao enviar para o Git, o arquivo api.txt será ignorado conforme .gitignore, garantindo que informações sensíveis não sejam expostas

Configuração da API LLM

Aviso importante: se os dados do TAPD exigirem alto nível de confidencialidade, não configure esta opção, ou adicione uma API LLM que atenda aos requisitos de confidencialidade em class APIManager no common_utils.py
O sistema agora suporta dois provedores de API LLM; escolha conforme sua necessidade:

Configuração da API DeepSeek

Se você precisar usar o recurso de resumo inteligente (generate_tapd_overview) ou a otimização description (preprocess_tapd_description), configure a chave da API DeepSeek ou SiliconFlow:

Obter chave de API: acesse a plataforma aberta DeepSeek, registre-se e obtenha a chave de API

Definir variável de ambiente (Windows PowerShell):

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

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

Configuração da API SiliconFlow

A SiliconFlow oferece diversos modelos de alta qualidade, incluindo DeepSeek, Kimi, Qwen etc.:

Obter chave de API: acesse a plataforma aberta SiliconFlow, registre-se e obtenha a chave de API
Se for seu primeiro registro, na página de registro você pode preencher meu código de convite nYbojgoI; após o registro bem-sucedido, ambas as partes recebem RMB 14 de crédito, equivalente a 1 milhão de tokens de teste gratuito