@enfyra/mcp-server 0.0.9 → 0.0.11

package/package.json

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

package/src/index.mjs

@@ -351,6 +351,109 @@ server.tool('login', 'Force login to Enfyra and get new tokens', {
   return { content: [{ type: 'text', text: `Logged in successfully!\nToken expires: ${new Date(getTokenExpiry()).toISOString()}` }] };
 });
 
+// ============================================================================
+// PACKAGE TOOLS
+// ============================================================================
+
+server.tool(
+  'search_npm',
+  'Search NPM registry for packages. Returns name, version, description for installation.',
+  {
+    query: z.string().describe('Package name or search term (e.g., "axios", "node-ssh", "dayjs")'),
+    limit: z.number().optional().default(5).describe('Max results (default: 5)'),
+  },
+  async ({ query, limit }) => {
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`NPM search failed: ${response.statusText}`);
+    const data = await response.json();
+
+    const packages = data.objects.map((obj) => ({
+      name: obj.package.name,
+      version: obj.package.version,
+      description: obj.package.description || '',
+    }));
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ packages, total: data.total }, null, 2),
+      }],
+    };
+  },
+);
+
+server.tool(
+  'install_package',
+  [
+    'Install an NPM package on Enfyra. Searches NPM registry for exact version, then creates package_definition record.',
+    'Enfyra handles the actual yarn add internally based on type.',
+    'Type "Server" = available in handlers/hooks as $ctx.$pkgs.packageName.',
+    'Type "App" = available in extensions via getPackages().',
+  ].join(' '),
+  {
+    name: z.string().describe('Exact NPM package name (e.g., "node-ssh", "axios")'),
+    type: z.enum(['Server', 'App']).default('Server').describe('Where to install: Server (handlers/hooks) or App (extensions)'),
+    version: z.string().optional().describe('Specific version. If omitted, fetches latest from NPM.'),
+  },
+  async ({ name, type, version }) => {
+    // Step 1: Get package info from NPM if version not specified
+    let pkgVersion = version;
+    let pkgDescription = '';
+
+    if (!pkgVersion) {
+      const npmUrl = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(name)}&size=5`;
+      const npmResponse = await fetch(npmUrl);
+      if (!npmResponse.ok) throw new Error(`NPM search failed: ${npmResponse.statusText}`);
+      const npmData = await npmResponse.json();
+
+      const exactMatch = npmData.objects.find((obj) => obj.package.name === name);
+      if (!exactMatch) throw new Error(`Package "${name}" not found on NPM`);
+
+      pkgVersion = exactMatch.package.version;
+      pkgDescription = exactMatch.package.description || '';
+    }
+
+    // Step 2: Check if already installed
+    const checkFilter = JSON.stringify({ name: { _eq: name } });
+    const existing = await fetchAPI(ENFYRA_API_URL, `/package_definition?filter=${encodeURIComponent(checkFilter)}&limit=1`);
+    if (existing.data && existing.data.length > 0) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Package "${name}" is already installed (version: ${existing.data[0].version}, type: ${existing.data[0].type}).\n${JSON.stringify(existing.data[0], null, 2)}`,
+        }],
+      };
+    }
+
+    // Step 3: Get current user for installedBy
+    const me = await fetchAPI(ENFYRA_API_URL, '/me');
+    const userId = me.data?.[0]?.id || me.data?.[0]?._id;
+    if (!userId) throw new Error('Cannot get current user ID');
+
+    // Step 4: Install via package_definition
+    const body = {
+      name,
+      version: pkgVersion,
+      description: pkgDescription,
+      type,
+      installedBy: { id: userId },
+    };
+
+    const result = await fetchAPI(ENFYRA_API_URL, '/package_definition', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Package "${name}@${pkgVersion}" installed successfully (type: ${type}).\n${JSON.stringify(result, null, 2)}`,
+      }],
+    };
+  },
+);
+
 // ============================================================================
 // MENU & EXTENSION TOOLS
 // ============================================================================

package/src/lib/mcp-instructions.js

@@ -69,7 +69,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Not all system tables have a REST route.** `query_table`, `find_one_record`, `create_record`, etc. all go through the dynamic REST API and will return **404** if the table has no registered route.',
     '- **`column_definition` has NO route** — do NOT call `query_table("column_definition", …)`. It will always 404.',
     '- To check which tables are accessible via MCP tools, call `get_all_routes` and look for the route whose `mainTable.id` matches the table you need, or `get_all_metadata` to see all table names.',
-    '- **Tables confirmed to have REST routes (system):** `table_definition`, `route_definition`, `user_definition`, `setting_definition`, `ai_config_definition`, `role_definition`, `menu_definition`, `extension_definition`, `folder_definition`, `file_definition`, `file_permission_definition`, `package_definition`, `bootstrap_script_definition`, `storage_config_definition`, `ai_conversation_definition`, `ai_message_definition`, `websocket_definition`, `websocket_event_definition`, `oauth_config_definition`, `oauth_account_definition`, `method_definition`, `pre_hook_definition`, `post_hook_definition`, `route_handler_definition`, `route_permission_definition`.',
+    '- **Tables confirmed to have REST routes (system):** `table_definition`, `route_definition`, `user_definition`, `setting_definition`, `ai_config_definition`, `role_definition`, `menu_definition`, `extension_definition`, `folder_definition`, `file_definition`, `file_permission_definition`, `package_definition`, `bootstrap_script_definition`, `storage_config_definition`, `ai_conversation_definition`, `ai_message_definition`, `websocket_definition`, `websocket_event_definition`, `oauth_config_definition`, `oauth_account_definition`, `method_definition`, `pre_hook_definition`, `post_hook_definition`, `route_handler_definition`, `route_permission_definition`, `flow_definition`, `flow_step_definition`, `flow_execution_definition`.',
     '- **Tables without REST routes (internal/system only):** `column_definition`, `relation_definition` — these are managed indirectly via cascade on `table_definition` (PATCH /table_definition/{id} with columns/relations array). The `create_column` MCP tool handles this automatically.',
     '',
     '### Schema / table migration (sequential only)',
@@ -100,6 +100,17 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Client**: `io("ORIGIN/namespace", {auth: {token: JWT}})` — e.g. `io("http://localhost:3000/chat", {auth: {token: "…"}})`. WebSocket origin usually matches HTTP host (drop `/api` for WS path). `path` in gateway = 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.',
     '',
+    '### Flows (Automated Workflows)',
+    '- Enfyra supports automated workflows via **`flow_definition`**, **`flow_step_definition`**, and **`flow_execution_definition`** tables.',
+    '- **Flow** (`flow_definition`): `name`, `triggerType` (`schedule`, `event`, `webhook`, `manual`), `triggerConfig` (JSON), `timeout`, `isEnabled`.',
+    '- **Step** (`flow_step_definition`): `flow` → flow id, `key` (unique identifier for data chain), `stepOrder`, `type` (`script`, `condition`, `query`, `create`, `update`, `delete`, `http`, `trigger_flow`, `sleep`, `log`), `config` (JSON), `timeout`, `onError` (`stop`, `skip`, `retry`), `retryAttempts`.',
+    '- **Execution history** (`flow_execution_definition`): `flow` → flow id, `status`, `triggerPayload`, `context` (full data chain), `completedSteps`, `error`, `startedAt`, `completedAt`, `duration`.',
+    '- **triggerConfig examples**: schedule: `{"cron":"0 2 * * *","timezone":"UTC"}`, event: `{"table":"order_definition","action":"create"}`, webhook: `{"path":"/hooks/payment"}`, manual: `{}`.',
+    '- **Step config examples**: script: `{"code":"return $ctx.$repos.user_definition.find({limit:10})"}`, condition: `{"code":"return $ctx.$flow.$last?.data?.length > 0"}`, query: `{"table":"user_definition","filter":{"status":{"_eq":"active"}},"limit":10}`, http: `{"url":"https://api.example.com","method":"POST","body":{}}`, sleep: `{"ms":5000}`, trigger_flow: `{"flowId":2}`.',
+    '- **Data chain**: Steps access previous results via `$ctx.$flow.<stepKey>` and `$ctx.$flow.$last`. Trigger payload via `$ctx.$flow.$trigger`.',
+    '- **Workflow**: Create flow → `create_record` on `flow_definition`. Add steps → `create_record` on `flow_step_definition` with `flow: {id}`. Trigger manually or via schedule/event/webhook.',
+    '- **In handlers/hooks**: Trigger flows via `$ctx.$flows.trigger("flow-name", {payload})` or `$ctx.$flows.trigger(flowId, {payload})`.',
+    '',
     '### Extension (Vue SFC only — NOT React)',
     '- **CRITICAL:** MUST call `create_record` or `update_record` on `extension_definition` — outputting Vue code in chat does NOT save it. User will NOT see it.',
     '- **Code format:** Vue SFC only. Structure: `<template>...</template>` + `<script setup>...</script>`. Server auto-compiles; if compile fails, fix and retry.',
@@ -156,9 +167,13 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **type "page":** Full-page extension. Requires `menu: { id }` — create menu first (`create_menu` or `create_record` on `menu_definition`), find by path/label, then create extension with `menu: { id: menuId }`. `menu_definition` uses **label** not name — filter by `label` or `path`.',
     '- **type "widget":** Widget extension. No menu required. Embed via `<Widget :id="extensionId" />` in other extensions or pages.',
     '',
-    '#### NPM packages:',
-    '- Before using (e.g. dayjs, chart.js) — check `package_definition` (filter `type: App`, `name`, `isEnabled`). If not found, tell user to install via Settings → Packages.',
-    '- Use `getPackages([\'dayjs\'])` in code; call in `onMounted` or async handler.',
+    '#### NPM packages (install via MCP):',
+    '- **Use `install_package` tool** — just pass the package name and type. The tool auto-fetches version from NPM, checks if already installed, and creates the record.',
+    '- Example: `install_package({ name: "node-ssh", type: "Server" })` — that is all. Tool handles everything.',
+    '- **Search first with `search_npm`** if unsure of exact package name.',
+    '- **Server** packages → available as `$ctx.$pkgs.packageName` in handlers/hooks.',
+    '- **App** packages → available via `getPackages([\'dayjs\'])` in extensions (call in `onMounted`).',
+    '- **Do NOT use `create_record` on `package_definition` directly** — use `install_package` instead.',
     '',
     '#### Important patterns:',
     '- **useApi:** Must call `execute()` — does NOT auto-run. Supports batch operations with `ids` or `files` options.',
@@ -179,6 +194,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\``,
     `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\``,
     `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for page pass menuId). \`update_record\` on extension_definition to change code.`,
+    `- Flow tables: \`${base}/flow_definition\`, \`${base}/flow_step_definition\`, \`${base}/flow_execution_definition\` — use standard CRUD tools.`,
     `- Other: \`${base}/menu_definition\`, \`${base}/websocket_definition\`, \`${base}/admin/reload\`, etc.`,
     '',
     'When asked which endpoint the API calls, respond with **HTTP method + full URL** using this base. Call `get_enfyra_api_context` to confirm the resolved base if needed.',