@enfyra/mcp-server 0.0.28 → 0.0.30

package/README.md

@@ -20,8 +20,9 @@ npx @enfyra/mcp-server config
 - **Interactive (default in a terminal):** first asks **where** to write config with an arrow-key selector — Claude Code, Cursor, Codex, or all — 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 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.
+- **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 project values as defaults, and replaces the old project `enfyra` entry for that host.
+- **Global/user config:** add `--global` only when you intentionally want the selected host config under your home directory instead of this project.
 - **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`.
@@ -34,18 +35,18 @@ Use this table to see **where** each host stores config. The **`mcpServers.enfyr
 
 | | **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 |
+| **Project (repo, default)** | **`.codex/config.toml`** in the project | **`.mcp.json`** at repository root | **`.cursor/mcp.json`** in the project |
+| **Global (explicit `--global`)** | `~/.codex/config.toml` | `~/.mcp.json` from this helper, or Claude's `~/.claude.json` via `claude mcp add --scope user` | `~/.cursor/mcp.json` |
+| **Typical install** | `npx @enfyra/mcp-server config --codex` | `npx @enfyra/mcp-server config --claude-code` | `npx @enfyra/mcp-server config --cursor` |
+| **Precedence / merge** | Project config is merged/replaced for `enfyra` | Project `.mcp.json` is merged/replaced for `enfyra` | Project `.cursor/mcp.json` is merged/replaced for `enfyra` |
+| **Gotcha** | Open this folder in a new Codex 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:
+The config command writes project Codex config to `./.codex/config.toml` by default:
 
 ```bash
 npx @enfyra/mcp-server config --codex
@@ -73,7 +74,7 @@ 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`.
+The config writer replaces only `[mcp_servers.enfyra]` and `[mcp_servers.enfyra.env]`; other Codex config and other MCP servers are preserved. Open this folder in a new Codex session after updating `./.codex/config.toml`. Use `--global --codex` only when you intentionally want `~/.codex/config.toml`.
 
 </details>
 
@@ -184,18 +185,19 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `ENFYRA_API_URL` | Base for REST + GraphQL + auth (see table below) | `http://localhost:3000/api` |
+| `ENFYRA_API_URL` | Base for REST + GraphQL + auth through the Nuxt/app proxy | `http://localhost:3000/api` |
 | `ENFYRA_EMAIL` | Admin email | — |
 | `ENFYRA_PASSWORD` | Admin password | — |
 
-### `ENFYRA_API_URL` — two valid setups
+### `ENFYRA_API_URL` — use the app proxy
 
-| Mode | Example | When to use |
-|------|---------|-------------|
-| **Via Nuxt admin (typical local dev)** | `http://localhost:3000/api` | Browser app on 3000; Nitro proxies `/api/*` to Nest (`API_URL`, often `http://localhost:1105`). GraphQL at `{ENFYRA_API_URL}/graphql` is proxied to the backend `/graphql`. |
-| **Direct to Nest backend** | `http://localhost:1105` | Call Enfyra **without** the Nuxt prefix. **Do not** append `/api` unless your reverse proxy serves routes under `/api`—`http://localhost:1105/api/...` will not match default Nest paths. |
+For normal apps and demos, set `ENFYRA_API_URL` to the Nuxt/app proxy:
 
-Pick the base URL that matches how **your** HTTP client reaches the same server as the Enfyra REST API.
+```text
+http://localhost:3000/api
+```
+
+The Enfyra backend is private infrastructure. MCP, browser code, SSR routes, GraphQL calls, and generated app code should go through the app origin `/api/**`; do not connect them directly to the backend host/port. Direct backend URLs are only for Enfyra core/server debugging when you intentionally bypass the app proxy.
 
 ### SSR app auth pattern
 

package/package.json

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

package/src/lib/config-local.mjs

@@ -13,32 +13,34 @@ function printHelp() {
 Usage:
   npx @enfyra/mcp-server config [options]
 
-Writes project config under the current working directory and Codex config under your home directory:
+Writes project config under the current working directory:
   • ./.mcp.json           — Claude Code project scope
   • ./.cursor/mcp.json    — Cursor project scope
-  • ~/.codex/config.toml  — Codex user scope
+  • ./.codex/config.toml  — Codex project scope
 
 Options:
   --api-url, -a <url>     ENFYRA_API_URL
   --email, -e <email>     ENFYRA_EMAIL
   --password, -p <secret> ENFYRA_PASSWORD
+  --global                Write global/user config for selected hosts instead of project config
   --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 all; with TTY and no target flags, choose with ↑/↓:
   --claude-code, --claude, --claude-only   Only ./.mcp.json (Claude Code project scope)
   --cursor, --cursor-only                  Only ./.cursor/mcp.json (Cursor)
-  --codex, --codex-only                    Only ~/.codex/config.toml (Codex)
+  --codex, --codex-only                    Only ./.codex/config.toml (Codex project scope)
   Passing multiple target flags writes each selected target.
   -h, --help              Show this help
 
 Interactive mode: lets you choose Claude Code / Cursor / Codex / all if you did not pass target flags; then asks for URL / email / password
-  when missing. Existing ./.mcp.json, ./.cursor/mcp.json, and ~/.codex/config.toml are used as defaults. Re-run to update.
+  when missing. Existing project config is 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 --global --codex
   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
@@ -57,6 +59,7 @@ function parseArgs(argv) {
     help: false,
     yes: false,
     reconfig: false,
+    global: false,
   };
   let pickClaude = false;
   let pickCursor = false;
@@ -73,6 +76,7 @@ function parseArgs(argv) {
     else if (a === 'help') out.help = true;
     else if (a === '--yes') out.yes = true;
     else if (a === '--reconfig') out.reconfig = true;
+    else if (a === '--global') out.global = 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();
@@ -200,11 +204,23 @@ async function readCodexEnfyraEnv(absPath) {
   return null;
 }
 
-async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex) {
+function getCodexConfigPath(root, globalScope) {
+  return globalScope ? join(homedir(), '.codex', 'config.toml') : join(root, '.codex', 'config.toml');
+}
+
+function getClaudeConfigPath(root, globalScope) {
+  return globalScope ? join(homedir(), '.mcp.json') : join(root, '.mcp.json');
+}
+
+function getCursorConfigPath(root, globalScope) {
+  return globalScope ? join(homedir(), '.cursor', 'mcp.json') : join(root, '.cursor', 'mcp.json');
+}
+
+async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex, globalScope) {
   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'));
+  if (readClaude) paths.push(getClaudeConfigPath(root, globalScope));
+  if (readCursor) paths.push(getCursorConfigPath(root, globalScope));
+  if (!globalScope && !readClaude && readCursor) paths.push(join(root, '.mcp.json'));
   const seen = new Set();
   for (const p of paths) {
     if (seen.has(p)) continue;
@@ -225,7 +241,7 @@ async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex) {
     }
   }
   if (readCodex) {
-    const codex = await readCodexEnfyraEnv(join(homedir(), '.codex', 'config.toml'));
+    const codex = await readCodexEnfyraEnv(getCodexConfigPath(root, globalScope));
     if (codex) return codex;
   }
   return { apiUrl: '', email: '', password: '' };
@@ -234,15 +250,15 @@ async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex) {
 async function promptTargetChoice() {
   const choices = [
     {
-      label: 'Claude Code — ./.mcp.json',
+      label: 'Claude Code — project ./.mcp.json',
       value: { claude: true, cursor: false, codex: false },
     },
     {
-      label: 'Cursor — ./.cursor/mcp.json',
+      label: 'Cursor — project ./.cursor/mcp.json',
       value: { claude: false, cursor: true, codex: false },
     },
     {
-      label: 'Codex — ~/.codex/config.toml',
+      label: 'Codex — project ./.codex/config.toml',
       value: { claude: false, cursor: false, codex: true },
     },
     {
@@ -259,7 +275,7 @@ async function promptTargetChoice() {
     'Where should Enfyra MCP config be written?\n'
       + '  [1] Claude Code — ./.mcp.json\n'
       + '  [2] Cursor — ./.cursor/mcp.json\n'
-      + '  [3] Codex — ~/.codex/config.toml\n'
+      + '  [3] Codex — ./.codex/config.toml\n'
       + '  [4] All [default]\n'
       + 'Choice [4]: ',
   )).trim().toLowerCase();
@@ -420,7 +436,7 @@ export async function runLocalConfig(argv) {
     writeCodex = t.codex;
   }
 
-  const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex);
+  const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex, opts.global);
 
   let apiUrl;
   let email;
@@ -441,17 +457,17 @@ export async function runLocalConfig(argv) {
   const written = [];
 
   if (writeClaude) {
-    const p = join(root, '.mcp.json');
+    const p = getClaudeConfigPath(root, opts.global);
     await mergeMcpFile(p, serverEntry);
     written.push(p);
   }
   if (writeCursor) {
-    const p = join(root, '.cursor', 'mcp.json');
+    const p = getCursorConfigPath(root, opts.global);
     await mergeMcpFile(p, serverEntry);
     written.push(p);
   }
   if (writeCodex) {
-    const p = join(homedir(), '.codex', 'config.toml');
+    const p = getCodexConfigPath(root, opts.global);
     await mergeCodexConfig(p, apiUrl, email, password);
     written.push(p);
   }
@@ -459,9 +475,9 @@ export async function runLocalConfig(argv) {
   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('  • Codex: open this folder in a new Codex session so project ./.codex/config.toml is loaded.');
   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('  • Cursor: open this folder, restart Cursor or reload MCP, then 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

@@ -48,9 +48,10 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Extensions/packages/menus:** `extension_definition`, `menu_definition`, `package_definition`, `bootstrap_script_definition`; extensions are Vue SFC only, and packages should be installed with `install_package`.',
     '- **Platform config:** `setting_definition`, `cors_origin_definition`, reload endpoints, logs, and metadata endpoints.',
     '',
-    '### 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`.',
+    '### ENFYRA_API_URL (MCP must use the app proxy)',
+    '- **Required default:** point MCP at the Nuxt/app origin proxy, e.g. `http://localhost:3000/api`. Nuxt proxies `/api/*` to the hidden Enfyra backend (`API_URL`, e.g. `http://localhost:1105`).',
+    '- Treat the Enfyra backend as private infrastructure. Do not tell app-building agents to connect MCP, browser code, SSR code, or generated app code directly to the backend host/port.',
+    '- Direct-to-backend URLs such as `http://localhost:1105` are only for Enfyra core/server debugging when the user explicitly asks to bypass the app proxy. They are not valid guidance for normal apps or deployable demos.',
     '- 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',
@@ -60,7 +61,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
+    '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server logs itself in with email/password against `{ENFYRA_API_URL}/auth/login`; for normal app work, `ENFYRA_API_URL` must still be the app proxy base such as `{{ nuxtApp }}/api`.',
     '',
     '### 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.',
@@ -194,7 +195,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- In custom dynamic code, use the same lightweight pattern: `const result = await @REPOS.main.find({ fields: "id", limit: 1, meta: filter ? "filterCount" : "totalCount", ...(filter ? { filter } : {}) }); const count = filter ? result.meta?.filterCount : result.meta?.totalCount;`.',
     '',
     '### GraphQL (same prefix as REST / ENFYRA_API_URL)',
-    `- **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\`.`,
+    `- **POST** \`${graphqlHttpUrl}\` — GraphQL endpoint (body: GraphQL query). With the required app proxy base: e.g. \`http://localhost:3000/api/graphql\`.`,
     `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text); same base pattern as above.`,
     '- A table appears in the schema when `gql_definition` has an enabled row for that table. The REST route `availableMethods` list does not enable GraphQL.',
     '- **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`. If every column is skipped for input (only PK, or only `createdAt`/`updatedAt`, or all unpublished), the schema emits **no** `Query.<tableName>` and **no** create/update/delete mutations for that table (an output `type` may still exist for relation wiring).',
@@ -218,7 +219,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '-   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**.',
+    '- **Client**: Browser apps must connect through the app/Nuxt Socket.IO bridge, not the hidden Enfyra backend. For the Enfyra Nuxt bridge this is typically `io("/ws/<namespace>")`, e.g. `io("/ws/chat")`, while the backend gateway metadata path remains `/chat`.',
     '- **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 }`.',
     '- MCP wrapper: use **`run_admin_test`** with `kind:"websocket_event"` or `kind:"websocket_connection"` instead of hand-building the HTTP call.',