jira

JIRA Skill

使用 atlassian MCP 服务掌握 Jira 自动化与集成。此 Skill 支持以编程方式访问 Jira 事项、项目和元数据。

[!CRITICAL] ⚠️ 重要 - 参数传递：

使用函数调用语法（不要使用标志语法）。参数应放在函数调用中，而不是作为标志：

mcporter call 'atlassian.functionName(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary"])'

关键规则：

• 函数调用中的参数使用 camelCase
• 字符串值使用双引号："value"
• 数组值使用方括号表示法：["item1", "item2"]
• 对象值使用对象表示法：{key: "value"}
• 环境变量在引号外插值："'$VAR'"
• 不要使用 --flag 语法，也无需转义 JSON 字符串

快速设置

获取工单摘要（一次调用）

获取工单信息的最快方式：

mise x node@20 -- ./scripts/get_ticket_summary.sh TICKET-123

返回人类可读的摘要，包含：

• 键、摘要、类型、状态、优先级、经办人
• 创建/更新时间戳
• 完整描述
• 关联资源（PR 等）
• Jira 直达链接

用于解析的 JSON 输出：

mise x node@20 -- ./scripts/get_ticket_summary.sh TICKET-123 --json

返回包含 ticket 和 remoteLinks 对象的结构化 JSON。

获取当前用户信息

mise x node@20 -- ./scripts/get_current_user.sh

返回：accountId、displayName、email

或者获取指定字段：

mise x node@20 -- ./scripts/get_current_user.sh --account-id
mise x node@20 -- ./scripts/get_current_user.sh --email
mise x node@20 -- ./scripts/get_current_user.sh --display-name

获取 Cloud ID（所有操作必需）

export JIRA_CLOUD_ID=$(mise x node@20 -- ./scripts/get_cloud_id.sh)
export JIRA_URL=$(mise x node@20 -- ./scripts/get_cloud_id.sh --url)

此操作会设置后续所有 mcporter 调用所需的环境变量。

核心操作

搜索事项

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser() AND status = Open")'

指定字段：

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser()", fields: ["key", "summary", "status", "assignee"])'

使用分页：

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser()", maxResults: 50)'

返回：包含 key、fields.summary、fields.status.name 的 issues[] 数组

常用 JQL：

• assignee = currentUser() - 分配给你的事项
• status = Open - 按状态筛选
• project = PROJ - 指定项目
• updated >= -7d - 最近 7 天内更新的事项
• issuetype = Bug - 指定事项类型

获取事项详情

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

指定字段：

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary", "status", "assignee", "description"])'

使用 expand 获取更多详情：

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", expand: ["changelog", "editmeta"])'

返回：完整事项对象，包含 key、fields（摘要、状态、经办人、描述等）

获取事项转换

mise x node@20 -- mcporter call 'atlassian.getTransitionsForJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

返回：工作流状态变更可用转换项的 ID 和名称列表

将事项转换为新状态

mise x node@20 -- mcporter call 'atlassian.transitionJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", transition: {id: "11"})'

同时更新字段：

mise x node@20 -- mcporter call 'atlassian.transitionJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", transition: {id: "11"}, fields: {assignee: {id: "USER_ID"}})'

获取项目元数据

mise x node@20 -- mcporter call 'atlassian.getJiraProjectIssueTypesMetadata(cloudId: "'$JIRA_CLOUD_ID'", projectIdOrKey: "PROJ")'

编辑 Jira 事项字段

TODO：添加更新事项字段的示例

为事项添加评论

mise x node@20 -- mcporter call 'atlassian.addCommentToJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", commentBody: "Your comment here")'

附带 GitHub 永久链接：

mise x node@20 -- mcporter call 'atlassian.addCommentToJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", commentBody: "See implementation details:\n\nhttps://github.com/owner/repo/blob/commit-hash/path/to/file.ts#L123")'

返回：包含 id、body、author、created、updated 的评论对象

创建新事项

TODO：添加创建新事项的示例

获取事项类型元数据

mise x node@20 -- mcporter call 'atlassian.getJiraIssueTypeMetaWithFields(cloudId: "'$JIRA_CLOUD_ID'", projectIdOrKey: "PROJ", issueTypeId: "10001")'

获取相关链接（PR、Confluence 等）

mise x node@20 -- mcporter call 'atlassian.getJiraIssueRemoteIssueLinks(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

返回：包含关联资源的 remoteIssueLinks[] 数组

筛选 GitHub PR：

mise x node@20 -- mcporter call 'atlassian.getJiraIssueRemoteIssueLinks(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")' | \
  jq '.[]? | select(.type.name == "GitHub" or (.globalId | contains("github"))) | .object.url'

辅助脚本

脚本	用途
./scripts/get_ticket_summary.sh	一次调用获取工单摘要 - 一次调用即可获取所有工单信息（人类可读或 JSON 格式）
./scripts/get_current_user.sh	获取已认证用户信息（accountId、displayName、email）
./scripts/get_cloud_id.sh	获取 Jira Cloud ID 和 URL

常见问题与解决方案

问题	解决方案
没有可用的云 ID	运行 ./scripts/get_cloud_id.sh 获取并导出云 ID
需要当前用户信息	使用 ./scripts/get_current_user.sh 获取 accountId、displayName 和 email
搜索返回 0 个结果	检查 JQL 语法。尝试使用 status = Open，而不是 status = "To Do"。先在 Jira 界面中测试查询。
在 remoteIssueLinks 中找不到 PR 链接	并非所有 PR 都会自动关联。检查是否已在 GitHub/Jira 中创建“Link”。
转换失败并显示“Cannot transition”	转换 ID 错误。务必先运行 getTransitionsForJiraIssue，查看当前状态的有效转换。
“Invalid arguments”或命令失败	使用函数调用语法，而不是标志语法。参数应放在 functionName(param: value) 中，而不是 --param value
数组无法正常使用	在函数调用中使用方括号表示法：fields: ["key", "summary"]，而不是 --fields '["key","summary"]'
对象无法正常使用	在函数调用中使用对象表示法：transition: {id: "11"}，而不是 --transition '{"id":"11"}'

使用架构内省发现函数参数

mcporter CLI 可以检查 MCP 服务架构，以发现正确的参数及其类型。

列出所有可用工具

mise x node@20 -- mcporter list atlassian --json | jq -r ".tools[].name"

返回：

atlassianUserInfo
getAccessibleAtlassianResources
getConfluenceSpaces
getConfluencePage
getPagesInConfluenceSpace
getConfluencePageFooterComments
getConfluencePageInlineComments
getConfluencePageDescendants
createConfluencePage
updateConfluencePage
createConfluenceFooterComment
createConfluenceInlineComment
searchConfluenceUsingCql
getJiraIssue
editJiraIssue
createJiraIssue
getTransitionsForJiraIssue
transitionJiraIssue
lookupJiraAccountId
searchJiraIssuesUsingJql
addCommentToJiraIssue
addWorklogToJiraIssue
getJiraIssueRemoteIssueLinks
getVisibleJiraProjects
getJiraProjectIssueTypesMetadata
getJiraIssueTypeMetaWithFields
search
fetch

检查特定工具的架构

mise x node@20 -- mcporter list atlassian --json | jq '.tools[] | select(.name == "addCommentToJiraIssue")'

这会返回完整的 JSON 架构，包括：

• inputSchema.properties - 所有可用参数及其类型和说明
• inputSchema.required - 必填参数
• options - 每个参数的 CLI 专用元数据

仅筛选必填参数：

mise x node@20 -- mcporter list atlassian --json | \
  jq '.tools[] | select(.name == "addCommentToJiraIssue") | .inputSchema.required[]'

获取参数说明：

mise x node@20 -- mcporter list atlassian --json | \
  jq '.tools[] | select(.name == "addCommentToJiraIssue") | .inputSchema.properties | to_entries[] | "\(.key): \(.value.description)"'

这种内省方法适用于任何工具——只需更改 select() 筛选器中的工具名称。

提示

• 每个会话只需设置一次：

  export JIRA_CLOUD_ID=$(mise x node@20 -- ./scripts/get_cloud_id.sh)
  export JIRA_URL=$(mise x node@20 -- ./scripts/get_cloud_id.sh --url)
  

• 函数调用语法是 mcporter 的标准语法 - 使用 mcporter call 'func(param: value)'，不要使用标志

• 转换前务必先使用 getTransitionsForJiraIssue - 转换 ID 会因项目工作流而异

• 在引号外插入环境变量：mcporter call 'func(cloudId: "'$VAR'")' 可行，但 mcporter call 'func(cloudId: "$VAR")' 不可行

• 在 Shell 脚本中使用 jq 解析 JSON

• 不确定参数时使用架构内省 - mcporter list atlassian --json | jq 是你的好帮手

• 完整工作流示例请参阅 examples/ 目录