@enfyra/mcp-server 0.0.92 → 0.0.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.92",
+  "version": "0.0.94",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-instructions.js

@@ -24,6 +24,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `GraphQL endpoints: \`${graphqlHttpUrl}\` and \`${graphqlSchemaUrl}\`.`,
     '',
     '### Work Flow',
+    '- For a quick target/base sanity check, call `get_enfyra_api_context`; do not call broad discovery just to confirm which instance this MCP is connected to.',
     '- Discover before deciding. For architecture/capability questions call `discover_enfyra_system`; for DB/pk/runtime/cache context call `discover_runtime_context`; for filters/deep/sort/relation query shape call `discover_query_capabilities`. Run broad discovery tools sequentially, not in parallel.',
     '- Inspect narrowly. Use `inspect_table`, `inspect_route`, and `inspect_feature` for the table/route/feature being changed instead of loading broad metadata.',
     '- Load examples only when needed. Before generating schemas, app connection code, OAuth, Socket.IO, handlers/hooks, flows, files, guards, permissions, or extensions, call `get_enfyra_examples` with the matching category.',

package/src/mcp-server-entry.mjs

@@ -13,6 +13,7 @@ import { createHash } from 'node:crypto';
 // Configuration
 const ENFYRA_API_URL = process.env.ENFYRA_API_URL || 'http://localhost:3000/api';
 const ENFYRA_API_TOKEN = process.env.ENFYRA_API_TOKEN || '';
+const DISCOVERY_FETCH_TIMEOUT_MS = 12000;
 
 // Import modules
 import { exchangeApiToken, refreshAccessToken, getValidToken, resetTokens, getTokenExpiry, initAuth } from './lib/auth.js';
@@ -360,6 +361,40 @@ function targetInstance() {
   };
 }
 
+async function discoveryFetch(path, { fallbackData = [], timeoutMs = DISCOVERY_FETCH_TIMEOUT_MS } = {}) {
+  let timeoutId;
+  try {
+    const timeout = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`Discovery request timeout after ${timeoutMs}ms for ${path}`));
+      }, timeoutMs);
+    });
+    return await Promise.race([
+      fetchAPI(ENFYRA_API_URL, path),
+      timeout,
+    ]);
+  } catch (error) {
+    return {
+      statusCode: null,
+      success: false,
+      error: String(error?.message || error),
+      data: fallbackData,
+    };
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+function collectPartialErrors(results) {
+  return Object.entries(results)
+    .filter(([, result]) => result?.error)
+    .map(([name, result]) => ({ name, error: result.error }));
+}
+
+function jsonContent(payload, { pretty = false } = {}) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, pretty ? 2 : 0) }] };
+}
+
 async function getMetadataTables() {
   const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
   return {
@@ -584,7 +619,7 @@ server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Us
         ...summarizeMetadata(result, { search, limit }),
         detailHint: 'Default response is capped and minimal. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.',
       };
-  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  return jsonContent(payload);
 });
 
 server.tool('get_table_metadata', 'Get concise metadata for a specific table by name', {
@@ -601,7 +636,7 @@ server.tool('get_table_metadata', 'Get concise metadata for a specific table by
         table: summarizeTable(table),
         queryHint: `Use query_table({ tableName: "${tableName}", fields: [...] }) for records. query_table without fields returns only the primary key.`,
       };
-  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  return jsonContent(payload);
 });
 
 server.tool(
@@ -615,7 +650,7 @@ server.tool(
   },
   async ({ category }) => {
     const result = getExamples(category);
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    return jsonContent(result);
   },
 );
 
@@ -624,15 +659,14 @@ server.tool(
   [
     'Call this first when you need to understand the live Enfyra instance.',
     'Returns a concise capability map from live metadata/routes/method rows, including schema management, REST route behavior, GraphQL enablement, and relation handling.',
+    'Do not use this only to confirm the API base; use get_enfyra_api_context for that cheaper target check.',
     'Run broad discovery tools sequentially; do not call multiple broad discovery tools in parallel.',
   ].join(' '),
   {},
   async () => {
-    const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
-    const [routesResult, methodsResult] = await Promise.all([
-      fetchAPI(ENFYRA_API_URL, '/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*&limit=1000'),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_method?limit=100'),
-    ]);
+    const metadata = await discoveryFetch('/metadata');
+    const routesResult = await discoveryFetch('/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*&limit=1000');
+    const methodsResult = await discoveryFetch('/enfyra_method?limit=100');
 
     const tables = normalizeTables(metadata);
     const tableNames = tables.map((table) => table?.name).filter(Boolean).sort();
@@ -643,10 +677,18 @@ server.tool(
     const tableDefinition = tables.find((table) => table?.name === 'enfyra_table');
     const gqlDefinition = tables.find((table) => table?.name === 'enfyra_graphql');
     const routeTableList = [...routeTables].sort();
+    const noRouteTableList = noRouteTables.sort();
+    const sample = (items, max = 40) => ({
+      total: items.length,
+      returned: Math.min(items.length, max),
+      items: items.slice(0, max),
+      truncated: items.length > max,
+    });
 
     const payload = {
       targetInstance: targetInstance(),
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
+      partialErrors: collectPartialErrors({ metadata, routesResult, methodsResult }),
       counts: {
         tables: tableNames.length,
         routes: routes.length,
@@ -662,10 +704,12 @@ server.tool(
       rest: {
         routePattern: 'Dynamic REST routes expose GET/POST at /<route-path> and PATCH/DELETE at /<route-path>/:id; there is no GET /<route-path>/:id.',
         publicAccess: 'publicMethods controls anonymous REST access per route/method; otherwise Bearer JWT + routePermissions apply.',
-        routeTables: routeTableList,
-        noRouteTables,
+        routeTables: sample(routeTableList),
+        noRouteTables: sample(noRouteTableList),
         canonicalCrudTools: 'query_table/create_record/update_record/delete_record use dynamic REST routes and only work for route-backed tables.',
         customRouteWorkflow: 'For a new endpoint use create_route without mainTableId, then create_handler/create_pre_hook/create_post_hook. Do not create a table just to get a path.',
+        routeSamples: sample(routes, 25),
+        detailHint: 'Use get_all_routes({ search, limit }) or inspect_route({ path }) for route details. Use inspect_table({ tableName }) for table detail.',
       },
       schemaManagement: {
         createTable: 'POST /enfyra_table supports isSingleRecord at create time and supports columns and relations arrays in the same cascade call. MCP create_table exposes isSingleRecord, columns, and relations directly. It does not accept alias at create time; table name drives the default route/schema behavior.',
@@ -693,11 +737,10 @@ server.tool(
           : 'Use update_table graphqlEnabled, then reload_graphql if needed.',
         gqlDefinitionColumns: (gqlDefinition?.columns || []).map((column) => column.name),
       },
-      tableNames,
-      routes,
+      tableSamples: sample(tableNames, 40),
     };
 
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -709,36 +752,42 @@ server.tool(
   ].join(' '),
   {},
   async () => {
-    const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
-    const [
-      routesResult,
-      methodsResult,
-      gqlResult,
-      flowsResult,
-      websocketResult,
-      storageResult,
-      settingsResult,
-      meResult,
-    ] = await Promise.all([
-      fetchAPI(ENFYRA_API_URL, '/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000'),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_method?limit=100'),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_graphql?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_flow?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_websocket?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_storage_config?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
-      fetchAPI(ENFYRA_API_URL, '/enfyra_setting?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
-      fetchAPI(ENFYRA_API_URL, '/me').catch((error) => ({ error: String(error.message || error), data: [] })),
-    ]);
+    const metadata = await discoveryFetch('/metadata');
+    const routesResult = await discoveryFetch('/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000');
+    const methodsResult = await discoveryFetch('/enfyra_method?limit=100');
+    const gqlResult = await discoveryFetch('/enfyra_graphql?limit=1000');
+    const flowsResult = await discoveryFetch('/enfyra_flow?limit=1000');
+    const websocketResult = await discoveryFetch('/enfyra_websocket?limit=1000');
+    const storageResult = await discoveryFetch('/enfyra_storage_config?limit=1000');
+    const settingsResult = await discoveryFetch('/enfyra_setting?limit=1000');
+    const meResult = await discoveryFetch('/me', { fallbackData: null });
 
     const tables = normalizeTables(metadata);
     const routes = summarizeRoutes(routesResult);
     const routeTables = new Set(routes.map((route) => route.mainTable).filter(Boolean));
     const adminRoutes = routes.filter((route) => route.path?.startsWith('/admin'));
     const publicRoutes = routes.filter((route) => route.publicMethods?.length);
+    const sample = (items, max = 25) => ({
+      total: items.length,
+      returned: Math.min(items.length, max),
+      items: items.slice(0, max),
+      truncated: items.length > max,
+    });
 
     const payload = {
       targetInstance: targetInstance(),
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
+      partialErrors: collectPartialErrors({
+        metadata,
+        routesResult,
+        methodsResult,
+        gqlResult,
+        flowsResult,
+        websocketResult,
+        storageResult,
+        settingsResult,
+        meResult,
+      }),
       authenticatedUser: Array.isArray(meResult?.data) ? meResult.data[0] || null : meResult?.data || null,
       database: getMetadataDatabaseContext(metadata, tables),
       counts: {
@@ -759,12 +808,12 @@ server.tool(
       methods: (methodsResult?.data || []).map((method) => ({ id: method.id || method._id, name: method.name })),
       routeRuntime: {
         routePattern: 'GET/POST /<route-path>; PATCH/DELETE /<route-path>/:id; no dynamic GET /<route-path>/:id.',
-        adminRoutes: adminRoutes.map((route) => route.path).sort(),
-        publicRoutes: publicRoutes.map((route) => ({
+        adminRoutes: sample(adminRoutes.map((route) => route.path).sort()),
+        publicRoutes: sample(publicRoutes.map((route) => ({
           path: route.path,
           mainTable: route.mainTable,
           publicMethods: route.publicMethods,
-        })),
+        }))),
       },
       cacheAndCluster: {
         metadataMutationReloads: 'Metadata-backed mutations emit cache invalidation; admin reload endpoints exist for metadata/routes/graphql/guards/all.',
@@ -781,7 +830,7 @@ server.tool(
         'MCP can test flow steps and websocket scripts through admin test endpoints, but not prove every production queue/client path without a real end-to-end client.',
       ].filter(Boolean),
     };
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -795,8 +844,8 @@ server.tool(
     tableName: z.string().optional().describe('Optional table name to summarize query fields and relation/deep capabilities.'),
   },
   async ({ tableName }) => {
-    const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
-    const routesResult = await fetchAPI(ENFYRA_API_URL, '/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000');
+    const metadata = await discoveryFetch('/metadata');
+    const routesResult = await discoveryFetch('/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000');
     const tables = normalizeTables(metadata);
     const routes = summarizeRoutes(routesResult);
     const table = tableName ? tables.find((item) => item.name === tableName) : null;
@@ -807,6 +856,7 @@ server.tool(
 
     const payload = {
       targetInstance: targetInstance(),
+      partialErrors: collectPartialErrors({ metadata, routesResult }),
       operators: {
         filter: FILTER_OPERATORS,
         fieldPermissionConditions: FIELD_PERMISSION_CONDITION_OPERATORS,
@@ -862,7 +912,7 @@ server.tool(
       discoveryRule: 'When building a query, inspect table metadata first, then use relation propertyName and primary column from that metadata.',
     };
 
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -1002,7 +1052,7 @@ server.tool(
       },
     };
 
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -1014,6 +1064,7 @@ server.tool(
   'get_enfyra_api_context',
   [
     'Returns the resolved API base URL for this MCP session (env ENFYRA_API_URL).',
+    'Use this as the cheap first target sanity check before broad discovery or mutations.',
     'Use when the user asks which HTTP endpoint or full URL applies: combine enfyraApiUrl with paths from server instructions (GET/POST /{table}, PATCH/DELETE /{table}/{id}, no GET /{table}/{id}).',
     'Auth: publicMethods on a route can allow a method without Bearer; otherwise JWT + routePermissions — see server instructions.',
     'If path might differ from table name, use get_all_routes before asserting a URL.',
@@ -1025,6 +1076,7 @@ server.tool(
     const base = ENFYRA_API_URL.replace(/\/$/, '');
     const gql = buildGraphqlUrls(ENFYRA_API_URL);
     const payload = {
+      targetInstance: targetInstance(),
       enfyraApiUrl: base,
       graphqlHttpUrl: gql.graphqlHttpUrl,
       graphqlSchemaUrl: gql.graphqlSchemaUrl,
@@ -1041,7 +1093,7 @@ server.tool(
       pathResolution: 'Confirm route path with get_all_routes or metadata — path may not equal table name.',
       note: 'Full tool→HTTP mapping is in MCP server instructions (shown to the model at connect).',
     };
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -1703,6 +1755,51 @@ async function collectRestDefinitionState() {
   };
 }
 
+async function collectFeatureSearchState() {
+  const metadata = await discoveryFetch('/metadata');
+  const routesResult = await discoveryFetch('/enfyra_route?limit=500');
+  const handlersResult = await discoveryFetch('/enfyra_route_handler?limit=500');
+  const preHooksResult = await discoveryFetch('/enfyra_pre_hook?limit=500');
+  const postHooksResult = await discoveryFetch('/enfyra_post_hook?limit=500');
+  const routePermissionsResult = await discoveryFetch('/enfyra_route_permission?limit=500');
+  const guardsResult = await discoveryFetch('/enfyra_guard?limit=500');
+  const guardRulesResult = await discoveryFetch('/enfyra_guard_rule?limit=500');
+  const fieldPermissionsResult = await discoveryFetch('/enfyra_field_permission?limit=500');
+  const columnRulesResult = await discoveryFetch('/enfyra_column_rule?limit=500');
+  const methodsResult = await discoveryFetch('/enfyra_method?limit=100');
+  const methodIdNameMap = Object.fromEntries(
+    unwrapData(methodsResult).map((method) => [String(getId(method)), method.name]),
+  );
+
+  return {
+    metadata,
+    tables: normalizeTables(metadata),
+    routes: unwrapData(routesResult),
+    handlers: unwrapData(handlersResult),
+    preHooks: unwrapData(preHooksResult),
+    postHooks: unwrapData(postHooksResult),
+    routePermissions: unwrapData(routePermissionsResult),
+    guards: unwrapData(guardsResult),
+    guardRules: unwrapData(guardRulesResult),
+    fieldPermissions: unwrapData(fieldPermissionsResult),
+    columnRules: unwrapData(columnRulesResult),
+    methodIdNameMap,
+    partialErrors: collectPartialErrors({
+      metadata,
+      routesResult,
+      handlersResult,
+      preHooksResult,
+      postHooksResult,
+      routePermissionsResult,
+      guardsResult,
+      guardRulesResult,
+      fieldPermissionsResult,
+      columnRulesResult,
+      methodsResult,
+    }),
+  };
+}
+
 function enrichRoute(route, state) {
   const routeId = getId(route);
   const routeHandlers = state.handlers
@@ -1868,7 +1965,7 @@ server.tool(
       throw new Error('inspect_feature query must be at least 2 characters. Use a table name, route path, event name, or specific feature keyword.');
     }
     const max = Math.max(1, Math.min(Number(limit || 8), 25));
-    const state = await collectRestDefinitionState();
+    const state = await collectFeatureSearchState();
     const q = rawQuery.toLowerCase();
     const matchesText = (value) => JSON.stringify(value ?? '').toLowerCase().includes(q);
     const tableMatches = state.tables.filter((table) => matchesText({
@@ -1892,6 +1989,7 @@ server.tool(
       targetInstance: targetInstance(),
       query: rawQuery,
       limit: max,
+      partialErrors: state.partialErrors,
       counts: {
         tables: tableMatches.length,
         routes: routeMatches.length,