本文面向 第一次配置 ：读完应能 自己拿到令牌、在 Cursor 应用内 配好 MCP，并用 Cursor Rules（User 或 Project） 让对话里 只写工单号（如 AK-99）即可驱动 拉工单、分析、方案、改代码。

配置入口以 Cursor 为准：MCP 走 Cursor → Settings → MCP（与编辑本机 mcp.json 等价，具体以你安装的 Cursor 版本界面为准）。「只发工单号」走 Cursor → Settings → Rules（User rules 或 随仓库的 Project rules），二选一即可，不必强依赖克隆某一份仓库。

说明：我们用的是 自建 Jira（例如 http://jira.xxx.com）+ 社区 MCP mcp-atlassian。它不是 Atlassian 官方产品，但官方文档齐全，适合接 Cursor。

---

一、配好之后你能做什么

• 在聊天里写：「请用 Jira MCP 拉取 AK-99，并分析根因」。
• 若已配置 User Rules 或 Project Rules（见第五节），可直接发：AK-99。
• AI 会通过 MCP 调 Jira 接口拿到标题、描述、评论等，再结合你 @ 的代码仓库 给出修改建议或直接改代码。
• MCP 列表里是绿灯 只表示「进程能起来」；要拿到工单内容，还必须 令牌正确、本机能访问 Jira（VPN）。

---

二、第一步：在 Jira 里创建「个人访问令牌」（PAT）

自建 Jira（Server / Data Center）一般用 PAT，不要用浏览器里「复制 Cookie」代替。

1. 浏览器打开公司 Jira（需已登录），例如：http://jira.xxx.com。
2. 点右上角 头像 → Profile（个人资料）。
3. 找到 Personal Access Tokens（个人访问令牌）（有的版本在 Security 或 账户设置 里）。
4. 点 Create token / 创建令牌，起个名字（如 cursor-mcp），如有到期时间按需选择。
5. 立刻复制 生成出来的字符串（只显示一次）。这就是下文里的 PAT。

若你只有 Atlassian 云（xxx.atlassian.net），令牌在 Atlassian 账户 - API tokens 创建，且 MCP 要用 邮箱 + API Token 方式（见第七节）。

---

三、第二步：本机安装 uv（用来启动 MCP）

mcp-atlassian 推荐用 uvx 一行启动，不必自己 pip install。

1. 打开 uv 安装说明，按 macOS / Windows 装好。
2. 打开终端，执行：

uvx --version

有版本号即可。

---

四、第三步：在 Cursor 里配置 MCP（随 Cursor）

4.0 推荐：用 Cursor 设置界面

1. 打开 Cursor → Settings（设置）→ MCP（或 Features → MCP，以你版本为准）。
2. Add new MCP server / 添加服务器，填写示例：
   • Name：mcp-atlassian
   • Command：uvx
   • Args（逐条）：mcp-atlassian
   • Environment variables：
     • JIRA_URL = http://jira.xxx.com（改成你们真实地址，注意 http / https）
     • JIRA_PERSONAL_TOKEN = 第二节复制的 PAT
3. 保存后看列表是否为 绿色；若不是，点进该服务器查看 日志。

界面配置与 Cursor 写入本机 mcp.json 是同一套数据；若你更习惯手写 JSON，见下一小节。

4.1 备选：直接编辑 mcp.json

路径（不要把含 PAT 的文件提交到 Git）：

系统	典型路径
macOS	~/.cursor/mcp.json（即 /Users/你的用户名/.cursor/mcp.json）
Windows	%USERPROFILE%\.cursor\mcp.json

若文件里已有别的 MCP（如 fetch），只增加 mcp-atlassian 一段，不要删掉原有内容。

4.2 JSON 片段（自建 Jira + PAT）

把 你的PAT粘贴在此处 换成 PAT；JIRA_URL 改成真实地址。

"mcp-atlassian": {
  "command": "uvx",
  "args": ["mcp-atlassian"],
  "env": {
    "JIRA_URL": "http://jira.xxx.com",
    "JIRA_PERSONAL_TOKEN": "你的PAT粘贴在此处"
  }
}

完整文件形态（注意最外层是 mcpServers，多个服务用逗号隔开）：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "http://jira.xxx.com",
        "JIRA_PERSONAL_TOKEN": "你的PAT粘贴在此处"
      }
    }
  }
}

不含真实密钥 的完整 mcpServers 示例见上文 4.2 第二个代码块。

4.3 若 HTTPS 证书报错（内网自签）

在 env 里额外加一行（仅在内网、评估安全后再用）：

"JIRA_SSL_VERIFY": "false"

4.4 保存并重启

1. 保存设置或 mcp.json。
2. 完全退出 Cursor 再打开（或设置里重载 MCP）。
3. 在 Settings → MCP 中确认 mcp-atlassian 为绿色。

---

五、第四步：会话里「只输入工单号」（随 Cursor Rules）

5.0 默认行为 vs 你想要的行为

• Cursor 默认：只发一行 AK-99，模型不保证会去调 Jira MCP。
• 你想要的效果：发工单号 → 自动按 Jira 处理 → 拉工单 → 分析 → 给方案/改代码。

要做到后者，需要 Rules（规则） 或 每次手写完整指令（见 5.4～5.6）。规则一律在 Cursor → Settings → Rules 侧配置（User rules 全局生效；Project rules 随当前仓库的 .cursor/rules/）。

5.1 两种方式（二选一）

方式	适合谁	做法
A. User Rules（随 Cursor，不依赖仓库）	个人本机、多仓库通用	Cursor → Settings → Rules → User rules，粘贴 第八节「User Rules 粘贴块」中的 Markdown 正文（与仓库规则逻辑一致，不含 YAML 头）。保存后新开对话验证。
B. Project Rules（随仓库）	团队统一行为	克隆含 .cursor/rules/jira_ticket_auto.mdc 的仓库，在 Cursor 里 打开该仓库根目录；确认 Settings → Rules 中未禁用项目规则。

• User rules 没有 .mdc 里的 description / alwaysApply 元数据，规则全文靠你粘贴维护；更新时改 Settings 里同一段文字即可。
• Project rule 以仓库文件为真源，Git 拉代码即更新。

若两种方式都未配置，则只能依赖 每次写清「用 Jira MCP」（见 5.4）。

5.2 配好规则之后，会话里怎么用

在 mcp-atlassian 为绿 且 已配置 A 或 B 时，可直接发：

AK-99

或：

AK-99：看下这个问题并改代码

Agent 应按规则：先调 Jira MCP 拉工单 → 结合仓库分析 → 给出方案并实现（除非你说不要改代码）。

若你希望只做分析、不改代码，在同一条里说明，例如：AK-99 只分析不要改代码。

5.3 不配规则时：最简说法（复制即用）

把下面整段贴进对话（把 key 换成你的）：

请使用已连接的 mcp-atlassian（Jira）MCP：先查看可用工具名称与参数，
再调用获取工单详情的工具，拉取工单 AK-99 的标题、描述、状态、评论摘要。
拉取成功后：用中文总结问题现象与验收标准，并列出需要我补充的信息（若有）。

说明：不同版本工具名可能是 jira_get_issue 等，让 AI 先看工具列表再调最稳。

5.4 分析根因 + 给出解决「档案」（方案文档）

工单：AK-99。请用 Jira MCP 拉取全文后：
1）归纳根因假设（按可能性排序）；
2）给出可执行的解决方案（含影响范围、风险、回滚）；
3）若涉及本仓库代码，请 @ 相关路径并说明要改哪些模块。

5.5 在仓库里「实现」解决方案（改代码）

工单：AK-99。请先用 Jira MCP 拉取需求与验收点，再结合当前仓库实现：
1）列出改动文件清单；
2）直接按验收点实现或修复；
3）最后给出自测步骤与 PR 说明要点。

若工程在子目录，请写明或 @ 文件夹，例如：@airdroid_parental_control。

5.6 若 AI 说「调不到」或没动静

1. VPN 与浏览器能否打开同一 Jira。
2. Settings → MCP 里 JIRA_PERSONAL_TOKEN 是否填对。
3. 若依赖规则：是否在 User rules 里粘贴了第八节正文，或仓库根下存在 jira_ticket_auto.mdc 且 Rules 未关。
4. 点开 mcp-atlassian 日志，查 401/403/SSL。

---

六、附录：Atlassian 云（不是自建域名时）

若 Jira 地址是 https://xxx.atlassian.net，则不用 JIRA_PERSONAL_TOKEN，改用（示例）：

"env": {
  "JIRA_URL": "https://xxx.atlassian.net",
  "JIRA_USERNAME": "你的邮箱@公司.com",
  "JIRA_API_TOKEN": "在 id.atlassian.com 创建的 API Token"
}

详见 mcp-atlassian 认证说明。

---

七、安全提醒（必读）

• PAT 等同密码：不要发微信群、不要贴 PR、不要提交到 Git。
• 若 PAT 曾泄露到聊天或截图，请在 Jira 里 作废并重新生成。
• 工单描述里若含客户隐私，请先 脱敏 再让 AI 大范围分析。

---

八、附录：User Rules 粘贴块（与 Project rule 的差异）

将下面 从标题 # Jira 工单号 起直到文末 整段复制到 Cursor → Settings → Rules → User rules 中即可（不要复制 YAML --- 那段；User rules 不使用 description / alwaysApply 字段）。

若团队以仓库 .cursor/rules/jira_ticket_auto.mdc 为准，可与该文件 Markdown 正文 保持同步，避免两套文字漂移。

# Jira 工单号一键处理（仅匹配时生效）

## 何时生效

仅当**用户本条消息**在去掉首尾空白后满足其一，才执行下方步骤；**否则忽略本规则全文**（不要调用 Jira MCP）：

1. **整句**符合 Jira Issue Key：`^[A-Z][A-Z0-9]{1,9}-\d+$`（例：`AK-99`）。
2. **以该 Key 开头**，其后为空格、冒号、换行或句末（例：`AK-99：`、`AK-99 看下`）。

## 必须执行的步骤

1. **拉取工单**：使用已连接的 **mcp-atlassian**（Jira）MCP。先查看可用工具与参数，再调用用于**获取单个 Issue 详情**的工具（常见名为 `jira_get_issue`，以实际 schema 为准），传入识别到的 **issue key**。
2. **分析**：用中文归纳工单中的现象、期望、验收点、评论中的关键信息；必要时结合工作区代码 **SemanticSearch / Read / Grep** 定位相关模块。
3. **解决**：给出可落地的修改方案；若用户未明确禁止改代码，则**直接在工作区实现**修复或需求，并给出自测要点与风险说明。
4. **失败时**：若 MCP 报错或无法拉取，**不得编造**工单内容；说明可能原因（VPN、PAT、`JIRA_URL`、权限）并提示查看 MCP 日志。

## 注意

- 不要把 Jira PAT 或任何密钥写入仓库、PR 或对话外的明文文件。
- 工单含敏感信息时，先提醒脱敏再大范围引用。