---

name: jira-integration description: 当需要获取 Jira 工单、分析需求、更新工单状态、添加评论或转换问题状态时使用此技能。通过 MCP 或直接 REST 调用提供 Jira API 模式。 origin: ECC

Jira 集成技能

直接从 AI 编码工作流中获取、分析和更新 Jira 工单。支持 MCP 方式（推荐）和直接 REST API 两种方式。

何时激活

• 获取 Jira 工单以了解需求
• 从工单中提取可测试的验收标准
• 向 Jira 问题添加进度评论
• 转换工单状态（待办 → 进行中 → 完成）
• 将合并请求或分支链接到 Jira 问题
• 通过 JQL 查询搜索问题

前提条件

方案 A：MCP 服务器（推荐）

安装 mcp-atlassian MCP 服务器。这会直接向你的 AI 代理暴露 Jira 工具。

要求：

• Python 3.10+
• uvx（来自 uv），通过包管理器或官方 uv 安装文档安装

添加到你的 MCP 配置（例如 ~/.claude.json → mcpServers）：

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira issue tracking — search, create, update, comment, transition"
  }
}

安全提示： 切勿硬编码密钥。优先在系统环境（或密钥管理器）中设置 JIRA_URL、JIRA_EMAIL 和 JIRA_API_TOKEN。仅在本地未提交的配置文件中使用 MCP env 块。

获取 Jira API 令牌：

1. 前往 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 创建 API 令牌
3. 复制令牌 — 存储在环境变量中，切勿放入源代码

方案 B：直接 REST API

如果 MCP 不可用，直接通过 curl 或辅助脚本使用 Jira REST API v3。

必需的环境变量：

| 变量 | 描述 | |----------|-------------| | JIRA_URL | 你的 Jira 实例 URL（例如 https://yourorg.atlassian.net） | | JIRA_EMAIL | 你的 Atlassian 账户邮箱 | | JIRA_API_TOKEN | 来自 id.atlassian.com 的 API 令牌 |

将这些存储在 shell 环境、密钥管理器或未跟踪的本地 env 文件中。不要提交到仓库。

MCP 工具参考

配置 mcp-atlassian MCP 服务器后，以下工具可用：

| 工具 | 用途 | 示例 | |------|---------|---------| | jira_search | JQL 查询 | project = PROJ AND status = "In Progress" | | jira_get_issue | 按键获取完整问题详情 | PROJ-1234 | | jira_create_issue | 创建问题（任务、Bug、故事、Epic） | 新 Bug 报告 | | jira_update_issue | 更新字段（摘要、描述、指派人） | 更改指派人 | | jira_transition_issue | 更改状态 | 移至"审查中" | | jira_add_comment | 添加评论 | 进度更新 | | jira_get_sprint_issues | 列出冲刺中的问题 | 活跃冲刺审查 | | jira_create_issue_link | 链接问题（阻塞、关联） | 依赖跟踪 | | jira_get_issue_development_info | 查看关联的 PR、分支、提交 | 开发上下文 |

提示： 在转换状态前始终调用 jira_get_transitions — 转换 ID 因项目工作流而异。

直接 REST API 参考

获取工单

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

获取评论

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

添加评论

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

转换工单状态

# 1. 获取可用的转换
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. 执行转换（替换 TRANSITION_ID）
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

使用 JQL 搜索

curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/search" --data-urlencode 'jql=project = PROJ AND status = "In Progress"'