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文件。