第 21 期 | PM 神器：Jira / Linear 的 MCP 无缝接入

🎯 学习目标

• 理解并掌握 MCP (Multi-Component Project) 如何作为统一接口，无缝集成 Jira 或 Linear 等项目管理工具。
• 学会利用 Claude TUI 直接从终端创建、更新项目管理工单，并关联代码库状态。
• 掌握基于代码提交、分支差异等信息，自动化生成工单描述、故事点和验收标准的核心策略。
• 了解如何配置 Claude Tools 以与 Jira/Linear API 进行交互，实现开发流程与项目管理的深度融合。

📖 核心概念讲解

21.1 MCP 与项目管理工具的集成哲学

在现代软件开发中，开发人员与项目经理之间的协作效率至关重要。然而，频繁的上下文切换（从 IDE 到 Jira/Linear 界面，再到 Slack 等）常常成为生产力的瓶颈。MCP (Multi-Component Project) 的核心理念是提供一个统一的开发工作流编排层，它不仅仅管理代码库和 CI/CD，更将项目管理（PM）工具纳入其生态。

集成哲学：

1. 减少上下文切换： 开发者无需离开终端或 IDE，即可完成项目管理任务。
2. 数据源单一化： 代码库（Git）成为进度的“真实之源”。工单状态、故事点、验收标准等信息可以从代码变更中推断或生成，减少手动同步的错误和滞后。
3. 自动化与智能化： 利用 AI 和自动化脚本，根据代码库的实际情况（如分支合并、PR 提交、文件改动量），自动建议或更新工单信息。
4. 双向同步： 不仅能将开发进度推送到 PM 工具，也能从 PM 工具获取信息，指导开发决策。

MCP 作为集成桥梁：

graph TD
    A[开发者工作流 (IDE/Terminal)] --> B{Claude MCP}
    B --> C[Git/SCM (代码库)]
    B --> D[CI/CD Pipelines]
    B --> E[Jira/Linear API]
    E --> F[Jira/Linear Web UI]
    C -- "代码变更/进度" --> B
    B -- "创建/更新工单" --> E
    E -- "工单状态/信息" --> F
    F -- "PM决策/需求" --> A

通过 MCP，Claude 能够扮演一个智能助手，理解开发者的意图，并将其转化为 PM 工具可识别的操作。

21.2 Linear API / Jira API 核心能力与自动化策略

要实现与 Jira 或 Linear 的无缝集成，我们必须通过它们的 API 进行交互。虽然两个平台的 API 细节有所不同，但核心能力都是围绕工单（Issue/Ticket）的生命周期管理。

核心 API 能力：

• 创建工单 (Create Issue)：
  • 标题 (Title/Summary)
  • 描述 (Description)
  • 类型 (Type: Feature, Bug, Story)
  • 项目 (Project/Team)
  • 状态 (Status)
  • 经办人 (Assignee)
  • 优先级 (Priority)
  • 故事点 (Story Points)
  • 验收标准 (Acceptance Criteria)
• 更新工单 (Update Issue)： 修改上述任何字段。
• 添加评论 (Add Comment)：
• 查询工单 (Get Issue)： 根据 ID 或其他条件检索工单信息。
• 工作流管理 (Workflow Management)： 状态转换、自定义字段等。

自动化工单生成与更新策略：

Claude 通过 MCP 提供的集成层，可以根据以下策略自动化工单信息：

1. 基于 git diff 生成描述和故事点：

   • 描述： 分析当前分支与主分支的 git diff 输出，提取关键文件变更、新增功能点，结合 commit message 生成初步的工单描述。
   • 故事点： 简单启发式规则可以包括：
     • 代码行数变化 (LOC)
     • 文件修改数量
     • 引入新模块/依赖的复杂度
     • 与现有代码库的耦合度分析
   • 当然，这些都是建议值，仍需人工确认。

2. 基于 PR 描述或代码注释生成验收标准：

   • PR 描述： 许多团队要求 PR 描述包含完成标准。Claude 可以解析 PR 文本，提取出 ## Acceptance Criteria 或类似的段落。
   • 代码注释： 在某些特定文件（如 README.md, CONTRIBUTING.md）或代码注释中，定义了功能需求或测试点，Claude 可以从中提取。

3. 基于分支命名或 commit message 关联工单：

   • 例如，分支名为 feature/JIRA-123-new-feature，Claude 可以自动识别 JIRA-123 并关联。
   • Commit message 中包含 [LINEAR-456] Implement X 也可以作为关联依据。

21.3 MCP 配置与工具链映射

为了让 Claude 能够与 Jira/Linear 交互，我们需要在 MCP 的配置文件中进行相应的配置。这通常涉及到 API 密钥、默认项目 ID、以及与 Claude 命令行的映射关系。

核心配置项：

这些配置允许 Claude 在执行 claude pm 命令时，知道如何认证、向哪个平台发送请求，以及如何解析参数。

💻 模拟 Claude TUI 交互

以下模拟了 Claude 通过 MCP 与 Jira/Linear 进行交互的几种典型场景。

场景一：基于当前代码差异创建新的 Linear Feature 工单

假设你刚刚完成了一个新功能的开发，并希望在 Linear 中为其创建一个 Feature 工单。Claude 可以分析你的本地改动，并尝试预填充工单信息。

> claude pm create issue --type feature --title "Implement User Profile Page" --diff-from main --assignee @me

╭─ Claude ─────────────────────────────────────────────────────────────────────────────────────────╮
│  正在分析当前分支与 'main' 分支的代码差异...                                                     │
│  检测到以下主要文件变更：                                                                        │
│  - src/pages/UserProfile.tsx (新增)                                                              │
│  - src/components/Avatar.tsx (修改)                                                              │
│  - api/users.ts (修改)                                                                           │
│                                                                                                  │
│  建议的工单描述：                                                                                │
│  ```                                                                                             │
│  此功能将为用户提供一个个人资料页面，允许他们查看和编辑自己的基本信息。                          │
│  主要包含以下模块：                                                                              │
│  - **用户界面：** 基于 `UserProfile.tsx` 实现，展示用户头像、姓名、邮箱等。                     │
│  - **组件更新：** `Avatar.tsx` 组件更新以支持新的头像尺寸和加载逻辑。                           │
│  - **API集成：** `api/users.ts` 增加获取和更新用户资料的端点。                                   │
│  ```                                                                                             │
│                                                                                                  │
│  建议的故事点 (基于代码复杂度初步评估): 5 SP                                                     │
│                                                                                                  │
│  是否确认创建此 Linear Feature 工单？ (y/N) y                                                    │
│  正在创建 Linear 工单...                                                                         │
│  Linear 工单已成功创建！                                                                         │
│  ID: LINEAR-1234                                                                                 │
│  URL: https://linear.app/your-team/issue/LINEAR-1234/implement-user-profile-page                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

场景二：更新 Jira 工单状态并添加评论

你已经完成了某个 Jira Bug 的修复，并希望将其状态更新为“待测试”并添加一条评论。

> claude pm update issue JIRA-456 --status "Ready For Test" --comment "Bug fixed, tested locally. Ready for QA review."

╭─ Claude ─────────────────────────────────────────────────────────────────────────────────────────╮
│  正在连接 Jira API...                                                                            │
│  正在获取工单 JIRA-456 的当前信息...                                                             │
│  工单 JIRA-456 (Title: UI Glitch on Login Page) 当前状态为 "In Progress"。                     │
│  确认将工单状态从 "In Progress" 更新为 "Ready For Test" 并添加评论吗？ (y/N) y                   │
│  Jira 工单 JIRA-456 已成功更新。                                                                 │
│  URL: https://your-company.atlassian.net/browse/JIRA-456                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

场景三：基于 GitHub Pull Request 自动生成 Linear 验收标准

你提交了一个 Pull Request，并在其描述中包含了详细的验收标准。希望 Claude 能将其提取并同步到关联的 Linear 工单中。

> claude pm generate acceptance-criteria --pr-url "https://github.com/my-org/my-repo/pull/789" --issue-id LINEAR-567

╭─ Claude ─────────────────────────────────────────────────────────────────────────────────────────╮
│  正在从 GitHub PR #789 获取描述...                                                               │
│  检测到 PR 描述中包含以下验收标准段落：                                                         │
│                                                                                                  │
│  **验收标准 (Acceptance Criteria):**                                                             │
│  - 用户能够通过 `/profile` 路径访问个人资料页面。                                                │
│  - 页面显示用户姓名、邮箱和头像。                                                                │
│  - 用户可以点击头像上传新图片，并实时预览。                                                      │
│  - 保存按钮在信息有修改时启用，点击后成功更新用户信息。                                          │
│  - 错误提示在保存失败时正确显示。                                                                │
│                                                                                                  │
│  是否将这些标准添加到 Linear 工单 LINEAR-567 的验收标准字段？ (y/N) y                            │
│  正在更新 Linear 工单 LINEAR-567...                                                              │
│  Linear 工单 LINEAR-567 的验收标准已成功更新。                                                   │
│  URL: https://linear.app/your-team/issue/LINEAR-567/add-user-profile-editing                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

💻 代码演示

这里我们将展示一些核心的配置片段和 Claude 内部可能使用的工具脚本，以实现上述功能。

1. Claude MCP 配置文件 (~/.config/claude/mcp_config.yaml)

# ~/.config/claude/mcp_config.yaml
# MCP (Multi-Component Project) Configuration for Claude Tools

pm_tools:
  default: linear # 或者 'jira'

  linear:
    api_key: env:LINEAR_API_KEY # 从环境变量读取 API Key，推荐方式
    default_team_id: "your-linear-team-id-uuid" # 替换为你的 Linear Team ID
    
    # 将 Claude 内部的工单类型映射到 Linear 的 Issue Type ID
    # 需要在 Linear API Explorer (https://developers.linear.app/explorer) 中查找你的 Issue Type ID
    issue_type_map:
      feature: "your-feature-issue-type-id" # 例如: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
      bug: "your-bug-issue-type-id"
      task: "your-task-issue-type-id"
      story: "your-story-issue-type-id"

  jira:
    base_url: "https://your-company.atlassian.net" # 你的 Jira Cloud 实例 URL
    username: env:JIRA_USERNAME # Jira 注册邮箱
    api_token: env:JIRA_API_TOKEN # 从环境变量读取 Jira API Token
    default_project: "PROJ" # 默认的 Jira Project Key

    # 将 Claude 内部的工单类型映射到 Jira 的 Issue Type Name
    issue_type_map:
      feature: "Story"
      bug: "Bug"
      task: "Task"
      story: "Story"

# Claude 内部工具链配置，用于处理 PM 相关逻辑
tools:
  pm_diff_analyzer:
    command: "python {{claude_home}}/scripts/pm/diff_analyzer.py"
    description: "分析 Git 差异，生成工单描述和故事点建议"
    args: ["--base-branch", "{{base_branch}}", "--target-branch", "{{target_branch}}"]

  pm_pr_parser:
    command: "python {{claude_home}}/scripts/pm/pr_parser.py"
    description: "解析 Pull Request 描述，提取验收标准"
    args: ["--pr-url", "{{pr_url}}"]

环境变量设置示例 (Bash):

export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxxxxxxx"
export JIRA_USERNAME="[email protected]"
export JIRA_API_TOKEN="ATATT3xFfxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. diff_analyzer.py (简化版 Python 脚本示例)

这个脚本模拟了 Claude 如何分析 git diff 来生成工单描述和故事点。

# {{claude_home}}/scripts/pm/diff_analyzer.py
import argparse
import subprocess
import json
import re

def run_command(cmd):
    """Helper to run shell commands."""
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return result.stdout.strip()

def analyze_diff(base_branch, target_branch):
    """Analyzes git diff to generate issue description and story points."""
    try:
        diff_output = run_command(["git", "diff", "--numstat", base_branch, target_branch])
        # Example diff_output:
        # 10	2	src/pages/UserProfile.tsx
        # 5	0	src/components/Avatar.tsx
        # 3	1	api/users.ts

        files_changed = []
        lines_added = 0
        lines_deleted = 0
        
        for line in diff_output.split('\n'):
            if not line:
                continue
            parts = line.split('\t')
            if len(parts) == 3:
                added, deleted, filename = parts
                lines_added += int(added)
                lines_deleted += int(deleted)
                files_changed.append(filename)

        # Heuristic for story points:
        # 1 SP per ~20 lines changed (added + deleted)
        # +1 SP per 5 files changed
        # Min 1, Max 13
        story_points = max(1, min(13, round((lines_added + lines_deleted) / 20) + round(len(files_changed) / 5)))

        # Generate a simple description based on files changed
        description = f"此工单涉及以下文件变更：\n"
        for f in files_changed:
            description += f"- {f}\n"
        description += f"\n总共新增 {lines_added} 行，删除 {lines_deleted} 行。"
        description += "\n\n请根据实际工作量调整故事点和完善描述。"

        return {
            "description": description,
            "story_points": story_points,
            "files_changed": files_changed,
            "lines_added": lines_added,
            "lines_deleted": lines_deleted
        }
    except subprocess.CalledProcessError as e:
        print(f"Error running git diff: {e.stderr}")
        return {"description": "无法生成描述，请检查 Git 仓库状态。", "story_points": 0}

def main():
    parser = argparse.ArgumentParser(description="Analyze Git diff for PM tools.")
    parser.add_argument("--base-branch", default="main", help="Base branch for diff comparison.")
    parser.add_argument("--target-branch", default="HEAD", help="Target branch for diff comparison.")
    args = parser.parse_args()

    analysis_result = analyze_diff(args.base_branch, args.target_branch)
    print(json.dumps(analysis_result, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

3. Linear API 调用示例 (cURL)

这是一个 Claude 内部可能用于创建 Linear Issue 的 cURL 命令示例。

# Claude 内部工具会根据用户输入和 diff_analyzer.py 的输出构建此请求
curl -X POST 'https://api.linear.app/graphql' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -d '{
    "query": "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id url identifier } } }",
    "variables": {
      "input": {
        "teamId": "your-linear-team-id-uuid",
        "title": "Implement User Profile Page",
        "description": "此工单涉及以下文件变更:\n- src/pages/UserProfile.tsx\n- src/components/Avatar.tsx\n- api/users.ts\n\n总共新增 18 行，删除 3 行。\n\n请根据实际工作量调整故事点和完善描述。",
        "assigneeId": "your-linear-user-id-uuid", # 需要提前获取用户ID
        "issueTypeIds": ["your-feature-issue-type-id"],
        "storyPoints": 5
      }
    }
  }'

🔧 涉及的 Tools / Commands

📝 本期要点回顾

1. MCP 是核心枢纽： Claude 的 MCP 架构为开发与项目管理工具的无缝集成提供了统一的接口和编排能力。
2. 减少上下文切换： 通过终端直接操作 Jira/Linear，显著提升开发人员的工作效率，避免频繁切换应用。
3. 代码即真相： 充分利用 Git 代码仓库的变更信息（git diff、PR 描述）作为工单信息（描述、故事点、验收标准）的自动化生成依据。
4. API 驱动集成： Jira 和 Linear 提供的强大 API 是实现自动化和深度集成的基础，所有操作都通过这些 API 完成。
5. 可配置与可扩展： mcp_config.yaml 提供了灵活的配置选项，而外部脚本（如 Python）则允许我们根据团队需求定制更复杂的自动化逻辑。
6. 智能辅助决策： Claude 可以根据代码变更量等启发式规则，为故事点和验收标准提供智能建议，但最终仍需人工确认。

🔗 参考资料

1. Linear API Documentation: 深入了解 Linear 的 GraphQL API，包括认证、查询和变更操作。
   • https://developers.linear.app/docs/
2. Jira Cloud REST API Documentation: 学习 Jira Cloud 的 REST API，涵盖工单、项目、用户等资源。
   • https://developer.atlassian.com/cloud/jira/platform/rest/v3/
3. Git diff 命令详解: 掌握 git diff 的各种用法，特别是 numstat 参数，对于代码变更分析至关重要。
   • https://git-scm.com/docs/git-diff