AI导哈

Jira自动化测试服务

MCP Jira Automation是一款AI辅助的Jira工作流自动化服务，能够自动解析Jira问题、生成或更新测试用例、执行测试并反馈结果至Jira。

  • by ahmetguness
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 ahmetguness/mcp-jira-automation

使用说明

MCP Jira自动化

MCP Jira Automation是用于Jira驱动的开发工作流的AI辅助自动化服务。它轮询或接收Jira问题，解决目标源代码库，与AI提供商生成或更新测试，在Docker中执行测试，打开拉取请求，并将结果报告给Jira。

该服务旨在与单独运行的 mcp-atlassian 服务器，它通过模型上下文协议提供Jira访问。

建筑

mcp-atlassian (standalone service, port 9000)
    -> mcp-jira-automation (this project)

graph TD
    A[Jira issue] --> B[MCP Atlassian]
    B --> C[Jira poller or webhook]
    C --> D[Pipeline handler]
    D --> E[Repository resolver]
    E --> F[SCM provider]
    F --> G[Source repository]
    G --> H[AI provider]
    H --> I[Generated tests and commands]
    I --> J{Executor}
    J -->|local| K[Local Docker]
    J -->|ssh| L[Remote Docker over SSH]
    K --> M[Test results]
    L --> M
    M --> N[Pull request]
    M --> O[Jira comment]
    O --> B

能力

  • 阅读Jira问题 mcp-atlassian.
  • 从Jira自定义字段、问题描述或存储库URL解析存储库。
  • 支持GitHub、GitLab和Bitbucket源代码控制集成。
  • 使用OpenAI、Anthropic、Gemini、vLLM或Aider进行AI辅助测试生成。
  • 针对现有的远程API或在隔离的Docker沙箱中运行生成的测试。
  • 支持本地Docker执行和SSH远程Docker执行。
  • 使用生成的测试更改创建拉取请求。
  • 将执行摘要和失败发布回Jira。
  • 支持按问题提示覆盖和全局自定义提示。

需求

  • Node.js 20或更高版本
  • Docker，使用本地执行器或沙盒模式时
  • GitHub、GitLab或Bitbucket的访问令牌
  • 跑步 mcp-atlassian 服务
  • 至少一个AI提供者的凭据，或Aider CLI访问权限

安装

安装依赖项，构建项目，并链接 mja CLI：

npm install
npm run build
npm install -g .

创建本地配置文件：

cp .env.example .env
cp mcp-atlassian.env.example mcp-atlassian.env

使用Jira、SCM、AI提供者、执行器和MCP设置编辑这两个文件。

运行服务

开始 mcp-atlassian 第一。安装详见上游工程：

https://github.com/sooperset/mcp-atlassian

例子：

cd /path/to/mcp-atlassian
uv run mcp-atlassian --transport streamable-http --host 0.0.0.0 --port 9000 --path /mcp

如果你使用 UV_ENV_FILE，指向您的 mcp-atlassian.env 文件，以便MCP服务可以加载Jira凭据：

[Environment]::SetEnvironmentVariable("UV_ENV_FILE", "C:\path\to\mcp-atlassian.env", "User")

然后启动自动化服务：

mja app

有用的CLI命令：

mja app
mja help

码头工人

使用Docker Compose构建并启动完整的本地堆栈：

docker compose up --build

组合堆栈开始：

  • mcp-atlassian 在端口上 9000
  • 用于执行器容器的受限Docker套接字代理
  • 这 runner 此应用程序的服务

跑步者读到 .env 在运行时，同时 mcp-atlassian 读取 mcp-atlassian.env。容器特定值在中被覆盖 docker-compose.yml。这将保留本地Windows值，例如 AIDER_PATH=C:\Users\...\aider.exe 防止泄漏到Linux容器中；Docker镜像安装Aider并使用 AIDER_PATH=aider.

Jira工作流

除非启用了webhook模式，否则该服务将使用JQL查询轮询Jira。 JQL_ASSIGNED_TO_BOT 可以添加队列筛选器，但轮询的范围始终为 JIRA_ASSIGNEE_JQL。默认情况下，这将使用 JIRA_EMAIL.

对于每个匹配问题，服务：

  1. 读取问题元数据和描述。
  2. 解析目标存储库。
  3. 通过配置的SCM提供程序克隆或访问存储库。
  4. 根据问题、存储库上下文和可选提示覆盖构建AI提示。
  5. 生成测试更改。
  6. 使用配置的执行后端运行测试。
  7. 创建拉取请求。
  8. 将结果发布到Jira。

存储库解析

目标存储库按以下顺序解析：

  1. Jira Repository 自定义字段。
  2. A. Repository: owner/repo 问题描述中的行。
  3. 问题描述中的GitHub、GitLab或Bitbucket URL。

问题描述示例

Repository: ahmet/example-api

base_url: https://staging.example.com

Test the authentication endpoints:
- POST /api/auth/register
- POST /api/auth/login
- GET /api/auth/profile

每期覆盖

字段 描述
base_url: https://... 此问题的目标API URL。这隐式地启用了任务的远程执行。
execution_mode: remote 针对已在运行的API运行测试。
execution_mode: sandbox 在Docker中启动后端，并在沙盒内本地运行测试。

按问题提示覆盖

添加一个 [PROMPT]...[/PROMPT] 阻止问题描述，以提供特定任务的AI指令：

Repository: ahmet/example-api

[PROMPT]
Only test the /auth endpoints.
Write test names and comments in English.
[/PROMPT]

快速定制

系统提示可以在三个级别进行自定义：

级别 方法 范围
全局 创建 prompts/custom.md 所有问题
全局 设置 CUSTOM_PROMPT_FILE=/path/to/prompt.md 在 .env 所有问题
每期 添加 [PROMPT]...[/PROMPT] Jira描述 单一问题

使用 prompts/custom.md.example 作为一个起点。

执行模式

远程模式

远程模式针对已经运行的API生成并运行测试。它不会安装后端依赖项或启动应用程序服务。

EXECUTION_MODE=remote
API_BASE_URL=https://staging-api.example.com

API基本URL按以下顺序解析：

  1. Jira自定义字段或 base_url 在问题描述中。
  2. API_BASE_URL 在 .env.
  3. 如果可用，从存储库README自动检测。

沙盒模式

沙盒模式将存储库克隆到Docker中，检测项目类型，安装依赖关系，启动后端服务，并独立运行测试。

EXECUTION_MODE=sandbox

执行器后端

本地Docker

当Docker与此服务在同一台机器上运行时，请使用本地后端：

EXECUTOR_BACKEND=local

SSH Docker

当Docker在远程主机上运行时，使用SSH后端：

EXECUTOR_BACKEND=ssh
SSH_HOST=192.0.2.10
SSH_PORT=22
SSH_USER=ubuntu
SSH_PRIVATE_KEY_PATH=/home/user/.ssh/id_rsa
SSH_REMOTE_WORKDIR=/opt/mcp-jira-automation/workspaces
SSH_CLEANUP_WORKSPACE=true
SSH_REMOVE_IMAGE=false

远程用户必须有权访问 git Docker。

AI提供商

选择AI提供商 AI_PROVIDER:

AI_PROVIDER=openai
AI_MODEL=gpt-4o

支持的值：

  • openai
  • anthropic
  • gemini
  • vllm
  • aider

对于助手：

AI_PROVIDER=aider
AIDER_MODEL=gpt-4o
AIDER_PATH=aider
OPENAI_API_KEY=sk-...

aider 被视为外部CLI依赖关系。将其保存在此存储库之外：

  • 使用 AIDER_PATH=aider 当该命令在上可用时 PATH.
  • 或设置 AIDER_PATH 到项目目录外的绝对可执行路径。
  • 项目本地路径，如 ./aider, .venv/.../aider，或 node_modules/.bin/aider 被拒绝。
  • Docker runner镜像安装Aider并设置 AIDER_PATH=aider。不要将特定于主机的Windows路径传递到容器中。

配置参考

应用环境

变量 描述
JIRA_BASE_URL Jira基本URL
JIRA_EMAIL Jira帐户电子邮件。
JIRA_API_TOKEN Jira API令牌。
JIRA_PROJECT_KEY Jira项目密钥。
JIRA_AI_BOT_DISPLAY_NAME Jira显示机器人用户的名称。
JIRA_ASSIGNEE_JQL 用于轮询的JQL受让值。默认为 JIRA_EMAIL.
JIRA_REPO_FIELD_ID 可选存储库自定义字段ID。省略时自动检测。
JIRA_CREDENTIALS_FIELD_ID 可选凭据自定义字段ID
JIRA_BASE_URL_FIELD_ID 可选的基本URL自定义字段ID
JQL_ASSIGNED_TO_BOT 可选的额外队列筛选器。
MODE poll 或 webhook.
POLL_INTERVAL_MS 轮询间隔（毫秒）。
WEBHOOK_PORT webhook模式的HTTP端口。
WEBHOOK_SECRET 用于验证webhook签名的HMAC密钥。
SCM_PROVIDER github, gitlab，或 bitbucket.
GITHUB_TOKEN GitHub访问令牌。
GITLAB_TOKEN GitLab访问令牌。
GITLAB_URL GitLab基本URL。省略时默认为GitLab.com。
BITBUCKET_EMAIL 用于Bitbucket Cloud API访问的Atlassian帐户电子邮件。
BITBUCKET_API_TOKEN 比特桶API令牌。
BITBUCKET_USERNAME 可选Bitbucket用户名。
BITBUCKET_WORKSPACE 可选Bitbucket工作区。
AI_PROVIDER openai, anthropic, gemini, vllm，或 aider.
AI_MODEL 所选提供程序的型号名称。
OPENAI_API_KEY OpenAI API密钥。
ANTHROPIC_API_KEY 无烟煤API键。
GEMINI_API_KEY Gemini API密钥。
VLLM_BASE_URL vLLM OpenAI兼容的API基本URL
VLLM_MODEL vLLM型号名称。
AIDER_MODEL 助手型号名称。
AIDER_PATH Aider可执行文件的路径。
EXECUTION_MODE remote 或 sandbox.
API_BASE_URL 远程模式的目标API URL。
EXECUTOR_BACKEND local 或 ssh.
EXEC_POLICY strict 或 permissive.
DOCKER_IMAGE auto 或者一个明确的Docker镜像。
EXEC_TIMEOUT_MS 测试执行超时（毫秒）。
ALLOW_INSTALL_SCRIPTS 启用时允许依赖项安装脚本。
SSH_HOST SSH执行器的远程主机。
SSH_PORT SSH端口
SSH_USER SSH用户名。
SSH_PRIVATE_KEY_PATH SSH私钥的路径。
SSH_REMOTE_WORKDIR 远程工作区根目录。
SSH_CONNECT_TIMEOUT_MS SSH连接超时（毫秒）。
SSH_CLEANUP_WORKSPACE 启用后，在执行后删除远程工作区。
SSH_REMOVE_IMAGE 启用后，在执行后删除Docker映像。
CONTAINER_TEST_ENV 逗号分隔 KEY=VALUE 测试容器的覆盖。
REQUIRE_APPROVAL 启用后，在运行生成的测试之前需要Jira批准。
MCP_URL MCP Atlassian流式HTTP URL
MCP_TRANSPORT streamable-http 或 sse.
MCP_SSE_URL 传统SSE URL
CUSTOM_PROMPT_FILE 自定义系统提示文件的路径。
LOG_LEVEL debug, info, warn, error，或 silent.
STATE_FILE 持久状态文件路径。
MAX_ATTEMPTS 失败问题的最大重试次数。

MCP Atlassian环境

变量 描述
JIRA_URL Jira实例URL
JIRA_USERNAME Jira帐户电子邮件。
JIRA_API_TOKEN Jira API令牌。
CONFLUENCE_URL 可选汇流URL
CONFLUENCE_USERNAME 可选Confluence帐户电子邮件。
CONFLUENCE_API_TOKEN 可选Confluence API令牌。
TRANSPORT streamable-http 或 sse.
PORT MCP服务器端口
HOST MCP服务器主机。
MCP_HTTP_PATH 流式HTTP传输的HTTP路径。
TOOLSETS 启用MCP工具集。
READ_ONLY_MODE 启用时禁用写入操作。
FASTMCP_LOG_LEVEL FastMCP日志级别。
MCP_VERBOSE 启用正常的详细MCP日志记录。
MCP_VERY_VERBOSE 启用调试级MCP日志记录。

发展

npm run build
npm run lint
npm test

在不链接CLI的情况下运行应用程序：

npm run mja:app

操作说明

  • 保持 .env 和 mcp-atlassian.env 脱离版本控制。它们包含API令牌和机密。
  • 在生产webhook模式下，设置 WEBHOOK_SECRET.
  • 使用 EXEC_POLICY=strict 除非目标存储库需要更广泛的命令执行。
  • 生成的测试可能由于问题上下文不完整、缺少身份验证详细信息或对API行为的假设不正确而失败。失败将报告给Jira和pull请求进行审查。
  • 当测试失败时，仍可能创建拉取请求。这是有意的，因此可以查看生成的更改和执行日志。
  • SSH后端专注于远程Docker执行。与本地沙盒后端的完全功能对等可能取决于目标项目和远程主机配置。

相关 MCP