@jira-deploy/mcp

GitHub Copilot MCP Server，讓 Copilot 能用自然語言操作 Jira 上版流程。

功能

• 開上版單並自動填欄位（依平台設定）
• 切換 Jira 狀態（不需要知道 transition ID）
• 輪詢等待主管 Approve
• 部署完成後留言記錄
• 查詢 Jira issue / JQL
• 查詢 Bitbucket PR、diff、comments，並可回寫 PR comment
• 查詢 Confluence page、space、version、Team Calendar
• Slack 通知擴充點（填 env 即啟用）

安裝

使用已發布版本

若套件已發布到 registry，使用者端可直接安裝：

npm install -g @jira-deploy/mcp

或直接用 npx：

npx -y @jira-deploy/mcp

如果要使用 JSON config，可透過 --config 明確傳入：

npx -y @jira-deploy/mcp --config ~/.ares/config.json

MCP app 維持走 npm / npx 發布與安裝，不提供 standalone binary 安裝。

本地開發 / 從 monorepo 啟動

cd jira-deploy-mcp
pnpm install
cd apps/jira-deploy-mcp
cp .env.example .env
# 編輯 .env 填入你的 Jira 設定

設定 VSCode MCP

把 .vscode-mcp.json 的內容合併到你專案的 .vscode/mcp.json， 並把 args 裡的路徑改成實際位置。

若你是使用已發布版本，可改成類似下面的設定：

{
  "servers": {
    "jira-deploy": {
      "command": "npx",
      "args": ["-y", "@jira-deploy/mcp", "--config", "/path/to/config.json"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

建議把 Jira、Bitbucket、Confluence、Jabber 的機密設定放在 JSON config、系統環境變數或 .env 檔，不要 commit 到 git（.env 已在 .gitignore）。--config 的值會優先於 shell env；未使用 --config 時，MCP 仍可讀取既有 env。

使用者端使用方式

安裝好並接入 MCP client 後，可以直接在 Chat 裡說：

幫我開一張 APP STG 上版單
把 PROJ-123 切到 Pending Approval
等 PROJ-123 被 approve
把 PROJ-123 切到 Approved
查 PROJ-123 的狀態跟留言
查 demo-web 這個 PR 的 diff
查 Confluence Release Manager 值班表

MCP app 適合：

• VS Code Copilot Chat
• 支援 MCP 的桌面 client
• 想把 Jira 動作當成工具提供給 agent 使用的情境

Utility Tools

除了上版流程工具，MCP app 也整合了協作者新增的查詢型工具。這些工具現在都在 apps/jira-deploy-mcp/src/utility-tools.js，不再需要根目錄額外的 mcp/ folder 或獨立 server。

Jira:

• jira_get_issue
• jira_search_issues

Bitbucket:

• bitbucket_list_prs
• bitbucket_get_pr
• bitbucket_get_pr_changes
• bitbucket_get_pr_diff
• bitbucket_get_pr_comments
• bitbucket_add_pr_comment
• bitbucket_add_pr_inline_comment
• bitbucket_get_file

Confluence:

• confluence_search
• confluence_get_page
• confluence_get_children
• confluence_list_spaces
• confluence_get_page_storage
• confluence_create_page
• confluence_update_page
• confluence_list_versions
• confluence_get_page_version
• confluence_get_calendar_events

使用方式（在 Copilot Chat 說）

完整流程（一句話觸發）：

幫我開 A平台 STG 上版單，版號 v1.2.3，PR 連結 https://github.com/...

分步控制：

# 1. 開單
開一張 A平台 STG 上版單，版號 v1.2.3

# 2. 切狀態等待審核
把 PROJ-123 切到 Pending Approval

# 3. 等待 Approve（Copilot 會輪詢）
等 PROJ-123 被 approve

# 4. Approve 後切狀態（觸發 Jira Automation → Jenkins）
把 PROJ-123 切到 Approved

# 5. 等部署完成後收尾
在 PROJ-123 加留言「STG 部署完成，build: https://jenkins/...」
把 PROJ-123 切到 Done

平台設定

編輯 packages/jira-core/platform-config.js 新增平台：

export const PLATFORMS = {
  'a平台': {
    projectKey: 'PROJ',
    issueType: 'Task',
    components: ['A Platform'],
    labels: ['deploy', 'stg'],
    customFields: {
      // customfield_10100: { value: 'STG' },
    },
  },
  // 新增更多平台...
};

Jenkins 串接

在 Jira Automation 設定規則：

Trigger:   Issue transitioned → to status "Approved"
Condition: Label includes "stg" AND Component = "A Platform"
Action:    Send web request
  URL:     https://jenkins.your-org.com/job/a-platform-stg/buildWithParameters
  Method:  POST
  Headers: Authorization: Basic <base64(user:token)>
  Body:    {"ENV": "STG", "ISSUE_KEY": "{{issue.key}}"}

這樣 Agent 切狀態到 Approved，Jenkins build 就自動觸發，不需要 Agent 直接呼叫 Jenkins API。

Slack 通知擴充

在 .env 加入：

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_ID=C0XXXXXXX

再到 src/notifier.js 把 notifySlack 的 TODO 取消註解即可， 其他程式碼不需要改動。

取得 Jira API Token

1. 前往 https://id.atlassian.com/manage-profile/security/api-tokens
2. 建立 token，複製到 .env 的 JIRA_API_TOKEN

查詢 Custom Field ID

curl -u email:token \
  "https://your-org.atlassian.net/rest/api/2/field" | jq '.[] | select(.custom) | {id, name}'

發布與維護

發布策略與後續維護流程請看：

• docs/publishing.md
• docs/maintenance.md

Agent Workflow POC (PM → Planner → Coder → Tester)

已新增 4 個自訂 agents：

• .github/agents/pm.agent.md
• .github/agents/planner.agent.md
• .github/agents/coder.agent.md
• .github/agents/tester.agent.md

流程設計

1. PM 收需求、定義 scope 與 acceptance criteria。
2. Planner 產出可執行任務與檔案層級修改清單。
3. Coder 先讀 codebase 與文件（README、copilot-instructions、package.json）再實作。
4. Tester 依 acceptance criteria 驗證並給出 release verdict。

VS Code Copilot Chat 使用

• 用 /agent 選擇 PM 開始。
• 每個 agent 回覆後可透過 handoff 按鈕切到下一個 agent。

Copilot CLI 使用

CLI 可使用同一批 agent 定義，但沒有 VS Code handoff 按鈕。 改用 /agent 手動切換：

/agent PM
/agent Planner
/agent Coder
/agent Tester