@enfyra/mcp-server 0.1.52 → 0.1.54

package/README.md

@@ -246,6 +246,18 @@ Without a target flag, interactive mode asks which client to configure. Non-inte
 
 For normal apps and demos, enter the app/admin URL such as `http://localhost:3000` or `https://demo.enfyra.io`. Treat the direct Enfyra backend host as private infrastructure unless you are debugging Enfyra core/server internals.
 
+## Metadata Contract
+
+The MCP server uses Enfyra metadata lazily:
+
+- `GET /metadata` returns only `dbType` and `enfyraVersion`.
+- `GET /metadata/{tableName}` returns one permission-projected table schema.
+- `get_all_tables` and normal discovery use a lightweight `enfyra_table` catalog.
+- `get_table_metadata`, `inspect_table`, mutation validation, and schema operations fetch only the table schemas they need.
+- Explicit broad schema searches fan out to per-table metadata with bounded concurrency and reuse the MCP runtime cache.
+
+Use `get_all_tables` for table names, then `get_table_metadata` or `inspect_table` for columns and relations. `get_all_metadata(includeFull=true)` is an explicit broad operation and should not be used as startup discovery.
+
 ## Common Examples
 
 Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate implementation patterns. It returns focused examples for:

package/dist/lib/mcp-instructions.js

@@ -21,6 +21,7 @@ export function buildMcpServerInstructions(apiBaseUrl, options = {}) {
         '- Primary success criterion: one-shot done. A capable baseline model (GLM-5-Turbo or stronger) should finish a fully specified, non-destructive task in one task turn, using the smallest necessary sequence of MCP calls and without asking the user to relay intermediate plans or retry avoidable failures.',
         '- Primary efficiency criterion: lazy-load by domain. Startup instructions are only a router; load required knowledge, examples, live metadata, script contexts, and theme contracts only when that exact task needs them. Never load broad discovery, full knowledge, or a full reference merely as a precaution.',
         '- For target sanity checks, call `get_enfyra_api_context`; do not load broad metadata only to confirm the API base.',
+        '- Metadata is lazy: `GET /metadata` is runtime context only, while table schema comes from `GET /metadata/:name`. Use `get_all_tables` for a lightweight catalog and `get_table_metadata` or `inspect_table` for one schema; do not preload all table schemas.',
         '- When the goal or tool path is ambiguous, call `discover_enfyra_workflows` with intent/risk/surface; follow its `primaryPath` and `avoidTools`. Skip it when the exact focused operation is already clear.',
         '- Inspect only the target: use `inspect_table`, `inspect_route`, `inspect_feature`, `search_admin_extensions`, or `search_runtime_zone`. Do not run broad discovery after the target is known.',
         '- Load examples with `get_enfyra_examples` only for an unfamiliar pattern. For extension UI, load `get_extension_theme_contract`; call build_extension_ui only when the requested UI needs those contracts.',

package/dist/lib/mcp-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,0BAA0B,CAAC,UAAU,EAAE,UAAiC,EAAE;IACxF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAEvD,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,EAAE;QACF,qBAAqB;QACrB,gTAAgT;QAChT,mTAAmT;QACnT,qHAAqH;QACrH,6MAA6M;QAC7M,gMAAgM;QAChM,6MAA6M;QAC7M,4EAA4E;QAC5E,2NAA2N;QAC3N,kTAAkT;QAClT,6LAA6L;QAC7L,yLAAyL;QACzL,mPAAmP;KACpP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,0BAA0B,CAAC,UAAU,EAAE,UAAiC,EAAE;IACxF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAEvD,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,EAAE;QACF,qBAAqB;QACrB,gTAAgT;QAChT,mTAAmT;QACnT,qHAAqH;QACrH,gQAAgQ;QAChQ,6MAA6M;QAC7M,gMAAgM;QAChM,6MAA6M;QAC7M,4EAA4E;QAC5E,2NAA2N;QAC3N,kTAAkT;QAClT,6LAA6L;QAC7L,yLAAyL;QACzL,mPAAmP;KACpP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/lib/metadata-client.d.ts

@@ -0,0 +1,8 @@
+import type { MetadataContext, MetadataTableCatalogEntry, UnknownRecord } from "./types.js";
+export declare function unwrapTableMetadata(result: unknown): UnknownRecord | null;
+export declare function fetchMetadataContext(apiUrl: string): Promise<MetadataContext>;
+export declare function fetchTableMetadata(apiUrl: string, tableName: string): Promise<UnknownRecord>;
+export declare function fetchTableCatalog(apiUrl: string): Promise<MetadataTableCatalogEntry[]>;
+export declare function fetchTableMetadataByRef(apiUrl: string, tableRef: unknown): Promise<UnknownRecord>;
+export declare function resolveTableCatalogEntry(tables: MetadataTableCatalogEntry[], tableRef: unknown): MetadataTableCatalogEntry | null;
+export declare function fetchMetadataTables(apiUrl: string, catalog: MetadataTableCatalogEntry[], concurrency?: number): Promise<UnknownRecord[]>;

package/dist/lib/metadata-client.js

@@ -0,0 +1,69 @@
+import { fetchAPI } from "./fetch.js";
+const TABLE_CATALOG_FIELDS = "id,name,alias,description,isSingleRecord";
+const DEFAULT_METADATA_CONCURRENCY = 4;
+function unwrapData(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object" && Array.isArray(result.data)) {
+        return result.data;
+    }
+    return [];
+}
+export function unwrapTableMetadata(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const record = result;
+    const data = record.data;
+    if (data && typeof data === "object" && !Array.isArray(data))
+        return data;
+    const table = record.table;
+    if (table && typeof table === "object" && !Array.isArray(table))
+        return table;
+    return null;
+}
+export async function fetchMetadataContext(apiUrl) {
+    const result = await fetchAPI(apiUrl, "/metadata");
+    return {
+        dbType: result?.dbType ?? null,
+        enfyraVersion: result?.enfyraVersion ?? null,
+    };
+}
+export async function fetchTableMetadata(apiUrl, tableName) {
+    const result = await fetchAPI(apiUrl, `/metadata/${encodeURIComponent(tableName)}`);
+    const table = unwrapTableMetadata(result);
+    if (!table)
+        throw new Error(`Metadata for table "${tableName}" did not contain a table object.`);
+    return table;
+}
+export async function fetchTableCatalog(apiUrl) {
+    const result = await fetchAPI(apiUrl, `/enfyra_table?fields=${encodeURIComponent(TABLE_CATALOG_FIELDS)}&limit=0&sort=name`);
+    return unwrapData(result)
+        .filter((item) => Boolean(item && typeof item === "object" && typeof item.name === "string"));
+}
+export async function fetchTableMetadataByRef(apiUrl, tableRef) {
+    const catalog = await fetchTableCatalog(apiUrl);
+    const entry = resolveTableCatalogEntry(catalog, tableRef);
+    if (!entry)
+        throw new Error(`Table not found: ${String(tableRef)}`);
+    return fetchTableMetadata(apiUrl, entry.name);
+}
+export function resolveTableCatalogEntry(tables, tableRef) {
+    const normalizedRef = String(tableRef ?? "");
+    return tables.find((table) => (String(table.id ?? table._id ?? "") === normalizedRef
+        || table.name === normalizedRef
+        || table.alias === normalizedRef)) ?? null;
+}
+export async function fetchMetadataTables(apiUrl, catalog, concurrency = DEFAULT_METADATA_CONCURRENCY) {
+    const tables = new Array(catalog.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(Math.max(1, concurrency), catalog.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (nextIndex < catalog.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            tables[index] = await fetchTableMetadata(apiUrl, catalog[index].name);
+        }
+    }));
+    return tables;
+}
+//# sourceMappingURL=metadata-client.js.map

package/dist/lib/metadata-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-client.js","sourceRoot":"","sources":["../../src/lib/metadata-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,MAAM,oBAAoB,GAAG,0CAA0C,CAAC;AACxE,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAEvC,SAAS,UAAU,CAAC,MAAe;IACjC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACzC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAE,MAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1F,OAAQ,MAAwB,CAAC,IAAiB,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,MAAM,GAAG,MAAuB,CAAC;IACvC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACzB,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAqB,CAAC;IAC3F,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAsB,CAAC;IAC/F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAc;IACvD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnD,OAAO;QACL,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI;QAC9B,aAAa,EAAE,MAAM,EAAE,aAAa,IAAI,IAAI;KAC7C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc,EAAE,SAAiB;IACxE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,aAAa,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,mCAAmC,CAAC,CAAC;IACjG,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAc;IACpD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,MAAM,EACN,wBAAwB,kBAAkB,CAAC,oBAAoB,CAAC,oBAAoB,CACrF,CAAC;IACF,OAAO,UAAU,CAAC,MAAM,CAAC;SACtB,MAAM,CAAC,CAAC,IAAI,EAAqC,EAAE,CAAC,OAAO,CAC1D,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAQ,IAAkC,CAAC,IAAI,KAAK,QAAQ,CACjG,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,MAAc,EAAE,QAAiB;IAC7E,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,wBAAwB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACpE,OAAO,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAAmC,EACnC,QAAiB;IAEjB,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,aAAa;WAClD,KAAK,CAAC,IAAI,KAAK,aAAa;WAC5B,KAAK,CAAC,KAAK,KAAK,aAAa,CACjC,CAAC,IAAI,IAAI,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAc,EACd,OAAoC,EACpC,WAAW,GAAG,4BAA4B;IAE1C,MAAM,MAAM,GAAoB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,KAAK,IAAI,EAAE;QAC/D,OAAO,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,SAAS,CAAC;YACxB,SAAS,IAAI,CAAC,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QACxE,CAAC;IACH,CAAC,CAAC,CAAC,CAAC;IACJ,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/platform-operation-tools.d.ts

@@ -78,6 +78,7 @@ export declare function buildExtensionUploadModalSnippet(input: any): {
 };
 export declare function buildExtensionApiUsageSnippet(input?: AnyRecord): {
     action: string;
+    operation: string;
     snippet: string;
     contract: string[];
 };

package/dist/lib/platform-operation-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { createHash } from 'node:crypto';
 import { fetchAPI } from './fetch.js';
+import { fetchTableCatalog, fetchTableMetadataByRef, resolveTableCatalogEntry } from './metadata-client.js';
 import { validatePortableScriptSource, validateScriptSourceIfPresent } from './mutation-guards.js';
 import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertExtensionKnowledgeAck, assertGlobalRulesAck, dynamicCodeKnowledgeAckParam, extensionKnowledgeAckParam, globalRulesAckParam, } from './required-knowledge.js';
 const AUTO_INJECTED_EXTENSION_COMPONENT_TAGS = [
@@ -849,12 +850,34 @@ function toPascalIdentifier(value, fallback = 'Items') {
 export function buildExtensionApiUsageSnippet(input = {}) {
     const resource = String(input.resource || input.name || 'items');
     const pascal = toPascalIdentifier(resource, 'Items');
-    const path = input.path || `/${resource}`;
-    const method = String(input.method || 'GET').toUpperCase();
+    const operation = String(input.operation || input.mode || input.intent || '').toLowerCase() || String(input.method || 'GET').toLowerCase();
+    const normalizedOperation = {
+        get: 'list',
+        read: 'list',
+        load: 'list',
+        post: 'create',
+        patch: 'update',
+        put: 'update',
+        del: 'delete',
+        remove: 'delete',
+        destroy: 'delete',
+    }[operation] || operation;
+    const defaultMethodByOperation = {
+        list: 'GET',
+        find_one: 'GET',
+        create: 'POST',
+        update: 'PATCH',
+        delete: 'DELETE',
+        batch_update: 'PATCH',
+        batch_delete: 'DELETE',
+    };
+    const method = String(input.method || defaultMethodByOperation[normalizedOperation] || 'GET').toUpperCase();
+    const rawPath = String(input.path || `/${resource}`);
+    const path = rawPath.replace(/\/:id\/?$/, '');
     const responseName = input.responseName || `${resource}Response`;
     const pendingName = input.pendingName || `${resource}Pending`;
     const errorName = input.errorName || `${resource}Error`;
-    const executeName = input.executeName || (method === 'GET' ? `load${pascal}` : `${method.toLowerCase()}${pascal}`);
+    const executeName = input.executeName || (method === 'GET' ? `load${pascal}` : `${normalizedOperation.replace(/(^|_)([a-z])/g, (_m, _p, ch) => ch.toUpperCase()).replace(/^./, (ch) => ch.toLowerCase())}${pascal}Api`);
     const refreshName = input.refreshName || `refresh${pascal}`;
     const options = [];
     if (method !== 'GET')
@@ -878,6 +901,60 @@ export function buildExtensionApiUsageSnippet(input = {}) {
             lines.push(`onMounted(() => { ${executeName}(); });`);
         }
     }
+    else if (normalizedOperation === 'create') {
+        const handlerName = input.handlerName || `create${pascal.replace(/s$/, '')}`;
+        const payloadName = input.payloadName || 'payload';
+        lines.push(...[
+            '',
+            `async function ${handlerName}(${payloadName}) {`,
+            `  const response = await ${executeName}({ body: ${payloadName} });`,
+            '  if (!response) return null;',
+            '  return response;',
+            '}',
+        ]);
+    }
+    else if (normalizedOperation === 'update') {
+        const handlerName = input.handlerName || `update${pascal.replace(/s$/, '')}`;
+        const recordName = input.recordName || 'record';
+        const bodyName = input.bodyName || 'body';
+        const idExpression = input.idExpression || `${recordName}.id`;
+        const bodyArg = bodyName === 'body' ? 'body' : `body: ${bodyName}`;
+        lines.push(...[
+            '',
+            `async function ${handlerName}(${recordName}, ${bodyName}) {`,
+            `  const response = await ${executeName}({ id: ${idExpression}, ${bodyArg} });`,
+            '  if (!response) return null;',
+            '  return response;',
+            '}',
+        ]);
+    }
+    else if (normalizedOperation === 'delete') {
+        const handlerName = input.handlerName || `delete${pascal.replace(/s$/, '')}`;
+        const recordName = input.recordName || 'record';
+        const idExpression = input.idExpression || `${recordName}.id`;
+        lines.push(...[
+            '',
+            `async function ${handlerName}(${recordName}) {`,
+            `  const response = await ${executeName}({ id: ${idExpression} });`,
+            '  if (!response) return null;',
+            '  return response;',
+            '}',
+        ]);
+    }
+    else if (normalizedOperation === 'batch_update' || normalizedOperation === 'batch_delete') {
+        const handlerName = input.handlerName || `${normalizedOperation === 'batch_update' ? 'update' : 'delete'}${pascal}Batch`;
+        const idsName = input.idsName || 'ids';
+        const bodyName = input.bodyName || 'body';
+        const args = normalizedOperation === 'batch_update' ? `{ ids: ${idsName}, body: ${bodyName} }` : `{ ids: ${idsName} }`;
+        lines.push(...[
+            '',
+            `async function ${handlerName}(${normalizedOperation === 'batch_update' ? `${idsName}, ${bodyName}` : idsName}) {`,
+            `  const response = await ${executeName}(${args});`,
+            '  if (!response) return null;',
+            '  return response;',
+            '}',
+        ]);
+    }
     else {
         const handlerName = input.handlerName || `${method.toLowerCase()}${pascal}Record`;
         lines.push(...[
@@ -891,9 +968,11 @@ export function buildExtensionApiUsageSnippet(input = {}) {
     }
     return {
         action: 'extension_api_usage_built',
+        operation: normalizedOperation,
         snippet: lines.join('\n'),
         contract: [
             'useApi returns refs plus execute/refresh; it does not auto-run.',
+            'The useApi path is the base route string or a () => string getter; do not pass computed refs and do not put :id placeholders in the path.',
             'Pass query/body as objects or computed objects, not JSON.stringify strings.',
             'Read normal list rows from data.value?.data or from the direct execute() response.',
             'For mutations, call execute({ body }), execute({ id, body }), execute({ id }), or execute({ ids }) from a user action.',
@@ -1764,19 +1843,6 @@ async function patchExtensionCode(apiUrl, { id, name, search, replace, searchMod
         validation: result.validation,
     };
 }
-function normalizeMetadataTables(metadata) {
-    const tables = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
-    return Array.isArray(tables) ? tables : Object.values(tables || {});
-}
-async function getMetadataTables(apiUrl) {
-    return normalizeMetadataTables(await fetchAPI(apiUrl, '/metadata'));
-}
-function resolveTable(tables, tableName) {
-    const table = tables.find((item) => item?.name === tableName || item?.alias === tableName || sameId(getId(item), tableName));
-    if (!table)
-        throw new Error(`Table not found: ${tableName}`);
-    return table;
-}
 function resolveColumn(table, columnName) {
     const column = (table.columns || []).find((item) => item?.name === columnName || sameId(getId(item), columnName));
     if (!column)
@@ -2860,6 +2926,36 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
         return jsonText(buildExtensionUiSnippet(kind, input));
     });
+    server.tool('build_extension_api_usage', [
+        'Generate a contract-safe useApi snippet for Enfyra admin extensions.',
+        'Use this instead of writing useApi calls from memory so route paths, execute({ id, body }), query/body objects, and mutation handlers follow the app composable contract.',
+        'The tool returns code only; apply it with patch_extension_code or update_extension_code and then validate/save normally.',
+    ].join(' '), {
+        operation: z.enum(['list', 'find_one', 'create', 'update', 'delete', 'batch_update', 'batch_delete']).default('list').describe('API usage pattern to generate. Reads use the base route with query objects; mutations append ids through execute options.'),
+        resource: z.string().default('items').describe('Resource variable base name, e.g. notes, projects, messages.'),
+        path: z.string().optional().describe('Base API route path such as /notes. Do not include /:id; the builder strips a trailing /:id if provided.'),
+        queryExpression: z.string().optional().describe('Raw Vue expression for query object/computed. Do not JSON.stringify.'),
+        bodyExpression: z.string().optional().describe('Raw Vue expression for default body object/computed when useful. Do not JSON.stringify.'),
+        errorContext: z.string().optional().describe('Safe error context label for useApi error reporting.'),
+        responseName: z.string().optional().describe('Optional data ref variable name.'),
+        pendingName: z.string().optional().describe('Optional pending ref variable name.'),
+        errorName: z.string().optional().describe('Optional error ref variable name.'),
+        executeName: z.string().optional().describe('Optional execute alias name.'),
+        refreshName: z.string().optional().describe('Optional refresh alias name.'),
+        rowsName: z.string().optional().describe('Optional computed rows variable for list/find_one operations.'),
+        handlerName: z.string().optional().describe('Optional generated handler function name for mutations.'),
+        recordName: z.string().optional().describe('Record parameter name for update/delete handlers.'),
+        payloadName: z.string().optional().describe('Payload parameter name for create handlers.'),
+        bodyName: z.string().optional().describe('Body parameter name for update/batch_update handlers.'),
+        idsName: z.string().optional().describe('Ids parameter name for batch handlers.'),
+        idExpression: z.string().optional().describe('Raw id expression for update/delete handlers. Defaults to record.id.'),
+        autoLoad: z.boolean().optional().default(true).describe('For reads, generate onMounted(() => execute()).'),
+        onErrorExpression: z.string().optional().describe('Raw onError handler expression when custom handling is needed.'),
+        extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
+    }, async ({ extensionKnowledgeAckKey, ...input }) => {
+        assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
+        return jsonText(buildExtensionApiUsageSnippet(input));
+    });
     server.tool('build_extension_drawer', [
         'Generate a contract-safe CommonDrawer Vue snippet for Enfyra admin extensions.',
         'Use this before writing or patching drawer/editing workflows so the model does not have to remember CommonDrawer slots, footer action props, full-width fields, or button type rules.',
@@ -3079,7 +3175,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         globalRulesAckKey: globalRulesAckParam(z),
     }, async ({ tableName, isEnabled, globalRulesAckKey }) => {
         assertGlobalRulesAck(globalRulesAckKey);
-        const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
+        const catalog = await fetchTableCatalog(ENFYRA_API_URL);
+        const table = resolveTableCatalogEntry(catalog, tableName);
+        if (!table)
+            throw new Error(`Table not found: ${tableName}`);
         const existing = await findRecord(ENFYRA_API_URL, 'enfyra_graphql', { table: { id: { _eq: getId(table) } } }, 'id,_id,table.id,isEnabled');
         const operation = await createOrPatch(ENFYRA_API_URL, 'enfyra_graphql', existing, {
             table: { id: getId(table) },
@@ -3367,7 +3466,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         globalRulesAckKey: globalRulesAckParam(z),
     }, async ({ tableName, columnName, ruleType, value, message, description, isEnabled, globalRulesAckKey }) => {
         assertGlobalRulesAck(globalRulesAckKey);
-        const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
+        const table = await fetchTableMetadataByRef(ENFYRA_API_URL, tableName);
         const column = resolveColumn(table, columnName);
         const existing = await findRecord(ENFYRA_API_URL, 'enfyra_column_rule', {
             column: { id: { _eq: getId(column) } },
@@ -3407,11 +3506,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
         if (!!columnName === !!relationName)
             throw new Error('Provide exactly one of columnName or relationName.');
         assertOneScope({ roleId, roleName, allowedUserIds });
-        const [tables, role] = await Promise.all([
-            getMetadataTables(ENFYRA_API_URL),
+        const [table, role] = await Promise.all([
+            fetchTableMetadataByRef(ENFYRA_API_URL, tableName),
             resolveRole(ENFYRA_API_URL, { roleId, roleName }),
         ]);
-        const table = resolveTable(tables, tableName);
         const field = columnName ? resolveColumn(table, columnName) : resolveRelation(table, relationName);
         const filter = {
             action: { _eq: action },