Jira Pilot

Jira Pilot ✈️

为人类和 Agent 打造的 AI 驱动型 Jira 命令行工具和 MCP 服务。

jira-pilot 是新一代命令行工具，将传统开发者工具与现代 AI 功能相结合。

• 面向人类： 一款精美的交互式命令行工具，用于管理问题、冲刺、看板和代码。现已支持 AI 代码审查、史诗规划、每日站会和自然语言 JQL。
• 面向 Agent： 完全合规的 Model Context Protocol (MCP) 服务，提供 14 个工具，让 AI 助手（如 Claude Desktop、Cursor 或 Gemini）能够安全地与您的 Jira 实例交互。

---

功能一览

👤 以人为本的功能

功能	描述
问题管理	创建、编辑、查看、列出、转换状态、分配和评论问题
工作与时间	新增： 记录工作时间（2h 30m）、管理冲刺（开始／完成）和子任务
开发者工具	新增： 打开 PR、保存本地筛选器、集成 git 分支
高级工具	新增： 批量分配、批量添加标签、批量转换符合 JQL 条件的问题状态
高级数据	新增： 上传附件、通过别名管理自定义字段
AI Copilot	总结内容、起草描述、建议操作、审查代码、规划史诗、生成站会报告
交互式向导	使用 enquirer 提供分步提示 — 无需任何标志
丰富的可视化	概览仪表板、加载动画和格式化输出
导出	输出到 JSON 或 Markdown 文件，支持管道传输的 JSON 输出

🤖 Agent 功能（MCP）

功能	描述
14 个 MCP 工具	list_issues、get_issue、create_issue、update_issue、transition_issue、assign_issue、add_comment、add_worklog、create_subtask、add_attachment、search_users、myself、list_projects、list_sprints
针对大模型优化	简洁、结构化的 JSON 响应，高效利用令牌
Stdio 传输	标准 MCP stdio 服务 — 适用于任何 MCP 客户端

---

🚀 安装

先决条件

• Node.js 20.0.0 或更高版本

全局安装（推荐）

npm install -g jira-pilot

安装后，即可全局使用 jira 命令。

---

⚙️ 配置

使用工具前，请设置您的凭据。您可以在 Atlassian 帐户设置中获取 API Token。

初始设置

jira config setup

系统会提示您填写：

1. Jira 站点 URL — 例如：https://your-company.atlassian.net
2. 电子邮箱 — 您的 Atlassian 帐户邮箱
3. API Token — 您从 Atlassian 生成的令牌
4. 启用 AI — 开启／关闭 AI 功能
5. AI 提供商 — 在 openai、gemini 或 anthropic 之间选择
6. AI API Key — 所选提供商的 API 密钥

配置文件与管理

管理多个环境的凭据（例如，工作与个人、生产与开发）。

jira config view              # Show current configuration (keys are masked)
jira config save work         # Save current creds as profile 'work'
jira config use personal      # Switch to profile 'personal'
jira config profiles          # List all saved profiles
jira config delete-profile work
jira config clear             # Remove all stored credentials

自定义字段别名

为自定义字段 ID 定义别名，让命令更易于使用：

jira config field set points customfield_10011
jira config field list

---

✨ 交互体验

Jira Pilot 专为完整的交互体验而设计。你无需记住复杂的标志。

只需运行命令，我们会引导你完成操作：

1. 选择：使用方向键 ↑ ↓ 浏览列表（项目、问题类型、优先级）。
2. 筛选：开始输入内容，以筛选较长的列表（例如，查找特定经办人）。
3. 向导：创建问题等复杂流程会拆分为简单步骤。
4. 确认：执行破坏性操作前会提示确认（y/N）。

示例：

jira issue create
? Select Project: PROJ - My Project
? Select Issue Type: Bug
? Summary: Login page crashes
? Priority: High
? Assignee: Me

---

🖥️ 文本用户界面（TUI）

在持久运行的交互式终端界面中使用 Jira。

jira tui

主要功能：

• 仪表板：概览分配给你的工作。
• 问题导航器：浏览、筛选和查看问题。
• 看板：直观呈现并管理敏捷看板上的工作。
• 交互操作：使用方向键浏览行和列。

导航快捷键：

• ← / → ：切换选项卡（仪表板、问题、看板）或看板列
• ↑ / ↓ ：浏览列表
• Enter ：选择 / 查看详情
• Esc / b ：返回
• q ：退出

---

📊 我的仪表板

以全局概览开启一天，了解当前待办事项。

jira dashboard

你将看到：

• 👋 欢迎消息：个性化问候。
• 🔥 高优先级：分配给你且需要立即关注的问题。
• 📋 最近活动：你最近查看或更新的问题。
• 🚀 Sprint 状态：（如适用）活跃 Sprint 的进度。

---

📖 使用指南

📋 问题管理

列出问题

# List issues assigned to you in active sprints (interactive)
jira issue list

# List with custom JQL
jira issue list --jql "project = PROJ AND priority = High"

# Filter by project, assignee, or status via flags
jira issue list --project PROJ --assignee "john.doe" --status "In Progress"

# Limit results
jira issue list --limit 20

# Natural Language JQL (AI)
jira issue list --ask "high priority bugs assigned to me"

# Export results to file
jira issue list --export json    # Creates issues-TIMESTAMP.json
jira issue list --export md      # Creates issues-TIMESTAMP.md

# Pipeable JSON output (to stdout)
jira issue list --output json | jq .

搜索问题

使用 JQL text ~ "query" 快速搜索文本：

jira issue search "login bug"
jira issue search "error 500" --project PROJ

查看问题详情

jira issue view PROJ-123

显示：摘要、状态、优先级、经办人、描述、组件、标签、日期、版本和近期评论。

创建问题

# Interactive wizard (recommended)
jira issue create

# Non-interactive with flags for speed
jira issue create -p PROJ -s "Fix login bug"
jira issue create -p PROJ -t Bug -s "Crash on save" --priority High
jira issue create -p PROJ -t Story -s "Add dark mode" -d "Users want a dark theme" -a me

# With Custom Fields (using Alias or ID)
jira issue create -p PROJ -s "Story" --custom "points=5" --custom "customfield_10022=DevOps"

编辑问题

# Interactive Field Picker
jira issue edit PROJ-123

# Quick Edits
jira issue edit PROJ-123 -s "New Summary" --priority High
jira issue edit PROJ-123 -d "New description"
jira issue edit PROJ-123 --custom "points=8"

转换问题状态

# Interactive — shows available transitions
jira issue transition PROJ-123

# Direct — specify target status
jira issue transition PROJ-123 --status "In Progress"
jira issue transition PROJ-123 -s Done

分配 / 重新分配

# Interactive — choose Myself, Unassign, or Search
jira issue assign PROJ-123

# Quick assign
jira issue assign PROJ-123 -a me       # Assign to yourself
jira issue assign PROJ-123 -a none     # Unassign

添加评论

# Interactive — prompts for comment text
jira issue comment PROJ-123

# Inline comment
jira issue comment PROJ-123 -m "Fixed in latest build"

其他操作

# Link Issues
jira issue link PROJ-123 PROJ-456 -t Blocks

# Watchers
jira issue watch PROJ-123
jira issue unwatch PROJ-123

# Attachments
jira issue attach PROJ-123 ./logs/server.log

---

⏱️ 工作与时间

工作日志

轻松记录问题所花费的时间。

# Add worklog
jira issue worklog add PROJ-123 2h "Researching API"
jira issue worklog add PROJ-123 30m "Daily standup"
jira issue worklog add PROJ-123 1d "Implementation"

# List worklogs
jira issue worklog list PROJ-123

子任务

# Interactive subtask creation
jira issue subtask PARENT-123

# Quick subtask
jira issue subtask PARENT-123 -s "Implement backend logic" --assignee me

Sprint 管理

直接管理你的敏捷看板。

# List sprints
jira sprint list --board "My Board"
jira sprint list --board 5 --state active

# List issues in active sprint
jira sprint issues --board 5

# Start/Complete Sprints
jira sprint start 123 --start-date 2023-10-01 --end-date 2023-10-15
jira sprint complete 123

---

👨‍💻 开发者工作流

Pull Request

创建 GitHub PR，并根据 Jira 问题预填标题和正文。

jira issue pr PROJ-123
# Requires 'gh' CLI to be installed and authenticated

Git 集成

自动创建以问题摘要命名的功能分支。

jira git branch PROJ-123
# Creates: feature/PROJ-123-issue-summary-slug

已保存的筛选器

在本地保存复杂的 JQL 查询，以便快速访问。

# Save a filter
jira filter save "My Bugs" "assignee = currentUser() AND issuetype = Bug AND status != Done"

# List saved filters
jira filter list

# Use a saved filter
jira issue list --filter "My Bugs"

# Delete a filter
jira filter delete "My Bugs"

---

⚡ 高级工具（批量操作）

对匹配 JQL 查询的多个问题执行操作。适用于清理或批量更新。

批量转换状态

将多个问题移至新状态。

jira bulk transition -j "project = PROJ AND status = 'To Do'" -s "In Progress"
# Optional: -y to skip confirmation

批量分配

将一组问题分配给某位用户。

jira bulk assign -j "priority = High AND assignee is EMPTY" --assignee me

批量添加标签

为一组问题添加或移除标签。

jira bulk label -j "fixVersion = 1.0" --add "release-candidate" --remove "wip"

---

📂 项目与看板

列出项目

jira project list
# Displays: project key, name, lead, and style in a formatted table.

列出看板

# List all boards
jira board list

# Filter by project
jira board list -p PROJ

# Filter by type
jira board list -t scrum
jira board list -t kanban

---

🤖 AI 功能

**需要：**在 config setup 中启用 AI。

总结问题

通过 AI 生成的 TL;DR，概括包含评论的长问题讨论：

jira ai summarize PROJ-123

起草问题描述

根据粗略笔记或项目符号生成结构化的问题描述：

# Interactive — prompts for your notes
jira ai draft

# Inline with issue type context
jira ai draft -i "login fails, returns 500, only on mobile" -t bug
jira ai draft -i "add dark mode toggle to settings" -t story

建议后续操作

分析问题，并获取 AI 提供的下一步操作建议：

jira ai suggest PROJ-123

返回：立即执行的下一步操作、潜在阻碍、建议的状态转换和建议。

AI 代码审查

根据问题要求分析关联的 PR / 代码更改：

jira ai review PROJ-123

需要在配置中设置 githubToken。

AI Epic 规划

将 Epic 拆分为子 Story / Task，并批量创建：

jira ai plan EPIC-123    # Interactive selection of proposed tasks

AI 站会报告

根据近期活动生成每日站会报告：

jira ai standup

输出：昨天、今天、阻碍。

---

🧠 与 AI Agent 配合使用（MCP）

jira-pilot 实现了 Model Context Protocol（MCP），可即插即用地供 AI 助手使用。

启动 MCP 服务

jira mcp

可用的 MCP 工具（14 个）

构建完全自主的 Jira Agent 所需的一切：

1. jira_list_issues：通过 JQL 搜索（支持 limit）
2. jira_get_issue：获取完整详情
3. jira_create_issue：创建新问题（支持 ADF）
4. jira_update_issue：更新摘要、描述、优先级和经办人
5. jira_transition_issue：更改状态
6. jira_assign_issue：更改经办人
7. jira_add_comment：添加评论
8. jira_add_worklog：记录工时
9. jira_create_subtask：创建子任务
10. jira_add_attachment：上传文件（绝对路径）
11. jira_search_users：搜索用户
12. jira_myself：获取当前用户详情
13. jira_list_projects：列出可访问的项目
14. jira_list_sprints：列出某个看板的冲刺

Agent 配置（Claude Desktop）

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-pilot", "mcp"]
    }
  }
}

VS Code / Cursor 配置

添加到你的 .vscode/mcp.json 或同类文件中：

{
  "servers": {
    "jira-pilot": {
      "command": "jira",
      "args": ["mcp"]
    }
  }
}

📝 提示词

预定义模板，帮助大模型有效地与 Jira 交互。

提示词	参数	描述
jira-assist	无	系统提示词，指导大模型如何最好地使用 Jira Pilot 工具。
jira-summarize-issue	issueKey	获取问题并指示大模型提供简洁的摘要。

📦 资源

直接将 Jira 数据用作上下文。

URI	描述
jira://myself	当前已验证身份的用户详情（不包含敏感个人身份信息）。
jira://projects	所有可访问的 Jira 项目列表。

🔍 验证

你可以使用官方检查器验证 MCP 服务实现：

# If running fro source
npx @modelcontextprotocol/inspector node dist/bin/jira.js mcp

# If installed globally (or via npx)
npx @modelcontextprotocol/inspector npx -y jira-pilot mcp

---

📦 CLI 命令参考

运行 jira help 或 jira [command] help 查看所有选项。

jira [command]

Commands:
  config           Configure Jira credentials & profiles
  issue            Manage Jira issues
  project          Manage Jira projects
  board            Manage Jira boards
  sprint           Manage Sprints
  bulk             Bulk operations on Jira issues
  dashboard        Show a quick overview of your Jira activity
  git              Git integration for Jira
  ai               AI Helper commands
  mcp              Start MCP Agent Server (Stdio)

---

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解如何提交拉取请求以及设置开发环境。

请注意，本项目遵循 贡献者行为准则。参与本项目即表示你同意遵守其中的条款。

🛡️ 安全

如果你发现本项目存在安全漏洞，请查看 SECURITY.md 了解漏洞报告政策。

📄 许可证

ISC