Pipeline MCP Tools API

Pipeline Broker 透過 MCP（Model Context Protocol）提供 17 個 tool，分為五大類別。所有 tool 經由 TCP stdio 連線呼叫。

Tool 選擇決策樹

下圖以「我現在想做什麼？」為入口，依任務類別分流到對應 tool。每一支葉節點上的工具名稱對應下方各章節，可直接點章節錨點查 API 參數。

決策樹對應的常見情境與調用者：

情境	工具	主要呼叫者
新建一個 phase 計畫	`set_phase_plan`	PM
啟動已建立的 phase	`start_phase`	PM
Dev / Reviewer 收到啟動訊號後表示開工	`begin_developing`	Dev / Reviewer
PM 派發任務 / Agent 主動詢問	`send_message`	All
回覆某個 PM 派發的 `develop` 訊息	`reply_message`	Dev / Reviewer
進入 wait loop，等對方訊息	`wait_for_message`	All（Agent main loop 用）
Dev / Reviewer 完成 1 個 Issue	`report_completion`	Dev / Reviewer
Reviewer 跑完整批 review	`report_review`	Reviewer
卡住、需要人類判斷	`request_human`	All
之前被 `request_human` 暫停，要繼續	`resume`	PM（人下指令）
偵測到嚴重錯誤，整條停	`stop_pipeline`	All
看當前 pipeline state / queue 長度	`get_pipeline_status`	All
寫一行 audit log	`log_activity`	All
看訊息 / 活動歷史	`get_message_history`、`get_activity_log`	PM、debugging
看 phase 計畫與進度	`get_phase_plan`	PM、Dev、Reviewer

讀圖重點：

5 個入口分類對應下方 5 個 H2 章節（Phase 管理 / 訊息 / 結果回報 / 安全與控制 / 監控），跟隨樹走到葉節點即得 tool 名稱，再到對應章節查 API 參數。
reply_message vs send_message：有 reply_to 才用 reply_message；它會把訊息掛在原 thread 下（PM 後續可用 get_message_history 重組對話）。
request_human 與 resume 配對使用：request_human 會將 pipeline 切到 HUMAN_NEEDED 狀態並 pause 所有 agent；只有人類透過 PM 下 resume 才能解除。
監控類 tool 不會改變 pipeline 狀態，可在任何 state 下安全呼叫。

Phase 管理

`start_phase`

初始化新的 Phase，將 Pipeline 從 IDLE 轉為 PHASE_PREPARING。

項目	說明
參數	`phase: number` — Phase 編號 `issues: string[]` — 該 Phase 的 Issue ID 列表
狀態轉換	`IDLE → PHASE_PREPARING`
回傳	`{ success: boolean, phase: number, issueCount: number, state: string }`
限制	僅在 `IDLE` 狀態可呼叫

範例：

start_phase(phase: 2, issues: ["JOP-240", "JOP-238", "JOP-239", "JOP-241"])
→ { success: true, phase: 2, issueCount: 4, state: "PHASE_PREPARING" }

`begin_developing`

確認 Phase 準備完成，開始開發。

項目	說明
參數	無
狀態轉換	`PHASE_PREPARING → PHASE_DEVELOPING`
回傳	`{ success: boolean, state: string }`
限制	僅在 `PHASE_PREPARING` 狀態可呼叫

範例：

begin_developing()
→ { success: true, state: "PHASE_DEVELOPING" }

`report_completion`

回報 Issue 的開發結果（成功或失敗）。

項目	說明
參數	`issue: string` — Issue ID `result: "pass" \| "fail"` — 結果
狀態轉換	依邏輯： • pass + 還有 todo → 維持 `PHASE_DEVELOPING` • pass + 全部 done → `PHASE_REVIEWING` • fail + failCount ≥ 3 → `HUMAN_NEEDED`
回傳	`{ success: boolean, allDone: boolean, nextIssue?: string, failCount?: number }`
限制	僅在 `PHASE_DEVELOPING` 狀態可呼叫

範例（成功，還有下一個）：

report_completion(issue: "JOP-240", result: "pass")
→ { success: true, allDone: false, nextIssue: "JOP-238" }

範例（成功，全部完成）：

report_completion(issue: "JOP-241", result: "pass")
→ { success: true, allDone: true }

範例（失敗）：

report_completion(issue: "JOP-238", result: "fail")
→ { success: true, allDone: false, failCount: 2 }

`report_review`

回報 PR Review 結果。

項目	說明
參數	`result: "approved" \| "changes"` — 審查結果 `prId?: string` — PR 編號（changes 時） `hasNextPhase?: boolean` — 是否有下一個 Phase
狀態轉換	依邏輯： • approved + hasNextPhase → `IDLE`（+ Auto-Advance） • approved + !hasNextPhase → `COMPLETED` • changes + fixCount < 2 → `PHASE_DEVELOPING` • changes + fixCount ≥ 2 → `HUMAN_NEEDED`
回傳	`{ success: boolean, state: string, fixCount?: number }`
限制	僅在 `PHASE_REVIEWING` 狀態可呼叫

範例（通過，有下一 Phase）：

report_review(result: "approved", hasNextPhase: true)
→ { success: true, state: "IDLE" }

範例（要求修正）：

report_review(result: "changes", prId: "PR #4")
→ { success: true, state: "PHASE_DEVELOPING", fixCount: 1 }

Phase Plan 管理

`set_phase_plan`

設定多 Phase 的執行計畫，啟用 Auto-Advance。

項目	說明
參數	`planId: string` — 計畫 ID（如 `"jope-core"`） `phases: Array<{ phase: number, issues: string[] }>` — Phase 定義 `autoAdvance?: boolean` — 是否自動推進（預設 false） `cooldownMinutes?: number` — 冷卻時間（預設 5）
回傳	`{ success: boolean, totalPhases: number, totalIssues: number }`

範例：

set_phase_plan(
  planId: "jope-core",
  phases: [
    { phase: 1, issues: ["JOP-237"] },
    { phase: 2, issues: ["JOP-240", "JOP-238", "JOP-239", "JOP-241"] },
    { phase: 3, issues: ["JOP-243", "JOP-242"] }
  ],
  autoAdvance: true,
  cooldownMinutes: 5
)
→ { success: true, totalPhases: 3, totalIssues: 7 }

`get_phase_plan`

查詢目前的 Phase Plan 狀態。

項目	說明
參數	無
回傳	`{ planId, phases[], currentPhase, completedPhases[], autoAdvance, cooldownMinutes }`

`set_auto_advance`

啟用或停用 Auto-Advance。

項目	說明
參數	`enabled: boolean`
回傳	`{ success: boolean, autoAdvance: boolean }`

`cancel_auto_advance`

取消正在執行的 Auto-Advance（cooldown 或 session_reset 階段）。

項目	說明
參數	`reason: string` — 取消原因
回傳	`{ success: boolean, stage: string }`
限制	僅在 Auto-Advance 活動中可呼叫

訊息

`send_message`

發送訊息到目標 Agent 的佇列。

項目	說明
參數	`to: string` — 目標 Agent ID（`pm`, `dev`, `reviewer`） `subject: string` — 訊息類型 `body: object` — 訊息內容
回傳	`{ messageId: string, queued: boolean }`

範例：

send_message(
  to: "dev",
  subject: "develop",
  body: { issue: "JOP-240", phase: 2, totalIssues: 4, currentIndex: 1 }
)
→ { messageId: "msg-abc-123", queued: true }

`wait_for_message`

阻塞等待佇列中的下一則訊息（或超時）。

項目	說明
參數	`timeout_sec?: number` — 超時秒數（預設 3600）
回傳	`{ message: Message \| null, timedOut: boolean }`
行為	按 priority → timestamp 順序取出佇列中最高優先的訊息。若佇列為空，阻塞直到有新訊息或超時。

`reply_message`

回覆特定訊息（建立對話串）。

項目	說明
參數	`replyTo: string` — 被回覆的 message ID `subject: string` — 回覆類型 `body: object` — 回覆內容
回傳	`{ messageId: string, queued: boolean }`

`get_message_history`

查詢歷史訊息。

項目	說明
參數	`issue?: string` — 依 Issue 篩選 `limit?: number` — 數量限制
回傳	`{ messages: Message[] }`

監控

`get_pipeline_status`

取得 Pipeline 完整狀態快照。

項目	說明
參數	無
回傳	完整狀態物件（見下方）

回傳結構：

{
  "state": "PHASE_DEVELOPING",
  "phase": 2,
  "issues": {
    "JOP-240": { "status": "done", "failCount": 0 },
    "JOP-238": { "status": "in_progress", "failCount": 0 },
    "JOP-239": { "status": "todo", "failCount": 0 },
    "JOP-241": { "status": "todo", "failCount": 0 }
  },
  "agents": {
    "pm": { "connected": true, "lastSeen": "2026-04-11T01:10:00Z" },
    "dev": { "connected": true, "lastSeen": "2026-04-11T01:16:00Z" },
    "reviewer": { "connected": false, "lastSeen": null }
  },
  "queues": {
    "pm": 0,
    "dev": 1,
    "reviewer": 0
  },
  "phasePlan": { "planId": "jope-core", "autoAdvance": true },
  "autoAdvance": { "active": false },
  "fixCount": 0,
  "uptime": "2h 15m"
}

`log_activity`

寫入活動日誌。

項目	說明
參數	`message: string` — 日誌內容
回傳	`{ success: boolean }`
寫入位置	`.pipeline/logs/{agent}.log`

`get_activity_log`

讀取活動日誌。

項目	說明
參數	`agent?: string` — Agent ID 或 `"pipeline"` `tail_lines?: number` — 最後 N 行（預設 50）
回傳	`{ lines: string[] }`

安全與控制

`request_human`

暫停 Pipeline，標記為需人工介入。

項目	說明
參數	`reason: string` — 暫停原因
狀態轉換	`* → HUMAN_NEEDED`
回傳	`{ success: boolean, previousState: string }`
副作用	通知所有已連線的 Agent

`resume`

從 HUMAN_NEEDED 或 PAUSED 恢復。

項目	說明
參數	無
狀態轉換	`HUMAN_NEEDED → IDLE 或 PHASE_DEVELOPING` `PAUSED → IDLE`
回傳	`{ success: boolean, state: string }`

`stop_pipeline`

終止 Pipeline（不可恢復）。

項目	說明
參數	無
狀態轉換	`* → STOPPED`
回傳	`{ success: boolean }`
副作用	建立 `.stop-pipeline` 檔案，Broker 斷開所有 Agent

Tool 選擇決策樹​

Phase 管理​

start_phase​

begin_developing​

report_completion​

report_review​

Phase Plan 管理​

set_phase_plan​

get_phase_plan​

set_auto_advance​

cancel_auto_advance​

訊息​

send_message​

wait_for_message​

reply_message​

get_message_history​

監控​

get_pipeline_status​

log_activity​

get_activity_log​

安全與控制​

request_human​

resume​

stop_pipeline​

Tool 選擇決策樹

Phase 管理

`start_phase`

`begin_developing`

`report_completion`

`report_review`

Phase Plan 管理

`set_phase_plan`

`get_phase_plan`

`set_auto_advance`

`cancel_auto_advance`

訊息

`send_message`

`wait_for_message`

`reply_message`

`get_message_history`

監控

`get_pipeline_status`

`log_activity`

`get_activity_log`

安全與控制

`request_human`

`resume`

`stop_pipeline`