@enfyra/mcp-server 0.0.13 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-instructions.js

@@ -33,8 +33,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Direct to Nest:** `http://localhost:1105` — no `/api` suffix on default Nest. Wrong: `http://localhost:1105/api/table_definition` (404) unless a proxy adds `/api`.',
     '- GraphQL: `{base}/graphql` and `{base}/graphql-schema` always share this same base.',
     '',
+    '### Routes vs tables (custom endpoints, handlers, hooks)',
+    '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** with **`mainTableId`** of an **existing** table (resolve id via **`get_all_tables`**, **`get_all_metadata`**, or **`get_all_routes`**).',
+    '- **Wrong pattern:** calling **`create_table`** just to get an HTTP path, then overriding handlers on the **default** auto route `/{table_name}`. That adds unnecessary schema and breaks the usual CRUD surface for that table.',
+    '- **`create_table`** is only when the user needs **new persisted data** (new entity + columns). It is **not** the right tool when the goal is only a new path or custom script.',
+    '- **Right pattern:** **`create_route`** → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Same underlying table can have **multiple** routes (e.g. default CRUD at `/orders` and custom `/orders/stats` both pointing at `mainTable` orders).',
+    '',
     '### After a new table is created',
-    '- Enfyra creates a route at `/{table_name}` using the table **name** from `create_table` (not the alias).',
+    '- Enfyra creates a **default** route at `/{table_name}` using the table **name** from `create_table` (not the alias). Prefer **`create_route`** for additional or custom paths instead of new tables.',
     '- **Four REST HTTP operations** on that resource:',
     `  - **GET** \`${getList}\` — list / filter (query: filter, sort, page, limit, fields, meta).`,
     `  - **POST** \`${getList}\` — create (JSON body).`,
@@ -100,10 +106,21 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Enfyra uses **Socket.IO**. Gateways and events are stored in **`websocket_definition`** and **`websocket_event_definition`**; manage via REST (MCP `create_record`, `update_record`, `query_table` on those tables).',
     '- **Gateway** (`websocket_definition`): `path` = namespace (e.g. `/chat`), `requireAuth` (JWT in `auth.token`), `connectionHandlerScript` (runs on connect), `connectionHandlerTimeout`, `isEnabled`.',
     '- **Event** (`websocket_event_definition`): `gateway` → gateway id, `eventName` (client emits), `handlerScript`, `timeout`, `isEnabled`.',
-    '- **@SOCKET** in scripts: Connection handler — `@SOCKET.emit(event, data)` → this client; `@SOCKET.to(room).emit(event, data)` → room. Event handler — `@SOCKET.emit` → broadcast namespace; `@SOCKET.send` → this client; `@SOCKET.to(room).emit` → room.',
+    '- **@SOCKET in scripts (prefer template `@SOCKET.method()` over `$ctx.$socket.method()`):**',
+    '-   `@SOCKET.reply(event, data)` — send to this client only (WS context only).',
+    '-   `@SOCKET.join(room)` — join a room (WS context only).',
+    '-   `@SOCKET.leave(room)` — leave a room (WS context only).',
+    '-   `@SOCKET.emitToUser(userId, event, data)` — send to a specific user (across all gateways).',
+    '-   `@SOCKET.emitToRoom(room, event, data)` — send to a named room (across all gateways).',
+    '-   `@SOCKET.emitToGateway(path, event, data)` — broadcast to all connections on a gateway/namespace.',
+    '-   `@SOCKET.broadcast(event, data)` — broadcast to all connections on all gateways.',
+    '-   `@SOCKET.disconnect()` — force-disconnect the current socket from the gateway (WS context only). Use in connection handler to reject, or in event handler to kick user.',
+    '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect` are not available (no socket). Use `emitToUser`, `emitToRoom`, `emitToGateway`, `broadcast`.',
     '- **Context**: Connection — `@BODY` = {id, ip, headers}, `@USER` if auth. Event — `@BODY` = payload, `@USER` if auth. Both have `@SOCKET`.',
+    '- **ACK + results (recommended UX):** client can emit an event with Socket.IO ack callback. Server immediately acks `{ queued: true, requestId, eventName }` (or `{ queued: false, error }`). The handler result is returned asynchronously via `ws:result` or `ws:error` with the same `requestId`.',
     '- **Client**: `io("<HTTP_ORIGIN>/namespace", {auth: {token: JWT}})`. Use the **origin where Socket.IO is served** (usually the **Nest** HTTP origin, e.g. `http://localhost:1105/chat` in local server-only setups). If Socket.IO is exposed only through the Nuxt app, use that host and your deployment’s WS path—**do not** assume port 3000 without checking `API_URL` / proxy config. Gateway `path` in metadata = Socket.IO **namespace**.',
     '- **Workflow**: Create gateway → `create_record` on `websocket_definition`. Create event → `create_record` on `websocket_event_definition` with `gateway: {id}`. Changes auto-reload; test handlers before saving.',
+    '- **Test WS handler (recommended):** `POST {base}/admin/test/run` with `{ kind:"websocket_event", gatewayPath, eventName, timeoutMs, payload, script }` to run a websocket event script without a real client. Returns `{ success, result, logs, emitted }`.',
     '',
     '### Flows (Automated Workflows)',
     '- Enfyra supports automated workflows via **`flow_definition`**, **`flow_step_definition`**, and **`flow_execution_definition`** tables.',
@@ -199,6 +216,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- API testing is available at `/settings/api-tester` in the app UI.',
     '',
     '### MCP tool → HTTP',
+    '- **Routes:** `create_route` / `create_handler` / `create_pre_hook` / `create_post_hook` persist to `route_definition`, `route_handler_definition`, etc. (REST CRUD on those tables). Prefer **`create_route`** for new paths — not `create_table`.',
     `- \`get_all_metadata\` → GET \`${base}/metadata\``,
     `- \`get_table_metadata\` → GET \`${base}/metadata/<tableName>\``,
     `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args)`,

package/src/lib/table-tools.js

@@ -39,9 +39,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'create_table',
     [
       'Create a new table definition with an auto-included `id` primary key column.',
+      '**Not** for adding a custom API path or handler only — for that use **`create_route`** with an existing `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
       'Use create_column to add more columns after creation (columns are managed via cascade PATCH on table_definition, NOT via /column_definition).',
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
-      'Enfyra auto-creates a REST route at path `/<table_name>` (same segment as `name`, not alias).',
+      'Enfyra auto-creates a default REST route at path `/<table_name>` (same segment as `name`, not alias).',
       'REST surface for that route (matches server route engine): 4 HTTP operations — GET `/<table>` (list/filter), POST `/<table>` (create), PATCH `/<table>/:id` (update), DELETE `/<table>/:id` (delete).',
       'There is NO `GET /<table>/:id`. To fetch one row by id, use GET `/<table>?filter={"id":{"_eq":"<id>"}}&limit=1` or tool query_table / find_one_record.',
       `Full URLs: ${apiBase}/<table_name> (example table post: ${apiBase}/post).`,

package/src/mcp-server-entry.mjs

@@ -177,7 +177,26 @@ server.tool('delete_record', 'Delete a record by ID', {
 // ROUTE & HANDLER TOOLS
 // ============================================================================
 
-server.tool('get_all_routes', 'Get all route definitions with handlers, hooks, and permissions', {
+let _methodMap = null;
+async function getMethodMap() {
+  if (_methodMap) return _methodMap;
+  const result = await fetchAPI(ENFYRA_API_URL, '/method_definition?limit=0');
+  _methodMap = {};
+  for (const m of result.data) {
+    _methodMap[m.method] = m.id || m._id;
+  }
+  return _methodMap;
+}
+
+function resolveMethodIds(methodMap, names) {
+  return names.map(m => {
+    const id = methodMap[m.toUpperCase()];
+    if (!id) throw new Error(`Unknown method "${m}". Valid: ${Object.keys(methodMap).join(', ')}`);
+    return { id };
+  });
+}
+
+server.tool('get_all_routes', 'List all route definitions (path, mainTable, handlers, hooks, permissions). Call before create_route to avoid duplicate paths and to pick routeId for hooks/handlers.', {
   includeDisabled: z.boolean().optional().default(false).describe('Include disabled routes'),
 }, async ({ includeDisabled }) => {
   const filter = includeDisabled ? {} : { isEnabled: { _eq: true } };
@@ -185,57 +204,168 @@ server.tool('get_all_routes', 'Get all route definitions with handlers, hooks, a
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
 
-server.tool('create_route', 'Create a new route definition', {
-  path: z.string().describe('Route path (e.g., "/api/users")'),
-  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'REST', 'GQL_QUERY', 'GQL_MUTATION']).describe('HTTP method'),
-  tableId: z.string().describe('Main table ID for this route'),
-  isEnabled: z.boolean().optional().default(true).describe('Enable route'),
-  description: z.string().optional().describe('Route description'),
-}, async ({ path, method, tableId, isEnabled, description }) => {
-  const result = await fetchAPI(ENFYRA_API_URL, '/route_definition', {
-    method: 'POST',
-    body: JSON.stringify({ path, method, tableId, isEnabled, description }),
-  });
-  return { content: [{ type: 'text', text: `Route created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
-});
+server.tool(
+  'create_route',
+  [
+    '**Use this when the user wants a new API route or path** — not `create_table`. A route links a URL path to an existing table (`mainTableId`) and sets HTTP/GQL methods.',
+    'Do NOT create a new table_definition only to expose an endpoint; pick `mainTableId` from existing metadata unless the user explicitly needs new tables/columns.',
+    'availableMethods = which verbs the route responds to. publishedMethods = which verbs are public (no auth).',
+    'After creation the tool auto-reloads routes. Then create handlers for specific methods via create_handler on this route id.',
+    'Flow: resolve table id → create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
+  ].join(' '),
+  {
+    path: z.string().describe('URL path, must start with / (e.g., "/my-endpoint")'),
+    mainTableId: z.union([z.string(), z.number()]).describe('ID of the table_definition this route operates on. The route\'s $repos.main will query this table.'),
+    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE', 'GQL_QUERY', 'GQL_MUTATION']))
+      .describe('HTTP/GQL methods this route supports (availableMethods). Common: ["GET","POST","PATCH","DELETE"]'),
+    publishedMethods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE', 'GQL_QUERY', 'GQL_MUTATION'])).optional()
+      .describe('Methods accessible WITHOUT auth token. Omit = all methods require auth.'),
+    isEnabled: z.boolean().optional().default(true).describe('Enable route immediately'),
+    description: z.string().optional().describe('Route description'),
+  },
+  async ({ path: routePath, mainTableId, methods, publishedMethods, isEnabled, description }) => {
+    const methodMap = await getMethodMap();
 
-server.tool('create_handler', 'Create a handler for a route. Use template syntax: @BODY, @USER, #table_name, @THROW404', {
-  routeId: z.string().describe('Route definition ID'),
-  logic: z.string().describe('Handler logic (JavaScript code)'),
-  timeout: z.number().optional().describe('Handler timeout in ms (default: 30000)'),
-}, async ({ routeId, logic, timeout }) => {
-  const result = await fetchAPI(ENFYRA_API_URL, '/route_handler_definition', {
-    method: 'POST',
-    body: JSON.stringify({ routeId, logic, timeout: timeout || 30000 }),
-  });
-  return { content: [{ type: 'text', text: `Handler created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
-});
+    const body = {
+      path: routePath.startsWith('/') ? routePath : '/' + routePath,
+      mainTable: { id: mainTableId },
+      isEnabled,
+      description,
+      availableMethods: resolveMethodIds(methodMap, methods),
+    };
 
-server.tool('create_pre_hook', 'Create a pre-hook for a route. Use template syntax: @BODY, @QUERY, @USER', {
-  routeId: z.string().describe('Route definition ID'),
-  code: z.string().describe('Hook code (JavaScript)'),
-  methods: z.array(z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])).optional().describe('Methods this hook applies to'),
-  order: z.number().optional().default(0).describe('Hook execution order'),
-}, async ({ routeId, code, methods, order }) => {
-  const result = await fetchAPI(ENFYRA_API_URL, '/pre_hook_definition', {
-    method: 'POST',
-    body: JSON.stringify({ routeId, code, methods: methods || ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], order }),
-  });
-  return { content: [{ type: 'text', text: `Pre-hook created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
-});
+    if (publishedMethods && publishedMethods.length > 0) {
+      body.publishedMethods = resolveMethodIds(methodMap, publishedMethods);
+    }
 
-server.tool('create_post_hook', 'Create a post-hook for a route. Use template syntax: @DATA, @STATUS', {
-  routeId: z.string().describe('Route definition ID'),
-  code: z.string().describe('Hook code (JavaScript)'),
-  methods: z.array(z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])).optional().describe('Methods this hook applies to'),
-  order: z.number().optional().default(0).describe('Hook execution order'),
-}, async ({ routeId, code, methods, order }) => {
-  const result = await fetchAPI(ENFYRA_API_URL, '/post_hook_definition', {
-    method: 'POST',
-    body: JSON.stringify({ routeId, code, methods: methods || ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], order }),
-  });
-  return { content: [{ type: 'text', text: `Post-hook created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
-});
+    const result = await fetchAPI(ENFYRA_API_URL, '/route_definition', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+
+    return { content: [{ type: 'text', text: `Route created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+  },
+);
+
+server.tool(
+  'create_handler',
+  [
+    'Create a handler for a route+method. One handler per (route, method) pair.',
+    'Attach to the route the user cares about (`get_all_routes`): typically a path from `create_route`, not a spurious table created only for handlers.',
+    'Handler code runs inside a sandbox with $ctx. Use macros: @BODY, @QUERY, @PARAMS, @USER, @REPOS, @HELPERS, @THROW400..@THROW503, @SOCKET, @PKGS, @LOGS, @SHARE.',
+    'Or use $ctx directly: $ctx.$body, $ctx.$repos.main.find(), $ctx.$helpers.$bcrypt.hash(), etc.',
+    'require("pkg") works for installed Server packages. console.log() writes to $share.$logs.',
+  ].join(' '),
+  {
+    routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
+    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE', 'GQL_QUERY', 'GQL_MUTATION']))
+      .describe('Methods to create handlers for. Creates one handler per method.'),
+    logic: z.string().describe('Handler JavaScript code'),
+    timeout: z.number().optional().describe('Timeout in ms (default: system DEFAULT_HANDLER_TIMEOUT, usually 30000)'),
+  },
+  async ({ routeId, methods, logic, timeout }) => {
+    const methodMap = await getMethodMap();
+    const results = [];
+
+    for (const method of methods) {
+      const methodId = methodMap[method.toUpperCase()];
+      if (!methodId) throw new Error(`Unknown method: ${method}. Valid: ${Object.keys(methodMap).join(', ')}`);
+
+      const body = { route: { id: routeId }, method: { id: methodId }, logic };
+      if (timeout) body.timeout = timeout;
+
+      const result = await fetchAPI(ENFYRA_API_URL, '/route_handler_definition', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      results.push(result);
+    }
+
+    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+
+    return { content: [{ type: 'text', text: `Handler(s) created for [${methods.join(', ')}]. Routes reloaded.\n${JSON.stringify(results, null, 2)}` }] };
+  },
+);
+
+server.tool(
+  'create_pre_hook',
+  [
+    'Create a pre-hook that runs BEFORE the handler. Use to validate, transform, or inject data.',
+    'Use `routeId` from `create_route` or `get_all_routes` — do not create a new table just to get a route id.',
+    'Macros: @BODY, @QUERY, @PARAMS, @USER, @REPOS, @HELPERS, @THROW400..@THROW503.',
+    'If the hook returns a value, that value becomes the response (handler is skipped).',
+  ].join(' '),
+  {
+    routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
+    name: z.string().describe('Hook name (unique per route)'),
+    code: z.string().describe('Hook JavaScript code'),
+    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
+      .describe('Methods this hook applies to. Default: all REST methods.'),
+    priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
+    isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+  },
+  async ({ routeId, name, code, methods, priority, isEnabled }) => {
+    const methodMap = await getMethodMap();
+    const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
+
+    const result = await fetchAPI(ENFYRA_API_URL, '/pre_hook_definition', {
+      method: 'POST',
+      body: JSON.stringify({
+        route: { id: routeId },
+        name,
+        code,
+        methods: resolveMethodIds(methodMap, methodNames),
+        priority,
+        isEnabled,
+      }),
+    });
+
+    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+
+    return { content: [{ type: 'text', text: `Pre-hook "${name}" created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+  },
+);
+
+server.tool(
+  'create_post_hook',
+  [
+    'Create a post-hook that runs AFTER the handler. Use to transform responses or add metadata.',
+    'Use `routeId` from `create_route` or `get_all_routes` — do not create a new table just to get a route id.',
+    'Macros: @DATA (handler result), @STATUS (HTTP status code), @BODY, @QUERY, @USER, @SHARE.',
+    'Must return a value — that becomes the final response.',
+  ].join(' '),
+  {
+    routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
+    name: z.string().describe('Hook name (unique per route)'),
+    code: z.string().describe('Hook JavaScript code'),
+    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
+      .describe('Methods this hook applies to. Default: all REST methods.'),
+    priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
+    isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+  },
+  async ({ routeId, name, code, methods, priority, isEnabled }) => {
+    const methodMap = await getMethodMap();
+    const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
+
+    const result = await fetchAPI(ENFYRA_API_URL, '/post_hook_definition', {
+      method: 'POST',
+      body: JSON.stringify({
+        route: { id: routeId },
+        name,
+        code,
+        methods: resolveMethodIds(methodMap, methodNames),
+        priority,
+        isEnabled,
+      }),
+    });
+
+    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+
+    return { content: [{ type: 'text', text: `Post-hook "${name}" created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+  },
+);
 
 // Register table tools
 registerTableTools(server, ENFYRA_API_URL);
@@ -410,8 +540,8 @@ server.tool(
       pkgDescription = exactMatch.package.description || '';
     }
 
-    // Step 2: Check if already installed
-    const checkFilter = JSON.stringify({ name: { _eq: name } });
+    // Step 2: Check if already installed (same name AND type)
+    const checkFilter = JSON.stringify({ name: { _eq: name }, type: { _eq: type } });
     const existing = await fetchAPI(ENFYRA_API_URL, `/package_definition?filter=${encodeURIComponent(checkFilter)}&limit=1`);
     if (existing.data && existing.data.length > 0) {
       return {
@@ -456,7 +586,7 @@ server.tool(
 
 server.tool('create_menu', 'Create a menu item in the navigation', {
   label: z.string().describe('Menu label'),
-  type: z.enum(['separator', 'link', 'route', 'dropdown', 'widget', 'extension']).describe('Menu type'),
+  type: z.enum(['Menu', 'Dropdown Menu']).default('Menu').describe('Menu type: "Menu" for leaf items, "Dropdown Menu" for items with children'),
   icon: z.string().optional().describe('Lucide icon name'),
   path: z.string().optional().describe('Route path for type=route'),
   externalUrl: z.string().optional().describe('External URL for type=link'),
@@ -464,7 +594,11 @@ server.tool('create_menu', 'Create a menu item in the navigation', {
   isEnabled: z.boolean().optional().default(true).describe('Enable menu'),
   description: z.string().optional().describe('Menu description'),
 }, async (data) => {
-  const result = await fetchAPI(ENFYRA_API_URL, '/menu_definition', { method: 'POST', body: JSON.stringify(data) });
+  const body = { ...data };
+  if (body.path && !body.path.startsWith('/')) {
+    body.path = '/' + body.path;
+  }
+  const result = await fetchAPI(ENFYRA_API_URL, '/menu_definition', { method: 'POST', body: JSON.stringify(body) });
   return { content: [{ type: 'text', text: `Menu created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
 });
 
@@ -481,6 +615,7 @@ server.tool(
     menuId: z.string().optional().describe('Required for type=page — menu_definition id from create_menu. Omit for widget'),
     isEnabled: z.boolean().optional().default(true).describe('Enable extension'),
     description: z.string().optional().describe('Extension description'),
+    version: z.string().optional().default('1.0.0').describe('Extension version'),
   },
   async (data) => {
     const body = { ...data };