@enfyra/mcp-server 0.1.52 → 0.1.53

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":"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"}

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 = [
@@ -1764,19 +1765,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)
@@ -3079,7 +3067,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 +3358,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 +3398,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 },