jira

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JIRA Skill

Jira自动化技能

Master Jira automation and integration using the atlassian MCP server. This skill enables programmatic access to Jira issues, projects, and metadata.

[!CRITICAL] ⚠️ IMPORTANT - Parameter Passing:

Use function-call syntax (NOT flag syntax). Parameters go inside the function call, not as flags:
bash
mcporter call 'atlassian.functionName(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary"])'
Key Rules:
Parameters are camelCase inside the function call
String values use double quotes:
"value"
Array values use bracket notation:
["item1", "item2"]
Object values use object notation:
{key: "value"}
Environment variables are interpolated outside quotes:
"'$VAR'"
NO
--flag
syntax, NO JSON string escaping needed

使用Atlassian MCP Server掌握Jira自动化与集成。该技能支持以编程方式访问Jira工单、项目及元数据。

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

请使用函数调用语法（而非标志位语法）。参数需放在函数调用内部，而非作为标志位：
bash
mcporter call 'atlassian.functionName(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary"])'
核心规则：
函数调用内部的参数采用小驼峰命名（camelCase）
字符串值使用双引号：
"value"
数组值使用方括号语法：
["item1", "item2"]
对象值使用对象语法：
{key: "value"}
环境变量在引号外插入：
"'$VAR'"
禁止使用
--flag
语法，无需转义JSON字符串

Quick Setup

快速设置

Get Ticket Summary (One-Shot)

获取工单摘要（一键式）

The fastest way to get ticket information:

bash

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

Returns human-readable summary with:

Key, summary, type, status, priority, assignee
Created/updated timestamps
Full description
Linked resources (PRs, etc.)
Direct link to Jira

JSON output for parsing:

bash

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

Returns structured JSON with

ticket

and

remoteLinks

objects.

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

bash

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

返回易读格式的摘要，包含：

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

用于解析的JSON格式输出：

bash

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

返回包含

ticket

和

remoteLinks

对象的结构化JSON。

Get Current User Info

获取当前用户信息

bash

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

Returns:

accountId

displayName

email

Or get specific fields:

bash

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

bash

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

accountId

、

displayName

、

email

或获取指定字段：

bash

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

Get Cloud ID (Required for all operations)

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

bash

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)

This sets up environment variables for all subsequent mcporter calls.

bash

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调用设置环境变量。

Core Operations

核心操作

Search Issues

搜索工单

bash

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

With specific fields:

bash

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

With pagination:

bash

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

Returns:

issues[]

array with

key

fields.summary

fields.status.name

Common JQL:

```
assignee = currentUser()
```
- Issues assigned to you
```
status = Open
```
- Filter by status
```
project = PROJ
```
- Specific project
```
updated >= -7d
```
- Updated in last 7 days
```
issuetype = Bug
```
- Specific issue type

bash

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

指定字段搜索：

bash

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

分页搜索：

bash

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
```
- 指定工单类型（缺陷）

Get Issue Details

获取工单详情

bash

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

With specific fields:

bash

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

With expand for additional details:

bash

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

Returns: Full issue object with

key

fields

(summary, status, assignee, description, etc)

bash

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

获取指定字段的工单详情：

bash

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

展开获取额外详情：

bash

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

返回：包含

key

、

fields

（摘要、状态、经办人、描述等）的完整工单对象

Get Issue Transitions

获取工单可执行转换

bash

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

Returns: List of available transitions with IDs and names for workflow state changes

bash

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

返回：用于工作流状态变更的可用转换列表，包含ID及名称

Transition Issue to New Status

将工单转换至新状态

bash

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

With field updates:

bash

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

bash

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

转换时更新字段：

bash

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

Get Project Metadata

获取项目元数据

bash

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

bash

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

Edit Jira Issue Fields

编辑Jira工单字段

TODO: Add example for updating fields on an issue

TODO: 添加编辑工单子段的示例

Add Comment to Issue

为工单添加评论

bash

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

With GitHub permalink:

bash

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")'

Returns: Comment object with

id

body

author

created

updated

bash

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

添加带GitHub永久链接的评论：

bash

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

的评论对象

Create New Issue

创建新工单

TODO: Add example for creating a new issue

TODO: 添加创建新工单的示例

Get Issue Type Metadata

获取工单类型元数据

bash

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

bash

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

Get Related Links (PRs, Confluence, etc)

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

bash

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

Returns:

remoteIssueLinks[]

array with linked resources

Filter for GitHub PRs:

bash

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'

bash

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

返回：包含关联资源的

remoteIssueLinks[]

数组

筛选GitHub PR链接：

bash

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'

Helper Scripts

辅助脚本

Script	Purpose
`./scripts/get_ticket_summary.sh`	One-shot ticket summary - Get all ticket info in one call (human or JSON format)
`./scripts/get_current_user.sh`	Get authenticated user info (accountId, displayName, email)
`./scripts/get_cloud_id.sh`	Get Jira Cloud ID and URL

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

Common Issues & Solutions

常见问题与解决方案

Problem	Solution
No cloud ID available	Run `./scripts/get_cloud_id.sh` to fetch and export it
Need current user info	Use `./scripts/get_current_user.sh` to fetch accountId, displayName, email
Search returns 0 results	Verify JQL syntax. Try `status = Open` instead of `status = "To Do"` . Test queries in Jira UI first.
PR link not found in `remoteIssueLinks`	Not all PRs auto-link. Check if "Link" was created in GitHub/Jira.
Transition fails with "Cannot transition"	Wrong transition ID. Always run `getTransitionsForJiraIssue` first to see valid transitions for current status.
"Invalid arguments" or command fails	Use function-call syntax, NOT flag syntax. Parameters go inside `functionName(param: value)` not `--param value`
Arrays not working	Use bracket notation inside function call: `fields: ["key", "summary"]` NOT `--fields '["key","summary"]'`
Objects not working	Use object notation inside function call: `transition: {id: "11"}` NOT `--transition '{"id":"11"}'`

问题	解决方案
无可用Cloud ID	运行 `./scripts/get_cloud_id.sh` 获取并导出Cloud ID
需要当前用户信息	使用 `./scripts/get_current_user.sh` 获取accountId、displayName、email
搜索返回0条结果	验证JQL语法。尝试使用 `status = Open` 而非 `status = "To Do"` 。先在Jira界面测试查询语句。
在 `remoteIssueLinks` 中未找到PR链接	并非所有PR都会自动关联。检查是否已在GitHub/Jira中创建"链接"。
转换工单时提示"无法转换"	转换ID错误。请始终先运行 `getTransitionsForJiraIssue` 查看当前状态下的有效转换。
提示"参数无效"或命令执行失败	使用函数调用语法，而非标志位语法。参数需放在 `functionName(param: value)` 内部，而非 `--param value`
数组参数不生效	在函数调用内部使用方括号语法： `fields: ["key", "summary"]` ，而非 `--fields '["key","summary"]'`
对象参数不生效	在函数调用内部使用对象语法： `transition: {id: "11"}` ，而非 `--transition '{"id":"11"}'`

Discovering Function Parameters with Schema Introspection

通过模式自省发现函数参数

The mcporter CLI can introspect the MCP server schema to discover correct parameters and their types.

mcporter CLI可自省MCP Server的模式，以发现正确的参数及其类型。

List All Available Tools

列出所有可用工具

bash

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

Returns:

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

bash

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

Inspect a Specific Tool Schema

检查特定工具的模式

bash

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

This returns the full JSON schema including:

```
inputSchema.properties
```
- All available parameters with types and descriptions
```
inputSchema.required
```
- Which parameters are mandatory
```
options
```
- CLI-specific metadata for each parameter

Filter for just required parameters:

bash

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

Get parameter descriptions:

bash

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

This introspection approach works for any tool - just change the tool name in the

select()

filter.

bash

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

此命令会返回完整的JSON模式，包括：

```
inputSchema.properties
```
- 所有可用参数及其类型和描述
```
inputSchema.required
```
- 必需参数列表
```
options
```
- 每个参数的CLI特定元数据

仅筛选必需参数：

bash

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

获取参数描述：

bash

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

这种自省方法适用于所有工具 - 只需在

select()

筛选器中修改工具名称即可。

Tips

提示

Setup once per session:

bash

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)

Function-call syntax is the mcporter standard - use
```
mcporter call 'func(param: value)'
```
not flags
Always use
getTransitionsForJiraIssue
before transitioning - transition IDs vary by project workflow

Interpolate env vars outside the quotes:

mcporter call 'func(cloudId: "'$VAR'")'

works, but

mcporter call 'func(cloudId: "$VAR")'

does not

Use
jq
for JSON parsing in shell scripts
Use schema introspection when unsure about parameters -
```
mcporter list atlassian --json | jq
```
is your friend
See
```
examples/
```
directory for full workflow examples

会话内仅需设置一次：

bash

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/
```
目录获取完整工作流示例