feat(mcp): kbdb_graph_neighbors — knowledge graph 鄰居查詢薄殼（#68） #71

2026-07-19T07:56:07Z

Leo commented

2026-07-19 07:56:07 +00:00

動機

claude.ai 實測（#68）：MCP 只有 kbdb_query / kbdb_search / kbdb_get_record，AI 做不了關係遍歷。graph 查詢其實已存在（graph_neighbors workflow ＋ #28 的同步查詢端點 GET /q/:ns/:name），只差 MCP 面沒曝成 tool。本 PR 補齊 D17「KBDB MCP＝RAG 套餐」第三模式：關鍵字／語義／圖。

做法（薄殼，零平台核心變動）

新檔 mcp/src/tools/kbdb_graph.ts：kbdb_graph_neighbors tool（kbdb_* 前綴，D17 KBDB MCP 面）。
參數對齊 registry/examples/graph-neighbors/workflow.yaml 的 input 形狀：subject（必填，映射 workflow 的 node）、depth（選填預設 1）、kbdb_base（必填——workflow 刻意不寫死任何一家的庫，MCP 也不硬編）、template（選填預設 graph_triplet）、directed（選填）。namespace 由 MCP token 解析的 orgNamespace 自動注入（與 whoami 同源），不讓 client 亂帶。
實作：cypherFetch 打 GET /q/{orgNamespace}/graph_neighbors（既有 CYPHER_EXECUTOR service binding，不新增 binding、不新增零件、不碰 D1、不動 workflow 引擎本體），200 的最終節點輸出原樣回給 MCP client。
誠實錯誤（鐵律）：workflow 未部署 → 404 映成 workflow_not_installed ＋安裝指引（arcrun_push_workflow / acr push registry/examples/graph-neighbors/workflow.yaml），不 crash；HTTP 200 但 workflow 層 success:false（如缺參數）也回錯誤不假綠；409/413/500 帶 detail 透傳。
kbdb_graph_traverse 未加：repo 內只有 graph-neighbors 有 workflow 定義（registry/examples/），traverse 無可對齊的 input 形狀——不猜、不過度工程，等 workflow 進 registry 再補薄殼（一行 register 就能掛）。

測試（誠實狀態）

新增 mcp/tests/unit/tools/kbdb-graph.test.ts：假 McpServer ＋假 CYPHER_EXECUTOR binding，驗 (1) kbdb_* 註冊、(2) /q/:ns/graph_neighbors 路徑與 query 形狀（node/depth/template/namespace/kbdb_base/directed、depth 預設 1）、(3) 404→workflow_not_installed、(4) 500 透傳、(5) 200 但 success:false 不假綠、(6) 無 namespace 不發 fetch。7/7 綠。
pnpm vitest run（mcp 全套）：59/59 綠；tsc --noEmit 乾淨。
未 live 驗：本 session 不部署（部署是 leo 人類閘）；且 graph_neighbors workflow 依賴的 code 零件 live 狀態照 example 描述仍待驗——端到端要等 gated 部署後在真雲對一次。

部署

merge 後需 gated redeploy arcrun-mcp（leo 閘），本 PR 不含任何部署動作。

關聯 #68

🤖 Generated with Claude Code

https://claude.ai/code/session_01JUmjwkHLVBHM3ydhT1WSW3

## 動機 claude.ai 實測（#68）：MCP 只有 kbdb_query / kbdb_search / kbdb_get_record，AI 做不了關係遍歷。graph 查詢其實已存在（graph_neighbors workflow ＋ #28 的同步查詢端點 `GET /q/:ns/:name`），只差 MCP 面沒曝成 tool。本 PR 補齊 D17「KBDB MCP＝RAG 套餐」第三模式：關鍵字／語義／**圖**。 ## 做法（薄殼，零平台核心變動） - 新檔 `mcp/src/tools/kbdb_graph.ts`：`kbdb_graph_neighbors` tool（kbdb_* 前綴，D17 KBDB MCP 面）。 - 參數對齊 `registry/examples/graph-neighbors/workflow.yaml` 的 input 形狀：`subject`（必填，映射 workflow 的 `node`）、`depth`（選填預設 1）、`kbdb_base`（必填——workflow 刻意不寫死任何一家的庫，MCP 也不硬編）、`template`（選填預設 `graph_triplet`）、`directed`（選填）。`namespace` 由 MCP token 解析的 orgNamespace 自動注入（與 whoami 同源），不讓 client 亂帶。 - 實作：`cypherFetch` 打 `GET /q/{orgNamespace}/graph_neighbors`（**既有** CYPHER_EXECUTOR service binding，不新增 binding、不新增零件、不碰 D1、不動 workflow 引擎本體），200 的最終節點輸出原樣回給 MCP client。 - 誠實錯誤（鐵律）：workflow 未部署 → 404 映成 `workflow_not_installed` ＋安裝指引（arcrun_push_workflow / acr push registry/examples/graph-neighbors/workflow.yaml），不 crash；HTTP 200 但 workflow 層 `success:false`（如缺參數）也回錯誤不假綠；409/413/500 帶 detail 透傳。 - `kbdb_graph_traverse` **未加**：repo 內只有 graph-neighbors 有 workflow 定義（`registry/examples/`），traverse 無可對齊的 input 形狀——不猜、不過度工程，等 workflow 進 registry 再補薄殼（一行 register 就能掛）。 ## 測試（誠實狀態） - 新增 `mcp/tests/unit/tools/kbdb-graph.test.ts`：假 McpServer ＋假 CYPHER_EXECUTOR binding，驗 (1) kbdb_* 註冊、(2) `/q/:ns/graph_neighbors` 路徑與 query 形狀（node/depth/template/namespace/kbdb_base/directed、depth 預設 1）、(3) 404→workflow_not_installed、(4) 500 透傳、(5) 200 但 success:false 不假綠、(6) 無 namespace 不發 fetch。**7/7 綠**。 - `pnpm vitest run`（mcp 全套）：**59/59 綠**；`tsc --noEmit` 乾淨。 - **未 live 驗**：本 session 不部署（部署是 leo 人類閘）；且 graph_neighbors workflow 依賴的 `code` 零件 live 狀態照 example 描述仍待驗——端到端要等 gated 部署後在真雲對一次。 ## 部署 **merge 後需 gated redeploy arcrun-mcp（leo 閘）**，本 PR 不含任何部署動作。關聯 #68 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JUmjwkHLVBHM3ydhT1WSW3

Leo added 1 commit 2026-07-19 07:56:08 +00:00

feat(mcp): kbdb_graph_neighbors — graph 鄰居查詢薄殼（#68） 7eeab9f26f

MCP 面補齊 D17 KBDB RAG 套餐第三模式（關鍵字/語義/圖）：
- 新 tool kbdb_graph_neighbors：subject（必填）/depth（預設 1）/kbdb_base/
  template（預設 graph_triplet）/directed，形狀對齊
  registry/examples/graph-neighbors/workflow.yaml 的 input
- 薄殼調 GET /q/{orgNamespace}/graph_neighbors 同步查詢端點（#28 地基），
  走既有 CYPHER_EXECUTOR service binding，不新增 binding、不碰 D1、
  不動 workflow 引擎本體
- workflow 未部署 → 404 誠實回 workflow_not_installed ＋安裝指引，不 crash；
  HTTP 200 但 workflow 層 success:false 也不假綠
- graph_traverse 不加：repo 內無該 workflow 定義可對齊 input 形狀，不猜
- 測試：tests/unit/tools/kbdb-graph.test.ts（7 測，全綠）；tsc --noEmit 乾淨；
  mcp 全套 vitest 59/59 綠

merge 後需 gated redeploy arcrun-mcp（leo 閘）。

關聯 #68

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JUmjwkHLVBHM3ydhT1WSW3

Leo commented

2026-07-31 10:22:14 +00:00

08-01 複核：✅ 已 merge 並上線，關閉

證據：

源碼在 main：git ls-tree gitea/main mcp/src/tools/ → kbdb_graph.ts（另有後續的 kbdb_map.ts／kbdb_data.ts）
live 已生效：本 session 連上的 arcrun MCP connector 工具清單中確實可見 kbdb_graph_neighbors（leo21c 與 youlin 兩個實例都有）⇒ 本 PR 描述裡「未 live 驗、待 gated redeploy」那項已補上。

D17「KBDB MCP＝RAG 套餐」第三模式（圖）已補齊。kbdb_graph_traverse 當時刻意未加（無對齊的 workflow 定義），如日後 traverse workflow 進 registry 再補薄殼即可，不需留著本票。

關聯 #68。

## 08-01 複核：✅ 已 merge 並上線，關閉 **證據**： - 源碼在 main：`git ls-tree gitea/main mcp/src/tools/` → **`kbdb_graph.ts`**（另有後續的 `kbdb_map.ts`／`kbdb_data.ts`） - **live 已生效**：本 session 連上的 arcrun MCP connector 工具清單中確實可見 `kbdb_graph_neighbors`（leo21c 與 youlin 兩個實例都有）⇒ 本 PR 描述裡「未 live 驗、待 gated redeploy」那項已補上。 D17「KBDB MCP＝RAG 套餐」第三模式（圖）已補齊。`kbdb_graph_traverse` 當時刻意未加（無對齊的 workflow 定義），如日後 traverse workflow 進 registry 再補薄殼即可，不需留著本票。關聯 #68。

Leo closed this pull request

2026-07-31 10:22:14 +00:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Leo/Arcrun#71