@lumibase/mcp-server 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/index.cjs

@@ -16,6 +16,12 @@ var LumiBaseApiError = class extends Error {
   status;
   errors;
 };
+var McpUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpUnavailableError";
+  }
+};
 var LumiBaseClient = class {
   baseUrl;
   origin;
@@ -57,6 +63,40 @@ var LumiBaseClient = class {
   delete(path) {
     return this.request("DELETE", path);
   }
+  /**
+   * Sends a JSON-RPC request to the governed MCP endpoint (`POST /api/v1/mcp`).
+   *
+   * Deliberately NOT built on `request()`. That helper returns `json.data`,
+   * which is the REST envelope — a JSON-RPC response carries `result` / `error`
+   * at the top level and has no `data` key at all, so routing this through
+   * `request()` would quietly resolve to `undefined` for every call. The bug
+   * would look like "governance returned nothing" rather than "we read the wrong
+   * field".
+   *
+   * @throws {McpUnavailableError} when the site has not enabled `contentOs.mcp`.
+   * @throws {LumiBaseApiError} for transport/HTTP failures and JSON-RPC errors.
+   */
+  async jsonRpc(method, params) {
+    const res = await fetch(`${this.baseUrl}/mcp`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, ...params ? { params } : {} })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      const errors = body?.errors ?? [{ code: "UNKNOWN", message: `HTTP ${res.status}` }];
+      if (errors.some((e) => e.code === "MCP_DISABLED")) {
+        throw new McpUnavailableError(errors[0]?.message ?? "MCP endpoint disabled");
+      }
+      throw new LumiBaseApiError(res.status, errors);
+    }
+    if (body?.error) {
+      throw new LumiBaseApiError(res.status, [
+        { code: `JSONRPC_${body.error.code}`, message: body.error.message }
+      ]);
+    }
+    return body?.result;
+  }
   /**
    * GET a root-level (non-`/api/v1`) endpoint such as `/health` or `/metrics`
    * and return the raw response body as text. These endpoints are not
@@ -109,12 +149,6 @@ function configFromEnv() {
   return { url, siteId, token };
 }
 
-// src/tools/access.ts
-var import_zod3 = require("zod");
-
-// src/tools/_crud.ts
-var import_zod2 = require("zod");
-
 // src/tools/_shared.ts
 function formatError(err) {
   if (err instanceof LumiBaseApiError) {
@@ -154,6 +188,285 @@ async function run(fn) {
   }
 }
 var confirmDescription = "Must be true to confirm the destructive operation";
+var DECISION_STATUSES = /* @__PURE__ */ new Set(["executed", "pending_approval", "denied"]);
+function asGovernedDecision(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const status = value.status;
+  if (typeof status !== "string" || !DECISION_STATUSES.has(status)) return void 0;
+  return value;
+}
+function renderDecision(decision, executedText) {
+  if (decision.status === "executed") {
+    return decision.data === void 0 ? okText(executedText) : ok(decision.data);
+  }
+  if (decision.status === "pending_approval") {
+    const id = decision.agentApprovalId ?? decision.approvalId;
+    const space = decision.approvalSpace ?? (decision.agentApprovalId ? "agent" : id ? "legacy_ai" : void 0);
+    const endpoint = space === "agent" ? "POST /api/v1/agent/approvals/{approvalId}/decide" : space === "legacy_ai" ? "POST /api/v1/ai/approvals/{approvalId}/decide" : void 0;
+    const lines = [
+      "Not executed \u2014 pending approval.",
+      ...id ? [`Approval id: ${id}`] : [],
+      ...endpoint ? [`Decide at: ${endpoint}`] : [],
+      ...decision.runId ? [`Run: ${decision.runId}`] : [],
+      ...decision.message ? [decision.message] : []
+    ];
+    return okText(lines.join("\n"));
+  }
+  const reason = decision.code ? `[${decision.code}] ` : "";
+  return {
+    content: [{ type: "text", text: `Not executed \u2014 denied. ${reason}${decision.message ?? ""}`.trim() }],
+    isError: true
+  };
+}
+function okAfter(response, executedText) {
+  const decision = asGovernedDecision(response);
+  return decision === void 0 ? okText(executedText) : renderDecision(decision, executedText);
+}
+
+// src/governed.ts
+var GOVERNED_TOOLS = {
+  // ── items ────────────────────────────────────────────────────────────────
+  create_item: { skill: "createItem" },
+  update_item: { skill: "updateItem" },
+  delete_item: { skill: "deleteItem" },
+  // ── schema ───────────────────────────────────────────────────────────────
+  delete_collection: { skill: "deleteCollection" },
+  // `field_name` is this transport's name for the field; the skill reads `name`.
+  // Renamed explicitly rather than dropped (see repro R17).
+  delete_field: { skill: "deleteField", rename: { field_name: "name" } },
+  create_relation: { skill: "createRelation" },
+  delete_relation: { skill: "deleteRelation" },
+  // ── access ───────────────────────────────────────────────────────────────
+  delete_role: { skill: "deleteRole" },
+  delete_policy: { skill: "deletePolicy" },
+  // ── automation ───────────────────────────────────────────────────────────
+  delete_flow: { skill: "deleteFlow" },
+  run_flow: { skill: "runFlow" },
+  create_intent: { skill: "createIntent" },
+  delete_intent: { skill: "deleteIntent" },
+  // ── config ───────────────────────────────────────────────────────────────
+  upsert_setting: { skill: "upsertSetting" },
+  delete_setting: { skill: "deleteSetting" },
+  create_translation: { skill: "createTranslation" },
+  update_translation: { skill: "updateTranslation" },
+  delete_translation: { skill: "deleteTranslation" },
+  create_webhook: { skill: "createWebhook" },
+  update_webhook: { skill: "updateWebhook" },
+  delete_webhook: { skill: "deleteWebhook" },
+  // ── api keys / users / teams ──────────────────────────────────────────────
+  create_api_key: { skill: "createApiKey" },
+  rotate_api_key: { skill: "rotateApiKey" },
+  revoke_api_key: { skill: "revokeApiKey" },
+  invite_user: { skill: "inviteUser" },
+  update_user: { skill: "updateUser" },
+  remove_user: { skill: "removeUser" },
+  create_team: { skill: "createTeam" },
+  delete_team: { skill: "deleteTeam" },
+  // The team tools take the team as `id`; the skill names it `teamId` because it
+  // also takes a `userId` and one bare `id` would be ambiguous.
+  add_team_member: { skill: "addTeamMember", rename: { id: "teamId" } },
+  remove_team_member: { skill: "removeTeamMember", rename: { id: "teamId" } },
+  // ── extensions ───────────────────────────────────────────────────────────
+  uninstall_extension: { skill: "uninstallExtension" },
+  // ── cdc ──────────────────────────────────────────────────────────────────
+  // The change-feed skills name the subscription `subscriptionId` (as
+  // `getCdcSubscriptionStatus`/`replayCdcSubscription` do); the CRUD-generated
+  // stdio tool takes it as `id`, like every other `delete_*` tool.
+  // Known divergence, not a skipped gate: the harness builds `SubscriptionService`
+  // without `cache`/`audit`, so REST's `cdc_subscription_deleted` audit-log row
+  // and feed-flag cache eviction do not happen on this path. The run, tool-call
+  // and approval rows record the deletion instead, and the flag cache expires on
+  // its own TTL.
+  delete_cdc_subscription: { skill: "deleteCdcSubscription", rename: { id: "subscriptionId" } }
+};
+var UNGOVERNED_MUTATIONS = {
+  // Skill exists, but the canonical contract is narrower than what this tool
+  // advertises. Routing now would reject arguments callers legitimately send.
+  create_collection: "contract-narrower-than-tool: 16 advertised properties have no canonical counterpart",
+  create_policy: "contract-narrower-than-tool: enforceTfa/ipAllow/ipDeny/validFrom/validUntil",
+  create_role: "contract-narrower-than-tool: systemKey",
+  cdc_subscription_replay: "contract-narrower-than-tool: cursor has no canonical counterpart",
+  create_cdc_subscription: "contract-narrower-than-tool: payload_mode \u2014 the createCdcSubscription handler never forwards it, so a snapshot subscription would be created as reference",
+  // Skill and canonical contract both exist and accept the advertised arguments,
+  // but the skill's handler skips checks the REST route applies. Routing would
+  // add HITL and remove those checks, so these stay on REST until the handler
+  // carries them.
+  create_flow: "skill-weaker-than-rest: createFlow skips the active-graph validation and schedule-cron check of POST /flows and never sets nextRunAt, so an active schedule flow would never fire",
+  install_extension: "skill-weaker-than-rest: installExtension skips the bundle signature check, the reserved lumibase-* namespace check and the per-action extensions:* permission probes of POST /extensions",
+  update_extension: "skill-weaker-than-rest: updateExtension skips the per-action extensions:* permission probes, the unverified-official enable refusal, sandbox cache eviction and CDC subscription sync of PATCH /extensions/:id",
+  // No skill at all: nothing to route to. Listed so the set is closed.
+  add_policy_permission: "no-skill",
+  apply_access_import: "no-skill",
+  apply_schema: "no-skill",
+  approve_content: "no-skill",
+  assign_role_user: "no-skill",
+  attach_api_key_policy: "no-skill",
+  attach_api_key_role: "no-skill",
+  attach_policy_user: "no-skill",
+  attach_role_policy: "no-skill",
+  compile_intent: "no-skill",
+  create_preset: "no-skill",
+  create_release: "no-skill",
+  create_share: "no-skill",
+  delete_media: "no-skill",
+  delete_policy_permission: "no-skill",
+  delete_preset: "no-skill",
+  delete_release: "no-skill",
+  delete_tm: "no-skill",
+  detach_api_key_policy: "no-skill",
+  detach_api_key_role: "no-skill",
+  detach_policy_user: "no-skill",
+  detach_role_policy: "no-skill",
+  drop_materialization: "no-skill",
+  install_marketplace_extension: "no-skill",
+  publish_extension: "no-skill",
+  publish_release: "no-skill",
+  refresh_materialization: "no-skill",
+  reject_content: "no-skill",
+  remove_role_user: "no-skill",
+  restore_backup: "no-skill",
+  revoke_share: "no-skill",
+  run_panel: "no-skill",
+  submit_review: "no-skill",
+  translate_text: "no-skill",
+  update_cdc_subscription: "no-skill",
+  update_collection: "no-skill",
+  update_flow: "no-skill",
+  update_intent: "no-skill",
+  update_policy: "no-skill",
+  update_policy_permission: "no-skill",
+  update_preset: "no-skill",
+  update_release: "no-skill",
+  update_role: "no-skill",
+  update_team: "no-skill",
+  update_tm: "no-skill",
+  upsert_field: "no-skill",
+  upsert_tm: "no-skill"
+};
+var MUTATION_VERB = /^(create|update|delete|remove|upsert|set|add|attach|detach|revoke|rotate|invite|install|uninstall|enable|disable|publish|unpublish|promote|apply|run|trigger|restore|replay|drop|materialize|reset|assign|unassign|approve|reject|submit|claim|decide|import|veto|freeze|lift|seed|sync|purge|bump|stage|commit|schedule|cancel|retry|archive|clone|duplicate|move|rename|reorder|translate|compile|generate|refresh|configure)/;
+var MUTATION_EXCEPTIONS = /* @__PURE__ */ new Set(["cdc_subscription_replay"]);
+function isMutationTool(name) {
+  return MUTATION_EXCEPTIONS.has(name) || MUTATION_VERB.test(name);
+}
+var PROMPT_ONLY_ARGS = /* @__PURE__ */ new Set(["confirm"]);
+var camel = (key) => key.replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase());
+function toSkillArgs(args, binding) {
+  const out = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (PROMPT_ONLY_ARGS.has(key)) continue;
+    if (value === void 0) continue;
+    out[binding.rename?.[key] ?? camel(key)] = value;
+  }
+  return out;
+}
+function governedModeFromEnv(env = process.env) {
+  const raw = (env["LUMIBASE_MCP_GOVERNED"] ?? "auto").toLowerCase();
+  if (raw === "true" || raw === "on" || raw === "1") return "on";
+  if (raw === "false" || raw === "off" || raw === "0") return "off";
+  return "auto";
+}
+var GovernedDispatcher = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.mode = options.mode ?? governedModeFromEnv();
+    this.warn = options.warn ?? ((message) => console.error(message));
+  }
+  client;
+  mode;
+  warn;
+  available;
+  get enabled() {
+    return this.mode !== "off";
+  }
+  /**
+   * True when this deployment requires every mutation to go through governance.
+   *
+   * Read by the registration wrapper to refuse mutations that have no governed
+   * mapping. Without it, mode `on` only governed the 27 mapped tools and left the
+   * rest on REST — so the setting that exists to guarantee governance did not,
+   * and the guarantee failed silently for exactly the calls nobody had mapped
+   * yet.
+   */
+  get requiresGovernance() {
+    return this.mode === "on";
+  }
+  /**
+   * The refusal returned for a mutation that cannot be governed.
+   *
+   * Names the reason from {@link UNGOVERNED_MUTATIONS} when there is one, so the
+   * operator can tell "we know about this gap" from "nobody classified this tool".
+   */
+  refuseUngoverned(tool) {
+    const reason = UNGOVERNED_MUTATIONS[tool];
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Refused: "${tool}" changes state but has no governed mapping, and LUMIBASE_MCP_GOVERNED=on requires every mutation to run through the agent harness (autonomy levels, HITL approval, kill switch, run audit).
+` + (reason ? `Known gap: ${reason}.
+` : "This tool is in neither the governed nor the declared-ungoverned table, which means it was added without a governance decision.\n") + "Set LUMIBASE_MCP_GOVERNED=auto or off to accept ungoverned REST calls for it."
+        }
+      ],
+      isError: true
+    };
+  }
+  /** True when the governed endpoint answered a probe. */
+  probe() {
+    this.available ??= (async () => {
+      try {
+        await this.client.jsonRpc("tools/list");
+        return true;
+      } catch (err) {
+        if (this.mode === "on") return false;
+        this.warn(
+          err instanceof McpUnavailableError ? "[lumibase-mcp] governed tool calls unavailable: this site has contentOs.mcp disabled. Falling back to direct REST calls, which skip agent governance (autonomy levels, HITL approval, kill switch, run audit). Set LUMIBASE_MCP_GOVERNED=on to refuse instead of falling back." : `[lumibase-mcp] governed endpoint probe failed (${err instanceof Error ? err.message : String(err)}); falling back to direct REST calls, which skip agent governance. Set LUMIBASE_MCP_GOVERNED=on to refuse instead of falling back.`
+        );
+        return false;
+      }
+    })();
+    return this.available;
+  }
+  /**
+   * Runs `tool` through the harness.
+   *
+   * @returns the rendered tool result, or `undefined` when the caller should run
+   * its own REST handler instead (mode `auto` with governance unavailable).
+   */
+  async dispatch(tool, args, binding) {
+    if (!this.enabled) return void 0;
+    if (!await this.probe()) {
+      if (this.mode === "on") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Refused: "${tool}" must run through the governed harness, but this site has contentOs.mcp disabled. Enable it, or set LUMIBASE_MCP_GOVERNED=off to accept ungoverned REST calls.`
+            }
+          ],
+          isError: true
+        };
+      }
+      return void 0;
+    }
+    try {
+      const result = await this.client.jsonRpc("tools/call", { name: binding.skill, arguments: toSkillArgs(args, binding) });
+      const decision = asGovernedDecision(result?.structuredContent);
+      if (decision) return renderDecision(decision, `${tool} executed.`);
+      return {
+        content: result?.content ?? [{ type: "text", text: JSON.stringify(result ?? null, null, 2) }],
+        ...result?.isError === void 0 ? {} : { isError: result.isError }
+      };
+    } catch (err) {
+      return fail(err);
+    }
+  }
+};
+
+// src/tools/access.ts
+var import_zod3 = require("zod");
+
+// src/tools/_crud.ts
+var import_zod2 = require("zod");
 
 // src/tools/path.ts
 var import_zod = require("zod");
@@ -240,8 +553,8 @@ function registerCrud(server, client, opts) {
       async (args) => {
         const id = String(args[idParam]);
         return run(async () => {
-          await client.delete(`${basePath}/${encodePathSegment(id)}`);
-          return okText(`${resource} "${id}" deleted.`);
+          const response = await client.delete(`${basePath}/${encodePathSegment(id)}`);
+          return okAfter(response, `${resource} "${id}" deleted.`);
         });
       }
     );
@@ -313,8 +626,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, policyId }) => run(async () => {
-      await client.delete(`/roles/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
-      return okText(`Policy "${policyId}" detached from role "${id}".`);
+      const response = await client.delete(`/roles/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
+      return okAfter(response, `Policy "${policyId}" detached from role "${id}".`);
     })
   );
   server.registerTool(
@@ -336,8 +649,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/roles/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
-      return okText(`User "${userId}" removed from role "${id}".`);
+      const response = await client.delete(`/roles/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
+      return okAfter(response, `User "${userId}" removed from role "${id}".`);
     })
   );
   registerCrud(server, client, {
@@ -379,8 +692,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, permId }) => run(async () => {
-      await client.delete(`/policies/${encodePathSegment(id)}/permissions/${encodePathSegment(permId)}`);
-      return okText(`Permission "${permId}" deleted from policy "${id}".`);
+      const response = await client.delete(`/policies/${encodePathSegment(id)}/permissions/${encodePathSegment(permId)}`);
+      return okAfter(response, `Permission "${permId}" deleted from policy "${id}".`);
     })
   );
   server.registerTool(
@@ -407,8 +720,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/policies/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
-      return okText(`Policy "${id}" detached from user "${userId}".`);
+      const response = await client.delete(`/policies/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
+      return okAfter(response, `Policy "${id}" detached from user "${userId}".`);
     })
   );
   server.registerTool(
@@ -516,8 +829,8 @@ function registerAdminTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: import_zod4.z.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/materialize/${encodePathSegment(id)}`);
-      return okText(`Materialization "${id}" dropped.`);
+      const response = await client.delete(`/materialize/${encodePathSegment(id)}`);
+      return okAfter(response, `Materialization "${id}" dropped.`);
     })
   );
 }
@@ -693,8 +1006,8 @@ function registerApiKeyTools(server, client) {
       }
     },
     async ({ id, roleId }) => run(async () => {
-      await client.delete(`/api-keys/${encodePathSegment(id)}/roles/${encodePathSegment(roleId)}`);
-      return okText(`Role "${roleId}" detached from API key "${id}".`);
+      const response = await client.delete(`/api-keys/${encodePathSegment(id)}/roles/${encodePathSegment(roleId)}`);
+      return okAfter(response, `Role "${roleId}" detached from API key "${id}".`);
     })
   );
   server.registerTool(
@@ -721,8 +1034,8 @@ function registerApiKeyTools(server, client) {
       }
     },
     async ({ id, policyId }) => run(async () => {
-      await client.delete(`/api-keys/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
-      return okText(`Policy "${policyId}" detached from API key "${id}".`);
+      const response = await client.delete(`/api-keys/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
+      return okAfter(response, `Policy "${policyId}" detached from API key "${id}".`);
     })
   );
 }
@@ -914,8 +1227,8 @@ function registerCollectionTools(server, client) {
     },
     async ({ name, confirm: _ }) => {
       try {
-        await client.delete(`/collections/${encodePathSegment(name)}`);
-        return { content: [{ type: "text", text: `Collection "${name}" deleted.` }] };
+        const response = await client.delete(`/collections/${encodePathSegment(name)}`);
+        return okAfter(response, `Collection "${name}" deleted.`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError2(err)}` }], isError: true };
       }
@@ -1071,8 +1384,8 @@ function registerContentConfigTools(server, client) {
       }
     },
     async ({ key }) => run(async () => {
-      await client.delete(`/settings/${encodePathSegment(key)}`);
-      return okText(`Setting "${key}" deleted.`);
+      const response = await client.delete(`/settings/${encodePathSegment(key)}`);
+      return okAfter(response, `Setting "${key}" deleted.`);
     })
   );
 }
@@ -1235,8 +1548,8 @@ function registerExtensionTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: import_zod12.z.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/extensions/${encodePathSegment(id)}`);
-      return okText(`Extension "${id}" uninstalled.`);
+      const response = await client.delete(`/extensions/${encodePathSegment(id)}`);
+      return okAfter(response, `Extension "${id}" uninstalled.`);
     })
   );
   server.registerTool(
@@ -1392,12 +1705,10 @@ function registerFieldTools(server, client) {
     async ({ collection, field_name, force }) => {
       try {
         const qs = force ? "?force=true" : "";
-        await client.delete(
+        const response = await client.delete(
           `/collections/${encodePathSegment(collection)}/fields/${encodePathSegment(field_name)}${qs}`
         );
-        return {
-          content: [{ type: "text", text: `Field "${field_name}" deleted from "${collection}".` }]
-        };
+        return okAfter(response, `Field "${field_name}" deleted from "${collection}".`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError3(err)}` }], isError: true };
       }
@@ -1564,7 +1875,7 @@ function registerItemTools(server, client) {
     async ({ collection, data: itemData, status }) => {
       try {
         const data = await client.post(`/items/${encodePathSegment(collection)}`, {
-          ...itemData,
+          data: itemData,
           status
         });
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -1587,7 +1898,7 @@ function registerItemTools(server, client) {
       try {
         const data = await client.patch(
           `/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`,
-          itemData
+          { data: itemData }
         );
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       } catch (err) {
@@ -1607,8 +1918,10 @@ function registerItemTools(server, client) {
     },
     async ({ collection, id }) => {
       try {
-        await client.delete(`/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`);
-        return { content: [{ type: "text", text: `Item "${id}" deleted from "${collection}".` }] };
+        const response = await client.delete(
+          `/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`
+        );
+        return okAfter(response, `Item "${id}" deleted from "${collection}".`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError4(err)}` }], isError: true };
       }
@@ -1696,8 +2009,8 @@ function registerReleaseTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/releases/${encodePathSegment(id)}`);
-      return okText(`Release "${id}" deleted.`);
+      const response = await client.delete(`/releases/${encodePathSegment(id)}`);
+      return okAfter(response, `Release "${id}" deleted.`);
     })
   );
 }
@@ -1731,8 +2044,8 @@ function registerShareTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.post(`/shares/${encodePathSegment(id)}/revoke`, {});
-      return okText(`Share link "${id}" revoked.`);
+      const response = await client.post(`/shares/${encodePathSegment(id)}/revoke`, {});
+      return okAfter(response, `Share link "${id}" revoked.`);
     })
   );
 }
@@ -1841,8 +2154,8 @@ function registerRelationTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/relations/${encodePathSegment(id)}`);
-      return okText(`Relation "${id}" deleted.`);
+      const response = await client.delete(`/relations/${encodePathSegment(id)}`);
+      return okAfter(response, `Relation "${id}" deleted.`);
     })
   );
 }
@@ -1887,8 +2200,8 @@ function registerSearchMediaTools(server, client) {
       }
     },
     async ({ key }) => run(async () => {
-      await client.delete(`/media/${encodeMediaKey(key)}`);
-      return okText(`Media asset "${key}" deleted.`);
+      const response = await client.delete(`/media/${encodeMediaKey(key)}`);
+      return okAfter(response, `Media asset "${key}" deleted.`);
     })
   );
   server.registerTool(
@@ -1984,8 +2297,8 @@ function registerTranslationMemoryTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/tm/${encodePathSegment(id)}`);
-      return okText(`Translation-memory entry "${id}" deleted.`);
+      const response = await client.delete(`/tm/${encodePathSegment(id)}`);
+      return okAfter(response, `Translation-memory entry "${id}" deleted.`);
     })
   );
 }
@@ -2033,8 +2346,8 @@ function registerUsersTeamsTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: import_zod23.z.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/users/${encodePathSegment(id)}`);
-      return okText(`User "${id}" removed from the site.`);
+      const response = await client.delete(`/users/${encodePathSegment(id)}`);
+      return okAfter(response, `User "${id}" removed from the site.`);
     })
   );
   server.registerTool(
@@ -2074,8 +2387,8 @@ function registerUsersTeamsTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: import_zod23.z.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/teams/${encodePathSegment(id)}`);
-      return okText(`Team "${id}" deleted.`);
+      const response = await client.delete(`/teams/${encodePathSegment(id)}`);
+      return okAfter(response, `Team "${id}" deleted.`);
     })
   );
   server.registerTool(
@@ -2102,8 +2415,8 @@ function registerUsersTeamsTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/teams/${encodePathSegment(id)}/members/${encodePathSegment(userId)}`);
-      return okText(`User "${userId}" removed from team "${id}".`);
+      const response = await client.delete(`/teams/${encodePathSegment(id)}/members/${encodePathSegment(userId)}`);
+      return okAfter(response, `User "${userId}" removed from team "${id}".`);
     })
   );
 }
@@ -2132,7 +2445,33 @@ function registerWebhookTools(server, client) {
 }
 
 // src/tools/index.ts
-function registerAllTools(server, client) {
+function registerAllTools(server, client, options = {}) {
+  const dispatcher = options.dispatcher === void 0 ? new GovernedDispatcher(client) : options.dispatcher;
+  const target = dispatcher?.enabled ? withGovernedHandlers(server, dispatcher) : server;
+  registerModules(target, client);
+}
+function withGovernedHandlers(server, dispatcher) {
+  return new Proxy(server, {
+    get(t, prop, receiver) {
+      if (prop !== "registerTool") return Reflect.get(t, prop, receiver);
+      return (name, config, handler) => {
+        const binding = GOVERNED_TOOLS[name];
+        let wrapped = handler;
+        if (binding) {
+          wrapped = async (args) => await dispatcher.dispatch(name, args, binding) ?? await handler(args);
+        } else if (dispatcher.requiresGovernance && isMutationTool(name)) {
+          wrapped = async () => dispatcher.refuseUngoverned(name);
+        }
+        return t.registerTool(
+          name,
+          config,
+          wrapped
+        );
+      };
+    }
+  });
+}
+function registerModules(server, client) {
   registerCollectionTools(server, client);
   registerFieldTools(server, client);
   registerItemTools(server, client);

package/dist/index.js

@@ -15,6 +15,12 @@ var LumiBaseApiError = class extends Error {
   status;
   errors;
 };
+var McpUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpUnavailableError";
+  }
+};
 var LumiBaseClient = class {
   baseUrl;
   origin;
@@ -56,6 +62,40 @@ var LumiBaseClient = class {
   delete(path) {
     return this.request("DELETE", path);
   }
+  /**
+   * Sends a JSON-RPC request to the governed MCP endpoint (`POST /api/v1/mcp`).
+   *
+   * Deliberately NOT built on `request()`. That helper returns `json.data`,
+   * which is the REST envelope — a JSON-RPC response carries `result` / `error`
+   * at the top level and has no `data` key at all, so routing this through
+   * `request()` would quietly resolve to `undefined` for every call. The bug
+   * would look like "governance returned nothing" rather than "we read the wrong
+   * field".
+   *
+   * @throws {McpUnavailableError} when the site has not enabled `contentOs.mcp`.
+   * @throws {LumiBaseApiError} for transport/HTTP failures and JSON-RPC errors.
+   */
+  async jsonRpc(method, params) {
+    const res = await fetch(`${this.baseUrl}/mcp`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, ...params ? { params } : {} })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      const errors = body?.errors ?? [{ code: "UNKNOWN", message: `HTTP ${res.status}` }];
+      if (errors.some((e) => e.code === "MCP_DISABLED")) {
+        throw new McpUnavailableError(errors[0]?.message ?? "MCP endpoint disabled");
+      }
+      throw new LumiBaseApiError(res.status, errors);
+    }
+    if (body?.error) {
+      throw new LumiBaseApiError(res.status, [
+        { code: `JSONRPC_${body.error.code}`, message: body.error.message }
+      ]);
+    }
+    return body?.result;
+  }
   /**
    * GET a root-level (non-`/api/v1`) endpoint such as `/health` or `/metrics`
    * and return the raw response body as text. These endpoints are not
@@ -108,12 +148,6 @@ function configFromEnv() {
   return { url, siteId, token };
 }
 
-// src/tools/access.ts
-import { z as z3 } from "zod";
-
-// src/tools/_crud.ts
-import { z as z2 } from "zod";
-
 // src/tools/_shared.ts
 function formatError(err) {
   if (err instanceof LumiBaseApiError) {
@@ -153,6 +187,285 @@ async function run(fn) {
   }
 }
 var confirmDescription = "Must be true to confirm the destructive operation";
+var DECISION_STATUSES = /* @__PURE__ */ new Set(["executed", "pending_approval", "denied"]);
+function asGovernedDecision(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const status = value.status;
+  if (typeof status !== "string" || !DECISION_STATUSES.has(status)) return void 0;
+  return value;
+}
+function renderDecision(decision, executedText) {
+  if (decision.status === "executed") {
+    return decision.data === void 0 ? okText(executedText) : ok(decision.data);
+  }
+  if (decision.status === "pending_approval") {
+    const id = decision.agentApprovalId ?? decision.approvalId;
+    const space = decision.approvalSpace ?? (decision.agentApprovalId ? "agent" : id ? "legacy_ai" : void 0);
+    const endpoint = space === "agent" ? "POST /api/v1/agent/approvals/{approvalId}/decide" : space === "legacy_ai" ? "POST /api/v1/ai/approvals/{approvalId}/decide" : void 0;
+    const lines = [
+      "Not executed \u2014 pending approval.",
+      ...id ? [`Approval id: ${id}`] : [],
+      ...endpoint ? [`Decide at: ${endpoint}`] : [],
+      ...decision.runId ? [`Run: ${decision.runId}`] : [],
+      ...decision.message ? [decision.message] : []
+    ];
+    return okText(lines.join("\n"));
+  }
+  const reason = decision.code ? `[${decision.code}] ` : "";
+  return {
+    content: [{ type: "text", text: `Not executed \u2014 denied. ${reason}${decision.message ?? ""}`.trim() }],
+    isError: true
+  };
+}
+function okAfter(response, executedText) {
+  const decision = asGovernedDecision(response);
+  return decision === void 0 ? okText(executedText) : renderDecision(decision, executedText);
+}
+
+// src/governed.ts
+var GOVERNED_TOOLS = {
+  // ── items ────────────────────────────────────────────────────────────────
+  create_item: { skill: "createItem" },
+  update_item: { skill: "updateItem" },
+  delete_item: { skill: "deleteItem" },
+  // ── schema ───────────────────────────────────────────────────────────────
+  delete_collection: { skill: "deleteCollection" },
+  // `field_name` is this transport's name for the field; the skill reads `name`.
+  // Renamed explicitly rather than dropped (see repro R17).
+  delete_field: { skill: "deleteField", rename: { field_name: "name" } },
+  create_relation: { skill: "createRelation" },
+  delete_relation: { skill: "deleteRelation" },
+  // ── access ───────────────────────────────────────────────────────────────
+  delete_role: { skill: "deleteRole" },
+  delete_policy: { skill: "deletePolicy" },
+  // ── automation ───────────────────────────────────────────────────────────
+  delete_flow: { skill: "deleteFlow" },
+  run_flow: { skill: "runFlow" },
+  create_intent: { skill: "createIntent" },
+  delete_intent: { skill: "deleteIntent" },
+  // ── config ───────────────────────────────────────────────────────────────
+  upsert_setting: { skill: "upsertSetting" },
+  delete_setting: { skill: "deleteSetting" },
+  create_translation: { skill: "createTranslation" },
+  update_translation: { skill: "updateTranslation" },
+  delete_translation: { skill: "deleteTranslation" },
+  create_webhook: { skill: "createWebhook" },
+  update_webhook: { skill: "updateWebhook" },
+  delete_webhook: { skill: "deleteWebhook" },
+  // ── api keys / users / teams ──────────────────────────────────────────────
+  create_api_key: { skill: "createApiKey" },
+  rotate_api_key: { skill: "rotateApiKey" },
+  revoke_api_key: { skill: "revokeApiKey" },
+  invite_user: { skill: "inviteUser" },
+  update_user: { skill: "updateUser" },
+  remove_user: { skill: "removeUser" },
+  create_team: { skill: "createTeam" },
+  delete_team: { skill: "deleteTeam" },
+  // The team tools take the team as `id`; the skill names it `teamId` because it
+  // also takes a `userId` and one bare `id` would be ambiguous.
+  add_team_member: { skill: "addTeamMember", rename: { id: "teamId" } },
+  remove_team_member: { skill: "removeTeamMember", rename: { id: "teamId" } },
+  // ── extensions ───────────────────────────────────────────────────────────
+  uninstall_extension: { skill: "uninstallExtension" },
+  // ── cdc ──────────────────────────────────────────────────────────────────
+  // The change-feed skills name the subscription `subscriptionId` (as
+  // `getCdcSubscriptionStatus`/`replayCdcSubscription` do); the CRUD-generated
+  // stdio tool takes it as `id`, like every other `delete_*` tool.
+  // Known divergence, not a skipped gate: the harness builds `SubscriptionService`
+  // without `cache`/`audit`, so REST's `cdc_subscription_deleted` audit-log row
+  // and feed-flag cache eviction do not happen on this path. The run, tool-call
+  // and approval rows record the deletion instead, and the flag cache expires on
+  // its own TTL.
+  delete_cdc_subscription: { skill: "deleteCdcSubscription", rename: { id: "subscriptionId" } }
+};
+var UNGOVERNED_MUTATIONS = {
+  // Skill exists, but the canonical contract is narrower than what this tool
+  // advertises. Routing now would reject arguments callers legitimately send.
+  create_collection: "contract-narrower-than-tool: 16 advertised properties have no canonical counterpart",
+  create_policy: "contract-narrower-than-tool: enforceTfa/ipAllow/ipDeny/validFrom/validUntil",
+  create_role: "contract-narrower-than-tool: systemKey",
+  cdc_subscription_replay: "contract-narrower-than-tool: cursor has no canonical counterpart",
+  create_cdc_subscription: "contract-narrower-than-tool: payload_mode \u2014 the createCdcSubscription handler never forwards it, so a snapshot subscription would be created as reference",
+  // Skill and canonical contract both exist and accept the advertised arguments,
+  // but the skill's handler skips checks the REST route applies. Routing would
+  // add HITL and remove those checks, so these stay on REST until the handler
+  // carries them.
+  create_flow: "skill-weaker-than-rest: createFlow skips the active-graph validation and schedule-cron check of POST /flows and never sets nextRunAt, so an active schedule flow would never fire",
+  install_extension: "skill-weaker-than-rest: installExtension skips the bundle signature check, the reserved lumibase-* namespace check and the per-action extensions:* permission probes of POST /extensions",
+  update_extension: "skill-weaker-than-rest: updateExtension skips the per-action extensions:* permission probes, the unverified-official enable refusal, sandbox cache eviction and CDC subscription sync of PATCH /extensions/:id",
+  // No skill at all: nothing to route to. Listed so the set is closed.
+  add_policy_permission: "no-skill",
+  apply_access_import: "no-skill",
+  apply_schema: "no-skill",
+  approve_content: "no-skill",
+  assign_role_user: "no-skill",
+  attach_api_key_policy: "no-skill",
+  attach_api_key_role: "no-skill",
+  attach_policy_user: "no-skill",
+  attach_role_policy: "no-skill",
+  compile_intent: "no-skill",
+  create_preset: "no-skill",
+  create_release: "no-skill",
+  create_share: "no-skill",
+  delete_media: "no-skill",
+  delete_policy_permission: "no-skill",
+  delete_preset: "no-skill",
+  delete_release: "no-skill",
+  delete_tm: "no-skill",
+  detach_api_key_policy: "no-skill",
+  detach_api_key_role: "no-skill",
+  detach_policy_user: "no-skill",
+  detach_role_policy: "no-skill",
+  drop_materialization: "no-skill",
+  install_marketplace_extension: "no-skill",
+  publish_extension: "no-skill",
+  publish_release: "no-skill",
+  refresh_materialization: "no-skill",
+  reject_content: "no-skill",
+  remove_role_user: "no-skill",
+  restore_backup: "no-skill",
+  revoke_share: "no-skill",
+  run_panel: "no-skill",
+  submit_review: "no-skill",
+  translate_text: "no-skill",
+  update_cdc_subscription: "no-skill",
+  update_collection: "no-skill",
+  update_flow: "no-skill",
+  update_intent: "no-skill",
+  update_policy: "no-skill",
+  update_policy_permission: "no-skill",
+  update_preset: "no-skill",
+  update_release: "no-skill",
+  update_role: "no-skill",
+  update_team: "no-skill",
+  update_tm: "no-skill",
+  upsert_field: "no-skill",
+  upsert_tm: "no-skill"
+};
+var MUTATION_VERB = /^(create|update|delete|remove|upsert|set|add|attach|detach|revoke|rotate|invite|install|uninstall|enable|disable|publish|unpublish|promote|apply|run|trigger|restore|replay|drop|materialize|reset|assign|unassign|approve|reject|submit|claim|decide|import|veto|freeze|lift|seed|sync|purge|bump|stage|commit|schedule|cancel|retry|archive|clone|duplicate|move|rename|reorder|translate|compile|generate|refresh|configure)/;
+var MUTATION_EXCEPTIONS = /* @__PURE__ */ new Set(["cdc_subscription_replay"]);
+function isMutationTool(name) {
+  return MUTATION_EXCEPTIONS.has(name) || MUTATION_VERB.test(name);
+}
+var PROMPT_ONLY_ARGS = /* @__PURE__ */ new Set(["confirm"]);
+var camel = (key) => key.replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase());
+function toSkillArgs(args, binding) {
+  const out = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (PROMPT_ONLY_ARGS.has(key)) continue;
+    if (value === void 0) continue;
+    out[binding.rename?.[key] ?? camel(key)] = value;
+  }
+  return out;
+}
+function governedModeFromEnv(env = process.env) {
+  const raw = (env["LUMIBASE_MCP_GOVERNED"] ?? "auto").toLowerCase();
+  if (raw === "true" || raw === "on" || raw === "1") return "on";
+  if (raw === "false" || raw === "off" || raw === "0") return "off";
+  return "auto";
+}
+var GovernedDispatcher = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.mode = options.mode ?? governedModeFromEnv();
+    this.warn = options.warn ?? ((message) => console.error(message));
+  }
+  client;
+  mode;
+  warn;
+  available;
+  get enabled() {
+    return this.mode !== "off";
+  }
+  /**
+   * True when this deployment requires every mutation to go through governance.
+   *
+   * Read by the registration wrapper to refuse mutations that have no governed
+   * mapping. Without it, mode `on` only governed the 27 mapped tools and left the
+   * rest on REST — so the setting that exists to guarantee governance did not,
+   * and the guarantee failed silently for exactly the calls nobody had mapped
+   * yet.
+   */
+  get requiresGovernance() {
+    return this.mode === "on";
+  }
+  /**
+   * The refusal returned for a mutation that cannot be governed.
+   *
+   * Names the reason from {@link UNGOVERNED_MUTATIONS} when there is one, so the
+   * operator can tell "we know about this gap" from "nobody classified this tool".
+   */
+  refuseUngoverned(tool) {
+    const reason = UNGOVERNED_MUTATIONS[tool];
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Refused: "${tool}" changes state but has no governed mapping, and LUMIBASE_MCP_GOVERNED=on requires every mutation to run through the agent harness (autonomy levels, HITL approval, kill switch, run audit).
+` + (reason ? `Known gap: ${reason}.
+` : "This tool is in neither the governed nor the declared-ungoverned table, which means it was added without a governance decision.\n") + "Set LUMIBASE_MCP_GOVERNED=auto or off to accept ungoverned REST calls for it."
+        }
+      ],
+      isError: true
+    };
+  }
+  /** True when the governed endpoint answered a probe. */
+  probe() {
+    this.available ??= (async () => {
+      try {
+        await this.client.jsonRpc("tools/list");
+        return true;
+      } catch (err) {
+        if (this.mode === "on") return false;
+        this.warn(
+          err instanceof McpUnavailableError ? "[lumibase-mcp] governed tool calls unavailable: this site has contentOs.mcp disabled. Falling back to direct REST calls, which skip agent governance (autonomy levels, HITL approval, kill switch, run audit). Set LUMIBASE_MCP_GOVERNED=on to refuse instead of falling back." : `[lumibase-mcp] governed endpoint probe failed (${err instanceof Error ? err.message : String(err)}); falling back to direct REST calls, which skip agent governance. Set LUMIBASE_MCP_GOVERNED=on to refuse instead of falling back.`
+        );
+        return false;
+      }
+    })();
+    return this.available;
+  }
+  /**
+   * Runs `tool` through the harness.
+   *
+   * @returns the rendered tool result, or `undefined` when the caller should run
+   * its own REST handler instead (mode `auto` with governance unavailable).
+   */
+  async dispatch(tool, args, binding) {
+    if (!this.enabled) return void 0;
+    if (!await this.probe()) {
+      if (this.mode === "on") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Refused: "${tool}" must run through the governed harness, but this site has contentOs.mcp disabled. Enable it, or set LUMIBASE_MCP_GOVERNED=off to accept ungoverned REST calls.`
+            }
+          ],
+          isError: true
+        };
+      }
+      return void 0;
+    }
+    try {
+      const result = await this.client.jsonRpc("tools/call", { name: binding.skill, arguments: toSkillArgs(args, binding) });
+      const decision = asGovernedDecision(result?.structuredContent);
+      if (decision) return renderDecision(decision, `${tool} executed.`);
+      return {
+        content: result?.content ?? [{ type: "text", text: JSON.stringify(result ?? null, null, 2) }],
+        ...result?.isError === void 0 ? {} : { isError: result.isError }
+      };
+    } catch (err) {
+      return fail(err);
+    }
+  }
+};
+
+// src/tools/access.ts
+import { z as z3 } from "zod";
+
+// src/tools/_crud.ts
+import { z as z2 } from "zod";
 
 // src/tools/path.ts
 import { z } from "zod";
@@ -239,8 +552,8 @@ function registerCrud(server, client, opts) {
       async (args) => {
         const id = String(args[idParam]);
         return run(async () => {
-          await client.delete(`${basePath}/${encodePathSegment(id)}`);
-          return okText(`${resource} "${id}" deleted.`);
+          const response = await client.delete(`${basePath}/${encodePathSegment(id)}`);
+          return okAfter(response, `${resource} "${id}" deleted.`);
         });
       }
     );
@@ -312,8 +625,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, policyId }) => run(async () => {
-      await client.delete(`/roles/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
-      return okText(`Policy "${policyId}" detached from role "${id}".`);
+      const response = await client.delete(`/roles/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
+      return okAfter(response, `Policy "${policyId}" detached from role "${id}".`);
     })
   );
   server.registerTool(
@@ -335,8 +648,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/roles/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
-      return okText(`User "${userId}" removed from role "${id}".`);
+      const response = await client.delete(`/roles/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
+      return okAfter(response, `User "${userId}" removed from role "${id}".`);
     })
   );
   registerCrud(server, client, {
@@ -378,8 +691,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, permId }) => run(async () => {
-      await client.delete(`/policies/${encodePathSegment(id)}/permissions/${encodePathSegment(permId)}`);
-      return okText(`Permission "${permId}" deleted from policy "${id}".`);
+      const response = await client.delete(`/policies/${encodePathSegment(id)}/permissions/${encodePathSegment(permId)}`);
+      return okAfter(response, `Permission "${permId}" deleted from policy "${id}".`);
     })
   );
   server.registerTool(
@@ -406,8 +719,8 @@ function registerAccessTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/policies/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
-      return okText(`Policy "${id}" detached from user "${userId}".`);
+      const response = await client.delete(`/policies/${encodePathSegment(id)}/users/${encodePathSegment(userId)}`);
+      return okAfter(response, `Policy "${id}" detached from user "${userId}".`);
     })
   );
   server.registerTool(
@@ -515,8 +828,8 @@ function registerAdminTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: z4.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/materialize/${encodePathSegment(id)}`);
-      return okText(`Materialization "${id}" dropped.`);
+      const response = await client.delete(`/materialize/${encodePathSegment(id)}`);
+      return okAfter(response, `Materialization "${id}" dropped.`);
     })
   );
 }
@@ -692,8 +1005,8 @@ function registerApiKeyTools(server, client) {
       }
     },
     async ({ id, roleId }) => run(async () => {
-      await client.delete(`/api-keys/${encodePathSegment(id)}/roles/${encodePathSegment(roleId)}`);
-      return okText(`Role "${roleId}" detached from API key "${id}".`);
+      const response = await client.delete(`/api-keys/${encodePathSegment(id)}/roles/${encodePathSegment(roleId)}`);
+      return okAfter(response, `Role "${roleId}" detached from API key "${id}".`);
     })
   );
   server.registerTool(
@@ -720,8 +1033,8 @@ function registerApiKeyTools(server, client) {
       }
     },
     async ({ id, policyId }) => run(async () => {
-      await client.delete(`/api-keys/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
-      return okText(`Policy "${policyId}" detached from API key "${id}".`);
+      const response = await client.delete(`/api-keys/${encodePathSegment(id)}/policies/${encodePathSegment(policyId)}`);
+      return okAfter(response, `Policy "${policyId}" detached from API key "${id}".`);
     })
   );
 }
@@ -913,8 +1226,8 @@ function registerCollectionTools(server, client) {
     },
     async ({ name, confirm: _ }) => {
       try {
-        await client.delete(`/collections/${encodePathSegment(name)}`);
-        return { content: [{ type: "text", text: `Collection "${name}" deleted.` }] };
+        const response = await client.delete(`/collections/${encodePathSegment(name)}`);
+        return okAfter(response, `Collection "${name}" deleted.`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError2(err)}` }], isError: true };
       }
@@ -1070,8 +1383,8 @@ function registerContentConfigTools(server, client) {
       }
     },
     async ({ key }) => run(async () => {
-      await client.delete(`/settings/${encodePathSegment(key)}`);
-      return okText(`Setting "${key}" deleted.`);
+      const response = await client.delete(`/settings/${encodePathSegment(key)}`);
+      return okAfter(response, `Setting "${key}" deleted.`);
     })
   );
 }
@@ -1234,8 +1547,8 @@ function registerExtensionTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: z12.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/extensions/${encodePathSegment(id)}`);
-      return okText(`Extension "${id}" uninstalled.`);
+      const response = await client.delete(`/extensions/${encodePathSegment(id)}`);
+      return okAfter(response, `Extension "${id}" uninstalled.`);
     })
   );
   server.registerTool(
@@ -1391,12 +1704,10 @@ function registerFieldTools(server, client) {
     async ({ collection, field_name, force }) => {
       try {
         const qs = force ? "?force=true" : "";
-        await client.delete(
+        const response = await client.delete(
           `/collections/${encodePathSegment(collection)}/fields/${encodePathSegment(field_name)}${qs}`
         );
-        return {
-          content: [{ type: "text", text: `Field "${field_name}" deleted from "${collection}".` }]
-        };
+        return okAfter(response, `Field "${field_name}" deleted from "${collection}".`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError3(err)}` }], isError: true };
       }
@@ -1563,7 +1874,7 @@ function registerItemTools(server, client) {
     async ({ collection, data: itemData, status }) => {
       try {
         const data = await client.post(`/items/${encodePathSegment(collection)}`, {
-          ...itemData,
+          data: itemData,
           status
         });
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -1586,7 +1897,7 @@ function registerItemTools(server, client) {
       try {
         const data = await client.patch(
           `/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`,
-          itemData
+          { data: itemData }
         );
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
       } catch (err) {
@@ -1606,8 +1917,10 @@ function registerItemTools(server, client) {
     },
     async ({ collection, id }) => {
       try {
-        await client.delete(`/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`);
-        return { content: [{ type: "text", text: `Item "${id}" deleted from "${collection}".` }] };
+        const response = await client.delete(
+          `/items/${encodePathSegment(collection)}/${encodePathSegment(id)}`
+        );
+        return okAfter(response, `Item "${id}" deleted from "${collection}".`);
       } catch (err) {
         return { content: [{ type: "text", text: `Error: ${formatError4(err)}` }], isError: true };
       }
@@ -1695,8 +2008,8 @@ function registerReleaseTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/releases/${encodePathSegment(id)}`);
-      return okText(`Release "${id}" deleted.`);
+      const response = await client.delete(`/releases/${encodePathSegment(id)}`);
+      return okAfter(response, `Release "${id}" deleted.`);
     })
   );
 }
@@ -1730,8 +2043,8 @@ function registerShareTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.post(`/shares/${encodePathSegment(id)}/revoke`, {});
-      return okText(`Share link "${id}" revoked.`);
+      const response = await client.post(`/shares/${encodePathSegment(id)}/revoke`, {});
+      return okAfter(response, `Share link "${id}" revoked.`);
     })
   );
 }
@@ -1840,8 +2153,8 @@ function registerRelationTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/relations/${encodePathSegment(id)}`);
-      return okText(`Relation "${id}" deleted.`);
+      const response = await client.delete(`/relations/${encodePathSegment(id)}`);
+      return okAfter(response, `Relation "${id}" deleted.`);
     })
   );
 }
@@ -1886,8 +2199,8 @@ function registerSearchMediaTools(server, client) {
       }
     },
     async ({ key }) => run(async () => {
-      await client.delete(`/media/${encodeMediaKey(key)}`);
-      return okText(`Media asset "${key}" deleted.`);
+      const response = await client.delete(`/media/${encodeMediaKey(key)}`);
+      return okAfter(response, `Media asset "${key}" deleted.`);
     })
   );
   server.registerTool(
@@ -1983,8 +2296,8 @@ function registerTranslationMemoryTools(server, client) {
       }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/tm/${encodePathSegment(id)}`);
-      return okText(`Translation-memory entry "${id}" deleted.`);
+      const response = await client.delete(`/tm/${encodePathSegment(id)}`);
+      return okAfter(response, `Translation-memory entry "${id}" deleted.`);
     })
   );
 }
@@ -2032,8 +2345,8 @@ function registerUsersTeamsTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: z23.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/users/${encodePathSegment(id)}`);
-      return okText(`User "${id}" removed from the site.`);
+      const response = await client.delete(`/users/${encodePathSegment(id)}`);
+      return okAfter(response, `User "${id}" removed from the site.`);
     })
   );
   server.registerTool(
@@ -2073,8 +2386,8 @@ function registerUsersTeamsTools(server, client) {
       inputSchema: { id: idPathSegmentSchema, confirm: z23.literal(true).describe(confirmDescription) }
     },
     async ({ id }) => run(async () => {
-      await client.delete(`/teams/${encodePathSegment(id)}`);
-      return okText(`Team "${id}" deleted.`);
+      const response = await client.delete(`/teams/${encodePathSegment(id)}`);
+      return okAfter(response, `Team "${id}" deleted.`);
     })
   );
   server.registerTool(
@@ -2101,8 +2414,8 @@ function registerUsersTeamsTools(server, client) {
       }
     },
     async ({ id, userId }) => run(async () => {
-      await client.delete(`/teams/${encodePathSegment(id)}/members/${encodePathSegment(userId)}`);
-      return okText(`User "${userId}" removed from team "${id}".`);
+      const response = await client.delete(`/teams/${encodePathSegment(id)}/members/${encodePathSegment(userId)}`);
+      return okAfter(response, `User "${userId}" removed from team "${id}".`);
     })
   );
 }
@@ -2131,7 +2444,33 @@ function registerWebhookTools(server, client) {
 }
 
 // src/tools/index.ts
-function registerAllTools(server, client) {
+function registerAllTools(server, client, options = {}) {
+  const dispatcher = options.dispatcher === void 0 ? new GovernedDispatcher(client) : options.dispatcher;
+  const target = dispatcher?.enabled ? withGovernedHandlers(server, dispatcher) : server;
+  registerModules(target, client);
+}
+function withGovernedHandlers(server, dispatcher) {
+  return new Proxy(server, {
+    get(t, prop, receiver) {
+      if (prop !== "registerTool") return Reflect.get(t, prop, receiver);
+      return (name, config, handler) => {
+        const binding = GOVERNED_TOOLS[name];
+        let wrapped = handler;
+        if (binding) {
+          wrapped = async (args) => await dispatcher.dispatch(name, args, binding) ?? await handler(args);
+        } else if (dispatcher.requiresGovernance && isMutationTool(name)) {
+          wrapped = async () => dispatcher.refuseUngoverned(name);
+        }
+        return t.registerTool(
+          name,
+          config,
+          wrapped
+        );
+      };
+    }
+  });
+}
+function registerModules(server, client) {
   registerCollectionTools(server, client);
   registerFieldTools(server, client);
   registerItemTools(server, client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumibase/mcp-server",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "description": "LumiBase MCP server — lets AI assistants manage the full LumiBase Content OS: collections, fields, items, relations, RBAC (roles/policies/permissions/API keys), users & teams, intents, flows, webhooks, translations & translation memory, search, media & transform presets, read-only insights, presets, editorial workflow, content releases, share links, read-only deployments, extensions, and site administration.",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,13 +27,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.6.2",
     "tsup": "^8.5.1",
     "typescript": "^5.6.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "files": [
     "dist"