@enfyra/mcp-server 0.0.91 → 0.0.92

package/package.json

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

@@ -353,6 +353,13 @@ 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 getMetadataTables() {
   const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
   return {
@@ -617,6 +624,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.',
+    'Run broad discovery tools sequentially; do not call multiple broad discovery tools in parallel.',
   ].join(' '),
   {},
   async () => {
@@ -637,6 +645,7 @@ server.tool(
     const routeTableList = [...routeTables].sort();
 
     const payload = {
+      targetInstance: targetInstance(),
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
       counts: {
         tables: tableNames.length,
@@ -696,7 +705,7 @@ 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 () => {
@@ -728,6 +737,7 @@ server.tool(
     const publicRoutes = routes.filter((route) => route.publicMethods?.length);
 
     const payload = {
+      targetInstance: targetInstance(),
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
       authenticatedUser: Array.isArray(meResult?.data) ? meResult.data[0] || null : meResult?.data || null,
       database: getMetadataDatabaseContext(metadata, tables),
@@ -779,7 +789,7 @@ 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.'),
@@ -796,6 +806,7 @@ server.tool(
       : [];
 
     const payload = {
+      targetInstance: targetInstance(),
       operators: {
         filter: FILTER_OPERATORS,
         fieldPermissionConditions: FIELD_PERMISSION_CONDITION_OPERATORS,
@@ -859,11 +870,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.',
@@ -1844,14 +1856,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 }) => {
+  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 collectRestDefinitionState();
-    const q = query.toLowerCase();
+    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 +1889,9 @@ server.tool(
     ];
 
     const payload = {
-      query,
+      targetInstance: targetInstance(),
+      query: rawQuery,
+      limit: max,
       counts: {
         tables: tableMatches.length,
         routes: routeMatches.length,
@@ -1881,13 +1901,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) }] };