From 886a8e31d0bc959235fea69f2c920e7287e54680 Mon Sep 17 00:00:00 2001
From: uncle6me-web <uncle6.me@gmail.com>
Date: Sun, 14 Jun 2026 22:12:32 +0800
Subject: [PATCH] =?UTF-8?q?feat(kbdb,mcp):=20KBDB=20=E8=B3=87=E6=96=99?=
 =?UTF-8?q?=E5=B1=A4=E8=96=84=E6=AE=BC=20+=20self-hosted=20MCP=20=E8=AA=8D?=
 =?UTF-8?q?=E8=AD=89=20+=20cypher=20KBDB=20proxy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

三件一條鏈（HANDOFF §2/§3b，kbdb-base Phase 9）：

A. KBDB MCP 薄殼（9.1）：mcp/src/tools/kbdb_data.ts 6 工具
   template/record/query/search，調基本盤 API。鐵律：不給建表/SQL，只 template+slot。

B. MCP self-hosted 認證 401（mcp-account-source §5.5）：
   - partner-auth.ts：MULTI_TENANT=false 時 Bearer 明碼直接當 org_namespace，
     繞 KBDB partner 驗證（對齊 cypher 的 opaque-key 模型）。官方 SaaS 行為不變、共用同碼。
   - mcp-setup.ts：把 namespace/api_key 寫進 .mcp.json headers.Authorization。
   - 新增 self-hosted vs SaaS 分支單測（9 tests 綠）。

C. cypher KBDB proxy（9.5）+ CLI 薄殼（9.2）：
   - routes/kbdb-proxy.ts 純轉發 /kbdb/* → KBDB 基本盤（KBDB_BASE_URL HTTP fetch，
     不新增 service binding）。讓 CLI（只認證到 cypher）能達獨立 KBDB worker。
   - 租戶隔離：X-Arcrun-API-Key 自動當 owner_id 注入 records/entries（強制覆寫防跨租戶）；
     templates 全域共享（虛擬表定義是 schema 非資料）。
   - cli/src/commands/kbdb.ts：acr kbdb template/record/query/search，與 MCP kbdb_* 同能力。
   - kbdb base：entries 加 page_name 過濾（9.3）。

cypher + cli + mcp tsc exit 0。未驗收：端到端需 deploy + KBDB_BASE_URL 可達後實測。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/kbdb.ts                 | 123 ++++++++++++++
 cli/src/commands/mcp-setup.ts            |  18 ++-
 cli/src/index.ts                         |  39 +++++
 cypher-executor/src/index.ts             |   2 +
 cypher-executor/src/routes/kbdb-proxy.ts | 131 +++++++++++++++
 kbdb/src/actions/entry-crud.ts           |   2 +
 kbdb/src/routes/entries.ts               |   4 +-
 mcp/src/middleware/partner-auth.ts       |  13 ++
 mcp/src/tools/kbdb_data.ts               | 195 +++++++++++++++++++++++
 mcp/src/tools/registry.ts                |   4 +
 mcp/src/types.ts                         |   6 +
 mcp/tests/unit/partner-auth.test.ts      |  38 +++++
 mcp/wrangler.toml                        |   9 ++
 13 files changed, 582 insertions(+), 2 deletions(-)
 create mode 100644 cli/src/commands/kbdb.ts
 create mode 100644 cypher-executor/src/routes/kbdb-proxy.ts
 create mode 100644 mcp/src/tools/kbdb_data.ts

diff --git a/cli/src/commands/kbdb.ts b/cli/src/commands/kbdb.ts
new file mode 100644
index 0000000..65ad027
--- /dev/null
+++ b/cli/src/commands/kbdb.ts
@@ -0,0 +1,123 @@
+/**
+ * acr kbdb — KBDB 資料層 CLI 薄殼（kbdb-base Phase 9.2，HANDOFF §2）
+ *
+ *   acr kbdb template create <name> --slots a,b,c   建 template（虛擬表定義）
+ *   acr kbdb template list                          列出所有 template
+ *   acr kbdb record create <template> --values k=v…  填一筆 record
+ *   acr kbdb record get <record_id>                 取單筆 record
+ *   acr kbdb query <template>                        列某 template 下本租戶的 records
+ *   acr kbdb search <q>                              關鍵字搜尋（本租戶 LIKE）
+ *
+ * 薄殼鐵律（rule 07 §5）：能力長在基本盤 API，CLI 只做介面轉換 + 暴露，無業務邏輯。
+ * 透過 cypher 的 KBDB proxy（/kbdb/*）達 KBDB——CLI 本來就只認證到 cypher（X-Arcrun-API-Key），
+ * 與 MCP 薄殼（kbdb_data.ts）同一組基本盤能力，差異只來自介面慣例（rule 07 §3.4）。
+ * KBDB 鐵律：只 template/slot，無建表/SQL（proxy 端也不暴露）。
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadConfig, getCypherExecutorUrl } from '../lib/config.js';
+
+/** 取身份 + cypher URL，缺 api_key/namespace 直接退出（與 recipe.ts 一致）。 */
+function ctx(): { url: string; apiKey: string } {
+  const config = loadConfig();
+  if (!config.api_key) {
+    console.error(chalk.red('缺少 API Key / namespace，請先執行 acr init（或設 NAMESPACE）'));
+    process.exit(1);
+  }
+  return { url: getCypherExecutorUrl(config), apiKey: config.api_key };
+}
+
+/** 統一 fetch + JSON 解析 + 失敗印錯（薄殼只暴露，不含業務邏輯）。 */
+async function call(method: string, path: string, body?: unknown): Promise<unknown> {
+  const { url, apiKey } = ctx();
+  const res = await fetch(`${url}${path}`, {
+    method,
+    headers: { 'Content-Type': 'application/json', 'X-Arcrun-API-Key': apiKey },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data: unknown;
+  try { data = text ? JSON.parse(text) : {}; } catch { data = { raw: text }; }
+  if (!res.ok) {
+    console.error(chalk.red(`KBDB 失敗（HTTP ${res.status}）：${text || '(空回應)'}`));
+    process.exit(1);
+  }
+  return data;
+}
+
+/** 把 ["k=v","x=y"] 轉成 { k:"v", x:"y" }。 */
+function parseKeyVals(pairs: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const p of pairs) {
+    const i = p.indexOf('=');
+    if (i < 0) {
+      console.error(chalk.red(`--values 格式須為 key=value，收到："${p}"`));
+      process.exit(1);
+    }
+    out[p.slice(0, i)] = p.slice(i + 1);
+  }
+  return out;
+}
+
+// ── template ───────────────────────────────────────────────────────────────────
+
+export async function cmdKbdbTemplateCreate(name: string, opts: { slots?: string }): Promise<void> {
+  const slots = (opts.slots ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  if (slots.length === 0) {
+    console.error(chalk.red('需要 --slots a,b,c（至少一個欄位名）'));
+    process.exit(1);
+  }
+  const spinner = ora(`建 template "${name}"`).start();
+  const data = await call('POST', '/kbdb/templates', { name, slots });
+  spinner.succeed(chalk.green(`template "${name}" 已建（slots: ${slots.join(', ')}）`));
+  console.log(chalk.gray(JSON.stringify(data, null, 2)));
+}
+
+export async function cmdKbdbTemplateList(): Promise<void> {
+  const data = await call('GET', '/kbdb/templates') as { templates?: Array<{ name: string; slots_json?: string }>; count?: number };
+  const list = data.templates ?? [];
+  if (list.length === 0) {
+    console.log(chalk.yellow('（尚無 template，用 acr kbdb template create <name> --slots … 建一個）'));
+    return;
+  }
+  console.log(chalk.bold(`\n  ${list.length} 個 template：\n`));
+  for (const t of list) {
+    console.log(`  ${chalk.cyan(t.name)}  ${chalk.gray(t.slots_json ?? '')}`);
+  }
+  console.log();
+}
+
+// ── record ───────────────────────────────────────────────────────────────────
+
+export async function cmdKbdbRecordCreate(template: string, opts: { values?: string[] }): Promise<void> {
+  const values = parseKeyVals(opts.values ?? []);
+  if (Object.keys(values).length === 0) {
+    console.error(chalk.red('需要 --values slot=內容（可重複），如 --values name=Leo --values email=x@y.com'));
+    process.exit(1);
+  }
+  const spinner = ora(`填 record（template "${template}"）`).start();
+  const data = await call('POST', '/kbdb/records', { template, values });
+  spinner.succeed(chalk.green(`record 已存入 template "${template}"`));
+  console.log(chalk.gray(JSON.stringify(data, null, 2)));
+}
+
+export async function cmdKbdbRecordGet(recordId: string): Promise<void> {
+  const data = await call('GET', `/kbdb/records/${encodeURIComponent(recordId)}`);
+  console.log(chalk.gray(JSON.stringify(data, null, 2)));
+}
+
+// ── query / search ─────────────────────────────────────────────────────────────
+
+export async function cmdKbdbQuery(template: string): Promise<void> {
+  const data = await call('GET', `/kbdb/records/by-template/${encodeURIComponent(template)}`) as { records?: unknown[]; count?: number };
+  const recs = data.records ?? [];
+  console.log(chalk.bold(`\n  template "${template}" 下 ${recs.length} 筆 record（本租戶）：\n`));
+  console.log(chalk.gray(JSON.stringify(recs, null, 2)));
+}
+
+export async function cmdKbdbSearch(q: string): Promise<void> {
+  const data = await call('GET', `/kbdb/search?q=${encodeURIComponent(q)}`) as { entries?: unknown[]; count?: number; mode?: string };
+  const hits = data.entries ?? [];
+  console.log(chalk.bold(`\n  "${q}" 命中 ${hits.length} 筆（mode: ${data.mode ?? 'keyword'}，本租戶）：\n`));
+  console.log(chalk.gray(JSON.stringify(hits, null, 2)));
+}
diff --git a/cli/src/commands/mcp-setup.ts b/cli/src/commands/mcp-setup.ts
index d611834..92f5d55 100644
--- a/cli/src/commands/mcp-setup.ts
+++ b/cli/src/commands/mcp-setup.ts
@@ -18,6 +18,7 @@ import { loadConfig, getMcpUrl, DEFAULT_MCP_URL } from '../lib/config.js';
 interface McpServerEntry {
   type: 'http';
   url: string;
+  headers?: Record<string, string>;
 }
 interface McpJson {
   mcpServers?: Record<string, McpServerEntry | Record<string, unknown>>;
@@ -43,13 +44,28 @@ export function cmdMcpSetup(): void {
     }
   }
 
+  // 身份寫進 .mcp.json headers（HANDOFF §3b ②）：裸 .mcp.json 不送任何 header，
+  // MCP partner-auth 收不到 token → 一律 401。與 CLI 同一份身份來源（rule 07 §4）：
+  //   self-hosted → api_key 欄位存的是 namespace 明碼（config.ts NAMESPACE→api_key），
+  //     MCP（MULTI_TENANT=false）把 Bearer 當 org_namespace，與 cypher 的 X-Arcrun-API-Key 對齊。
+  //   standard → api_key 是平台 ak_（多租戶 MCP 仍走 partner 驗證；ak_ 不是 pk_live 的話平台側自理）。
+  // 不重實作身份解析：直接用 loadConfig() 已解析好的 api_key（薄殼只暴露，不自造邏輯）。
+  const identity = config.api_key && config.api_key.trim() !== '' ? config.api_key.trim() : undefined;
+  const entry: McpServerEntry = { type: 'http', url: mcpUrl };
+  if (identity) entry.headers = { Authorization: `Bearer ${identity}` };
+
   if (!doc.mcpServers || typeof doc.mcpServers !== 'object') doc.mcpServers = {};
-  doc.mcpServers[SERVER_KEY] = { type: 'http', url: mcpUrl };
+  doc.mcpServers[SERVER_KEY] = entry;
 
   writeFileSync(target, JSON.stringify(doc, null, 2) + '\n', 'utf8');
 
   console.log(chalk.green(`\n  ✓ 已寫入 ${target}`));
   console.log(chalk.gray(`    arcrun MCP → ${mcpUrl}`));
+  if (identity) {
+    console.log(chalk.gray(`    身份 → Authorization: Bearer ${identity.slice(0, 6)}…（${config.mode === 'self-hosted' ? 'self-hosted namespace 明碼' : 'api_key'}）`));
+  } else {
+    console.log(chalk.yellow(`    ⚠ config 無 api_key/namespace → .mcp.json 不帶身份；self-hosted MCP 會 401。先 acr init 或設 NAMESPACE 再重跑。`));
+  }
   if (mcpUrl === DEFAULT_MCP_URL && (!config.mcp_url || config.mcp_url.trim() === '')) {
     console.log(chalk.gray(`    （用平台預設；要連自己/客戶的 MCP，在 config 設 mcp_url 或 ARCRUN_MCP_URL env，再重跑）`));
   }
diff --git a/cli/src/index.ts b/cli/src/index.ts
index 9177a9f..35c4bef 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -24,6 +24,14 @@ import { cmdLogs } from './commands/logs.js';
 import { cmdUpdate } from './commands/update.js';
 import { cmdInstallHarness } from './commands/install-harness.js';
 import { cmdMcpSetup } from './commands/mcp-setup.js';
+import {
+  cmdKbdbTemplateCreate,
+  cmdKbdbTemplateList,
+  cmdKbdbRecordCreate,
+  cmdKbdbRecordGet,
+  cmdKbdbQuery,
+  cmdKbdbSearch,
+} from './commands/kbdb.js';
 import { cmdAuthRecipeList, cmdAuthRecipeInfo, cmdAuthRecipeScaffold } from './commands/auth-recipe.js';
 
 const program = new Command();
@@ -160,6 +168,37 @@ authRecipeCmd
   .description('輸出 credentials.yaml 範本 + workflow.yaml 使用範例')
   .action((service: string) => cmdAuthRecipeScaffold(service));
 
+// acr kbdb — KBDB 資料層薄殼（kbdb-base 9.2，透過 cypher KBDB proxy；與 MCP kbdb_* 同能力）
+const kbdbCmd = program.command('kbdb').description('KBDB 資料層（template/record/query/search；不建表、不寫 SQL）');
+const kbdbTemplateCmd = kbdbCmd.command('template').description('template = 虛擬表定義（name + slots）');
+kbdbTemplateCmd
+  .command('create <name>')
+  .description('建一個 template（虛擬表定義），如 --slots name,email,phone')
+  .requiredOption('--slots <list>', '欄位名清單，逗號分隔，如 name,email,phone')
+  .action((name: string, opts: { slots: string }) => cmdKbdbTemplateCreate(name, opts));
+kbdbTemplateCmd
+  .command('list')
+  .description('列出所有 template')
+  .action(() => cmdKbdbTemplateList());
+const kbdbRecordCmd = kbdbCmd.command('record').description('record = 依 template 填的一筆資料');
+kbdbRecordCmd
+  .command('create <template>')
+  .description('填一筆 record，如 --values name=Leo --values email=x@y.com（可重複）')
+  .option('--values <pair...>', 'slot=內容（可重複）')
+  .action((template: string, opts: { values?: string[] }) => cmdKbdbRecordCreate(template, opts));
+kbdbRecordCmd
+  .command('get <record_id>')
+  .description('取單筆 record 全文')
+  .action((recordId: string) => cmdKbdbRecordGet(recordId));
+kbdbCmd
+  .command('query <template>')
+  .description('列某 template 下本租戶的所有 record')
+  .action((template: string) => cmdKbdbQuery(template));
+kbdbCmd
+  .command('search <q>')
+  .description('關鍵字搜尋本租戶內容（LIKE，基本盤）')
+  .action((q: string) => cmdKbdbSearch(q));
+
 // acr list
 program
   .command('list')
diff --git a/cypher-executor/src/index.ts b/cypher-executor/src/index.ts
index 6d68d5b..c97fd30 100644
--- a/cypher-executor/src/index.ts
+++ b/cypher-executor/src/index.ts
@@ -20,6 +20,7 @@ import { authRouter } from './routes/auth';
 import { resumeRouter } from './routes/resume';
 import { executionsRouter } from './routes/executions';
 import { initSeedRouter } from './routes/init-seed';
+import { kbdbProxyRouter } from './routes/kbdb-proxy';
 
 const app = new Hono<{ Bindings: Bindings }>();
 
@@ -48,6 +49,7 @@ app.route('/', authRouter);
 app.route('/', resumeRouter);
 app.route('/', executionsRouter);  // LI SDD M2.1: /executions/* + /workflows/:name/executions
 app.route('/', initSeedRouter);    // 薄殼原則：seed recipe 是 API 行為（rule 07，壓測 §4.1）
+app.route('/', kbdbProxyRouter);   // kbdb-base 9.5：KBDB 資料層 proxy（讓 CLI 透過 cypher 達 KBDB，純轉發）
 
 // Worker 導出（fetch + scheduled）
 // scheduled handler 對應 wrangler.toml [triggers].crons，每分鐘 tick；
diff --git a/cypher-executor/src/routes/kbdb-proxy.ts b/cypher-executor/src/routes/kbdb-proxy.ts
new file mode 100644
index 0000000..4ed486b
--- /dev/null
+++ b/cypher-executor/src/routes/kbdb-proxy.ts
@@ -0,0 +1,131 @@
+/**
+ * KBDB 資料層 proxy（kbdb-base Phase 9.5，HANDOFF §2 + §3b 後續）
+ *
+ * 為什麼存在：CLI 是 client，只認證到 cypher-executor（X-Arcrun-API-Key），達不到獨立的
+ * KBDB worker（MCP 走內部 service binding 可達，CLI 不行）。故在 cypher 開一條 proxy，
+ * 讓 CLI 薄殼（acr kbdb *）透過「它本來就連的 cypher」打 KBDB 基本盤 API。
+ *
+ * 薄殼鐵律（rule 07）：本檔是 **proxy**，純轉發到 KBDB 基本盤 HTTP API，
+ *   無業務邏輯、不寫 SQL、不建表、不直連 D1。能力真身在 KBDB 基本盤（kbdb/src/routes/*）。
+ *
+ * KBDB 鐵律（leo 2026-06-14）：只暴露 template/record/query/search，**不開建表/SQL**。
+ *
+ * 租戶隔離（leo 2026-06-14 拍板，選項①）：
+ *   - X-Arcrun-API-Key（namespace/api_key）→ 自動當 owner_id 注入 records/entries 的寫入與查詢。
+ *     不同 namespace 的資料互相看不到。與 cypher 其他端點同身份模型。
+ *   - **templates 全域共享**（虛擬表定義是 schema 不是資料；類 Supabase 的表結構大家共用）→ 不注入 owner_id。
+ *
+ * cypher→KBDB 連法沿用既有慣例（webhook-handlers.ts / recipes.ts）：
+ *   KBDB_BASE_URL HTTP fetch + 選用 KBDB_INTERNAL_TOKEN Bearer。**不新增 service binding**（rule 02 §3.1）。
+ */
+import { Hono } from 'hono';
+import type { Bindings } from '../types';
+
+export const kbdbProxyRouter = new Hono<{ Bindings: Bindings }>();
+
+/** KBDB 基本盤 base URL + internal headers（沿用 webhook-handlers.ts 慣例）。 */
+function kbdbBase(env: Bindings): { base: string; headers: Record<string, string> } {
+  const base = (env.KBDB_BASE_URL ?? 'https://kbdb.finally.click').replace(/\/$/, '');
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (env.KBDB_INTERNAL_TOKEN) headers['Authorization'] = `Bearer ${env.KBDB_INTERNAL_TOKEN}`;
+  return { base, headers };
+}
+
+/** 取租戶身份（owner_id）。缺 header → 401（與 cypher 其他資料端點一致）。 */
+function tenant(c: { req: { header: (k: string) => string | undefined } }): string | null {
+  return c.req.header('X-Arcrun-API-Key') ?? null;
+}
+
+const NEED_KEY = { error: '缺少 X-Arcrun-API-Key header' } as const;
+
+// ── templates（全域共享，不注入 owner_id）──────────────────────────────────────
+
+// POST /kbdb/templates — 建 template（name + slots）。鐵律：這是「虛擬表定義」非建真表。
+kbdbProxyRouter.post('/kbdb/templates', async (c) => {
+  const owner = tenant(c);
+  if (!owner) return c.json(NEED_KEY, 401);
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.name || !Array.isArray(body.slots)) {
+    return c.json({ error: 'name 與 slots[] 必填' }, 400);
+  }
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(`${base}/templates`, {
+    method: 'POST',
+    headers,
+    // created_by 帶上租戶當溯源，但 template 本身全域可見可用
+    body: JSON.stringify({ name: body.name, slots: body.slots, description: body.description, created_by: owner }),
+  });
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// GET /kbdb/templates — 列出所有 template（全域）。
+kbdbProxyRouter.get('/kbdb/templates', async (c) => {
+  if (!tenant(c)) return c.json(NEED_KEY, 401);
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(`${base}/templates`, { headers });
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// GET /kbdb/templates/:idOrName — 取單一 template。
+kbdbProxyRouter.get('/kbdb/templates/:idOrName', async (c) => {
+  if (!tenant(c)) return c.json(NEED_KEY, 401);
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(`${base}/templates/${encodeURIComponent(c.req.param('idOrName'))}`, { headers });
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// ── records（以租戶 namespace 為 owner_id 隔離）────────────────────────────────
+
+// POST /kbdb/records — 填一筆 record（template + values）。owner_id 自動注入。
+kbdbProxyRouter.post('/kbdb/records', async (c) => {
+  const owner = tenant(c);
+  if (!owner) return c.json(NEED_KEY, 401);
+  const body = await c.req.json().catch(() => null);
+  if (!body || !body.template || !body.values) {
+    return c.json({ error: 'template 與 values 必填' }, 400);
+  }
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(`${base}/records`, {
+    method: 'POST',
+    headers,
+    // 強制以租戶身份隔離：忽略 caller 自帶 owner_id，一律用 header 身份（防跨租戶寫入）
+    body: JSON.stringify({ template: body.template, values: body.values, owner_id: owner }),
+  });
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// GET /kbdb/records/by-template/:template — 列某 template 下「本租戶」的 records。
+kbdbProxyRouter.get('/kbdb/records/by-template/:template', async (c) => {
+  const owner = tenant(c);
+  if (!owner) return c.json(NEED_KEY, 401);
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(
+    `${base}/records/by-template/${encodeURIComponent(c.req.param('template'))}?owner_id=${encodeURIComponent(owner)}`,
+    { headers },
+  );
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// GET /kbdb/records/:recordId — 取單筆 record。
+kbdbProxyRouter.get('/kbdb/records/:recordId', async (c) => {
+  if (!tenant(c)) return c.json(NEED_KEY, 401);
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(`${base}/records/${encodeURIComponent(c.req.param('recordId'))}`, { headers });
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
+
+// ── search（限本租戶範圍內）────────────────────────────────────────────────────
+
+// GET /kbdb/search?q= — entries LIKE 關鍵字搜尋，限本租戶 owner_id。
+kbdbProxyRouter.get('/kbdb/search', async (c) => {
+  const owner = tenant(c);
+  if (!owner) return c.json(NEED_KEY, 401);
+  const q = c.req.query('q');
+  if (!q) return c.json({ error: 'q 必填' }, 400);
+  const { base, headers } = kbdbBase(c.env);
+  const res = await fetch(
+    `${base}/entries/search?q=${encodeURIComponent(q)}&owner_id=${encodeURIComponent(owner)}`,
+    { headers },
+  );
+  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
+});
diff --git a/kbdb/src/actions/entry-crud.ts b/kbdb/src/actions/entry-crud.ts
index 39a8133..2ecc7f0 100644
--- a/kbdb/src/actions/entry-crud.ts
+++ b/kbdb/src/actions/entry-crud.ts
@@ -56,6 +56,7 @@ export interface ListEntriesFilter {
   entry_type?: string;
   owner_id?: string;
   parent_id?: string;
+  page_name?: string;   // exact-match lookup (e.g. skill-/example- idempotency key)
   limit?: number;
   offset?: number;
 }
@@ -66,6 +67,7 @@ export async function listEntries(db: D1Database, f: ListEntriesFilter = {}): Pr
   if (f.entry_type) { conds.push('entry_type = ?'); params.push(f.entry_type); }
   if (f.owner_id) { conds.push('owner_id = ?'); params.push(f.owner_id); }
   if (f.parent_id) { conds.push('parent_id = ?'); params.push(f.parent_id); }
+  if (f.page_name) { conds.push('page_name = ?'); params.push(f.page_name); }
   const where = conds.length ? `WHERE ${conds.join(' AND ')}` : '';
   const limit = Math.min(f.limit ?? 100, 1000);
   const offset = f.offset ?? 0;
diff --git a/kbdb/src/routes/entries.ts b/kbdb/src/routes/entries.ts
index 2fd11e6..d474084 100644
--- a/kbdb/src/routes/entries.ts
+++ b/kbdb/src/routes/entries.ts
@@ -20,13 +20,15 @@ entryRoutes.post('/', async (c) => {
   return c.json({ success: true, entry });
 });
 
-// GET /entries — list with filters (entry_type, owner_id, parent_id)
+// GET /entries — list with filters (entry_type, owner_id, parent_id, page_name)
 // e.g. list workflows under a project: ?parent_id=PROJECT&entry_type=workflow
+// e.g. get one by idempotency key: ?page_name=skill-rag_with_arcrun
 entryRoutes.get('/', async (c) => {
   const entries = await listEntries(c.env.DB, {
     entry_type: c.req.query('entry_type') || undefined,
     owner_id: c.req.query('owner_id') || undefined,
     parent_id: c.req.query('parent_id') || undefined,
+    page_name: c.req.query('page_name') || undefined,
     limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
     offset: c.req.query('offset') ? Number(c.req.query('offset')) : undefined,
   });
diff --git a/mcp/src/middleware/partner-auth.ts b/mcp/src/middleware/partner-auth.ts
index 19a8bcd..03201c8 100644
--- a/mcp/src/middleware/partner-auth.ts
+++ b/mcp/src/middleware/partner-auth.ts
@@ -11,6 +11,19 @@ export async function partnerAuthMiddleware(
   }
 
   const token = authHeader.slice(7);
+
+  // Self-hosted 單租戶（MULTI_TENANT=false）：Bearer 帶的是 namespace 明碼，不是平台 partner key。
+  // 與 cypher-executor 一致——cypher 把 X-Arcrun-API-Key 當「不驗證的 opaque 分區 key」（namespace
+  // 是明碼分區標籤非密碼，mindset §3 arcrun 不做授權判斷）。故 self-hosted 模式不打 KBDB partner
+  // 驗證，直接把 token 當 org_namespace。SDD: mcp-account-source.md；HANDOFF §3b。
+  if (c.env.MULTI_TENANT === 'false') {
+    c.set('org_namespace', token);
+    c.set('partner_token', token);  // 下游轉發給 cypher 當 X-Arcrun-API-Key（與 CLI 同一份身份）
+    await next();
+    return;
+  }
+
+  // 官方 SaaS（MULTI_TENANT 未設 / "true"）：維持 partner-key 驗證（行為不變）。
   const resp = await c.env.KBDB.fetch(
     `http://kbdb/partners/${encodeURIComponent(token)}/info`,
     {
diff --git a/mcp/src/tools/kbdb_data.ts b/mcp/src/tools/kbdb_data.ts
new file mode 100644
index 0000000..91fda9c
--- /dev/null
+++ b/mcp/src/tools/kbdb_data.ts
@@ -0,0 +1,195 @@
+/**
+ * KBDB 資料層 MCP 薄殼（kbdb-base Phase 9.1，HANDOFF §2）
+ *
+ * rule 07 §5（薄殼鐵律）：能力長在基本盤 API，MCP 只做介面轉換 + 暴露，無業務邏輯。
+ * 全走既有 kbdbFetch（KBDB service binding）打基本盤 HTTP API（kbdb/src/routes/*）。
+ *
+ * KBDB 鐵律（leo 2026-06-14，頂層 DECISION-kbdb-v3-baseplane.md）：
+ *   - 任何人不准動表；**不提供建表 / SQL tool**。
+ *   - AI 想存新類型的資料時只有「建 template（name+slots）+ 填 record（slot→content）」可用
+ *     ——類 Supabase 萬用表，schema 由 template/slot 表達，不是真的 CREATE TABLE。
+ *   - 薄殼只調基本盤 HTTP API，不直連 D1、不寫 SQL。
+ *
+ * 基本盤 API 契約（已存在，kbdb/src/routes）：
+ *   POST   /templates                 { name, slots[], description?, created_by? } → { template }
+ *   GET    /templates                 → { templates[], count }
+ *   GET    /templates/:idOrName       → { template }
+ *   POST   /records                   { template, values:{slot:content}, owner_id? } → { record }
+ *   GET    /records/by-template/:t    ?owner_id= → { records[], count }
+ *   GET    /records/:recordId         → { record }
+ *   GET    /entries/search            ?q=&owner_id= → { entries[], count, mode:'keyword' }
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { Env } from "../types.js";
+import { kbdbFetch } from "../lib/kbdb-client.js";
+import { errorResponse, successResponse } from "../lib/cypher-client.js";
+
+/** 註冊全部 KBDB 資料層工具（kbdb-base Phase 9.1）。不含建表/SQL tool（鐵律）。 */
+export function registerAllKbdbDataTools(server: McpServer, env: Env) {
+  registerCreateTemplate(server, env);
+  registerListTemplates(server, env);
+  registerCreateRecord(server, env);
+  registerGetRecord(server, env);
+  registerQuery(server, env);
+  registerSearch(server, env);
+}
+
+/**
+ * kbdb_create_template — 建一個 template（= 萬用表裡的一種「虛擬表/資料形狀」）。
+ * 這是 AI 想存「新類型資料」時的唯一入口：沒有建表 API，改用 template + slots 描述欄位。
+ */
+export function registerCreateTemplate(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_create_template",
+    "建一個 KBDB template（萬用表裡的一種資料形狀，類 Supabase 的虛擬表）。KBDB 不能建真的資料表——" +
+      "要存「新類型」的結構化資料時，就建一個 template 並用 slots 列出它的欄位名，之後用 kbdb_create_record 填值。" +
+      "例：name='contact', slots=['name','email','phone']。",
+    {
+      name: z.string().min(1).describe("template 名稱（唯一識別，之後填 record 用這個名字），如 'contact' / 'note'"),
+      slots: z.array(z.string().min(1)).min(1).describe("欄位名清單，如 ['name','email','phone']"),
+      description: z.string().optional().describe("這個 template 用途的簡述（選填）"),
+      created_by: z.string().optional().describe("建立者標記（選填）"),
+    },
+    async ({ name, slots, description, created_by }) => {
+      try {
+        const res = await kbdbFetch(env, "/templates", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ name, slots, description, created_by }),
+        });
+        if (!res.ok) {
+          return errorResponse("create_template_failed", `建 template 失敗`, ["檢查 name 是否重複", "確認 slots 是非空字串陣列"], await res.text().catch(() => ""));
+        }
+        const data = await res.json();
+        return successResponse(data, [
+          `template「${name}」已建。用 kbdb_create_record(template='${name}', values={...}) 填一筆資料`,
+        ]);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
+
+/** kbdb_list_templates — 列出所有已建的 template（看有哪些資料形狀可用）。 */
+export function registerListTemplates(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_list_templates",
+    "列出 KBDB 裡所有 template（已定義的資料形狀）。要存資料前先看有沒有現成 template 可用，沒有再 kbdb_create_template。",
+    {},
+    async () => {
+      try {
+        const res = await kbdbFetch(env, "/templates");
+        if (!res.ok) return errorResponse("list_templates_failed", `列 template 失敗`, ["稍後重試"], await res.text().catch(() => ""));
+        const data = await res.json();
+        return successResponse(data, ["每個 template 的 slots_json 是它的欄位清單", "填資料用 kbdb_create_record"]);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
+
+/** kbdb_create_record — 依某 template 填一筆 record（slot → 內容）。 */
+export function registerCreateRecord(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_create_record",
+    "依某 template 填一筆 record（一列資料）。values 是 {slot名: 內容}，slot 名要對得上 template 的 slots。" +
+      "template 不存在會失敗——先 kbdb_list_templates 確認，或 kbdb_create_template 建一個。",
+    {
+      template: z.string().min(1).describe("template 的 name 或 id"),
+      values: z.record(z.string()).describe("欄位內容 {slot名: 字串內容}，如 {name:'Leo', email:'leo@x.com'}"),
+      owner_id: z.string().optional().describe("資料歸屬標記（選填，如專案 id / 用戶 id）"),
+    },
+    async ({ template, values, owner_id }) => {
+      try {
+        const res = await kbdbFetch(env, "/records", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ template, values, owner_id }),
+        });
+        if (!res.ok) {
+          return errorResponse("create_record_failed", `填 record 失敗`, [
+            `確認 template「${template}」存在（kbdb_list_templates）`,
+            "values 的 slot 名要對得上 template 的 slots",
+          ], await res.text().catch(() => ""));
+        }
+        const data = await res.json();
+        return successResponse(data, [`已存入。用 kbdb_query(template='${template}') 列出此 template 的所有 record`]);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
+
+/** kbdb_get_record — 用 record_id 取單筆 record。 */
+export function registerGetRecord(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_get_record",
+    "用 record_id 取一筆 record 的所有欄位內容。record_id 從 kbdb_create_record 回傳或 kbdb_query 列出取得。",
+    {
+      record_id: z.string().min(1).describe("record 的 id（rec_xxx）"),
+    },
+    async ({ record_id }) => {
+      try {
+        const res = await kbdbFetch(env, `/records/${encodeURIComponent(record_id)}`);
+        if (res.status === 404) return errorResponse("not_found", `record「${record_id}」不存在`, ["確認 record_id 正確", "用 kbdb_query 列出某 template 的 record 取 id"]);
+        if (!res.ok) return errorResponse("get_record_failed", `取 record 失敗`, ["稍後重試"], await res.text().catch(() => ""));
+        const data = await res.json();
+        return successResponse(data);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
+
+/** kbdb_query — 列出某 template 底下的所有 record（結構化查詢）。 */
+export function registerQuery(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_query",
+    "列出某 template 底下的所有 record（結構化查詢，按 template 取整批資料）。要按關鍵字找內容用 kbdb_search。",
+    {
+      template: z.string().min(1).describe("template 的 name 或 id"),
+      owner_id: z.string().optional().describe("只取某歸屬的 record（選填）"),
+    },
+    async ({ template, owner_id }) => {
+      try {
+        const path = `/records/by-template/${encodeURIComponent(template)}` + (owner_id ? `?owner_id=${encodeURIComponent(owner_id)}` : "");
+        const res = await kbdbFetch(env, path);
+        if (!res.ok) return errorResponse("query_failed", `查詢 record 失敗`, [`確認 template「${template}」存在`], await res.text().catch(() => ""));
+        const data = await res.json();
+        return successResponse(data, ["用 kbdb_get_record(record_id) 取單筆全文", "按關鍵字找內容改用 kbdb_search"]);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
+
+/** kbdb_search — 對 entries 做 D1 LIKE 關鍵字搜尋（基本盤，非語義）。 */
+export function registerSearch(server: McpServer, env: Env) {
+  server.tool(
+    "kbdb_search",
+    "對 KBDB 內容做關鍵字搜尋（D1 LIKE，基本盤層；語義搜尋是另外的 embed 模組，基本盤沒有）。" +
+      "回命中的 entries。要按 template 取整批結構化資料用 kbdb_query。",
+    {
+      q: z.string().min(1).describe("搜尋關鍵字"),
+      owner_id: z.string().optional().describe("限定某歸屬範圍內搜（選填）"),
+    },
+    async ({ q, owner_id }) => {
+      try {
+        const path = `/entries/search?q=${encodeURIComponent(q)}` + (owner_id ? `&owner_id=${encodeURIComponent(owner_id)}` : "");
+        const res = await kbdbFetch(env, path);
+        if (!res.ok) return errorResponse("search_failed", `搜尋失敗`, ["稍後重試"], await res.text().catch(() => ""));
+        const data = await res.json();
+        return successResponse(data, ["mode:keyword = D1 LIKE（基本盤）", "找不到時換個關鍵字，或用 kbdb_query 按 template 列出"]);
+      } catch (e) {
+        return errorResponse("internal_error", e instanceof Error ? e.message : String(e), ["稍後重試"]);
+      }
+    },
+  );
+}
diff --git a/mcp/src/tools/registry.ts b/mcp/src/tools/registry.ts
index 2c3e2e1..d554e83 100644
--- a/mcp/src/tools/registry.ts
+++ b/mcp/src/tools/registry.ts
@@ -20,6 +20,7 @@ import { registerAllIntrospectionTools } from "./arcrun_introspection.js";
 import { registerAllWorkflowCrudTools } from "./arcrun_workflow_crud.js";
 import { registerAllSkillExampleTools } from "./arcrun_skills_examples.js";
 import { registerAllRecipeTools } from "./arcrun_recipe.js";
+import { registerAllKbdbDataTools } from "./kbdb_data.js";
 import { registerWhoami } from "./arcrun_whoami.js";
 
 export function registerAllTools(server: McpServer, env: Env, orgNamespace: string, partnerToken: string) {
@@ -50,6 +51,9 @@ export function registerAllTools(server: McpServer, env: Env, orgNamespace: stri
   registerAllSkillExampleTools(server, env);
   // kbdb-base §7.5.i: recipe 公庫/私庫工具（與 CLI 六能力對齊，rule 07 §5 MCP 不落後）
   registerAllRecipeTools(server, env);
+  // kbdb-base Phase 9.1: KBDB 資料層薄殼（template/record/query/search，HANDOFF §2）
+  // 鐵律：不提供建表/SQL tool，AI 只有 template+slot 可用（類 Supabase 萬用表）
+  registerAllKbdbDataTools(server, env);
   // §7.8 P1 D2: whoami（與 CLI acr whoami 對齊，AI 不繞 CLI 自己 curl 猜帳號）
   registerWhoami(server, env, orgNamespace);
 }
diff --git a/mcp/src/types.ts b/mcp/src/types.ts
index b5bfb72..a36a14f 100644
--- a/mcp/src/types.ts
+++ b/mcp/src/types.ts
@@ -9,6 +9,12 @@ export interface Env {
   // 設了會把 agent-feedback / agent-telemetry block 都寫到 platform user_id 下；
   // 沒設則 fallback 寫進 user 自己的 namespace
   PLATFORM_API_KEY?: string;
+  // Self-hosted 單租戶模式旗標（與 cypher-executor 同名同義）。
+  //   "false" = self-hosted：Bearer 帶的是 namespace 明碼（非平台 partner key），
+  //             不打 KBDB partner 驗證，直接當 org_namespace（對齊 cypher 的 opaque-key 模型）。
+  //   未設 / "true" = 官方 SaaS：維持 partner-key 驗證（行為完全不變）。
+  // SDD: sdk-and-website/mcp-account-source.md；HANDOFF §3b。
+  MULTI_TENANT?: string;
 }
 
 export interface ToolContext {
diff --git a/mcp/tests/unit/partner-auth.test.ts b/mcp/tests/unit/partner-auth.test.ts
index 69012cf..a2f37cc 100644
--- a/mcp/tests/unit/partner-auth.test.ts
+++ b/mcp/tests/unit/partner-auth.test.ts
@@ -40,3 +40,41 @@ describe("partner-auth: KBDB response validation", () => {
     expect(info.org_namespace).toBe("org-a");
   });
 });
+
+// HANDOFF §3b / mcp-account-source.md §5.5：self-hosted（MULTI_TENANT=false）下
+// Bearer 帶的是 namespace 明碼，不打 KBDB partner 驗證，直接當 org_namespace。
+// 與 cypher-executor 的 opaque-key 模型對齊（X-Arcrun-API-Key 不驗證直接當分區 key）。
+function resolveNamespace(
+  multiTenant: string | undefined,
+  token: string,
+  validatePartner: (t: string) => { valid: boolean; org_namespace: string },
+): { ok: boolean; org_namespace?: string } {
+  if (multiTenant === "false") {
+    // self-hosted：Bearer 明碼即 namespace，繞 partner 驗證
+    return { ok: true, org_namespace: token };
+  }
+  // SaaS：維持 partner-key 驗證（行為不變）
+  const info = validatePartner(token);
+  return info.valid ? { ok: true, org_namespace: info.org_namespace } : { ok: false };
+}
+
+describe("partner-auth: self-hosted (MULTI_TENANT=false) bypasses partner validation", () => {
+  const partnerValidatorThatAlwaysRejects = () => ({ valid: false, org_namespace: "" });
+
+  it("self-hosted: namespace 明碼直接當 org_namespace，不打 partner 驗證", () => {
+    const r = resolveNamespace("false", "leo", partnerValidatorThatAlwaysRejects);
+    expect(r.ok).toBe(true);
+    expect(r.org_namespace).toBe("leo");
+  });
+
+  it("SaaS (未設 MULTI_TENANT)：仍走 partner 驗證，明碼被擋", () => {
+    const r = resolveNamespace(undefined, "leo", partnerValidatorThatAlwaysRejects);
+    expect(r.ok).toBe(false);
+  });
+
+  it("SaaS：合法 partner key 通過並取 org_namespace", () => {
+    const r = resolveNamespace("true", "pk_live_x", () => ({ valid: true, org_namespace: "org-a" }));
+    expect(r.ok).toBe(true);
+    expect(r.org_namespace).toBe("org-a");
+  });
+});
diff --git a/mcp/wrangler.toml b/mcp/wrangler.toml
index dda37f7..dc13bfa 100644
--- a/mcp/wrangler.toml
+++ b/mcp/wrangler.toml
@@ -4,6 +4,15 @@ compatibility_date = "2024-11-27"
 compatibility_flags = [ "nodejs_compat" ]
 workers_dev = true   # 對齊 arcrun 部署慣例（rule 05）：deploy 掃描自動啟用 workers.dev URL
 
+# ── 租戶模式（self-hosted fork 必看）─────────────────────────────────────────────
+# 官方 SaaS：不設 MULTI_TENANT（預設多租戶）→ MCP 走 partner-key 驗證（pk_live）。
+# self-hosted 單租戶：fork 後設 MULTI_TENANT = "false" → MCP 接受 Bearer = namespace 明碼，
+#   不打 KBDB partner 驗證，直接當 org_namespace（與 cypher-executor 的 MULTI_TENANT=false 對齊）。
+#   self-hosted 用戶用 namespace 明碼即可連 MCP（不需平台 partner key）。
+# SDD: sdk-and-website/mcp-account-source.md（self-hosted 認證）；HANDOFF §3b。
+# [vars]
+# MULTI_TENANT = "false"
+
 # Service Bindings
 # 2026-05-07：COMPONENT_REGISTRY 從 inkstone-component-registry 改為 arcrun-registry
 # 原因：舊的 inkstone-component-registry 期望不同 query 參數名，MCP search 失敗。