@enfyra/mcp-server 0.0.25 → 0.0.27

package/README.md

@@ -1,6 +1,6 @@
 # Enfyra MCP Server
 
-MCP server for managing Enfyra instances from **Claude Code**, **Cursor**, and other MCP-compatible clients. All operations go through Enfyra's REST API.
+MCP server for managing Enfyra instances from **Codex**, **Claude Code**, **Cursor**, and other MCP-compatible clients. All operations go through Enfyra's REST API.
 
 
 **LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`) and tool descriptions in **`src/index.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
@@ -11,17 +11,18 @@ MCP server for managing Enfyra instances from **Claude Code**, **Cursor**, and o
 
 ## Quick local setup (`config` command)
 
-From your **Enfyra project root** (where you want `.mcp.json` / `.cursor/mcp.json`):
+From your **Enfyra project root**:
 
 ```bash
 npx @enfyra/mcp-server config
 ```
 
-- **Interactive (default in a terminal):** first asks **where** to write config — `[1]` Claude Code only, `[2]` Cursor only, `[3]` both (default) — unless you already passed `--claude-code` / `--cursor` / etc. Then prompts for `ENFYRA_API_URL`, `ENFYRA_EMAIL`, and `ENFYRA_PASSWORD` when missing. Press **Enter** to accept bracketed defaults (env + existing `enfyra` in either local file). Password **Enter** keeps the current saved password when updating.
+- **Interactive (default in a terminal):** first asks **where** to write config — `[1]` Claude Code, `[2]` Cursor, `[3]` Codex, `[4]` all (default) — unless you already passed target flags. Then prompts for `ENFYRA_API_URL`, `ENFYRA_EMAIL`, and `ENFYRA_PASSWORD` when missing. Press **Enter** to accept bracketed defaults from env or existing `enfyra` config. Password **Enter** keeps the current saved password when updating.
 - **Re-run anytime** to update the same files; other entries under `mcpServers` are preserved.
 - **Non-interactive** (CI / scripts): `npx @enfyra/mcp-server config --yes` plus optional `-a` / `-e` / `-p` and/or env vars.
-- **One IDE only:** `--claude-code` / `--claude` / `--claude-only` → `./.mcp.json` only. `--cursor` / `--cursor-only` → `./.cursor/mcp.json` only. Pass **both** target flags → write both files (same as default).
-- **Help:** `npx @enfyra/mcp-server config --help`
+- **One host only:** `--claude-code` / `--claude` / `--claude-only` → `./.mcp.json`. `--cursor` / `--cursor-only` → `./.cursor/mcp.json`. `--codex` / `--codex-only` → `~/.codex/config.toml`. Pass multiple target flags to write each selected host.
+- **Reconfigure:** `npx @enfyra/mcp-server config --reconfig` prompts for the target host again, uses existing values as defaults, and replaces the old `enfyra` entry for that host.
+- **Help:** `npx @enfyra/mcp-server -h` or `npx @enfyra/mcp-server config --help`
 
 Equivalent in this repo: `yarn mcp:config` (Yarn v1 reserves `yarn config` for registry settings). Same as `node src/index.mjs config` / `npm run mcp:config`.
 
@@ -31,16 +32,51 @@ Equivalent in this repo: `yarn mcp:config` (Yarn v1 reserves `yarn config` for r
 
 Use this table to see **where** each host stores config. The **`mcpServers.enfyra` JSON block** at the bottom of each section is identical; only the **file paths** and **CLI** differ.
 
-| | **Claude Code** | **Cursor** |
-|---|-----------------|------------|
-| **Global (all projects)** | `~/.claude.json` — scopes **user** or **local** | `~/.cursor/mcp.json` |
-| **Project (repo)** | **`.mcp.json`** at repository root (`--scope project`) | **`.cursor/mcp.json`** in the project |
-| **Typical install** | `claude mcp add --transport stdio …` | Edit `mcp.json` or **Settings → MCP** |
-| **Precedence / merge** | local → project `.mcp.json` → user | Project `.cursor/mcp.json` overrides global `~/.cursor/mcp.json` |
-| **Gotcha** | Do not put MCP server definitions in `.claude/settings.json` | Root **`.mcp.json`** is for Claude Code project scope, not Cursor — use **`.cursor/mcp.json`** for Cursor |
+| | **Codex** | **Claude Code** | **Cursor** |
+|---|-----------|-----------------|------------|
+| **Global (all projects)** | `~/.codex/config.toml` | `~/.claude.json` — scopes **user** or **local** | `~/.cursor/mcp.json` |
+| **Project (repo)** | Use global config | **`.mcp.json`** at repository root (`--scope project`) | **`.cursor/mcp.json`** in the project |
+| **Typical install** | `npx @enfyra/mcp-server config --codex` | `claude mcp add --transport stdio …` | Edit `mcp.json` or **Settings → MCP** |
+| **Precedence / merge** | `config.toml` section is replaced for `enfyra`; other servers are preserved | local → project `.mcp.json` → user | Project `.cursor/mcp.json` overrides global `~/.cursor/mcp.json` |
+| **Gotcha** | Restart Codex or start a new session after editing config | Do not put MCP server definitions in `.claude/settings.json` | Root **`.mcp.json`** is for Claude Code project scope, not Cursor — use **`.cursor/mcp.json`** for Cursor |
 
 Expand **one** block below for step-by-step setup.
 
+<details open>
+<summary><strong>Codex</strong> — setup</summary>
+
+The config command can write/update `~/.codex/config.toml` directly:
+
+```bash
+npx @enfyra/mcp-server config --codex
+```
+
+Non-interactive:
+
+```bash
+npx @enfyra/mcp-server config --codex --yes \
+  -a http://localhost:3000/api \
+  -e your-email@example.com \
+  -p your-password
+```
+
+The generated TOML section is:
+
+```toml
+[mcp_servers.enfyra]
+command = "npx"
+args = ["-y", "@enfyra/mcp-server"]
+
+[mcp_servers.enfyra.env]
+ENFYRA_API_URL = "http://localhost:3000/api"
+ENFYRA_EMAIL = "your-email@example.com"
+ENFYRA_PASSWORD = "your-password"
+```
+
+The config writer replaces only `[mcp_servers.enfyra]` and `[mcp_servers.enfyra.env]`; other Codex config and other MCP servers are preserved. Restart Codex or start a new session after updating `~/.codex/config.toml`.
+
+</details>
+
 <details open>
 <summary><strong>Claude Code</strong> — setup</summary>
 
@@ -161,6 +197,15 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 Pick the base URL that matches how **your** HTTP client reaches the same server as the Enfyra REST API.
 
+### SSR app auth pattern
+
+When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, use a same-origin proxy:
+
+- Browser code calls `{{ appOrigin }}/api/**`, never the raw Enfyra backend URL.
+- Cookie-managed password login is `POST {{ appOrigin }}/api/login`, not `/api/auth/login`. The SSR route calls backend `/auth/login` and stores Enfyra `accessToken`, `refreshToken`, and `expTime` as httpOnly cookies.
+- Cookie-managed OAuth should enable Enfyra OAuth cookie handling (`autoSetCookies` / set-cookies mode). Start OAuth at `{{ appOrigin }}/api/auth/:provider?redirect=...`; Enfyra redirects to `{{ appOrigin }}/api/auth/set-cookies`, then the SSR route sets cookies and redirects to the requested page.
+- Use token-query OAuth callback pages only for non-SSR/manual-token apps.
+
 ---
 
 ## Tools (summary)

package/package.json

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

package/src/index.mjs

@@ -6,6 +6,28 @@
 import { config as loadEnv } from 'dotenv';
 
 const args = process.argv.slice(2);
+if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+  console.log(`Enfyra MCP Server
+
+Usage:
+  npx @enfyra/mcp-server                 Start the MCP stdio server
+  npx @enfyra/mcp-server config [flags]  Write local MCP host config
+
+Common config flags:
+  --codex             Write ~/.codex/config.toml
+  --claude-code       Write ./.mcp.json
+  --cursor            Write ./.cursor/mcp.json
+  --reconfig          Prompt for host and credentials again, replacing the enfyra entry
+  --yes               Non-interactive
+  -a, --api-url       ENFYRA_API_URL
+  -e, --email         ENFYRA_EMAIL
+  -p, --password      ENFYRA_PASSWORD
+  -h, --help          Show config help
+
+Run \`npx @enfyra/mcp-server config --help\` for full config details.
+`);
+  process.exit(0);
+}
 if (args[0] === 'config') {
   loadEnv({ quiet: true });
   const { runLocalConfig } = await import('./lib/config-local.mjs');

package/src/lib/config-local.mjs

@@ -2,37 +2,43 @@ 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';
+import { homedir } from 'node:os';
 
 const SERVER_KEY = 'enfyra';
 
 function printHelp() {
-  console.log(`enfyra-mcp — write local project MCP config (Claude Code + Cursor)
+  console.log(`enfyra-mcp — write MCP config (Codex + Claude Code + Cursor)
 
 Usage:
   npx @enfyra/mcp-server config [options]
 
-Writes only under the current working directory:
+Writes project config under the current working directory and Codex config under your home directory:
   • ./.mcp.json           — Claude Code project scope
   • ./.cursor/mcp.json    — Cursor project scope
+  • ~/.codex/config.toml  — Codex user scope
 
 Options:
   --api-url, -a <url>     ENFYRA_API_URL
   --email, -e <email>     ENFYRA_EMAIL
   --password, -p <secret> ENFYRA_PASSWORD
+  --reconfig              Always choose target again in interactive mode and replace the old enfyra config for that target
   --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]:
+  Target — non-interactive default is all; with TTY and no target flags, you are prompted [1]/[2]/[3]/[4]:
   --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.
+  --codex, --codex-only                    Only ~/.codex/config.toml (Codex)
+  Passing multiple target flags writes each selected target.
   -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.
+  when missing. Existing ./.mcp.json, ./.cursor/mcp.json, and ~/.codex/config.toml 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 --codex --yes
+  npx @enfyra/mcp-server config --reconfig
   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
@@ -46,11 +52,14 @@ function parseArgs(argv) {
     password: undefined,
     claude: true,
     cursor: true,
+    codex: true,
     help: false,
     yes: false,
+    reconfig: false,
   };
   let pickClaude = false;
   let pickCursor = false;
+  let pickCodex = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     const next = () => {
@@ -60,26 +69,22 @@ function parseArgs(argv) {
       return v;
     };
     if (a === '--help' || a === '-h') out.help = true;
+    else if (a === 'help') out.help = true;
     else if (a === '--yes') out.yes = true;
+    else if (a === '--reconfig') out.reconfig = 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 if (a === '--codex-only' || a === '--codex') pickCodex = 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;
-    }
+  out.targetExplicit = pickClaude || pickCursor || pickCodex;
+  if (out.targetExplicit) {
+    out.claude = pickClaude;
+    out.cursor = pickCursor;
+    out.codex = pickCodex;
   }
   return out;
 }
@@ -115,7 +120,86 @@ async function mergeMcpFile(absPath, serverEntry) {
   await writeFile(absPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
 }
 
-async function loadExistingEnfyraEnv(root, readClaude, readCursor) {
+function tomlString(value) {
+  return JSON.stringify(String(value ?? ''));
+}
+
+function buildCodexTomlBlock(apiUrl, email, password) {
+  return [
+    '[mcp_servers.enfyra]',
+    'command = "npx"',
+    'args = ["-y", "@enfyra/mcp-server"]',
+    '',
+    '[mcp_servers.enfyra.env]',
+    `ENFYRA_API_URL = ${tomlString(apiUrl)}`,
+    `ENFYRA_EMAIL = ${tomlString(email)}`,
+    `ENFYRA_PASSWORD = ${tomlString(password)}`,
+    '',
+  ].join('\n');
+}
+
+async function mergeCodexConfig(absPath, apiUrl, email, password) {
+  let raw = '';
+  try {
+    raw = await readFile(absPath, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  const kept = [];
+  let skip = false;
+  for (const line of raw.split(/\r?\n/)) {
+    const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (header) {
+      const section = header[1].trim();
+      skip = section === 'mcp_servers.enfyra' || section.startsWith('mcp_servers.enfyra.');
+    }
+    if (!skip) kept.push(line);
+  }
+
+  const next = `${kept.join('\n').trimEnd()}\n\n${buildCodexTomlBlock(apiUrl, email, password)}`;
+  await mkdir(dirname(absPath), { recursive: true });
+  await writeFile(absPath, next, 'utf8');
+}
+
+function parseTomlString(value) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) return '';
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed.replace(/^['"]|['"]$/g, '');
+  }
+}
+
+async function readCodexEnfyraEnv(absPath) {
+  try {
+    const raw = await readFile(absPath, 'utf8');
+    const values = { apiUrl: '', email: '', password: '' };
+    let inEnv = false;
+    for (const line of raw.split(/\r?\n/)) {
+      const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
+      if (header) {
+        inEnv = header[1].trim() === 'mcp_servers.enfyra.env';
+        continue;
+      }
+      if (!inEnv) continue;
+      const pair = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.+?)\s*$/);
+      if (!pair) continue;
+      const key = pair[1];
+      const value = parseTomlString(pair[2]);
+      if (key === 'ENFYRA_API_URL') values.apiUrl = value;
+      if (key === 'ENFYRA_EMAIL') values.email = value;
+      if (key === 'ENFYRA_PASSWORD') values.password = value;
+    }
+    if (values.apiUrl || values.email || values.password) return values;
+  } catch {
+    /* */
+  }
+  return null;
+}
+
+async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex) {
   const paths = [];
   if (readClaude) paths.push(join(root, '.mcp.json'));
   if (readCursor) paths.push(join(root, '.cursor', 'mcp.json'));
@@ -139,6 +223,10 @@ async function loadExistingEnfyraEnv(root, readClaude, readCursor) {
       /* */
     }
   }
+  if (readCodex) {
+    const codex = await readCodexEnfyraEnv(join(homedir(), '.codex', 'config.toml'));
+    if (codex) return codex;
+  }
   return { apiUrl: '', email: '', password: '' };
 }
 
@@ -148,20 +236,24 @@ async function promptTargetChoice() {
     '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]: ',
+      + '  [3] Codex — ~/.codex/config.toml\n'
+      + '  [4] All [default]\n'
+      + 'Choice [4]: ',
   )).trim().toLowerCase();
   await rl.close();
-  if (line === '' || line === '3' || line === 'both' || line === 'b') {
-    return { claude: true, cursor: true };
+  if (line === '' || line === '4' || line === 'all' || line === 'a') {
+    return { claude: true, cursor: true, codex: true };
   }
   if (line === '1' || line === 'c' || line === 'claude') {
-    return { claude: true, cursor: false };
+    return { claude: true, cursor: false, codex: false };
   }
   if (line === '2' || line === 'u' || line === 'cursor') {
-    return { claude: false, cursor: true };
+    return { claude: false, cursor: true, codex: false };
   }
-  return { claude: true, cursor: true };
+  if (line === '3' || line === 'x' || line === 'codex') {
+    return { claude: false, cursor: false, codex: true };
+  }
+  return { claude: true, cursor: true, codex: true };
 }
 
 async function promptConfig(opts, existing) {
@@ -237,13 +329,15 @@ export async function runLocalConfig(argv) {
 
   let writeClaude = opts.claude;
   let writeCursor = opts.cursor;
-  if (usePrompt && !opts.targetExplicit) {
+  let writeCodex = opts.codex;
+  if (usePrompt && (!opts.targetExplicit || opts.reconfig)) {
     const t = await promptTargetChoice();
     writeClaude = t.claude;
     writeCursor = t.cursor;
+    writeCodex = t.codex;
   }
 
-  const existing = await loadExistingEnfyraEnv(root, true, true);
+  const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex);
 
   let apiUrl;
   let email;
@@ -273,10 +367,16 @@ export async function runLocalConfig(argv) {
     await mergeMcpFile(p, serverEntry);
     written.push(p);
   }
+  if (writeCodex) {
+    const p = join(homedir(), '.codex', 'config.toml');
+    await mergeCodexConfig(p, apiUrl, email, password);
+    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('  • Codex: restart Codex or start a new session so ~/.codex/config.toml is reloaded.');
   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`).');

package/src/lib/mcp-instructions.js

@@ -39,7 +39,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### Capability map (current Enfyra system)',
     '- **Schema/metadata:** `table_definition`, `relation_definition`, and schema tools manage tables, columns, relations, validation, and migrations. `column_definition` is internal/no-route; columns are created/updated through table schema operations.',
     '- **Dynamic REST API:** `route_definition`, `route_handler_definition`, `pre_hook_definition`, `post_hook_definition`, `route_permission_definition`, and `method_definition` define paths, methods, handlers, hooks, and permissions.',
-    '- **Auth/OAuth/session:** `user_definition`, `role_definition`, `oauth_config_definition`, `oauth_account_definition`; `session_definition` is internal/no-route. OAuth is browser redirect only; MCP login is email/password.',
+    '- **Auth/OAuth/session:** `user_definition`, `role_definition`, `oauth_config_definition`, `oauth_account_definition`; `session_definition` is internal/no-route. OAuth is browser redirect only; MCP login is email/password. `user_definition` is the single source of truth for app users.',
     '- **Guards/permissions/validation:** `guard_definition`, `guard_rule_definition`, `field_permission_definition`, and `column_rule_definition` control route guards, field access, and request body validation.',
     '- **GraphQL:** `gql_definition` enables tables in GraphQL. GraphQL endpoint and schema share `ENFYRA_API_URL`; GraphQL requires Bearer auth.',
     '- **Files/storage/assets:** `file_definition`, `file_permission_definition`, `folder_definition`, `storage_config_definition` plus upload/assets routes and file helpers.',
@@ -53,6 +53,15 @@ 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.',
     '',
+    '### When the user asks how to connect a Nuxt/Next/SSR app to Enfyra',
+    '- This is guidance for the assistant to answer users and generate app code. It is not a separate MCP tool workflow.',
+    '- For real user-facing SSR apps, proxy all Enfyra traffic through the SSR app origin: **`{{ nuxtApp }}/api/**`** (or the equivalent Next route handler prefix). Browser code should call same-origin `/api/...`, not the raw Enfyra backend URL.',
+    '- If the SSR app lets Enfyra manage httpOnly cookies, password login is **`POST {{ nuxtApp }}/api/login`**, not `{{ nuxtApp }}/api/auth/login`. The SSR route calls backend `/auth/login`, stores `accessToken`, `refreshToken`, and `expTime` cookies, and returns the backend login response.',
+    '- After cookie-managed login, browser fetches use `/api/<resource>` with normal credentials/cookies; the SSR proxy/middleware attaches or refreshes the Bearer token server-side. Do not read JWTs in browser JavaScript for this mode.',
+    '- For OAuth in SSR/cookie mode, enable cookie handling on the Enfyra OAuth config (`autoSetCookies` / set-cookies mode). Start OAuth at `{{ nuxtApp }}/api/auth/{provider}?redirect=<returnUrl>`. The proxy forwards to backend `/auth/{provider}` with the app origin, backend redirects to `{{ nuxtApp }}/api/auth/set-cookies`, the SSR route stores cookies, then redirects to `redirect`.',
+    '- Token-query OAuth (`appCallbackUrl` receives `accessToken`, `refreshToken`, `expTime`) is only for non-SSR or manually managed token apps. Do not recommend it for Nuxt/Next SSR when Enfyra can set cookies.',
+    '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server logs itself in with email/password against backend `/auth/login`. Do not copy that pattern into generated Nuxt/Next browser app code.',
+    '',
     '### Routes vs tables (custom endpoints, handlers, hooks)',
     '- REST-first workflow for any feature: **`inspect_feature`** to locate candidates → **`inspect_table`** for table/field/relation/rule context → **`inspect_route`** for handlers/hooks/guards/permissions → **`test_rest_endpoint`** to verify the actual HTTP behavior.',
     '- Use **`create_column_rule`** for standard request validation, **`create_field_permission`** for per-field read/create/update rules, **`create_route_permission`** for authenticated route access, and **`create_guard`** for pre/post-auth request gates.',
@@ -67,6 +76,11 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- MCP **`create_table` supports `isSingleRecord` directly**. Set `isSingleRecord: true` in the create call for settings/config tables that should keep only one record; do not create first and then patch only for this flag.',
     '- MCP **`create_table` does not accept `alias`**. Do not invent or send alias during table creation; default route/schema behavior is based on `name`. Use `update_table` later only when alias truly needs to change.',
     '- In `create_table.relations`, each relation uses `targetTable` (table id or `{id}`), `type`, `propertyName`, optional `inversePropertyName` or `mappedBy`, `isNullable`, `onDelete`, and `description`. The target table must already exist.',
+    '- **Use `user_definition` as the only user table.** Do not create app-specific user/profile mapping tables such as `chat_profile`, `app_user`, `customer_user`, or tables that only mirror/link Enfyra users. If an app needs extra user fields or user relations, add columns/relations directly on `user_definition`.',
+    '- When modeling features that involve users, relate domain tables directly to `user_definition` through real Enfyra relations. Examples: `chat_conversation_member.member` → `user_definition`, `chat_message.sender` → `user_definition`, `order.customer` → `user_definition`. Do not create duplicate scalar columns like `userId` or separate profile records just to point back to a user.',
+    '- **Prefer real relations over relation-shaped columns.** If a field represents another record or list of records, model it as `relations`, not as columns such as `userId`, `author_id`, `categoryIds`, `teamIds`, `itemsJson`, or object/array JSON containing related records. Ask only when the user explicitly wants denormalized snapshot data.',
+    '- Common mapping: one owner record → `many-to-one`; one record has many children → define the child `many-to-one` and use inverse/read deep relation; peer/tag lists → `many-to-many`; one profile/settings row per parent → `one-to-one` when supported by the model.',
+    '- If the user asks to add a foreign key field, interpret it as a relation request unless they explicitly say they need a plain scalar column. Do not create both a relation and a duplicate scalar FK column for the same concept.',
     '- **Never ask for or provide physical FK column names** when creating/updating relations. Do not include `fkCol`, `fkColumn`, `foreignKeyColumn`, `sourceColumn`, `targetColumn`, `junctionSourceColumn`, or `junctionTargetColumn` in create/update payloads unless you are only displaying existing metadata. Enfyra relation cascade derives physical FK/junction names from `propertyName` and table metadata, then hides FK columns from app form/schema definition.',
     '- For relation CRUD payloads, the public interface is the relation `propertyName`: example create body uses `"author": {"id": 1}`, not `"authorId"` or a physical FK column. Query/deep/filter keys also use relation `propertyName`.',
     '- 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.',
@@ -124,19 +138,21 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Enfyra exposes OAuth callback at **`{ENFYRA_API_URL}/auth/{provider}/callback`**. Example when `ENFYRA_API_URL` is `http://localhost:3000/api`: **Google** callback URL is **`http://localhost:3000/api/auth/google/callback`** — i.e. `{ENFYRA_API_URL}/auth/google/callback` (same pattern for Facebook/GitHub: `.../auth/facebook/callback`, `.../auth/github/callback`).',
     '- **Google Cloud Console** → OAuth client → **Authorized redirect URIs**: register **exactly** that URL (scheme + host + path, no typo, no extra slash).',
     '- **Enfyra** (`oauth_config_definition` / OAuth settings): field **`redirectUri`** must be the **same string** as in Google Console — byte-for-byte. If they differ, Google or the server will reject the flow.',
-    '- **`appCallbackUrl`** (Enfyra OAuth config) is **different**: it is the **frontend app** URL where Enfyra redirects **after** a successful OAuth (server attaches `accessToken`, `refreshToken`, etc. in query). That is your SPA route (e.g. `https://myapp.com/oauth/callback`), **not** the Google redirect URI.',
+    '- **SSR/cookie mode:** enable `autoSetCookies` / set-cookies mode in Enfyra OAuth config. Enfyra redirects to the SSR app endpoint `/api/auth/set-cookies`, which stores httpOnly cookies and then redirects to the original `redirect` URL.',
+    '- **Manual token mode only:** `appCallbackUrl` is the frontend URL where Enfyra redirects after OAuth with `accessToken`, `refreshToken`, etc. in query. Use this only when the app intentionally manages tokens itself; it is not the preferred Nuxt/Next SSR pattern.',
     '',
     '**Server flow (for answering users or designing FE):**',
-    '1. **Start login (redirect user in browser):** `GET {base}/auth/{provider}?redirect=<URL_ENCODED>` — **`redirect` is required** (where to send the user after the whole flow; encoded in `state`). Example: `?redirect=https%3A%2F%2Fmyapp.com%2Foauth-done`',
+    '1. **Start login (redirect user in browser):** SSR/cookie apps use `GET {{ nuxtApp }}/api/auth/{provider}?redirect=<URL_ENCODED>`; direct/manual apps may use `GET {base}/auth/{provider}?redirect=<URL_ENCODED>`. `redirect` is required and is where to send the user after the whole flow.',
     '2. Server **302** to Google/Facebook/GitHub authorization page.',
     '3. Provider calls back: `GET {base}/auth/{provider}/callback?code=...&state=...` (server exchanges code, creates/links user, issues JWT).',
-    '4. Server **302** to **`appCallbackUrl`** from OAuth config, with query params: **`accessToken`**, **`refreshToken`**, **`expTime`**, **`loginProvider`**, **`redirect`** (the original `redirect` from step 1). On failure, redirects to `redirect` with **`?error=...`**.',
+    '4. In SSR/cookie mode, backend redirects to `{{ nuxtApp }}/api/auth/set-cookies` with token query params; the SSR route stores httpOnly cookies and redirects to `redirect`. In manual token mode, backend redirects to `appCallbackUrl` with token query params. On failure, redirect includes `?error=...`.',
     '',
     '**Frontend build checklist:**',
-    '- Register **`appCallbackUrl`** in Enfyra (SPA route). Implement that page: on load read `accessToken`, `refreshToken`, `expTime` from query (then **strip from URL**), store tokens, use `Authorization: Bearer` for API.',
-    '- **“Login with Google” button:** `location.href = `${ENFYRA_API_URL}/auth/google?redirect=${encodeURIComponent(appCallbackUrlOrReturn)}`` — `ENFYRA_API_URL` is the API base (e.g. ends with `/api`). `redirect` is where the user should go after tokens are delivered (often matches or relates to `appCallbackUrl`).',
+    '- Nuxt/Next SSR: implement same-origin API proxy at `/api/**`, a password login route at `/api/login`, and OAuth set-cookie route at `/api/auth/set-cookies`. Browser code never stores JWTs.',
+    '- **“Login with Google” button in SSR/cookie apps:** `location.href = `/api/auth/google?redirect=${encodeURIComponent(returnUrl)}``.',
+    '- Manual token apps only: register `appCallbackUrl`, read token query params there, strip the URL, store tokens, and use `Authorization: Bearer`.',
     '- **Error handling:** If redirected with `?error=`, show message to user.',
-    '- **Do not confuse:** Google’s **Authorized redirect URI** = Enfyra **`redirectUri`** = `{ENFYRA_API_URL}/auth/google/callback`. **`appCallbackUrl`** = your SPA only (Enfyra redirects there *after* processing Google’s callback).',
+    '- **Do not confuse:** Google’s **Authorized redirect URI** = Enfyra **`redirectUri`** = backend/proxy `{API_BASE}/auth/google/callback`. SSR set-cookie route = app-owned `/api/auth/set-cookies`. `appCallbackUrl` is only for manual token mode.',
     '',
     '### System tables — which have REST routes',
     '- **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.',

package/src/mcp-server-entry.mjs

@@ -138,7 +138,7 @@ function inferPrimaryKeyContext(tables) {
     dominantPrimaryKey: dominant,
     counts,
     inferredBackendFamily: dominant === '_id' ? 'mongodb-like' : dominant === 'id' ? 'sql-like' : 'unknown',
-    exactDatabaseType: 'not exposed by current public/admin API; infer from metadata or add a backend context endpoint for exact mysql/postgres/mongodb/sqlite',
+    exactDatabaseType: 'not exposed by current public/admin API; infer from metadata or add a backend context endpoint for exact mysql/postgres/mongodb',
     sampleTables: primaryColumns.slice(0, 12),
   };
 }