@enfyra/mcp-server 0.0.91 → 0.0.93

package/package.json

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

package/src/lib/mcp-instructions.js

@@ -24,7 +24,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `GraphQL endpoints: \`${graphqlHttpUrl}\` and \`${graphqlSchemaUrl}\`.`,
     '',
     '### Work Flow',
-    '- 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`.',
+    '- 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.',
     '- For server scripts, call `discover_script_contexts` before writing or reviewing handler/hook/flow/websocket/GraphQL logic.',

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';
@@ -353,6 +354,43 @@ async function fetchAll(path) {
   return unwrapData(await fetchAPI(ENFYRA_API_URL, path));
 }
 
+function targetInstance() {
+  return {
+    apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
+    source: 'ENFYRA_API_URL environment variable used by this MCP server process',
+  };
+}
+
+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 }));
+}
+
 async function getMetadataTables() {
   const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
   return {
@@ -617,14 +655,13 @@ 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.',
+    '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();
@@ -637,7 +674,9 @@ server.tool(
     const routeTableList = [...routeTables].sort();
 
     const payload = {
+      targetInstance: targetInstance(),
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
+      partialErrors: collectPartialErrors({ metadata, routesResult, methodsResult }),
       counts: {
         tables: tableNames.length,
         routes: routes.length,
@@ -696,30 +735,19 @@ server.tool(
   'discover_runtime_context',
   [
     'Discover live runtime context that affects how an LLM should use Enfyra.',
-    'Reports inferred primary key/backend family, route/cache/admin surfaces, active metadata-backed runtime areas, and what is not exposed by the backend API.',
+    'Reports inferred primary key/backend family, route/cache/admin surfaces, active metadata-backed runtime areas, and what is not exposed by the backend API. 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,
-      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);
@@ -728,7 +756,19 @@ server.tool(
     const publicRoutes = routes.filter((route) => route.publicMethods?.length);
 
     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: {
@@ -779,14 +819,14 @@ server.tool(
   'discover_query_capabilities',
   [
     'Discover Enfyra query/filter/deep-fetch capabilities for the live instance.',
-    'Optionally pass tableName to include columns, relations, primary key, route paths, and examples for that table.',
+    'Prefer passing tableName. Without tableName this returns only generic query rules. Run broad discovery tools sequentially; do not call multiple broad discovery tools in parallel.',
   ].join(' '),
   {
     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;
@@ -796,6 +836,8 @@ server.tool(
       : [];
 
     const payload = {
+      targetInstance: targetInstance(),
+      partialErrors: collectPartialErrors({ metadata, routesResult }),
       operators: {
         filter: FILTER_OPERATORS,
         fieldPermissionConditions: FIELD_PERMISSION_CONDITION_OPERATORS,
@@ -859,11 +901,12 @@ server.tool(
   'discover_script_contexts',
   [
     'Discover runtime script contexts and macro availability for handlers, hooks, flows, websocket scripts, GraphQL, packages, and extensions.',
-    'Use before writing dynamic JavaScript logic so the model does not mix context variables across surfaces.',
+    'Use before writing dynamic JavaScript logic so the model does not mix context variables across surfaces. This tool is static and safe to call alone; avoid running it in parallel with other broad discovery calls.',
   ].join(' '),
   {},
   async () => {
     const payload = {
+      targetInstance: targetInstance(),
       transformer: {
         rule: 'Dynamic server scripts are transformed before sandbox execution. Macros expand to $ctx paths; comments are not transformed.',
         preferredSyntax: 'Prefer template macros in generated Enfyra scripts. Use macros such as @BODY/@QUERY/@PARAMS/@USER/@REQ/@RES/@REPOS/@CACHE/@HELPERS/@FETCH/@STORAGE/@UPLOADED_FILE/@SOCKET/@TRIGGER/@DATA/@ERROR/@STATUS/@ENV/@PKGS/@LOGS/@SHARE/@API/@THROW* instead of raw $ctx access whenever a macro exists. Use raw $ctx only for fields without a macro.',
@@ -1691,6 +1734,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
@@ -1844,14 +1932,20 @@ server.tool(
   'inspect_feature',
   [
     'Search live REST/system metadata for a feature name, route path, table, handler, hook, guard, or permission.',
-    'Use when the user mentions a capability and you need to find where it lives before editing.',
+    'Use when the user mentions a capability and you need to find where it lives before editing. Keep the query specific; broad searches return bounded summaries.',
   ].join(' '),
   {
     query: z.string().describe('Feature keyword, table name, route path, handler text, hook name, or guard name'),
+    limit: z.number().int().positive().max(25).optional().default(8).describe('Maximum matches returned per section. Default 8 to keep output small.'),
   },
-  async ({ query }) => {
-    const state = await collectRestDefinitionState();
-    const q = query.toLowerCase();
+  async ({ query, limit }) => {
+    const rawQuery = String(query || '').trim();
+    if (rawQuery.length < 2) {
+      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 collectFeatureSearchState();
+    const q = rawQuery.toLowerCase();
     const matchesText = (value) => JSON.stringify(value ?? '').toLowerCase().includes(q);
     const tableMatches = state.tables.filter((table) => matchesText({
       name: table.name,
@@ -1871,7 +1965,10 @@ server.tool(
     ];
 
     const payload = {
-      query,
+      targetInstance: targetInstance(),
+      query: rawQuery,
+      limit: max,
+      partialErrors: state.partialErrors,
       counts: {
         tables: tableMatches.length,
         routes: routeMatches.length,
@@ -1881,13 +1978,14 @@ server.tool(
         guards: guardMatches.length,
         permissions: permissionMatches.length,
       },
-      tables: tableMatches.map(summarizeTable).slice(0, 20),
-      routes: routeMatches.map((route) => enrichRoute(route, state)).slice(0, 20),
-      handlers: handlerMatches.slice(0, 20),
-      preHooks: preHookMatches.slice(0, 20),
-      postHooks: postHookMatches.slice(0, 20),
-      guards: guardMatches.slice(0, 20),
-      permissions: permissionMatches.slice(0, 20),
+      tables: tableMatches.slice(0, max).map(summarizeTable),
+      routes: routeMatches.slice(0, max).map((route) => enrichRoute(route, state)),
+      handlers: handlerMatches.slice(0, max),
+      preHooks: preHookMatches.slice(0, max),
+      postHooks: postHookMatches.slice(0, max),
+      guards: guardMatches.slice(0, max),
+      permissions: permissionMatches.slice(0, max),
+      detailHint: 'For a specific match, call inspect_table, inspect_route, trace_metadata_usage, or get_script_source instead of broadening this search.',
     };
 
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };