MCP Xray Python

🚀 QA自動導航儀：適用於Jira和Gemini的模型上下文協議（MCP）

QA自動導航儀是一款命令行工具（CLI），它實現了模型上下文協議（MCP）的概念。該工具就像一座橋樑，將Jira（作為知識庫服務器）與Google Gemini（通過Vertex AI）連接起來，用於生成測試用例。

✈️ 類比：自動駕駛儀

作為一名商業飛行員，我深知自動駕駛儀不會獨自操控飛機。飛行員仍然掌控著一切：監控系統、管理飛行計劃並做出關鍵決策。自動駕駛儀負責繁重且重複性的工作，讓飛行員能夠專注於戰略層面。

本項目將同樣的原則應用於質量保證（QA）領域。

❓ 問題所在

在Jira中手動創建測試用例是軟件開發生命週期中最必要但也最繁瑣的任務之一。這會消耗QA分析師大量寶貴的時間，而他們本可以將這些時間用於更有影響力的任務，如探索性測試、自動化策略設計或複雜的風險分析。

💡 解決方案：以“QA自動導航儀”作為MCP

受模型上下文協議（MCP）概念的啟發（該協議允許模型連接到知識庫服務器），此工具並非旨在取代QA分析師，而是增強他們的能力。

它就像一個智能橋樑，只需一個命令即可運行：

1. 從終端接收Jira的用戶故事（HU）ID。
2. 作為MCP：連接到Jira的API（“知識庫服務器”）以提取完整的上下文（描述、驗收標準）。
3. 諮詢模型：將該上下文與QA提示一起發送給Google Gemini。
4. 生成一組詳細的測試用例（採用Gherkin格式）。
5. 自動在Jira/Xray中創建“測試”類型的問題，並將其與原始的用戶故事關聯起來。

📈 結果

QA分析師（“飛行員”）無需花費數小時編寫測試用例，只需審查、調整和批准生成的測試用例，從而節省大量的時間和精力。

🔧 架構與工作流程

應用程序的流程如下：

1. 啟動：用戶（QA分析師）從終端運行run_mcp.py腳本，並傳入一個問題ID（例如：python run_mcp.py --issue PROJ-123）。
2. 提取（Jira）：腳本使用src/core/jira.py模塊連接到Jira的API，獲取PROJ-123的詳細信息（標題、描述、驗收標準）。
3. 生成（Gemini）：腳本將這些信息傳遞給src/core/llm.py模塊，該模塊構建一個提示並將其發送到Vertex AI中的Gemini API。
4. 響應（Gemini）：Gemini返回一個結構化的響應（例如：包含Gherkin格式測試用例列表的JSON）。
5. 創建（Jira/Xray）：腳本獲取這些測試用例，並再次使用src/core/jira.py在Jira中為每個測試用例創建“測試”類型的問題，並自動將它們與原始的用戶故事PROJ-123關聯起來。
6. 結束：腳本在終端打印確認信息。QA分析師現在可以在Jira中查看生成的測試用例。

🛠️ 技術棧

• 後端：Python 3.10+
• 人工智能：通過Google Cloud Vertex AI使用Google Gemini
• 集成：Jira REST API（使用requests庫）
• 命令行界面：Python的argparse
• 配置：使用python-dotenv安全管理憑證

📦 安裝指南

按照以下步驟在本地機器上配置和運行該項目：

1. 先決條件

• Python 3.10或更高版本。
• 安裝了Xray的Jira Cloud賬戶。
• 在Atlassian創建API令牌的權限。
• 啟用了Vertex AI API的Google Cloud項目，並擁有認證憑證（一個服務賬戶的JSON文件）。

2. 安裝步驟

• 克隆此倉庫：

git clone https://github.com/tu-usuario/mcp-xray-python.git
cd mcp-xray-python

• 創建虛擬環境：

python -m venv venv

• 激活虛擬環境：
  • macOS/Linux：

source venv/bin/activate

- **Windows**：

.\venv\Scripts\activate

• 安裝依賴項：

pip install -r requirements.txt

3. 配置憑證

本項目使用.env文件安全地管理敏感信息。

• 創建示例文件的副本：

cp .env.example .env

• 使用文本編輯器打開.env文件，並填寫所有變量：

# JIRA配置
JIRA_URL="https://tu-instancia.atlassian.net"
JIRA_USER="tu-email-de-jira@dominio.com"
JIRA_API_TOKEN="TU_API_TOKEN_DE_JIRA_AQUI"
JIRA_PROJECT_KEY="PROJ" # 你Jira項目的密鑰（例如：'TEST'）

# Google Vertex AI（Gemini）配置
VERTEX_AI_PROJECT_ID="tu-id-de-proyecto-gcp"
VERTEX_AI_LOCATION="us-central1" # 或你使用的區域

# Google Cloud憑證JSON文件的路徑
# 確保此路徑正確
GOOGLE_APPLICATION_CREDENTIALS="./ruta/a/tu/archivo-credenciales.json"

# Gemini模型配置
GEMINI_MODEL_NAME="gemini-1.5-pro" # 或你喜歡的模型

💻 使用示例

基礎用法

一旦你的虛擬環境（venv）激活且.env文件配置完成，運行該工具就像使用Jira問題ID運行run_mcp.py腳本一樣簡單。

# 基本使用示例：
python run_mcp.py --issue ALL-8296

# 示例：刪除過時的測試（而不是僅標記它們）：
python run_mcp.py --issue ALL-8296 --delete-obsolete

🧪 單元測試

項目包含一組單元測試，以確保主要模塊中代碼的質量和穩定性。

1. 安裝開發依賴項

確保你已安裝pytest（包含在requirements.txt中）：

pip install -r requirements.txt

2. 運行測試

從項目的根目錄，只需運行：

pytest

🤝 貢獻

歡迎貢獻！如果你有改進該工具、優化Gemini提示或添加新功能的想法，請按以下步驟操作：

1. Fork項目。
2. 創建你的功能分支（git checkout -b feature/MejoraIncreible）。
3. 提交你的更改（git commit -m 'Añade MejoraIncreible'）。
4. 將更改推送到分支（git push origin feature/MejoraIncreible）。
5. 打開一個Pull Request。

📄 許可證

本項目採用MIT許可證。有關詳細信息，請參閱LICENSE文件。