@enfyra/mcp-server 0.0.93 → 0.0.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.93",
+  "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

@@ -391,6 +391,10 @@ function collectPartialErrors(results) {
     .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 {
@@ -615,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', {
@@ -632,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(
@@ -646,7 +650,7 @@ server.tool(
   },
   async ({ category }) => {
     const result = getExamples(category);
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    return jsonContent(result);
   },
 );
 
@@ -655,6 +659,7 @@ 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(' '),
   {},
@@ -672,6 +677,13 @@ 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(),
@@ -692,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.',
@@ -723,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);
   },
 );
 
@@ -754,6 +767,12 @@ server.tool(
     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(),
@@ -789,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.',
@@ -811,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);
   },
 );
 
@@ -893,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);
   },
 );
 
@@ -1033,7 +1052,7 @@ server.tool(
       },
     };
 
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    return jsonContent(payload);
   },
 );
 
@@ -1045,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.',
@@ -1056,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,
@@ -1072,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);
   },
 );