@enfyra/mcp-server 0.0.11 → 0.0.13

package/src/lib/config-local.mjs

@@ -0,0 +1,286 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output, cwd } from 'node:process';
+import { dirname, join } from 'node:path';
+
+const SERVER_KEY = 'enfyra';
+
+function printHelp() {
+  console.log(`enfyra-mcp — write local project MCP config (Claude Code + Cursor)
+
+Usage:
+  npx @enfyra/mcp-server config [options]
+
+Writes only under the current working directory:
+  • ./.mcp.json           — Claude Code project scope
+  • ./.cursor/mcp.json    — Cursor project scope
+
+Options:
+  --api-url, -a <url>     ENFYRA_API_URL
+  --email, -e <email>     ENFYRA_EMAIL
+  --password, -p <secret> ENFYRA_PASSWORD
+  --yes                   Non-interactive: no prompts (CI / scripts); use CLI, env, existing file, then defaults
+  Target — non-interactive default is both; with TTY and no target flags, you are prompted [1]/[2]/[3]:
+  --claude-code, --claude, --claude-only   Only ./.mcp.json (Claude Code project scope)
+  --cursor, --cursor-only                  Only ./.cursor/mcp.json (Cursor)
+  Passing both target flags writes both files.
+  -h, --help              Show this help
+
+Interactive mode: asks Claude Code vs Cursor vs both if you did not pass target flags; then asks for URL / email / password
+  when missing. Existing ./.mcp.json and ./.cursor/mcp.json are used as defaults. Re-run to update.
+
+Examples:
+  npx @enfyra/mcp-server config
+  npx @enfyra/mcp-server config --claude-code
+  npx @enfyra/mcp-server config --cursor --yes
+  npx @enfyra/mcp-server config -a http://localhost:3000/api -e admin@x.com -p 'secret'
+  npx @enfyra/mcp-server config --yes
+  ENFYRA_PASSWORD=secret npx @enfyra/mcp-server config --yes -e admin@x.com
+`);
+}
+
+function parseArgs(argv) {
+  const out = {
+    apiUrl: undefined,
+    email: undefined,
+    password: undefined,
+    claude: true,
+    cursor: true,
+    help: false,
+    yes: false,
+  };
+  let pickClaude = false;
+  let pickCursor = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[i + 1];
+      if (v == null) throw new Error(`Missing value after ${a}`);
+      i += 1;
+      return v;
+    };
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--yes') out.yes = true;
+    else if (a === '--api-url' || a === '-a') out.apiUrl = next();
+    else if (a === '--email' || a === '-e') out.email = next();
+    else if (a === '--password' || a === '-p') out.password = next();
+    else if (a === '--claude-only' || a === '--claude-code' || a === '--claude') pickClaude = true;
+    else if (a === '--cursor-only' || a === '--cursor') pickCursor = true;
+    else throw new Error(`Unknown argument: ${a}`);
+  }
+  out.targetExplicit = pickClaude || pickCursor;
+  if (pickClaude || pickCursor) {
+    if (pickClaude && pickCursor) {
+      out.claude = true;
+      out.cursor = true;
+    } else if (pickClaude) {
+      out.claude = true;
+      out.cursor = false;
+    } else {
+      out.claude = false;
+      out.cursor = true;
+    }
+  }
+  return out;
+}
+
+function buildServerEntry(apiUrl, email, password) {
+  return {
+    command: 'npx',
+    args: ['-y', '@enfyra/mcp-server'],
+    env: {
+      ENFYRA_API_URL: apiUrl,
+      ENFYRA_EMAIL: email,
+      ENFYRA_PASSWORD: password,
+    },
+  };
+}
+
+async function mergeMcpFile(absPath, serverEntry) {
+  let data = { mcpServers: {} };
+  try {
+    const raw = await readFile(absPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.mcpServers && typeof parsed.mcpServers === 'object') {
+      data.mcpServers = { ...parsed.mcpServers };
+    } else if (parsed && typeof parsed === 'object') {
+      data = { ...parsed, mcpServers: parsed.mcpServers && typeof parsed.mcpServers === 'object' ? { ...parsed.mcpServers } : {} };
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  data.mcpServers = { ...data.mcpServers, [SERVER_KEY]: serverEntry };
+  const dir = dirname(absPath);
+  await mkdir(dir, { recursive: true });
+  await writeFile(absPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+async function loadExistingEnfyraEnv(root, readClaude, readCursor) {
+  const paths = [];
+  if (readClaude) paths.push(join(root, '.mcp.json'));
+  if (readCursor) paths.push(join(root, '.cursor', 'mcp.json'));
+  if (!readClaude && readCursor) paths.push(join(root, '.mcp.json'));
+  const seen = new Set();
+  for (const p of paths) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    try {
+      const raw = await readFile(p, 'utf8');
+      const j = JSON.parse(raw);
+      const e = j?.mcpServers?.[SERVER_KEY]?.env;
+      if (e && typeof e === 'object' && (e.ENFYRA_API_URL || e.ENFYRA_EMAIL || e.ENFYRA_PASSWORD)) {
+        return {
+          apiUrl: typeof e.ENFYRA_API_URL === 'string' ? e.ENFYRA_API_URL : '',
+          email: typeof e.ENFYRA_EMAIL === 'string' ? e.ENFYRA_EMAIL : '',
+          password: typeof e.ENFYRA_PASSWORD === 'string' ? e.ENFYRA_PASSWORD : '',
+        };
+      }
+    } catch {
+      /* */
+    }
+  }
+  return { apiUrl: '', email: '', password: '' };
+}
+
+async function promptTargetChoice() {
+  const rl = createInterface({ input, output });
+  const line = (await rl.question(
+    'Where should Enfyra MCP config be written?\n'
+      + '  [1] Claude Code — ./.mcp.json\n'
+      + '  [2] Cursor — ./.cursor/mcp.json\n'
+      + '  [3] Both [default]\n'
+      + 'Choice [3]: ',
+  )).trim().toLowerCase();
+  await rl.close();
+  if (line === '' || line === '3' || line === 'both' || line === 'b') {
+    return { claude: true, cursor: true };
+  }
+  if (line === '1' || line === 'c' || line === 'claude') {
+    return { claude: true, cursor: false };
+  }
+  if (line === '2' || line === 'u' || line === 'cursor') {
+    return { claude: false, cursor: true };
+  }
+  return { claude: true, cursor: true };
+}
+
+async function promptConfig(opts, existing) {
+  let apiUrl = opts.apiUrl;
+  let email = opts.email;
+  let password = opts.password;
+  if (apiUrl !== undefined && email !== undefined && password !== undefined) {
+    return { apiUrl: String(apiUrl).replace(/\/$/, ''), email, password };
+  }
+
+  const rl = createInterface({ input, output });
+  const q = (msg) => rl.question(msg);
+
+  const defaultUrl = (
+    opts.apiUrl ??
+    process.env.ENFYRA_API_URL ??
+    (existing.apiUrl || undefined) ??
+    'http://localhost:3000/api'
+  ).replace(/\/$/, '');
+  if (apiUrl === undefined) {
+    const line = (await q(`ENFYRA_API_URL [${defaultUrl}]: `)).trim();
+    apiUrl = line || defaultUrl;
+  }
+  apiUrl = String(apiUrl).replace(/\/$/, '');
+
+  const defaultEmail = opts.email ?? process.env.ENFYRA_EMAIL ?? existing.email ?? '';
+  if (email === undefined) {
+    const hint = defaultEmail ? `[${defaultEmail}]` : '[empty]';
+    const line = (await q(`ENFYRA_EMAIL ${hint}: `)).trim();
+    email = line || defaultEmail;
+  }
+
+  const defaultPass = opts.password ?? process.env.ENFYRA_PASSWORD ?? existing.password ?? '';
+  if (password === undefined) {
+    const hint = existing.password ? '(Enter = keep current)' : '(optional)';
+    const line = (await q(`ENFYRA_PASSWORD ${hint}: `)).trim();
+    password = line !== '' ? line : defaultPass;
+  }
+
+  await rl.close();
+  return { apiUrl, email, password };
+}
+
+function resolveNonInteractive(opts, existing) {
+  const apiUrl = (
+    opts.apiUrl ??
+    process.env.ENFYRA_API_URL ??
+    (existing.apiUrl || undefined) ??
+    'http://localhost:3000/api'
+  ).replace(/\/$/, '');
+  const email = opts.email ?? process.env.ENFYRA_EMAIL ?? existing.email ?? '';
+  const password = opts.password ?? process.env.ENFYRA_PASSWORD ?? existing.password ?? '';
+  return { apiUrl, email, password };
+}
+
+export async function runLocalConfig(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    console.error(e.message || e);
+    printHelp();
+    process.exit(1);
+    return;
+  }
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  const root = cwd();
+  const usePrompt = !opts.yes && input.isTTY && output.isTTY;
+
+  let writeClaude = opts.claude;
+  let writeCursor = opts.cursor;
+  if (usePrompt && !opts.targetExplicit) {
+    const t = await promptTargetChoice();
+    writeClaude = t.claude;
+    writeCursor = t.cursor;
+  }
+
+  const existing = await loadExistingEnfyraEnv(root, true, true);
+
+  let apiUrl;
+  let email;
+  let password;
+  if (usePrompt) {
+    const resolved = await promptConfig(opts, existing);
+    apiUrl = resolved.apiUrl;
+    email = resolved.email;
+    password = resolved.password;
+  } else {
+    const resolved = resolveNonInteractive(opts, existing);
+    apiUrl = resolved.apiUrl;
+    email = resolved.email;
+    password = resolved.password;
+  }
+
+  const serverEntry = buildServerEntry(apiUrl, email, password);
+  const written = [];
+
+  if (writeClaude) {
+    const p = join(root, '.mcp.json');
+    await mergeMcpFile(p, serverEntry);
+    written.push(p);
+  }
+  if (writeCursor) {
+    const p = join(root, '.cursor', 'mcp.json');
+    await mergeMcpFile(p, serverEntry);
+    written.push(p);
+  }
+
+  console.log('Enfyra MCP — local config updated:\n');
+  for (const p of written) console.log(`  ${p}`);
+  console.log('\nNext steps:');
+  console.log('  • Claude Code: open this folder; approve project MCP if prompted (`claude mcp reset-project-choices` to reset).');
+  console.log('  • Cursor: restart Cursor or reload MCP; confirm server under Settings → MCP.');
+  console.log('  • Run `config` again anytime to change values (same files are merged/overwritten for `enfyra`).');
+  if (!email || !password) {
+    console.log('\nWarning: ENFYRA_EMAIL or ENFYRA_PASSWORD is empty — tools may not authenticate until set.');
+  }
+}

package/src/lib/mcp-instructions.js

@@ -4,7 +4,7 @@
  * Maintain all assistant-facing rules here (and tool descriptions in index.mjs).
  */
 
-/** GraphQL shares the same URL prefix as REST: `{ENFYRA_API_URL}/graphql` and `{ENFYRA_API_URL}/graphql-schema`. */
+/** GraphQL SDL + HTTP endpoint are under the same base as REST: `{ENFYRA_API_URL}/graphql` and `{ENFYRA_API_URL}/graphql-schema` (Nuxt proxies these when base ends with `/api`). */
 export function buildGraphqlUrls(apiBaseUrl) {
   const base = String(apiBaseUrl || '').replace(/\/$/, '');
   return {
@@ -28,6 +28,11 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `**API base for this session:** \`${base}\` (from env ENFYRA_API_URL, no trailing slash).`,
     `**Full URL:** base + path segment. Example for table \`post\`: \`${examplePost}\`.`,
     '',
+    '### ENFYRA_API_URL (two valid setups)',
+    '- **Via Nuxt admin (typical):** `http://localhost:3000/api` — Nuxt proxies `/api/*` to Nest (`API_URL`, e.g. `http://localhost:1105`). Use this when MCP talks to the app origin.',
+    '- **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.',
+    '',
     '### After a new table is created',
     '- Enfyra creates a route at `/{table_name}` using the table **name** from `create_table` (not the alias).',
     '- **Four REST HTTP operations** on that resource:',
@@ -84,9 +89,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- On **SQL**, filters often use **`id`**. On **MongoDB**, documents may use **`_id`** — a filter for one row might be `{"_id":{"_eq":"..."}}` instead of `id`, depending on metadata.',
     '',
     '### GraphQL (same prefix as REST / ENFYRA_API_URL)',
-    `- **POST** \`${graphqlHttpUrl}\` — GraphQL endpoint (body: GraphQL query). Example with default base: \`http://localhost:3000/api/graphql\`.`,
-    `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text), e.g. \`.../api/graphql-schema\`.`,
-    '- A table appears in the schema only if its route has **both** `GQL_QUERY` and `GQL_MUTATION` in `availableMethods`, `path` = `/<table_name>`, and `mainTable` set.',
+    `- **POST** \`${graphqlHttpUrl}\` — GraphQL endpoint (body: GraphQL query). With Nuxt base: e.g. \`http://localhost:3000/api/graphql\`. With direct Nest: e.g. \`http://localhost:1105/graphql\`.`,
+    `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text); same base pattern as above.`,
+    '- A table appears in the schema if some **enabled route** for that table has **both** `GQL_QUERY` and `GQL_MUTATION` in `availableMethods` and a **`mainTable`** pointing at the table. The route **`path` does not need to be** `/<table_name>` (custom paths still qualify).',
     '- **Query** field = same string as `table_definition.name`. **Mutations** are literal concat: `create_`+tableName, `update_`+tableName, `delete_`+tableName (e.g. tableName `post` → `create_post`, input type `postInput`). See `generate-type-defs.ts`. No mutations if no non-PK columns for input.',
     '- **Auth:** `publishedMethods` may include `GQL_QUERY` and/or `GQL_MUTATION` **separately** — each controls anonymous access for queries vs mutations. Otherwise Bearer JWT + `routePermissions` must list the same method key (`GQL_QUERY` / `GQL_MUTATION`).',
     '- MCP does not wrap GraphQL; use REST tools or tell users the URLs above.',
@@ -97,19 +102,23 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **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.',
     '- **Context**: Connection — `@BODY` = {id, ip, headers}, `@USER` if auth. Event — `@BODY` = payload, `@USER` if auth. Both have `@SOCKET`.',
-    '- **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.',
+    '- **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.',
     '',
     '### 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})`.',
+    '- **Flow** (`flow_definition`): `name`, `triggerType` (`schedule`, `manual`), `triggerConfig` (JSON), `timeout`, `maxExecutions` (default 100, auto-cleanup old history), `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`, `parent` → self-ref to condition step (null = root), `branch` (`true`/`false` — which branch of parent condition).',
+    '- **Execution history** (`flow_execution_definition`): `flow` → flow id, `status`, `payload`, `context` (full data chain), `completedSteps`, `currentStep`, `error`, `startedAt`, `completedAt`, `duration`. Query separately — NOT nested under flow_definition.',
+    '- **triggerConfig examples**: schedule: `{"cron":"0 2 * * *","timezone":"UTC"}`, manual: `{}`. For event/webhook use cases, create a handler/hook with `@DISPATCH.trigger("flow-name", payload)` instead.',
+    '- **Step config examples**: script: `{"code":"return #user_definition.find({limit:10})"}`, condition: `{"code":"return @LAST?.data?.length > 0"}` (uses JS truthy/falsy: `return user` = truthy if exists, `return null` = falsy), query: `{"table":"user_definition","filter":{"status":{"_eq":"active"}},"limit":10}`, http: `{"url":"https://api.example.com","method":"POST","body":{}}` (auto Content-Type: application/json; **http `url` must be public-safe**—see Safety), sleep: `{"ms":5000}`, trigger_flow: `{"flowId":2}`.',
+    '- **Data chain**: Steps access previous results via `@FLOW.<stepKey>` and `@LAST`. Input payload via `@PAYLOAD`. Repos via `#table_name`.',
+    '- **Template syntax (flows)**: `@PAYLOAD` → `$ctx.$flow.$payload` (input data), `@LAST` → `$ctx.$flow.$last`, `@FLOW` → `$ctx.$flow`, `@META` → `$ctx.$flow.$meta`, `#table_name` → `$ctx.$repos.table_name`, `@HELPERS` → `$ctx.$helpers`, `@THROW4xx/5xx` → error helpers. Trigger other flows in handlers via `@DISPATCH.trigger(name, payload)` or `$ctx.$dispatch.trigger(name, payload)`.',
+    '- **Condition branching**: Condition step uses JavaScript truthy/falsy evaluation (e.g. `return user` → truthy if exists, falsy if null/0/undefined). Children with matching `parent: {id: conditionStepId}` and `branch: "true"/"false"` execute. Root steps (no parent) always execute sequentially.',
+    '- **Safety**: Max nesting depth 10 (flow triggering flow). Circular flow detection prevents A→B→A loops. HTTP steps: **SSRF hardening** — only `http`/`https`; blocks `localhost`, private IPs, and hostnames resolving to private IPs (use internet-facing URLs like `https://api.example.com`, not internal services, unless server policy changes). Default HTTP timeout 30s (AbortController). `$dispatch.trigger()` available inside flow steps.',
+    '- **Workflow**: Create flow → `create_record` on `flow_definition`. Add steps → `create_record` on `flow_step_definition` with `flow: {id}`. For branch steps, set `parent: {id: conditionStepId}` and `branch: "true"` or `"false"`. Trigger manually via `POST /admin/flow/trigger/{flowId}`.',
+    '- **Test step**: `POST /admin/flow/test-step` with body `{type, config, timeout}` — runs a single step without saving, returns `{success, result, error, duration}`.',
+    '- **In handlers/hooks**: Trigger flows via `$ctx.$dispatch.trigger("flow-name", {payload})` or `$ctx.$dispatch.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.',
@@ -164,6 +173,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- `$ctx` — runtime context',
     '',
     '#### Extension types:',
+    '- **FormEditor field-map:** Customize fields via `:field-map` prop. Options: `label` (override label), `description` (override description), `hideLabel`/`hideDescription` (boolean), `component` (custom Vue component replacing field), `componentProps`, `type` (override field type), `disabled`, `placeholder`. Custom component receives `modelValue`/`update:modelValue`.',
     '- **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.',
     '',
@@ -185,6 +195,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '#### Minimal example:',
     '`<template><div class="p-6"><h1 class="text-2xl font-bold">{{ title }}</h1><UButton @click="handleClick">Click</UButton></div></template><script setup>const title = ref(\'My Extension\'); const toast = useToast(); const handleClick = () => toast.add({ title: \'Clicked\', color: \'green\' });</script>`',
     '',
+    '### API Testing',
+    '- API testing is available at `/settings/api-tester` in the app UI.',
+    '',
     '### MCP tool → HTTP',
     `- \`get_all_metadata\` → GET \`${base}/metadata\``,
     `- \`get_table_metadata\` → GET \`${base}/metadata/<tableName>\``,