@exposify/supabase 0.3.11 → 0.3.13

package/README.md

@@ -28,12 +28,15 @@ npx @exposify/supabase init
 
 This is safe to re-run; see "Re-running `init`" below. It writes:
 
-- `supabase/migrations/<timestamp>_exposify_meta.sql` — a SQL migration that
+- `supabase/migrations/<timestamp>_exposify_meta_v2.sql` — a SQL migration that
   adds `exposify_meta()`, a `SECURITY DEFINER` function returning, per table,
-  whether RLS is enabled and any `COMMENT ON TABLE`/`COMMENT ON COLUMN` text
+  whether RLS is enabled, what the `authenticated` role is granted on it
+  (select/insert/update/delete), and any `COMMENT ON TABLE`/`COMMENT ON COLUMN` text
   you've written. It only ever returns catalog metadata (table/column names,
   flags, comments) — never row data — which is what makes it safe to grant
-  to `anon`/`authenticated` and call with a low-privilege key.
+  to `anon`/`authenticated` and call with a low-privilege key. A project with
+  the older `<timestamp>_exposify_meta.sql` (no grants) gets the `_v2` one on
+  the next `init`, which replaces the function.
 - `supabase/functions/mcp/index.ts` — the edge function itself. `init` owns
   the part between `// exposify:begin` and `// exposify:end` (imports and a
   `generated` options object). Everything after that is yours, starting with
@@ -204,9 +207,14 @@ swaps in on each request, and it stops working when it expires.
 ## 2. Decide what's exposed
 
 **Every RLS-enabled table is automatically readable.** A table only shows up
-at all if `exposify_meta()` reports RLS is turned on for it *and* PostgREST
-actually exposes it (the calling role has grants) — an RLS-less table is
-invisible, full stop, with no override. For each exposed table you get a
+at all if `exposify_meta()` reports RLS is turned on for it *and* the
+`authenticated` role has `SELECT` on it — an RLS-less table is
+invisible, full stop, with no override. RLS decides which rows; the grant
+decides whether the role can touch the table at all, and without it every
+call answers 403. Newer Supabase local images no longer grant `anon` and
+`authenticated` on new tables in `public`, so check with `doctor`, which
+prints the `grant` to run. A write you opt into below only becomes a tool
+when the role is granted that operation too. For each exposed table you get a
 `query_<table>` tool: typed filters (`eq`/`neq`/`gt`/`lt`/`like`), a `select`
 column list, `order`, and a `limit` capped server-side (100 rows by default,
 regardless of what the caller asks for).
@@ -244,9 +252,13 @@ Deno.serve(aiReady({
 ```
 
 Notes:
-- `update_<table>` and `delete_<table>` always require at least one filter —
-  there is no way to opt into a table-wide mutation, even where RLS would
-  technically allow it.
+- `update_<table>` and `delete_<table>` change one row: the filter must
+  include `eq` on every primary-key column (more filters only narrow it).
+  A filter that happens to match everything (`id neq -1`, `item like %`) is
+  refused, and there is no way to opt into a table-wide mutation, even where
+  RLS would technically allow it; an agent that means to change several rows
+  makes one call per row. A table without a primary key gets `insert_<table>`
+  but no update or delete tools (the cold-start log and `doctor` say so).
 - Column/table descriptions shown to the agent come from SQL comments
   (`COMMENT ON TABLE orders IS '...'`, `COMMENT ON COLUMN orders.status IS
   '...'`) — write these once and every generated tool reads them.
@@ -343,8 +355,11 @@ exits 1 if anything failed, so you can run it in CI.
   that `verify_jwt = false` for `mcp`.
 - **Database:** `exposify_meta()` is applied and the PostgREST schema is
   readable. It lists which tables became tools, and warns about tables that
-  never will: RLS off, or RLS on but no API grants. It also warns about
-  tables whose missing comments leave tools with thin descriptions.
+  never will: RLS off, or RLS on but no `SELECT` for `authenticated` (with the
+  `grant` to run). It warns about writes in the function's config the role
+  isn't granted, about the older `exposify_meta()` that doesn't report
+  grants, and about tables whose missing comments leave tools with thin
+  descriptions.
 - **Deployed function:** speaks MCP to `<project>/functions/v1/mcp`
   (`initialize`, then `tools/list`) and reports the tool count. If the
   function registered `exposify://diagnostics`, which it only does when

package/dist/cli.js

@@ -99,6 +99,8 @@ function introspectTables(openapi, metaRows) {
     const rlsEnabled = rows[0].rls_enabled;
     if (!rlsEnabled) continue;
     if (!exposedInOpenApi.has(name)) continue;
+    const grants = grantsOf(rows[0]);
+    if (grants && !grants.select) continue;
     const openApiColumns = new Map(columnsFromOpenApi(openapi, name).map((c) => [c.name, c]));
     const columns = [];
     for (const row of rows) {
@@ -116,11 +118,21 @@ function introspectTables(openapi, metaRows) {
       name,
       rlsEnabled: true,
       description: rows[0].table_comment ?? void 0,
-      columns
+      columns,
+      ...grants ? { grants } : {}
     });
   }
   return tables.sort((a, b) => a.name.localeCompare(b.name));
 }
+function grantsOf(row) {
+  if (typeof row.can_select !== "boolean") return void 0;
+  return {
+    select: row.can_select,
+    insert: row.can_insert === true,
+    update: row.can_update === true,
+    delete: row.can_delete === true
+  };
+}
 function groupByTable(rows) {
   const map = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -528,6 +540,53 @@ function configsEqual(a, b) {
   return sameSet(a.writes, b.writes) && sameSet(a.rpc, b.rpc) && a.anonymousSignIn === b.anonymousSignIn && a.broker === null === (b.broker === null) && a.broker?.brokerUrl === b.broker?.brokerUrl && a.oauth === b.oauth;
 }
 
+// src/config.ts
+var WRITE_OPS = ["insert", "update", "delete"];
+function parseWrites(writes = []) {
+  const grants = /* @__PURE__ */ new Map();
+  for (const entry of writes) {
+    const [table, op] = entry.split(".");
+    if (!table || !op) {
+      warnOnce(`ignoring malformed writes entry "${entry}" (expected "<table>.insert|update|delete|*")`);
+      continue;
+    }
+    const ops = op === "*" ? WRITE_OPS : isWriteOp(op) ? [op] : null;
+    if (!ops) {
+      warnOnce(`ignoring writes entry "${entry}": "${op}" is not insert, update, delete, or *`);
+      continue;
+    }
+    const set = grants.get(table) ?? /* @__PURE__ */ new Set();
+    for (const o of ops) set.add(o);
+    grants.set(table, set);
+  }
+  return grants;
+}
+function isWriteOp(op) {
+  return WRITE_OPS.includes(op);
+}
+var warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+  if (warned.has(message)) return;
+  warned.add(message);
+  try {
+    console.warn(`[@exposify/supabase] ${message}`);
+  } catch {
+  }
+}
+function writeToolOps(table, opted) {
+  const ops = [];
+  const ungranted = [];
+  const keyless = [];
+  const hasKey = table.columns.some((c) => c.isPrimaryKey);
+  for (const op of WRITE_OPS) {
+    if (!opted?.has(op)) continue;
+    if (table.grants && !table.grants[op]) ungranted.push(op);
+    else if (op !== "insert" && !hasKey) keyless.push(op);
+    else ops.push(op);
+  }
+  return { ops, ungranted, keyless };
+}
+
 // bin/doctor.ts
 var FUNCTION_NAME = "mcp";
 var FUNCTION_PATH = `supabase/functions/${FUNCTION_NAME}/index.ts`;
@@ -576,6 +635,17 @@ function invisibleTables(metaRows, exposed) {
   }
   return { rlsOff, notGranted };
 }
+function unavailableWrites(exposed, writes) {
+  const opted = parseWrites(writes);
+  const ungranted = [];
+  const keyless = [];
+  for (const table of exposed) {
+    const why = writeToolOps(table, opted.get(table.name));
+    for (const op of why.ungranted) ungranted.push({ table: table.name, op });
+    for (const op of why.keyless) keyless.push({ table: table.name, op });
+  }
+  return { ungranted, keyless };
+}
 function parseJsonRpcResponse(contentType, body, id) {
   const candidates = contentType.includes("text/event-stream") ? body.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()) : [body];
   for (const raw of candidates) {
@@ -670,9 +740,15 @@ async function runDoctor(deps) {
   );
   sections.push({ title: "Project", checks: project });
   const files = [];
-  const migration = findExistingMigration(await deps.listDir(MIGRATIONS_DIR), "_exposify_meta.sql");
+  const migrations = await deps.listDir(MIGRATIONS_DIR);
+  const migration = findExistingMigration(migrations, "_exposify_meta_v2.sql");
+  const legacyMigration = findExistingMigration(migrations, "_exposify_meta.sql");
   files.push(
-    migration ? { status: "pass", message: `migration ${MIGRATIONS_DIR}/${migration}` } : { status: "fail", message: "no *_exposify_meta.sql migration", fix: "npx @exposify/supabase init" }
+    migration ? { status: "pass", message: `migration ${MIGRATIONS_DIR}/${migration}` } : legacyMigration ? {
+      status: "warn",
+      message: `migration ${MIGRATIONS_DIR}/${legacyMigration} is the older exposify_meta(), which doesn't report grants`,
+      fix: "npx @exposify/supabase init (it adds *_exposify_meta_v2.sql), then supabase db push"
+    } : { status: "fail", message: "no *_exposify_meta_v2.sql migration", fix: "npx @exposify/supabase init" }
   );
   const functionSource = await deps.readText(FUNCTION_PATH);
   const authMode = functionSource === null ? null : detectAuthMode(functionSource);
@@ -718,6 +794,13 @@ async function runDoctor(deps) {
     } else {
       const tableCount = new Set(meta.value.map((r) => r.table_name)).size;
       db.push({ status: "pass", message: `exposify_meta() applied (${tableCount} table(s) in the catalog)` });
+      if (meta.value.length > 0 && grantsOf(meta.value[0]) === void 0) {
+        db.push({
+          status: "warn",
+          message: "exposify_meta() in the database is the older one: it doesn't report grants, so tables agents can't read are still listed as tools",
+          fix: "npx @exposify/supabase init, then supabase db push"
+        });
+      }
     }
     if (openapi.status === "rejected") {
       const reason = openapi.reason instanceof Error ? openapi.reason.message : String(openapi.reason);
@@ -727,10 +810,14 @@ async function runDoctor(deps) {
     }
     if (openapi.status === "fulfilled" && meta.status === "fulfilled") {
       const tables = introspectTables(openapi.value, meta.value);
+      const { rlsOff, notGranted } = invisibleTables(meta.value, tables);
       db.push(
-        tables.length > 0 ? { status: "pass", message: `${tables.length} table(s) exposed as tools: ${tables.map((t) => t.name).join(", ")}` } : { status: "warn", message: "no tables exposed (none have RLS on and API grants)", fix: "enable RLS on the tables agents should read" }
+        tables.length > 0 ? { status: "pass", message: `${tables.length} table(s) exposed as tools: ${tables.map((t) => t.name).join(", ")}` } : {
+          status: "warn",
+          message: "no tables exposed (none have RLS on and API grants)",
+          fix: notGranted.length > 0 ? "grant the authenticated role access (below)" : "enable RLS on the tables agents should read"
+        }
       );
-      const { rlsOff, notGranted } = invisibleTables(meta.value, tables);
       if (rlsOff.length > 0) {
         db.push({
           status: "warn",
@@ -741,8 +828,23 @@ async function runDoctor(deps) {
       if (notGranted.length > 0) {
         db.push({
           status: "warn",
-          message: `RLS on but not exposed by PostgREST (no API role grants): ${notGranted.join(", ")}`,
-          fix: "grant select on <name> to authenticated;"
+          message: `RLS on, but the authenticated role can't read them, so they aren't tools: ${notGranted.join(", ")}`,
+          fix: notGranted.map((t) => `grant select on public.${t} to authenticated;`).join(" ")
+        });
+      }
+      const { ungranted, keyless } = functionSource === null ? { ungranted: [], keyless: [] } : unavailableWrites(tables, parseFunctionFile(functionSource).config.writes);
+      if (keyless.length > 0) {
+        db.push({
+          status: "warn",
+          message: `writes in the function's config on tables without a primary key, so they aren't tools (an update or delete must name its row by key): ${keyless.map((w) => `${w.table}.${w.op}`).join(", ")}`,
+          fix: "add a primary key to the table"
+        });
+      }
+      if (ungranted.length > 0) {
+        db.push({
+          status: "warn",
+          message: `writes in the function's config the authenticated role isn't granted, so they aren't tools: ${ungranted.map((w) => `${w.table}.${w.op}`).join(", ")}`,
+          fix: ungranted.map((w) => `grant ${w.op} on public.${w.table} to authenticated;`).join(" ")
         });
       }
       const undocumented = tablesMissingDocs(tables).filter((t) => t.missingTableComment || t.columnsWithoutComments.length > 0);
@@ -898,7 +1000,8 @@ var FUNCTION_DIR = "supabase/functions/mcp";
 var FUNCTION_PATH2 = `${FUNCTION_DIR}/index.ts`;
 var MIGRATIONS_DIR2 = "supabase/migrations";
 var CONFIG_TOML2 = "supabase/config.toml";
-var META_SUFFIX = "_exposify_meta.sql";
+var META_SUFFIX = "_exposify_meta_v2.sql";
+var LEGACY_META_SUFFIX = "_exposify_meta.sql";
 var COMMENTS_SUFFIX = "_exposify_comments.sql";
 function authLabel(config) {
   return config.broker ? "hosted broker" : config.oauth ? "Supabase Auth OAuth" : "user JWT";
@@ -933,7 +1036,7 @@ function planInit(input) {
     changes.push({
       path: `${MIGRATIONS_DIR2}/${name}`,
       action: "create",
-      summary: "exposify_meta() migration",
+      summary: findExistingMigration(input.migrations, LEGACY_META_SUFFIX) ? "exposify_meta() update: it also reports the authenticated role's grants" : "exposify_meta() migration",
       content: input.metaMigrationSql,
       effect: "push"
     });
@@ -1049,14 +1152,10 @@ function staleFunctionReason(probe, config, exposedTables) {
     return config.oauth ? "the gateway still checks JWTs for the function, so MCP clients never get the login challenge (deploy with --no-verify-jwt)." : "the gateway still checks JWTs for the function, so broker tokens are rejected (deploy with --no-verify-jwt).";
   }
   if (probe.kind !== "ok" || !exposedTables) return null;
-  const exposed = new Set(exposedTables.map((t) => t.name));
+  const opted = parseWrites(config.writes);
   const expected = /* @__PURE__ */ new Set();
-  for (const w of config.writes) {
-    const dot = w.lastIndexOf(".");
-    const table = w.slice(0, dot);
-    if (!exposed.has(table)) continue;
-    const op = w.slice(dot + 1);
-    for (const o of op === "*" ? ["insert", "update", "delete"] : [op]) expected.add(`${o}_${sanitizeIdentifier(table)}`);
+  for (const table of exposedTables) {
+    for (const op of writeToolOps(table, opted.get(table.name)).ops) expected.add(`${op}_${sanitizeIdentifier(table.name)}`);
   }
   for (const fn of config.rpc) expected.add(`rpc_${sanitizeIdentifier(fn)}`);
   const live = new Set(probe.tools.filter((t) => /^(insert|update|delete|rpc)_/.test(t)));
@@ -1072,7 +1171,7 @@ function liveVerdict(s) {
   let deploy = false;
   if (s.migrationApplied === false) {
     push = true;
-    notes.push("exposify_meta() isn't in the database yet (migration not pushed).");
+    notes.push("the exposify_meta() migration isn't in the database yet (not pushed).");
   }
   if (s.pendingComments.length > 0) {
     push = true;
@@ -1261,7 +1360,8 @@ async function tryIntrospect(conn) {
       fetchOpenApi(postgrestUrl, headers, fetchWithTimeout),
       fetchExposifyMeta(postgrestUrl, headers, fetchWithTimeout)
     ]);
-    return { introspection: { tables: introspectTables(openapi, metaRows), openapi }, migrationApplied: true };
+    const current = metaRows.length === 0 || grantsOf(metaRows[0]) !== void 0;
+    return { introspection: { tables: introspectTables(openapi, metaRows), openapi }, migrationApplied: current };
   } catch (err) {
     if (err instanceof MissingExposifyMetaError) return { introspection: null, migrationApplied: false };
     console.log(`

package/dist/index.cjs

@@ -131,6 +131,22 @@ function resolveSupabaseConfig(options = {}, hostedBroker2 = false) {
     rateWindowMs: options.rateWindowMs
   };
 }
+function writeToolOps(table, opted) {
+  const ops = [];
+  const ungranted = [];
+  const keyless = [];
+  const hasKey = table.columns.some((c) => c.isPrimaryKey);
+  for (const op of WRITE_OPS) {
+    if (!opted?.has(op)) continue;
+    if (table.grants && !table.grants[op]) ungranted.push(op);
+    else if (op !== "insert" && !hasKey) keyless.push(op);
+    else ops.push(op);
+  }
+  return { ops, ungranted, keyless };
+}
+function writeTools(table, cfg) {
+  return writeToolOps(table, cfg.writes.get(table.name));
+}
 
 // src/postgrest-client.ts
 var FORWARDED_HEADERS = ["authorization", "apikey"];
@@ -275,6 +291,8 @@ function introspectTables(openapi, metaRows) {
     const rlsEnabled = rows[0].rls_enabled;
     if (!rlsEnabled) continue;
     if (!exposedInOpenApi.has(name)) continue;
+    const grants = grantsOf(rows[0]);
+    if (grants && !grants.select) continue;
     const openApiColumns = new Map(columnsFromOpenApi(openapi, name).map((c) => [c.name, c]));
     const columns = [];
     for (const row of rows) {
@@ -292,11 +310,21 @@ function introspectTables(openapi, metaRows) {
       name,
       rlsEnabled: true,
       description: rows[0].table_comment ?? void 0,
-      columns
+      columns,
+      ...grants ? { grants } : {}
     });
   }
   return tables.sort((a, b) => a.name.localeCompare(b.name));
 }
+function grantsOf(row) {
+  if (typeof row.can_select !== "boolean") return void 0;
+  return {
+    select: row.can_select,
+    insert: row.can_insert === true,
+    update: row.can_update === true,
+    delete: row.can_delete === true
+  };
+}
 function groupByTable(rows) {
   const map = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -366,9 +394,16 @@ function buildQueryString(args, maxRows) {
   params.set("limit", String(limit));
   return params.toString();
 }
-function requireFilter(filter) {
-  if (!filter || filter.length === 0) {
-    throw new Error("At least one filter is required -- refusing a table-wide update/delete.");
+function requireKeyFilter(filter, keyColumns2) {
+  if (keyColumns2.length === 0) {
+    throw new Error("This table has no primary key, so a single row can't be named -- refusing the update/delete.");
+  }
+  const pinned = new Set((filter ?? []).filter((f) => f.op === "eq").map((f) => f.column));
+  const unpinned = keyColumns2.filter((c) => !pinned.has(c));
+  if (unpinned.length > 0) {
+    throw new Error(
+      `The filter must include eq on the primary key (${unpinned.join(", ")}), so it changes one row -- refusing a filter that could match many. To change several rows, make one call per row.`
+    );
   }
   return filter;
 }
@@ -435,17 +470,16 @@ function propertyToZod(prop) {
 var FILTER_OPS = ["eq", "neq", "gt", "lt", "like"];
 function buildSupabaseMcpServer(deps) {
   const { cfg, tables, client, kb, incoming } = deps;
-  const server = new import_mcp.McpServer(
-    { name: deps.appName, version: deps.appVersion },
-    { instructions: instructionsFor(deps.warnings) }
+  const server = (0, import_core2.advertiseTools)(
+    new import_mcp.McpServer({ name: deps.appName, version: deps.appVersion }, { instructions: instructionsFor(deps.warnings) })
   );
   const taken = /* @__PURE__ */ new Set(["search_docs"]);
   for (const table of tables) {
     registerQueryTool(server, table, client, cfg, taken);
-    const grants = cfg.writes.get(table.name);
-    if (grants?.has("insert")) registerInsertTool(server, table, client, taken);
-    if (grants?.has("update")) registerUpdateTool(server, table, client, taken);
-    if (grants?.has("delete")) registerDeleteTool(server, table, client, taken);
+    const { ops } = writeTools(table, cfg);
+    if (ops.includes("insert")) registerInsertTool(server, table, client, taken);
+    if (ops.includes("update")) registerUpdateTool(server, table, client, taken);
+    if (ops.includes("delete")) registerDeleteTool(server, table, client, taken);
   }
   for (const fn of cfg.rpc) {
     registerRpcTool(server, fn, client, deps.openapi, taken);
@@ -537,23 +571,30 @@ function registerInsertTool(server, table, client, taken) {
     async (args) => toResult(() => client.insert(table.name, args.body))
   );
 }
+function keyColumns(table) {
+  return table.columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+}
+function keyFilterShape(table, verb) {
+  const keys = keyColumns(table);
+  const message = `The filter must include eq on ${keys.join(", ")} -- refusing ${verb === "update" ? "an update" : "a delete"} that could match many rows.`;
+  return filterShape(table.columns).refine((f) => !!f && keys.every((k) => f.some((x) => x.column === k && x.op === "eq")), { message }).describe(`Filters, ANDed together. Must include eq on ${keys.join(", ")} (the primary key), so one row changes.`);
+}
 function registerUpdateTool(server, table, client, taken) {
   const name = toolName("update", table.name, taken);
   const setShape = {};
   for (const col of table.columns) setShape[col.name] = columnToZod(col).optional();
+  const keys = keyColumns(table);
   server.registerTool(
     name,
     {
-      description: `Update rows in ${table.name}. At least one filter is required.`,
+      description: `Update one row in ${table.name}, named by its primary key (${keys.join(", ")}) with eq in the filter.`,
       inputSchema: {
-        filter: filterShape(table.columns).refine((f) => !!f && f.length > 0, {
-          message: "At least one filter is required -- refusing a table-wide update."
-        }),
+        filter: keyFilterShape(table, "update"),
         set: import_zod2.z.object(setShape)
       },
       annotations: { readOnlyHint: false, destructiveHint: true }
     },
-    async (args) => toResult(() => client.update(table.name, filterQueryString(requireFilter(args.filter)), args.set))
+    async (args) => toResult(() => client.update(table.name, filterQueryString(requireKeyFilter(args.filter, keys)), args.set))
   );
 }
 function registerDeleteTool(server, table, client, taken) {
@@ -561,15 +602,13 @@ function registerDeleteTool(server, table, client, taken) {
   server.registerTool(
     name,
     {
-      description: `Delete rows from ${table.name}. At least one filter is required.`,
+      description: `Delete one row from ${table.name}, named by its primary key (${keyColumns(table).join(", ")}) with eq in the filter.`,
       inputSchema: {
-        filter: filterShape(table.columns).refine((f) => !!f && f.length > 0, {
-          message: "At least one filter is required -- refusing a table-wide delete."
-        })
+        filter: keyFilterShape(table, "delete")
       },
       annotations: { readOnlyHint: false, destructiveHint: true }
     },
-    async (args) => toResult(() => client.delete(table.name, filterQueryString(requireFilter(args.filter))))
+    async (args) => toResult(() => client.delete(table.name, filterQueryString(requireKeyFilter(args.filter, keyColumns(table)))))
   );
 }
 function registerRpcTool(server, fn, client, openapi, taken) {
@@ -703,7 +742,7 @@ var INTROSPECTION_FIX = "check that SUPABASE_SERVICE_ROLE_KEY is available to th
 function supabaseToolsPhrase(ladder, cfg, hasDocs) {
   const query = ladder.tables.length;
   let write = 0;
-  for (const table of ladder.tables) write += cfg.writes.get(table.name)?.size ?? 0;
+  for (const table of ladder.tables) write += writeTools(table, cfg).ops.length;
   const rpc = cfg.rpc.length;
   const fn = Object.keys(cfg.functions).length;
   const parts = [`${query} query`];
@@ -730,6 +769,26 @@ function logColdStart(opts) {
     const details = ladder.mode === "manifest" ? ["from the bundled manifest"] : [];
     console.log((0, import_core4.formatReady)(LOG_PREFIX, { endpoint, tools: supabaseToolsPhrase(ladder, cfg, docs > 0), details, docs, auth }));
   }
+  const keyless = ladder.tables.flatMap((t) => writeTools(t, cfg).keyless.map((op) => `${t.name}.${op}`));
+  if (keyless.length > 0) {
+    console.warn(
+      (0, import_core4.formatWarning)(
+        LOG_PREFIX,
+        `writes opted in on tables without a primary key, so they aren't tools (an update or delete must name its row by key): ${keyless.join(", ")}`,
+        "add a primary key to the table"
+      )
+    );
+  }
+  const ungranted = ladder.tables.flatMap((t) => writeTools(t, cfg).ungranted.map((op) => ({ table: t.name, op })));
+  if (ungranted.length > 0) {
+    console.warn(
+      (0, import_core4.formatWarning)(
+        LOG_PREFIX,
+        `writes opted in but not granted to the authenticated role, so they aren't tools: ${ungranted.map((w) => `${w.table}.${w.op}`).join(", ")}`,
+        ungranted.map((w) => `grant ${w.op} on public.${w.table} to authenticated;`).join(" ")
+      )
+    );
+  }
   if (ladder.mode === "manifest") {
     console.warn(
       (0, import_core4.formatWarning)(LOG_PREFIX, "live schema introspection failed; tools come from the bundled manifest and may be out of date", INTROSPECTION_FIX)

package/dist/index.d.cts

@@ -18,6 +18,18 @@ interface TableSchema {
     /** From `exposify_meta()`'s `table_comment` (a `COMMENT ON TABLE`). */
     description?: string;
     columns: ColumnSchema[];
+    /**
+     * What the `authenticated` role may do on the table (`exposify_meta()`'s
+     * `can_*` columns). Absent when the database still has the older function,
+     * which didn't report grants: then nothing is filtered on them.
+     */
+    grants?: TableGrants;
+}
+interface TableGrants {
+    select: boolean;
+    insert: boolean;
+    update: boolean;
+    delete: boolean;
 }
 /** One row of `exposify_meta()` -- the migration returns one row per column. */
 interface MetaRow {
@@ -26,6 +38,11 @@ interface MetaRow {
     table_comment: string | null;
     column_name: string;
     column_comment: string | null;
+    /** Absent from the older `exposify_meta()` (before the `_v2` migration). */
+    can_select?: boolean;
+    can_insert?: boolean;
+    can_update?: boolean;
+    can_delete?: boolean;
 }
 /** Registered sibling edge function exposed as a tool. */
 interface FunctionToolConfig {
@@ -217,6 +234,11 @@ declare function loadManifest(raw: unknown): ExposifyManifest | null;
  * appears, silently, exactly like a table PostgREST doesn't know about at
  * all. There is no override: an RLS-less table is invisible even if the
  * owner explicitly lists it in `writes`.
+ *
+ * The OpenAPI document is fetched with the service role key, so it lists
+ * tables the `authenticated` role can't touch. A table `exposify_meta()`
+ * reports no SELECT grant for is left out too: every call to its query tool
+ * would answer 403.
  */
 declare function introspectTables(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[]): TableSchema[];
 

package/dist/index.d.ts

@@ -18,6 +18,18 @@ interface TableSchema {
     /** From `exposify_meta()`'s `table_comment` (a `COMMENT ON TABLE`). */
     description?: string;
     columns: ColumnSchema[];
+    /**
+     * What the `authenticated` role may do on the table (`exposify_meta()`'s
+     * `can_*` columns). Absent when the database still has the older function,
+     * which didn't report grants: then nothing is filtered on them.
+     */
+    grants?: TableGrants;
+}
+interface TableGrants {
+    select: boolean;
+    insert: boolean;
+    update: boolean;
+    delete: boolean;
 }
 /** One row of `exposify_meta()` -- the migration returns one row per column. */
 interface MetaRow {
@@ -26,6 +38,11 @@ interface MetaRow {
     table_comment: string | null;
     column_name: string;
     column_comment: string | null;
+    /** Absent from the older `exposify_meta()` (before the `_v2` migration). */
+    can_select?: boolean;
+    can_insert?: boolean;
+    can_update?: boolean;
+    can_delete?: boolean;
 }
 /** Registered sibling edge function exposed as a tool. */
 interface FunctionToolConfig {
@@ -217,6 +234,11 @@ declare function loadManifest(raw: unknown): ExposifyManifest | null;
  * appears, silently, exactly like a table PostgREST doesn't know about at
  * all. There is no override: an RLS-less table is invisible even if the
  * owner explicitly lists it in `writes`.
+ *
+ * The OpenAPI document is fetched with the service role key, so it lists
+ * tables the `authenticated` role can't touch. A table `exposify_meta()`
+ * reports no SELECT grant for is left out too: every call to its query tool
+ * would answer 403.
  */
 declare function introspectTables(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[]): TableSchema[];
 

package/dist/index.js

@@ -94,6 +94,22 @@ function resolveSupabaseConfig(options = {}, hostedBroker2 = false) {
     rateWindowMs: options.rateWindowMs
   };
 }
+function writeToolOps(table, opted) {
+  const ops = [];
+  const ungranted = [];
+  const keyless = [];
+  const hasKey = table.columns.some((c) => c.isPrimaryKey);
+  for (const op of WRITE_OPS) {
+    if (!opted?.has(op)) continue;
+    if (table.grants && !table.grants[op]) ungranted.push(op);
+    else if (op !== "insert" && !hasKey) keyless.push(op);
+    else ops.push(op);
+  }
+  return { ops, ungranted, keyless };
+}
+function writeTools(table, cfg) {
+  return writeToolOps(table, cfg.writes.get(table.name));
+}
 
 // src/postgrest-client.ts
 var FORWARDED_HEADERS = ["authorization", "apikey"];
@@ -238,6 +254,8 @@ function introspectTables(openapi, metaRows) {
     const rlsEnabled = rows[0].rls_enabled;
     if (!rlsEnabled) continue;
     if (!exposedInOpenApi.has(name)) continue;
+    const grants = grantsOf(rows[0]);
+    if (grants && !grants.select) continue;
     const openApiColumns = new Map(columnsFromOpenApi(openapi, name).map((c) => [c.name, c]));
     const columns = [];
     for (const row of rows) {
@@ -255,11 +273,21 @@ function introspectTables(openapi, metaRows) {
       name,
       rlsEnabled: true,
       description: rows[0].table_comment ?? void 0,
-      columns
+      columns,
+      ...grants ? { grants } : {}
     });
   }
   return tables.sort((a, b) => a.name.localeCompare(b.name));
 }
+function grantsOf(row) {
+  if (typeof row.can_select !== "boolean") return void 0;
+  return {
+    select: row.can_select,
+    insert: row.can_insert === true,
+    update: row.can_update === true,
+    delete: row.can_delete === true
+  };
+}
 function groupByTable(rows) {
   const map = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -316,6 +344,7 @@ function messageOf(err) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z2 } from "zod";
 import {
+  advertiseTools,
   toToolResult,
   DISPATCH_TIMEOUT_MS
 } from "@exposify/core";
@@ -332,9 +361,16 @@ function buildQueryString(args, maxRows) {
   params.set("limit", String(limit));
   return params.toString();
 }
-function requireFilter(filter) {
-  if (!filter || filter.length === 0) {
-    throw new Error("At least one filter is required -- refusing a table-wide update/delete.");
+function requireKeyFilter(filter, keyColumns2) {
+  if (keyColumns2.length === 0) {
+    throw new Error("This table has no primary key, so a single row can't be named -- refusing the update/delete.");
+  }
+  const pinned = new Set((filter ?? []).filter((f) => f.op === "eq").map((f) => f.column));
+  const unpinned = keyColumns2.filter((c) => !pinned.has(c));
+  if (unpinned.length > 0) {
+    throw new Error(
+      `The filter must include eq on the primary key (${unpinned.join(", ")}), so it changes one row -- refusing a filter that could match many. To change several rows, make one call per row.`
+    );
   }
   return filter;
 }
@@ -401,17 +437,16 @@ function propertyToZod(prop) {
 var FILTER_OPS = ["eq", "neq", "gt", "lt", "like"];
 function buildSupabaseMcpServer(deps) {
   const { cfg, tables, client, kb, incoming } = deps;
-  const server = new McpServer(
-    { name: deps.appName, version: deps.appVersion },
-    { instructions: instructionsFor(deps.warnings) }
+  const server = advertiseTools(
+    new McpServer({ name: deps.appName, version: deps.appVersion }, { instructions: instructionsFor(deps.warnings) })
   );
   const taken = /* @__PURE__ */ new Set(["search_docs"]);
   for (const table of tables) {
     registerQueryTool(server, table, client, cfg, taken);
-    const grants = cfg.writes.get(table.name);
-    if (grants?.has("insert")) registerInsertTool(server, table, client, taken);
-    if (grants?.has("update")) registerUpdateTool(server, table, client, taken);
-    if (grants?.has("delete")) registerDeleteTool(server, table, client, taken);
+    const { ops } = writeTools(table, cfg);
+    if (ops.includes("insert")) registerInsertTool(server, table, client, taken);
+    if (ops.includes("update")) registerUpdateTool(server, table, client, taken);
+    if (ops.includes("delete")) registerDeleteTool(server, table, client, taken);
   }
   for (const fn of cfg.rpc) {
     registerRpcTool(server, fn, client, deps.openapi, taken);
@@ -503,23 +538,30 @@ function registerInsertTool(server, table, client, taken) {
     async (args) => toResult(() => client.insert(table.name, args.body))
   );
 }
+function keyColumns(table) {
+  return table.columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+}
+function keyFilterShape(table, verb) {
+  const keys = keyColumns(table);
+  const message = `The filter must include eq on ${keys.join(", ")} -- refusing ${verb === "update" ? "an update" : "a delete"} that could match many rows.`;
+  return filterShape(table.columns).refine((f) => !!f && keys.every((k) => f.some((x) => x.column === k && x.op === "eq")), { message }).describe(`Filters, ANDed together. Must include eq on ${keys.join(", ")} (the primary key), so one row changes.`);
+}
 function registerUpdateTool(server, table, client, taken) {
   const name = toolName("update", table.name, taken);
   const setShape = {};
   for (const col of table.columns) setShape[col.name] = columnToZod(col).optional();
+  const keys = keyColumns(table);
   server.registerTool(
     name,
     {
-      description: `Update rows in ${table.name}. At least one filter is required.`,
+      description: `Update one row in ${table.name}, named by its primary key (${keys.join(", ")}) with eq in the filter.`,
       inputSchema: {
-        filter: filterShape(table.columns).refine((f) => !!f && f.length > 0, {
-          message: "At least one filter is required -- refusing a table-wide update."
-        }),
+        filter: keyFilterShape(table, "update"),
         set: z2.object(setShape)
       },
       annotations: { readOnlyHint: false, destructiveHint: true }
     },
-    async (args) => toResult(() => client.update(table.name, filterQueryString(requireFilter(args.filter)), args.set))
+    async (args) => toResult(() => client.update(table.name, filterQueryString(requireKeyFilter(args.filter, keys)), args.set))
   );
 }
 function registerDeleteTool(server, table, client, taken) {
@@ -527,15 +569,13 @@ function registerDeleteTool(server, table, client, taken) {
   server.registerTool(
     name,
     {
-      description: `Delete rows from ${table.name}. At least one filter is required.`,
+      description: `Delete one row from ${table.name}, named by its primary key (${keyColumns(table).join(", ")}) with eq in the filter.`,
       inputSchema: {
-        filter: filterShape(table.columns).refine((f) => !!f && f.length > 0, {
-          message: "At least one filter is required -- refusing a table-wide delete."
-        })
+        filter: keyFilterShape(table, "delete")
       },
       annotations: { readOnlyHint: false, destructiveHint: true }
     },
-    async (args) => toResult(() => client.delete(table.name, filterQueryString(requireFilter(args.filter))))
+    async (args) => toResult(() => client.delete(table.name, filterQueryString(requireKeyFilter(args.filter, keyColumns(table)))))
   );
 }
 function registerRpcTool(server, fn, client, openapi, taken) {
@@ -669,7 +709,7 @@ var INTROSPECTION_FIX = "check that SUPABASE_SERVICE_ROLE_KEY is available to th
 function supabaseToolsPhrase(ladder, cfg, hasDocs) {
   const query = ladder.tables.length;
   let write = 0;
-  for (const table of ladder.tables) write += cfg.writes.get(table.name)?.size ?? 0;
+  for (const table of ladder.tables) write += writeTools(table, cfg).ops.length;
   const rpc = cfg.rpc.length;
   const fn = Object.keys(cfg.functions).length;
   const parts = [`${query} query`];
@@ -696,6 +736,26 @@ function logColdStart(opts) {
     const details = ladder.mode === "manifest" ? ["from the bundled manifest"] : [];
     console.log(formatReady(LOG_PREFIX, { endpoint, tools: supabaseToolsPhrase(ladder, cfg, docs > 0), details, docs, auth }));
   }
+  const keyless = ladder.tables.flatMap((t) => writeTools(t, cfg).keyless.map((op) => `${t.name}.${op}`));
+  if (keyless.length > 0) {
+    console.warn(
+      formatWarning(
+        LOG_PREFIX,
+        `writes opted in on tables without a primary key, so they aren't tools (an update or delete must name its row by key): ${keyless.join(", ")}`,
+        "add a primary key to the table"
+      )
+    );
+  }
+  const ungranted = ladder.tables.flatMap((t) => writeTools(t, cfg).ungranted.map((op) => ({ table: t.name, op })));
+  if (ungranted.length > 0) {
+    console.warn(
+      formatWarning(
+        LOG_PREFIX,
+        `writes opted in but not granted to the authenticated role, so they aren't tools: ${ungranted.map((w) => `${w.table}.${w.op}`).join(", ")}`,
+        ungranted.map((w) => `grant ${w.op} on public.${w.table} to authenticated;`).join(" ")
+      )
+    );
+  }
   if (ladder.mode === "manifest") {
     console.warn(
       formatWarning(LOG_PREFIX, "live schema introspection failed; tools come from the bundled manifest and may be out of date", INTROSPECTION_FIX)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exposify/supabase",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -27,7 +27,7 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@exposify/core": "0.3.16",
+    "@exposify/core": "0.3.17",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },

package/sql/exposify_meta.sql

@@ -2,8 +2,12 @@
 --
 -- Exposes, per PostgREST's RPC convention (POST /rpc/exposify_meta), one row
 -- per column of every ordinary table in the `public` schema: whether Row
--- Level Security is enabled on its table, and the table/column comments an
--- owner wrote via `COMMENT ON TABLE` / `COMMENT ON COLUMN`.
+-- Level Security is enabled on its table, the table/column comments an
+-- owner wrote via `COMMENT ON TABLE` / `COMMENT ON COLUMN`, and what the
+-- `authenticated` role (the one agents' tool calls run as) is granted on the
+-- table. Without a grant every call answers 403, however the RLS policies
+-- read: Supabase's newer local images no longer grant `anon`/`authenticated`
+-- on new public tables, so a table can have RLS on and still be unreachable.
 --
 -- This is the runtime source of truth for the DB exposure policy (RLS-gated,
 -- reads auto) and for tool/param descriptions -- see the design spec's "DB
@@ -20,13 +24,22 @@
 --   alter function public.agentify_meta() rename to exposify_meta();
 -- or drop the old one after confirming nothing else calls it:
 --   drop function public.agentify_meta();
-create or replace function public.exposify_meta()
+--
+-- The grant columns were added later, as a new migration
+-- (`<timestamp>_exposify_meta_v2.sql`): adding output columns changes the
+-- function's return type, which `create or replace` can't do, hence the drop.
+drop function if exists public.exposify_meta();
+create function public.exposify_meta()
 returns table (
   table_name text,
   rls_enabled boolean,
   table_comment text,
   column_name text,
-  column_comment text
+  column_comment text,
+  can_select boolean,
+  can_insert boolean,
+  can_update boolean,
+  can_delete boolean
 )
 language sql
 security definer
@@ -37,7 +50,12 @@ as $$
     c.relrowsecurity as rls_enabled,
     obj_description(c.oid, 'pg_class') as table_comment,
     a.attname as column_name,
-    col_description(c.oid, a.attnum) as column_comment
+    col_description(c.oid, a.attnum) as column_comment,
+    -- "any column" so a grant on some columns counts, as PostgREST sees it.
+    has_any_column_privilege('authenticated', c.oid, 'SELECT') as can_select,
+    has_any_column_privilege('authenticated', c.oid, 'INSERT') as can_insert,
+    has_any_column_privilege('authenticated', c.oid, 'UPDATE') as can_update,
+    has_table_privilege('authenticated', c.oid, 'DELETE') as can_delete
   from pg_catalog.pg_class c
   join pg_catalog.pg_namespace n on n.oid = c.relnamespace
   join pg_catalog.pg_attribute a on a.attrelid = c.oid