Mcpagentre

🚀 MCP_Agent:RE 項目指南

MCP_Agent:RE 是一個用於從 TAPD 平臺獲取需求和缺陷數據並生成質量分析報告的 Python 項目，旨在為 AI 客戶端提供數據支持。以下是項目的詳細介紹和使用指南。

對話效果預覽

項目收錄信息

此項目於 2025 年 6 月 10 日由 punkpeye (Frank Fiegel) 收錄於 TAPD Data Fetcher | Glama。

項目代碼地址

• 本項目 GitHub 地址：https://github.com/OneCuriousLearner/MCPAgentRE
• 本項目在 Gitee 上同步更新，鏡像地址為：https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE

✨ 主要特性

本項目提供了豐富的 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 工具註冊方式

可用的 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-chat、deepseek-reasoner 模型
  • 支持 SiliconFlow API：moonshotai/Kimi-K2-Instruct 等模型
  • 自動檢測 API 類型並適配不同的請求格式和錯誤處理

全局實例管理函數

• get_config() - 獲取全局 MCPToolsConfig 實例（單例模式）
• get_model_manager() - 獲取全局 ModelManager 實例（單例模式）
• get_file_manager() - 獲取全局 FileManager 實例（單例模式）
• get_api_manager() - 獲取全局 APIManager 實例（單例模式）

📦 安裝指南

以下是將項目移植到其他 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

2. 安裝 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 文件，確保敏感信息不被洩露

2. 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

💻 使用示例

測試模式

驗證數據獲取

uv run tapd_data_fetcher.py

預期輸出：

成功加載配置: 用戶=********, 工作區=********
===== 開始獲取需求數據 =====
需求數據獲取完成，共獲取 X 條
===== 開始獲取缺陷數據 =====
缺陷數據獲取完成，共獲取 Y 條
數據已成功保存至 msg_from_fetcher.json 文件。

驗證 MCP 工具註冊

uv run check_mcp_tools.py

輸出結果如下：

成功加載配置: 用戶=4ikoesFM, 工作區=37857678
✅ MCP 服務器啟動成功！
📊 已註冊工具數量: 14

🛠️ 已註冊的工具列表:
    1. example_tool -
    示例工具函數（用於演示 MCP 工具註冊方式）

    功能描述:
        ...
    2. get_tapd_data - 從 TAPD API 獲取需求和缺陷數據並保存到本地文件

    功能描述:
        ...

快速驗證向量化功能（推薦）

uv run test\vector_quick_start.py

• 該腳本會自動運行數據獲取、向量化和搜索功能，驗證整體流程是否正常
• 首次使用時需要連接 VPN 以下載模型
• 預期輸出：顯示向量化成功和搜索演示結果

上下文優化器和假數據生成測試

# 生成模擬 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 格式的模擬數據

詞頻分析工具測試

uv run mcp_tools\word_frequency_analyzer.py

• 該腳本會分析 local_data/msg_from_fetcher.json 中的數據，生成關鍵詞詞雲統計

文檔摘要生成測試（仍在開發中）

uv run mcp_tools\docx_summarizer.py

• 該腳本會提取指定 .docx 文檔中的文本、圖片和表格信息，並生成摘要
• 預期輸出：生成的摘要 JSON 文件和提取的圖片、表格文件

測試用例評估器

# 運行自定義規則演示
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.json 與 config/require_list_config.json
• 詳細說明請參閱 knowledge_documents\AI 測試用例評估器操作手冊.md

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 腳本運行

評分規則配置

# 查看規則配置
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

運行需求單知識庫

uv run mcp_tools/test_case_require_list_knowledge_base.py

運行 AI 評估器

uv run mcp_tools/test_case_evaluator.py

📚 詳細文檔

項目結構

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

如何將項目連接到 AI 客戶端

前提條件

• 已在本地電腦上完成項目的遷移和驗證
• 已安裝並運行 MCP 服務器
• 已在本地電腦上安裝並運行 AI 客戶端（以 Claude Desktop 為例）

連接步驟

1. 打開 Claude Desktop

• 啟動 Claude Desktop 客戶端

2. 配置 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": "處理結果"}

2. 註冊工具到服務器

• 在 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)

3. 描述文檔最佳實踐

• 為 AI 客戶端添加清晰的文檔：
  • 函數級文檔：使用詳細的中文說明，包括參數類型和返回值結構
  • 參數說明：明確每個參數的數據類型和預期用途
  • 返回說明：詳細描述返回字典的每個字段
  • 示例：提供調用示例和預期輸出

🔧 技術細節

本項目是一個用於從 TAPD 平臺獲取需求和缺陷數據並生成質量分析報告的 Python 項目，旨在為 AI 客戶端提供數據支持。項目提供了豐富的 MCP 工具集，支持 TAPD 數據的獲取、處理、分析和智能摘要功能。

數據獲取工具

• get_tapd_data()：從 TAPD API 獲取需求和缺陷數據並保存到本地文件，返回數量統計。該函數適用於首次獲取數據或定期更新本地數據，包含需求和缺陷數據的完整集成。
• get_tapd_stories()：獲取 TAPD 項目需求數據，支持分頁並直接返回 JSON 數據，但不保存至本地，建議僅在數據量較小時使用。
• get_tapd_bugs()：獲取 TAPD 項目缺陷數據，支持分頁並直接返回 JSON 數據，但不保存至本地，建議僅在數據量較小時使用。

數據預處理工具

• preprocess_tapd_description()：清理 TAPD 數據中 description 字段的 HTML 樣式，提取文字、鏈接、圖片內容並通過 DeepSeek API 優化表達（需要配置 DeepSeek API 密鑰），大幅壓縮數據長度同時保留關鍵信息。
• preview_tapd_description_cleaning()：預覽 description 字段清理效果，展示壓縮比例和提取信息，不修改原始數據。
• docx_summarizer.py：提取 .docx 文檔中的文本、圖片和表格信息，並生成摘要。

向量化與搜索工具

• vectorize_data()：向量化工具，支持自定義數據源的向量化，將數據轉換為向量格式，用於後續的語義搜索和分析。
• get_vector_info()：獲取簡化版向量數據庫狀態和統計信息。
• search_data()：基於語義相似度的智能搜索，支持自然語言查詢，返回與查詢最相關的結果。

數據生成與分析工具

• generate_fake_tapd_data()：生成模擬 TAPD 數據，用於測試和演示。
• generate_tapd_overview()：使用 LLM 簡要生成項目概覽報告與摘要，用於瞭解項目概況（需要在環境中配置 DeepSeek API 密鑰）。
• analyze_word_frequency()：分析 TAPD 數據的詞頻分佈，生成關鍵詞詞雲統計，為搜索功能提供精準關鍵詞建議。

統一接口腳本

位於 mcp_tools\common_utils.py，提供統一的工具接口，簡化 MCP 工具的註冊和調用。包含的工具類有 MCPToolsConfig、ModelManager、TextProcessor、FileManager 和 APIManager，以及全局實例管理函數。

項目結構

項目包含多個目錄和文件，用於存儲配置文件、知識文檔、文檔數據、本地數據、MCP 工具、模型、測試腳本等。詳細的項目結構請參考上文的項目結構部分。

📄 許可證

文檔中未提及相關信息，暫無法提供。

📖 相關文檔或網址

• TAPD 幫助文檔
• TAPD 開放平臺文檔
• MCP 中文站
• Model Context Protocol
• DeepSeek API Docs
• 創建對話請求 - SiliconFlow

常見問題排查

• 依賴缺失：若提示 ModuleNotFoundError，檢查是否執行 uv add 命令，或嘗試 uv add <缺失模塊名>
• API 連接失敗：確認 API_USER / API_PASSWORD / WORKSPACE_ID 正確，且 TAPD 賬號有對應項目的讀取權限
• Python 版本不匹配：確保目標電腦 Python 版本為 3.10.x（通過 python --version 驗證）