@jira-deploy/mcp 1.0.0

package/.env.example

@@ -0,0 +1,38 @@
+# Example environment variables for jira-deploy-mcp
+# Copy to .env and fill values for your environment
+
+
+# General
+DRY_RUN=true
+
+# Jira 設定
+JIRA_BASE_URL=https://your-org.atlassian.net
+JIRA_USER_EMAIL=your-email@company.com
+JIRA_API_TOKEN=your_jira_api_token
+
+# 預設專案 key（可在開單時 override）
+JIRA_PROJECT_KEY=OPS
+
+# 輪詢設定
+POLL_INTERVAL_MS=30000
+POLL_TIMEOUT_MS=3600000
+
+# Bitbucket 設定
+BITBUCKET_URL=https://bitbucket.example.com
+BITBUCKET_API_TOKEN=your_bitbucket_api_token
+
+# Confluence
+CONF_BASE_URL=https://confluence.example.com
+CONF_TOKEN=your-confluence-token
+
+# Jabber (XMPP)
+# Prefer storing the password in macOS Keychain and leave JABBER_PASSWORD empty.
+# Set JABBER_PASSWORD only for CI or quick overrides.
+JABBER_SERVER=10.244.192.137
+JABBER_USER=your_jabber_account_number # e.g., BK00619
+JABBER_DOMAIN=linebank.com.tw
+JABBER_PASSWORD=
+JABBER_KEYCHAIN_SERVICE=jabber-copilot
+JABBER_KEYCHAIN_ACCOUNT=your_jabber_account_number # e.g., BK00619
+JABBER_TO=
+JABBER_NOTIFY_SCRIPT=src/scripts/jabber_notify.py

package/README.md

@@ -0,0 +1,245 @@
+# @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，使用者端可直接安裝：
+
+```bash
+npm install -g @jira-deploy/mcp
+```
+
+或直接用 `npx`：
+
+```bash
+npx -y @jira-deploy/mcp
+```
+
+MCP app 維持走 npm / npx 發布與安裝，不提供 binary / Homebrew 安裝。
+
+### 本地開發 / 從 monorepo 啟動
+
+```bash
+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` 裡的路徑改成實際位置。
+
+若你是使用已發布版本，可改成類似下面的設定：
+
+```json
+{
+  "servers": {
+    "jira-deploy": {
+      "command": "npx",
+      "args": ["-y", "@jira-deploy/mcp"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-org.atlassian.net",
+        "JIRA_API_TOKEN": "your_jira_api_token",
+        "BITBUCKET_URL": "https://bitbucket.example.com",
+        "BITBUCKET_API_TOKEN": "your_bitbucket_api_token",
+        "CONF_BASE_URL": "https://confluence.example.com",
+        "CONF_TOKEN": "your_confluence_token"
+      }
+    }
+  }
+}
+```
+
+建議把 Jira 的機密設定放在系統環境變數或 `.env` 檔，
+不要 commit 到 git（`.env` 已在 .gitignore）。
+
+## 使用者端使用方式
+
+安裝好並接入 MCP client 後，可以直接在 Chat 裡說：
+
+```text
+幫我開一張 IBK STG 上版單
+把 CID-1718 切到 Pending Approval
+等 CID-1718 被 approve
+把 CID-1718 切到 Approved
+查 CID-1718 的狀態跟留言
+查 tw-bank-webapp 這個 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. 切狀態等待審核
+把 OPS-123 切到 Pending Approval
+
+# 3. 等待 Approve（Copilot 會輪詢）
+等 OPS-123 被 approve
+
+# 4. Approve 後切狀態（觸發 Jira Automation → Jenkins）
+把 OPS-123 切到 Approved
+
+# 5. 等部署完成後收尾
+在 OPS-123 加留言「STG 部署完成，build: https://jenkins/...」
+把 OPS-123 切到 Done
+```
+
+## 平台設定
+
+編輯 `packages/jira-core/platform-config.js` 新增平台：
+
+```js
+export const PLATFORMS = {
+  'a平台': {
+    projectKey: 'OPS',
+    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
+
+```bash
+curl -u email:token \
+  "https://your-org.atlassian.net/rest/api/2/field" | jq '.[] | select(.custom) | {id, name}'
+```
+
+## 發布與維護
+
+發布策略與後續維護流程請看：
+
+- [docs/publishing.md](../../docs/publishing.md)
+- [docs/maintenance.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` 手動切換：
+
+```text
+/agent PM
+/agent Planner
+/agent Coder
+/agent Tester
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jira-deploy/mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for Jira deploy ticket workflow",
+  "type": "module",
+  "main": "./src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ap311036/jira-deploy-mcp.git",
+    "directory": "apps/jira-deploy-mcp"
+  },
+  "bin": {
+    "jira-deploy-mcp": "./src/index.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.3.0",
+    "@jira-deploy/core": "1.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import {config} from 'dotenv';
+import {fileURLToPath} from 'url';
+import {dirname, join} from 'path';
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {JiraClient, Notifier, getToolDefinitions, executeTool} from '@jira-deploy/core';
+import {getUtilityToolDefinitions, executeUtilityTool} from './utility-tools.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+config({path: join(__dirname, '..', '.env')});
+
+const jira = new JiraClient();
+const notifier = new Notifier(jira);
+
+const server = new Server(
+  {name: '@jira-deploy/mcp', version: '1.0.0'},
+  {capabilities: {tools: {}}}
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [...getToolDefinitions(), ...getUtilityToolDefinitions()],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const {name, arguments: args} = request.params;
+
+  try {
+    const utilityResult = await executeUtilityTool(name, args ?? {});
+    if (utilityResult) return utilityResult;
+    return await executeTool(name, args ?? {}, {jira, notifier});
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({error: err.message}),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[@jira-deploy/mcp] MCP Server ready');

package/src/utility-tools.js

@@ -0,0 +1,910 @@
+import http from 'http';
+import https from 'https';
+
+const DRY_RUN = process.env.DRY_RUN === 'true';
+
+function ok(data) {
+  return {content: [{type: 'text', text: JSON.stringify(data, null, 2)}]};
+}
+
+function text(data) {
+  return {content: [{type: 'text', text: data}]};
+}
+
+function requiredEnv(names, label) {
+  const values = Object.fromEntries(names.map((name) => [name, process.env[name]]));
+  const missing = names.filter((name) => !values[name]);
+  if (missing.length > 0 && !DRY_RUN) {
+    throw new Error(`${label} requires env vars: ${missing.join(', ')}`);
+  }
+  return values;
+}
+
+function parseJsonBody(data) {
+  if (!data.trim()) return {};
+  return JSON.parse(data);
+}
+
+function requestJson(baseUrl, path, {token, method = 'GET', body, timeoutMs = 15000} = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, baseUrl);
+    const lib = url.protocol === 'https:' ? https : http;
+    const payload = body ? JSON.stringify(body) : null;
+    const req = lib.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        method,
+        rejectUnauthorized: false,
+        headers: {
+          Accept: 'application/json',
+          ...(token ? {Authorization: `Bearer ${token}`} : {}),
+          ...(payload
+            ? {'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload)}
+            : {}),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              resolve(parseJsonBody(data));
+            } catch (err) {
+              reject(new Error(`JSON parse error: ${err.message}`));
+            }
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 300)}`));
+          }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function requestText(baseUrl, path, {token, timeoutMs = 15000} = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, baseUrl);
+    const lib = url.protocol === 'https:' ? https : http;
+    const req = lib.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'GET',
+        rejectUnauthorized: false,
+        headers: {
+          Accept: 'text/plain',
+          ...(token ? {Authorization: `Bearer ${token}`} : {}),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(data);
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 300)}`));
+          }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    req.end();
+  });
+}
+
+function jiraConfig() {
+  const baseUrl = process.env.JIRA_BASE_URL;
+  const token = process.env.JIRA_API_TOKEN ?? process.env.JIRA_TOKEN;
+  if (!DRY_RUN && (!baseUrl || !token)) {
+    throw new Error('Jira utility tools require JIRA_BASE_URL and JIRA_API_TOKEN');
+  }
+  return {baseUrl, token};
+}
+
+function bitbucketConfig() {
+  const baseUrl = process.env.BITBUCKET_URL ?? process.env.BITBUCKET_BASE_URL;
+  const token = process.env.BITBUCKET_API_TOKEN ?? process.env.BITBUCKET_TOKEN;
+  if (!DRY_RUN && (!baseUrl || !token)) {
+    throw new Error('Bitbucket utility tools require BITBUCKET_URL and BITBUCKET_API_TOKEN');
+  }
+  return {baseUrl, token};
+}
+
+function confluenceConfig() {
+  requiredEnv(['CONF_BASE_URL', 'CONF_TOKEN'], 'Confluence utility tools');
+  return {baseUrl: process.env.CONF_BASE_URL, token: process.env.CONF_TOKEN};
+}
+
+function stripHtml(html) {
+  return (html || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+export function getUtilityToolDefinitions() {
+  return [
+    {
+      name: 'jira_get_issue',
+      description:
+        'Get a Jira issue by key. Returns summary, status, type, priority, assignee, description, comments, linked issues, and attachments.',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {issueKey: {type: 'string', description: 'Jira issue key, e.g. LBPRJ-10949'}},
+      },
+    },
+    {
+      name: 'jira_search_issues',
+      description: 'Search Jira issues using JQL. Returns key, summary, status, type, priority, and assignee.',
+      inputSchema: {
+        type: 'object',
+        required: ['jql'],
+        properties: {
+          jql: {type: 'string', description: 'JQL query string'},
+          maxResults: {type: 'number', default: 20, description: 'Max results to return'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_list_prs',
+      description: 'List pull requests for a Bitbucket repository.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          state: {type: 'string', enum: ['OPEN', 'MERGED', 'DECLINED', 'ALL'], default: 'OPEN'},
+          limit: {type: 'number', default: 25},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_get_pr',
+      description: 'Get Bitbucket pull request details and recent activity.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_get_pr_changes',
+      description: 'Get the list of changed files in a Bitbucket pull request.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_get_pr_diff',
+      description: 'Get Bitbucket pull request diff content for code review.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+          path: {type: 'string', description: 'Optional file path filter'},
+          contextLines: {type: 'number', default: 3},
+          excludePatterns: {
+            type: 'array',
+            items: {type: 'string'},
+            default: ['__snapshots__', 'messages_en.json', 'messages_ko.json'],
+          },
+        },
+      },
+    },
+    {
+      name: 'bitbucket_get_pr_comments',
+      description: 'Get all comments on a Bitbucket pull request, including inline anchors.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_add_pr_comment',
+      description: 'Add a general comment to a Bitbucket pull request.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId', 'text'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+          text: {type: 'string'},
+          parentId: {type: 'number'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_add_pr_inline_comment',
+      description: 'Add an inline Bitbucket pull request comment on a specific file and line.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'prId', 'text', 'filePath', 'line'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          prId: {type: 'number'},
+          text: {type: 'string'},
+          filePath: {type: 'string'},
+          line: {type: 'number'},
+          lineType: {type: 'string', enum: ['ADDED', 'REMOVED', 'CONTEXT'], default: 'ADDED'},
+          fileType: {type: 'string', enum: ['FROM', 'TO'], default: 'TO'},
+        },
+      },
+    },
+    {
+      name: 'bitbucket_get_file',
+      description: 'Get raw file content from a Bitbucket repository.',
+      inputSchema: {
+        type: 'object',
+        required: ['projectKey', 'repoSlug', 'filePath'],
+        properties: {
+          projectKey: {type: 'string'},
+          repoSlug: {type: 'string'},
+          filePath: {type: 'string'},
+          branch: {type: 'string', default: 'master'},
+        },
+      },
+    },
+    {
+      name: 'confluence_search',
+      description: 'Search Confluence pages using CQL.',
+      inputSchema: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: {type: 'string', description: 'CQL query'},
+          limit: {type: 'number', default: 10},
+        },
+      },
+    },
+    {
+      name: 'confluence_get_page',
+      description: 'Get full readable content of a Confluence page by ID.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId'],
+        properties: {pageId: {type: 'string'}},
+      },
+    },
+    {
+      name: 'confluence_get_children',
+      description: 'Get child pages of a Confluence page.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId'],
+        properties: {pageId: {type: 'string'}, limit: {type: 'number', default: 25}},
+      },
+    },
+    {
+      name: 'confluence_list_spaces',
+      description: 'List available Confluence spaces.',
+      inputSchema: {
+        type: 'object',
+        required: [],
+        properties: {limit: {type: 'number', default: 20}},
+      },
+    },
+    {
+      name: 'confluence_get_page_storage',
+      description: 'Get raw Confluence storage-format HTML for a page.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId'],
+        properties: {pageId: {type: 'string'}},
+      },
+    },
+    {
+      name: 'confluence_create_page',
+      description: 'Create a new Confluence page under a parent page. Body must be storage-format HTML.',
+      inputSchema: {
+        type: 'object',
+        required: ['spaceKey', 'parentId', 'title', 'body'],
+        properties: {
+          spaceKey: {type: 'string'},
+          parentId: {type: 'string'},
+          title: {type: 'string'},
+          body: {type: 'string'},
+        },
+      },
+    },
+    {
+      name: 'confluence_update_page',
+      description: 'Update an existing Confluence page title/body and increment the version.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId', 'body'],
+        properties: {
+          pageId: {type: 'string'},
+          title: {type: 'string'},
+          body: {type: 'string'},
+          minorEdit: {type: 'boolean', default: false},
+        },
+      },
+    },
+    {
+      name: 'confluence_list_versions',
+      description: 'List historical versions of a Confluence page.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId'],
+        properties: {
+          pageId: {type: 'string'},
+          limit: {type: 'number', default: 25},
+          start: {type: 'number', default: 0},
+        },
+      },
+    },
+    {
+      name: 'confluence_get_page_version',
+      description: 'Get readable body and metadata of a historical Confluence page version.',
+      inputSchema: {
+        type: 'object',
+        required: ['pageId', 'version'],
+        properties: {pageId: {type: 'string'}, version: {type: 'number'}},
+      },
+    },
+    {
+      name: 'confluence_get_calendar_events',
+      description:
+        'Query Confluence Team Calendar events. Useful for finding Release Manager / Sign off staff.',
+      inputSchema: {
+        type: 'object',
+        required: ['subCalendarId', 'date'],
+        properties: {
+          subCalendarId: {type: 'string'},
+          date: {type: 'string', description: 'YYYY-MM-DD'},
+        },
+      },
+    },
+  ];
+}
+
+export async function executeUtilityTool(name, args = {}) {
+  switch (name) {
+    case 'jira_get_issue':
+      return jiraGetIssue(args);
+    case 'jira_search_issues':
+      return jiraSearchIssues(args);
+    case 'bitbucket_list_prs':
+      return bitbucketListPrs(args);
+    case 'bitbucket_get_pr':
+      return bitbucketGetPr(args);
+    case 'bitbucket_get_pr_changes':
+      return bitbucketGetPrChanges(args);
+    case 'bitbucket_get_pr_diff':
+      return bitbucketGetPrDiff(args);
+    case 'bitbucket_get_pr_comments':
+      return bitbucketGetPrComments(args);
+    case 'bitbucket_add_pr_comment':
+      return bitbucketAddPrComment(args);
+    case 'bitbucket_add_pr_inline_comment':
+      return bitbucketAddPrInlineComment(args);
+    case 'bitbucket_get_file':
+      return bitbucketGetFile(args);
+    case 'confluence_search':
+      return confluenceSearch(args);
+    case 'confluence_get_page':
+      return confluenceGetPage(args);
+    case 'confluence_get_children':
+      return confluenceGetChildren(args);
+    case 'confluence_list_spaces':
+      return confluenceListSpaces(args);
+    case 'confluence_get_page_storage':
+      return confluenceGetPageStorage(args);
+    case 'confluence_create_page':
+      return confluenceCreatePage(args);
+    case 'confluence_update_page':
+      return confluenceUpdatePage(args);
+    case 'confluence_list_versions':
+      return confluenceListVersions(args);
+    case 'confluence_get_page_version':
+      return confluenceGetPageVersion(args);
+    case 'confluence_get_calendar_events':
+      return confluenceGetCalendarEvents(args);
+    default:
+      return null;
+  }
+}
+
+async function jiraGetIssue({issueKey}) {
+  if (DRY_RUN) {
+    return ok({key: issueKey, fields: {summary: '[DRY] Mock issue', status: {name: 'To Do'}}});
+  }
+  const {baseUrl, token} = jiraConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/2/issue/${issueKey}?expand=renderedFields`,
+    {token},
+  );
+  const f = data.fields || {};
+  return ok({
+    key: data.key,
+    summary: f.summary || '',
+    type: f.issuetype?.name || '',
+    status: f.status?.name || '',
+    priority: f.priority?.name || '',
+    assignee: f.assignee?.displayName || '',
+    reporter: f.reporter?.displayName || '',
+    created: (f.created || '').slice(0, 10),
+    updated: (f.updated || '').slice(0, 10),
+    labels: f.labels || [],
+    description: f.description || '',
+    comments: (f.comment?.comments || []).map((c) => ({
+      author: c.author?.displayName || '',
+      created: (c.created || '').slice(0, 10),
+      body: c.body || '',
+    })),
+    linkedIssues: (f.issuelinks || []).map((l) => {
+      const issue = l.inwardIssue || l.outwardIssue || {};
+      const rel = l.inwardIssue ? l.type?.inward : l.type?.outward;
+      return `${rel} -> ${issue.key} [${issue.fields?.status?.name || ''}] ${issue.fields?.summary || ''}`;
+    }),
+    attachments: (f.attachment || []).map((a) => a.filename),
+  });
+}
+
+async function jiraSearchIssues({jql, maxResults = 20}) {
+  if (DRY_RUN) return ok({total: 0, issues: []});
+  const {baseUrl, token} = jiraConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/2/search?jql=${encodeURIComponent(jql)}&maxResults=${maxResults}&fields=summary,status,assignee,issuetype,priority`,
+    {token},
+  );
+  const issues = (data.issues || []).map((i) => ({
+    key: i.key,
+    summary: i.fields?.summary || '',
+    type: i.fields?.issuetype?.name || '',
+    status: i.fields?.status?.name || '',
+    priority: i.fields?.priority?.name || '',
+    assignee: i.fields?.assignee?.displayName || '',
+  }));
+  return ok({total: data.total, issues});
+}
+
+async function bitbucketListPrs({projectKey, repoSlug, state = 'OPEN', limit = 25}) {
+  if (DRY_RUN) return ok({total: 0, prs: []});
+  const {baseUrl, token} = bitbucketConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests?state=${state}&limit=${limit}`,
+    {token},
+  );
+  const prs = (data.values || []).map((pr) => ({
+    id: pr.id,
+    title: pr.title,
+    state: pr.state,
+    author: pr.author?.user?.displayName || '',
+    sourceBranch: pr.fromRef?.displayId || '',
+    targetBranch: pr.toRef?.displayId || '',
+    updated: pr.updatedDate ? new Date(pr.updatedDate).toISOString().slice(0, 10) : '',
+  }));
+  return ok({total: data.size, prs});
+}
+
+async function bitbucketGetPr({projectKey, repoSlug, prId}) {
+  if (DRY_RUN) return ok({id: prId, title: '[DRY] Mock PR', state: 'OPEN'});
+  const {baseUrl, token} = bitbucketConfig();
+  const [pr, activities] = await Promise.all([
+    requestJson(baseUrl, `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}`, {token}),
+    requestJson(
+      baseUrl,
+      `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/activities?limit=20`,
+      {token},
+    ),
+  ]);
+  return ok({
+    id: pr.id,
+    title: pr.title,
+    state: pr.state,
+    author: pr.author?.user?.displayName || '',
+    sourceBranch: pr.fromRef?.displayId || '',
+    targetBranch: pr.toRef?.displayId || '',
+    created: pr.createdDate ? new Date(pr.createdDate).toISOString().slice(0, 10) : '',
+    updated: pr.updatedDate ? new Date(pr.updatedDate).toISOString().slice(0, 10) : '',
+    description: pr.description || '',
+    reviewers: (pr.reviewers || []).map((r) => ({
+      name: r.user?.displayName || '',
+      status: r.status || '',
+    })),
+    recentActivity: (activities.values || []).slice(0, 10).map((a) => ({
+      action: a.action,
+      user: a.user?.displayName || '',
+      comment: a.comment?.text?.slice(0, 200) || '',
+    })),
+  });
+}
+
+async function bitbucketGetPrChanges({projectKey, repoSlug, prId}) {
+  if (DRY_RUN) return ok({total: 0, files: []});
+  const {baseUrl, token} = bitbucketConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/changes?limit=100`,
+    {token},
+  );
+  const files = (data.values || []).map((c) => ({
+    path: c.path?.toString || '',
+    srcPath: c.srcPath?.toString || '',
+    type: c.type,
+  }));
+  return ok({total: files.length, files});
+}
+
+async function bitbucketGetPrDiff({
+  projectKey,
+  repoSlug,
+  prId,
+  path,
+  contextLines = 3,
+  excludePatterns = ['__snapshots__', 'messages_en.json', 'messages_ko.json'],
+}) {
+  if (DRY_RUN) return ok({diffs: []});
+  const {baseUrl, token} = bitbucketConfig();
+  const pathParam = path ? `&path=${encodeURIComponent(path)}` : '';
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/diff?contextLines=${contextLines}&whitespace=IGNORE_ALL${pathParam}`,
+    {token},
+  );
+  const diffs = (data.diffs || [])
+    .filter((d) => {
+      const filePath = d.destination?.toString || d.source?.toString || '';
+      return !excludePatterns.some((pattern) => filePath.includes(pattern));
+    })
+    .map((d) => {
+      const filePath = d.destination?.toString || d.source?.toString || '';
+      const hunks = (d.hunks || []).map((h) => {
+        const lines = [];
+        for (const seg of h.segments || []) {
+          const prefix = seg.type === 'ADDED' ? '+' : seg.type === 'REMOVED' ? '-' : ' ';
+          for (const l of seg.lines || []) {
+            lines.push({
+              prefix,
+              lineType: seg.type,
+              srcLine: l.source || null,
+              dstLine: l.destination || null,
+              content: l.line || '',
+            });
+          }
+        }
+        return {
+          srcLine: h.sourceLine,
+          srcSpan: h.sourceSpan,
+          dstLine: h.destinationLine,
+          dstSpan: h.destinationSpan,
+          lines,
+        };
+      });
+      return {filePath, srcPath: d.source?.toString || '', hunks};
+    });
+  return ok({diffs});
+}
+
+async function bitbucketGetPrComments({projectKey, repoSlug, prId}) {
+  if (DRY_RUN) return ok({total: 0, comments: []});
+  const {baseUrl, token} = bitbucketConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/activities?limit=100`,
+    {token},
+  );
+  const comments = (data.values || [])
+    .filter((a) => a.action === 'COMMENTED')
+    .map((a) => ({
+      id: a.comment?.id,
+      author: a.user?.displayName || '',
+      text: a.comment?.text || '',
+      created: a.createdDate ? new Date(a.createdDate).toISOString().slice(0, 10) : '',
+      anchor: a.commentAnchor
+        ? {
+            path: a.commentAnchor.path || '',
+            line: a.commentAnchor.line,
+            lineType: a.commentAnchor.lineType,
+            fileType: a.commentAnchor.fileType,
+          }
+        : null,
+    }));
+  return ok({total: comments.length, comments});
+}
+
+async function bitbucketAddPrComment({projectKey, repoSlug, prId, text: commentText, parentId}) {
+  const {baseUrl, token} = bitbucketConfig();
+  if (DRY_RUN) return ok({success: true, dryRun: true, text: commentText});
+  const result = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/comments`,
+    {method: 'POST', token, body: {text: commentText, ...(parentId ? {parent: {id: parentId}} : {})}},
+  );
+  return ok({success: true, commentId: result.id, text: result.text});
+}
+
+async function bitbucketAddPrInlineComment({
+  projectKey,
+  repoSlug,
+  prId,
+  text: commentText,
+  filePath,
+  line,
+  lineType = 'ADDED',
+  fileType = 'TO',
+}) {
+  const {baseUrl, token} = bitbucketConfig();
+  if (DRY_RUN) return ok({success: true, dryRun: true, text: commentText, filePath, line});
+  const result = await requestJson(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/pull-requests/${prId}/comments`,
+    {
+      method: 'POST',
+      token,
+      body: {
+        text: commentText,
+        anchor: {line, lineType, fileType, path: filePath, srcPath: filePath},
+      },
+    },
+  );
+  return ok({success: true, commentId: result.id, text: result.text, anchor: result.anchor});
+}
+
+async function bitbucketGetFile({projectKey, repoSlug, filePath, branch = 'master'}) {
+  if (DRY_RUN) return text('[DRY] Mock file content');
+  const {baseUrl, token} = bitbucketConfig();
+  const encodedPath = filePath.split('/').map(encodeURIComponent).join('/');
+  const content = await requestText(
+    baseUrl,
+    `/rest/api/1.0/projects/${projectKey}/repos/${repoSlug}/raw/${encodedPath}?at=${encodeURIComponent(branch)}`,
+    {token},
+  );
+  return text(content);
+}
+
+async function confluenceSearch({query, limit = 10}) {
+  if (DRY_RUN) return ok({total: 0, results: []});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/content/search?cql=${encodeURIComponent(query)}&limit=${limit}&expand=space,version`,
+    {token},
+  );
+  const results = (data.results || []).map((r) => ({
+    id: r.id,
+    title: r.title,
+    type: r.type,
+    space: r.space?.name || '',
+    spaceKey: r.space?.key || '',
+    url: `${baseUrl}/pages/viewpage.action?pageId=${r.id}`,
+    lastModified: (r.version?.when || '').slice(0, 10),
+    lastModifiedBy: r.version?.by?.displayName || '',
+  }));
+  return ok({total: data.totalSize, results});
+}
+
+async function confluenceGetPage({pageId}) {
+  if (DRY_RUN) return ok({id: pageId, title: '[DRY] Mock page', body: 'dry'});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/content/${pageId}?expand=body.storage,version,space,ancestors`,
+    {token},
+  );
+  return ok({
+    id: data.id,
+    title: data.title,
+    type: data.type,
+    space: data.space?.name || '',
+    spaceKey: data.space?.key || '',
+    url: `${baseUrl}/pages/viewpage.action?pageId=${data.id}`,
+    version: data.version?.number,
+    lastModified: (data.version?.when || '').slice(0, 10),
+    lastModifiedBy: data.version?.by?.displayName || '',
+    ancestors: (data.ancestors || []).map((a) => ({id: a.id, title: a.title})),
+    body: stripHtml(data.body?.storage?.value || ''),
+  });
+}
+
+async function confluenceGetChildren({pageId, limit = 25}) {
+  if (DRY_RUN) return ok({total: 0, children: []});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/content/${pageId}/child/page?limit=${limit}&expand=version,space`,
+    {token},
+  );
+  const children = (data.results || []).map((r) => ({
+    id: r.id,
+    title: r.title,
+    url: `${baseUrl}/pages/viewpage.action?pageId=${r.id}`,
+    lastModified: (r.version?.when || '').slice(0, 10),
+  }));
+  return ok({total: data.size, children});
+}
+
+async function confluenceListSpaces({limit = 20}) {
+  if (DRY_RUN) return ok({total: 0, spaces: []});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(baseUrl, `/rest/api/space?limit=${limit}&expand=description.plain`, {
+    token,
+  });
+  const spaces = (data.results || []).map((s) => ({
+    key: s.key,
+    name: s.name,
+    type: s.type,
+    description: s.description?.plain?.value?.slice(0, 100) || '',
+  }));
+  return ok({total: data.size, spaces});
+}
+
+async function confluenceGetPageStorage({pageId}) {
+  if (DRY_RUN) return ok({id: pageId, title: '[DRY] Mock page', version: 1, body: '<p>dry</p>'});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(baseUrl, `/rest/api/content/${pageId}?expand=body.storage,version,title`, {
+    token,
+  });
+  return ok({
+    id: data.id,
+    title: data.title,
+    version: data.version?.number,
+    body: data.body?.storage?.value || '',
+  });
+}
+
+async function confluenceCreatePage({spaceKey, parentId, title, body}) {
+  const {baseUrl, token} = confluenceConfig();
+  if (DRY_RUN) return ok({id: 'DRY', title, url: `${baseUrl}/pages/viewpage.action?pageId=DRY`});
+  const data = await requestJson(baseUrl, '/rest/api/content', {
+    method: 'POST',
+    token,
+    body: {
+      type: 'page',
+      title,
+      ancestors: [{id: parentId}],
+      space: {key: spaceKey},
+      body: {storage: {value: body, representation: 'storage'}},
+    },
+    timeoutMs: 20000,
+  });
+  return ok({id: data.id, title: data.title, url: `${baseUrl}/pages/viewpage.action?pageId=${data.id}`});
+}
+
+async function confluenceUpdatePage({pageId, title, body, minorEdit = false}) {
+  const {baseUrl, token} = confluenceConfig();
+  if (DRY_RUN) return ok({id: pageId, title: title || '[DRY] Mock page', version: 2, dryRun: true});
+  const current = await requestJson(baseUrl, `/rest/api/content/${pageId}?expand=version,title`, {token});
+  const nextVersion = (current.version?.number || 0) + 1;
+  const resolvedTitle = title || current.title;
+  const data = await requestJson(baseUrl, `/rest/api/content/${pageId}`, {
+    method: 'PUT',
+    token,
+    body: {
+      type: 'page',
+      title: resolvedTitle,
+      version: {number: nextVersion, minorEdit: !!minorEdit},
+      body: {storage: {value: body, representation: 'storage'}},
+    },
+    timeoutMs: 20000,
+  });
+  return ok({
+    id: data.id,
+    title: data.title,
+    version: data.version?.number,
+    url: `${baseUrl}/pages/viewpage.action?pageId=${data.id}`,
+  });
+}
+
+async function confluenceListVersions({pageId, limit = 25, start = 0}) {
+  if (DRY_RUN) return ok({total: 0, start, limit, versions: []});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/content/${pageId}/version?limit=${limit}&start=${start}`,
+    {token},
+  );
+  const versions = (data.results || []).map((v) => ({
+    version: v.number,
+    date: (v.when || '').slice(0, 10),
+    author: v.by?.displayName || '',
+    message: v.message || '',
+    minorEdit: !!v.minorEdit,
+  }));
+  return ok({total: data.size, start: data.start, limit: data.limit, versions});
+}
+
+async function confluenceGetPageVersion({pageId, version}) {
+  if (DRY_RUN) return ok({id: pageId, title: '[DRY] Mock page', version, body: 'dry'});
+  const {baseUrl, token} = confluenceConfig();
+  const data = await requestJson(
+    baseUrl,
+    `/rest/api/content/${pageId}?status=historical&version=${version}&expand=body.storage,version`,
+    {token},
+  );
+  return ok({
+    id: data.id,
+    title: data.title,
+    version: data.version?.number,
+    date: (data.version?.when || '').slice(0, 10),
+    author: data.version?.by?.displayName || '',
+    message: data.version?.message || '',
+    body: stripHtml(data.body?.storage?.value || ''),
+  });
+}
+
+async function confluenceGetCalendarEvents({subCalendarId, date}) {
+  if (DRY_RUN) {
+    return ok({
+      date,
+      total: 1,
+      events: [{what: 'Sign off staff', who: 'Alvin Wang (BK00236)'}],
+      signOffStaff: {name: 'Alvin Wang (BK00236)'},
+      dryRun: true,
+    });
+  }
+  const {baseUrl, token} = confluenceConfig();
+  const nextDay = new Date(date);
+  nextDay.setDate(nextDay.getDate() + 1);
+  const endDate = nextDay.toISOString().slice(0, 10);
+  const data = await requestJson(
+    baseUrl,
+    `/rest/calendar-services/1.0/calendar/events.json?subCalendarId=${encodeURIComponent(subCalendarId)}&start=${date}&end=${endDate}&userTimeZoneId=Asia%2FTaipei`,
+    {token},
+  );
+  const events = (data.events ?? []).map((e) => ({
+    what: e.what ?? e.title ?? '',
+    who: e.who ?? e.displayName ?? '',
+    start: e.start ?? '',
+    end: e.end ?? '',
+    allDay: !!e.allDay,
+  }));
+  const signOff = events.find(
+    (e) =>
+      (e.what ?? '').toLowerCase().includes('sign off staff') ||
+      (e.who ?? '').toLowerCase().includes('sign off staff'),
+  );
+  return ok({
+    date,
+    total: events.length,
+    events,
+    signOffStaff: signOff ? {name: signOff.who || signOff.what, event: signOff} : null,
+  });
+}