@enfyra/mcp-server 0.1.10 → 0.1.12

package/README.md

@@ -9,24 +9,26 @@ This package is the MCP bridge only. Assistant rules, schema behavior, dynamic s
 From your project root:
 
 ```bash
-npx @enfyra/mcp-server config
+npx @enfyra/mcp-server@latest config
 ```
 
 The config command writes project config for Codex, Claude Code, Cursor, VS Code / GitHub Copilot, and Google Antigravity. It preserves other MCP servers and replaces only the `enfyra` entry.
 
 Interactive setup asks for your Enfyra app/admin URL, then guides you to the token page when needed and asks for `ENFYRA_API_TOKEN`.
 
+Generated MCP host configs run `npx -y @enfyra/mcp-server@latest` so every host start resolves the current npm `latest` dist-tag published by Enfyra.
+
 ```bash
 # Non-interactive, all supported clients
-npx @enfyra/mcp-server config --yes \
+npx @enfyra/mcp-server@latest config --yes \
   --app-url http://localhost:3000 \
   -t efy_pat_your-token
 
 # One or more clients
-npx @enfyra/mcp-server config --codex
-npx @enfyra/mcp-server config --cursor --claude-code
-npx @enfyra/mcp-server config --vscode
-npx @enfyra/mcp-server config --antigravity
+npx @enfyra/mcp-server@latest config --codex
+npx @enfyra/mcp-server@latest config --cursor --claude-code
+npx @enfyra/mcp-server@latest config --vscode
+npx @enfyra/mcp-server@latest config --antigravity
 ```
 
 Equivalent in this repo:
@@ -39,18 +41,18 @@ yarn mcp:config
 
 | Client | Command | Project config |
 |--------|---------|----------------|
-| Codex | `npx @enfyra/mcp-server config --codex` | `.codex/config.toml` |
-| Claude Code | `npx @enfyra/mcp-server config --claude-code` | `.mcp.json` |
-| Cursor | `npx @enfyra/mcp-server config --cursor` | `.cursor/mcp.json` |
-| VS Code / GitHub Copilot | `npx @enfyra/mcp-server config --vscode` | `.vscode/mcp.json` |
-| Google Antigravity | `npx @enfyra/mcp-server config --antigravity` | `.agents/mcp_config.json` |
+| Codex | `npx @enfyra/mcp-server@latest config --codex` | `.codex/config.toml` |
+| Claude Code | `npx @enfyra/mcp-server@latest config --claude-code` | `.mcp.json` |
+| Cursor | `npx @enfyra/mcp-server@latest config --cursor` | `.cursor/mcp.json` |
+| VS Code / GitHub Copilot | `npx @enfyra/mcp-server@latest config --vscode` | `.vscode/mcp.json` |
+| Google Antigravity | `npx @enfyra/mcp-server@latest config --antigravity` | `.agents/mcp_config.json` |
 | MCP Inspector / other project-scoped hosts | Paste the shared STDIO config below | Host-specific project config |
 
 <details>
 <summary><strong>Codex setup</strong></summary>
 
 ```bash
-npx @enfyra/mcp-server config --codex
+npx @enfyra/mcp-server@latest config --codex
 ```
 
 Generated project config:
@@ -58,7 +60,7 @@ Generated project config:
 ```toml
 [mcp_servers.enfyra]
 command = "npx"
-args = ["-y", "@enfyra/mcp-server"]
+args = ["-y", "@enfyra/mcp-server@latest"]
 
 [mcp_servers.enfyra.env]
 ENFYRA_API_URL = "http://localhost:3000/api"
@@ -77,7 +79,7 @@ Official reference: [Codex config](https://developers.openai.com/codex/config-re
 <summary><strong>Claude Code setup</strong></summary>
 
 ```bash
-npx @enfyra/mcp-server config --claude-code
+npx @enfyra/mcp-server@latest config --claude-code
 ```
 
 Project config is written to `.mcp.json`. MCP server definitions do not belong in `.claude/settings.json`.
@@ -88,7 +90,7 @@ Claude Code also supports its own CLI:
 claude mcp add --transport stdio --scope project \
   --env ENFYRA_API_URL=http://localhost:3000/api \
   --env ENFYRA_API_TOKEN=efy_pat_your-token \
-  enfyra -- npx -y @enfyra/mcp-server
+  enfyra -- npx -y @enfyra/mcp-server@latest
 ```
 
 Scope precedence when the same server name exists in multiple places is local, then project, then user. Project-scoped `.mcp.json` may require approval in Claude Code.
@@ -101,7 +103,7 @@ Official references: [Claude Code MCP](https://docs.anthropic.com/en/docs/claude
 <summary><strong>Cursor setup</strong></summary>
 
 ```bash
-npx @enfyra/mcp-server config --cursor
+npx @enfyra/mcp-server@latest config --cursor
 ```
 
 Cursor project config is written to `.cursor/mcp.json`. Global config is `~/.cursor/mcp.json` on macOS/Linux or `%USERPROFILE%\.cursor\mcp.json` on Windows.
@@ -116,7 +118,7 @@ Official reference: [Cursor MCP](https://cursor.com/docs/context/mcp).
 <summary><strong>VS Code / GitHub Copilot setup</strong></summary>
 
 ```bash
-npx @enfyra/mcp-server config --vscode
+npx @enfyra/mcp-server@latest config --vscode
 ```
 
 VS Code workspace config is written to `.vscode/mcp.json`:
@@ -127,7 +129,7 @@ VS Code workspace config is written to `.vscode/mcp.json`:
     "enfyra": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@enfyra/mcp-server"],
+      "args": ["-y", "@enfyra/mcp-server@latest"],
       "env": {
         "ENFYRA_API_URL": "http://localhost:3000/api",
         "ENFYRA_API_TOKEN": "efy_pat_your-token"
@@ -147,7 +149,7 @@ Official references: [VS Code MCP servers](https://code.visualstudio.com/docs/co
 <summary><strong>Google Antigravity setup</strong></summary>
 
 ```bash
-npx @enfyra/mcp-server config --antigravity
+npx @enfyra/mcp-server@latest config --antigravity
 ```
 
 Antigravity project config is written to `.agents/mcp_config.json`:
@@ -157,7 +159,7 @@ Antigravity project config is written to `.agents/mcp_config.json`:
   "mcpServers": {
     "enfyra": {
       "command": "npx",
-      "args": ["-y", "@enfyra/mcp-server"],
+      "args": ["-y", "@enfyra/mcp-server@latest"],
       "env": {
         "ENFYRA_API_URL": "http://localhost:3000/api",
         "ENFYRA_API_TOKEN": "efy_pat_your-token"
@@ -183,7 +185,7 @@ Use the shared STDIO config with any project-scoped host that accepts an `mcpSer
   "mcpServers": {
     "enfyra": {
       "command": "npx",
-      "args": ["-y", "@enfyra/mcp-server"],
+      "args": ["-y", "@enfyra/mcp-server@latest"],
       "env": {
         "ENFYRA_API_URL": "http://localhost:3000/api",
         "ENFYRA_API_TOKEN": "efy_pat_your-token"
@@ -202,7 +204,7 @@ Official reference: [MCP Inspector](https://modelcontextprotocol.io/docs/tools/i
 ## Config Command
 
 ```bash
-npx @enfyra/mcp-server config [options]
+npx @enfyra/mcp-server@latest config [options]
 ```
 
 | Option | Use |
@@ -256,7 +258,7 @@ The MCP server includes safety guards for LLM callers:
 - Write tools require `get_enfyra_required_knowledge` acknowledgement before mutating Enfyra state. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first. If the acknowledgement is missing, the tool error tells the caller to read `get_enfyra_required_knowledge` and pass the required key.
 - Script-backed records validate `sourceCode` through `/admin/script/validate` before saving.
 - `validate_dynamic_script` checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
-- `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
+- `validate_extension_code` locally rejects common extension component-resolution mistakes, such as `resolveComponent()` or lowercase auto-injected component tags like `<ubutton>`, then checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
 - Dynamic script guidance distinguishes secure repositories (`@REPOS.main`, `@REPOS.secure.<table>`) from trusted internal repositories (`@REPOS.<table>`), and tells agents not to return raw trusted records to users.
 - `compiledCode` is generated from `sourceCode` and may differ textually because macros are expanded; the MCP server never accepts hand-written `compiledCode`.
 - Long source/code values in read responses are written to `/tmp/enfyra-mcp-sources` and returned as length/hash/preview/tmpFile metadata so LLM callers can inspect full source from the file path without truncating tool output.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
+  "packageManager": "yarn@4.17.0",
   "license": "MIT",
   "main": "src/index.mjs",
   "bin": {
-    "mcp-server": "src/index.mjs",
-    "enfyra-mcp-server": "src/index.mjs"
+    "enfyra-mcp-server": "src/index.mjs",
+    "mcp-server": "src/index.mjs"
   },
   "files": [
     "src"

package/src/index.mjs

@@ -10,8 +10,8 @@ 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 project-local MCP host config
+  npx @enfyra/mcp-server@latest                 Start the MCP stdio server
+  npx @enfyra/mcp-server@latest config [flags]  Write project-local MCP host config
 
 Common config flags:
   --codex             Write ./.codex/config.toml
@@ -25,7 +25,7 @@ Common config flags:
   -t, --api-token     ENFYRA_API_TOKEN
   -h, --help          Show config help
 
-Run \`npx @enfyra/mcp-server config --help\` for full config details.
+Run \`npx @enfyra/mcp-server@latest config --help\` for full config details.
 `);
   process.exit(0);
 }

package/src/lib/config-local.mjs

@@ -5,6 +5,7 @@ import { stdin as input, stdout as output, cwd } from 'node:process';
 import { dirname, join } from 'node:path';
 
 const SERVER_KEY = 'enfyra';
+const MCP_PACKAGE_SPEC = '@enfyra/mcp-server@latest';
 const forceColor = process.env.FORCE_COLOR != null && process.env.FORCE_COLOR !== '0';
 const canStyle = forceColor || (output.isTTY && process.env.NO_COLOR == null);
 const style = {
@@ -67,7 +68,7 @@ function printHelp() {
 ${style.dim('Write project-local MCP client config for Enfyra.')}
 
 ${style.bold('Usage')}
-  npx @enfyra/mcp-server config [options]
+  npx @enfyra/mcp-server@latest config [options]
 
 ${style.bold('Supported clients')}
   Codex        ./.codex/config.toml
@@ -99,15 +100,15 @@ ${style.bold('Interactive mode')}
   Existing Enfyra config and environment variables are used as defaults. Re-run anytime to update.
 
 ${style.bold('Examples')}
-  npx @enfyra/mcp-server config
-  npx @enfyra/mcp-server config --yes
-  npx @enfyra/mcp-server config --codex --cursor
-  npx @enfyra/mcp-server config --vscode
-  npx @enfyra/mcp-server config --antigravity
-  npx @enfyra/mcp-server config --claude-code
-  npx @enfyra/mcp-server config --reconfig
-  npx @enfyra/mcp-server config --app-url http://localhost:3000 -t 'efy_pat_...'
-  ENFYRA_APP_URL=https://demo.enfyra.io ENFYRA_API_TOKEN=efy_pat_... npx @enfyra/mcp-server config --yes
+  npx @enfyra/mcp-server@latest config
+  npx @enfyra/mcp-server@latest config --yes
+  npx @enfyra/mcp-server@latest config --codex --cursor
+  npx @enfyra/mcp-server@latest config --vscode
+  npx @enfyra/mcp-server@latest config --antigravity
+  npx @enfyra/mcp-server@latest config --claude-code
+  npx @enfyra/mcp-server@latest config --reconfig
+  npx @enfyra/mcp-server@latest config --app-url http://localhost:3000 -t 'efy_pat_...'
+  ENFYRA_APP_URL=https://demo.enfyra.io ENFYRA_API_TOKEN=efy_pat_... npx @enfyra/mcp-server@latest config --yes
 `);
 }
 
@@ -170,7 +171,7 @@ function parseArgs(argv) {
 function buildServerEntry(apiUrl, apiToken) {
   return {
     command: 'npx',
-    args: ['-y', '@enfyra/mcp-server'],
+    args: ['-y', MCP_PACKAGE_SPEC],
     env: {
       ENFYRA_API_URL: apiUrl,
       ENFYRA_API_TOKEN: apiToken,
@@ -256,7 +257,7 @@ function buildCodexTomlBlock(apiUrl, apiToken) {
   return [
     '[mcp_servers.enfyra]',
     'command = "npx"',
-    'args = ["-y", "@enfyra/mcp-server"]',
+    `args = ["-y", "${MCP_PACKAGE_SPEC}"]`,
     '',
     '[mcp_servers.enfyra.env]',
     `ENFYRA_API_URL = ${tomlString(apiUrl)}`,

package/src/lib/mcp-examples.js

@@ -667,13 +667,13 @@ update_record({
   ]),
   uniques: JSON.stringify([["message", "member"]]),
   indexes: JSON.stringify([
-    ["member", "isRead", "conversation"],
-    ["conversation", "member", "isRead"]
+    ["conversation", "isRead"]
   ])
 })`,
         notes: [
           'Unread is per user and per message; do not put global read state on conversation.',
-          'readAt is a datetime field and gets its own auto index; the explicit indexes here are compound unread lookup indexes.',
+          'message and member appear in the unique constraint, so they must not be added to indexes; unique fields are already indexed by the unique constraint.',
+          'readAt is a datetime field and gets its own auto index; explicit indexes should cover only non-unique hot lookup fields.',
           'For chat-list UX, default to a boolean unread dot instead of exact counts.',
         ],
       },

package/src/lib/mcp-instructions.js

@@ -34,6 +34,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
     '- Prefer the most specific business operation tool over raw metadata CRUD. `discover_enfyra_workflows` provides the current operation-tool map and negative-routing avoidTools.',
     '- Before saving standalone dynamic script or extension code, call `validate_dynamic_script` or `validate_extension_code` unless the chosen ensure/update tool already validates the code.',
+    '- Extension SFCs must use auto-injected components directly in templates, such as `<UButton>`, and must not call `resolveComponent()` for Nuxt UI/eApp components.',
     '- For existing script-backed records, use `trace_metadata_usage` then `get_script_source`; edit with `patch_script_source` or `update_script_source` so source is hash-checked and validated.',
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',
     '',

package/src/lib/platform-operation-tools.js

@@ -12,6 +12,36 @@ import {
   globalRulesAckParam,
 } from './required-knowledge.js';
 
+const AUTO_INJECTED_EXTENSION_COMPONENT_TAGS = [
+  'CommonDrawer',
+  'CommonModal',
+  'EmptyState',
+  'FormEditor',
+  'FormEditorLazy',
+  'NuxtLink',
+  'PermissionGate',
+  'UBadge',
+  'UButton',
+  'UCheckbox',
+  'UDropdownMenu',
+  'UForm',
+  'UFormField',
+  'UIcon',
+  'UInput',
+  'UModal',
+  'USelect',
+  'USelectMenu',
+  'USkeleton',
+  'USwitch',
+  'UTabs',
+  'UTextarea',
+  'UTooltip',
+  'Widget',
+];
+const AUTO_INJECTED_EXTENSION_COMPONENT_BY_LOWERCASE = new Map(
+  AUTO_INJECTED_EXTENSION_COMPONENT_TAGS.map((tag) => [tag.toLowerCase(), tag]),
+);
+
 function unwrapData(result) {
   return Array.isArray(result?.data) ? result.data : [];
 }
@@ -360,6 +390,7 @@ function getExtensionThemeContract() {
     ],
     components: [
       'Use Nuxt UI/eApp components for normal controls: UButton, UInput, UTextarea, USelectMenu/USelect, USwitch, UCheckbox, UTabs, UBadge, UModal, and CommonDrawer when available.',
+      'Use auto-injected components directly in the template with PascalCase names. Do not call resolveComponent() to manually resolve Nuxt UI/eApp components inside extension SFCs; it can compile but render unresolved lowercase DOM tags such as <ubutton>.',
       'Buttons should have stable geometry: hover may change color, border, or shadow but must not move the button or resize its content. Disabled buttons keep disabled cursor/visual state.',
       'Inputs and textareas should not add hover movement or decorative hover states; focus, invalid, disabled, and loading states must be explicit.',
       'Dynamic extensions resolve UModal to the app CommonModal. Do not pass ui.content: "eapp-surface-card" or "surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller ui.content should only append z-index, width, or max-width classes.',
@@ -541,7 +572,66 @@ async function validateDynamicScript(apiUrl, sourceCode, scriptLanguage = 'javas
   };
 }
 
+function readTemplateBlocks(code) {
+  const blocks = [];
+  const lower = String(code || '').toLowerCase();
+  let index = 0;
+  while (index < lower.length) {
+    const openStart = lower.indexOf('<template', index);
+    if (openStart === -1) break;
+    const boundary = lower[openStart + '<template'.length];
+    if (boundary && !/\s|>/.test(boundary)) {
+      index = openStart + 1;
+      continue;
+    }
+    const openEnd = lower.indexOf('>', openStart + '<template'.length);
+    if (openEnd === -1) break;
+    const closeStart = lower.indexOf('</template', openEnd + 1);
+    if (closeStart === -1) break;
+    blocks.push(String(code).slice(openEnd + 1, closeStart));
+    index = closeStart + '</template'.length;
+  }
+  return blocks;
+}
+
+function readTemplateTagName(template, start) {
+  const next = template[start + 1];
+  if (!next || next === '!' || next === '?') return null;
+  let index = start + (next === '/' ? 2 : 1);
+  while (/\s/.test(template[index] || '')) index += 1;
+  const nameStart = index;
+  while (/[\w.-]/.test(template[index] || '')) index += 1;
+  return index > nameStart ? template.slice(nameStart, index) : null;
+}
+
+export function validateExtensionCodeLocally(code) {
+  if (/\bresolveComponent\s*\(/.test(String(code || ''))) {
+    throw new Error('Invalid extension component resolution: do not call resolveComponent() in Enfyra extensions. Use auto-injected components such as <UButton> directly in the template so the app/compiler resolves them correctly.');
+  }
+
+  const violations = [];
+  for (const template of readTemplateBlocks(code)) {
+    let index = 0;
+    while (index < template.length) {
+      const tagStart = template.indexOf('<', index);
+      if (tagStart === -1) break;
+      const tagName = readTemplateTagName(template, tagStart);
+      if (tagName && tagName === tagName.toLowerCase() && !tagName.includes('-')) {
+        const expected = AUTO_INJECTED_EXTENSION_COMPONENT_BY_LOWERCASE.get(tagName);
+        if (expected) violations.push({ tag: tagName, expected });
+      }
+      index = tagStart + 1;
+    }
+  }
+  if (violations.length) {
+    const first = violations[0];
+    throw new Error(`Invalid extension component casing: use <${first.expected}> instead of <${first.tag}>. Enfyra/Nuxt UI auto-injected components must keep PascalCase in extension templates; lowercase tags render as unresolved DOM elements.`);
+  }
+  return { componentCasing: 'passed' };
+}
+
 async function validateExtensionCode(apiUrl, code, name) {
+  const localChecks = validateExtensionCodeLocally(code);
   const result = await fetchAPI(apiUrl, '/enfyra_extension/preview', {
     method: 'POST',
     body: JSON.stringify({ code, name }),
@@ -551,6 +641,7 @@ async function validateExtensionCode(apiUrl, code, name) {
   }
   return {
     valid: true,
+    localChecks,
     extensionId: result?.extensionId || name || null,
     compiledLength: typeof result?.compiledCode === 'string' ? result.compiledCode.length : undefined,
   };

package/src/lib/required-knowledge.js

@@ -1,8 +1,8 @@
-export const GLOBAL_RULES_ACK_KEY = 'EFYRA::GLOBAL-RULES::READ-LIVE-CONTEXT-FIRST::2bW-20260701';
+export const GLOBAL_RULES_ACK_KEY = 'EFYRA::GLOBAL-RULES::UNIQUE-FIELDS-ARE-INDEXED::2bW-20260701B';
 export const DYNAMIC_CODE_KNOWLEDGE_ACK_KEY = 'EFYRA::SECURE-REPO-CONTRACT::R9x-kelp-42Q::NO-RAW-TRUSTED';
 export const EXTENSION_KNOWLEDGE_ACK_KEY = 'EFYRA::EXTENSION-THEME-CONTRACT::VIOLET-IS-NOT-A-PLAN::7mQ';
 
-const REQUIRED_KNOWLEDGE_VERSION = '2026-07-01.global-rules-v1';
+const REQUIRED_KNOWLEDGE_VERSION = '2026-07-01.global-rules-v2';
 
 export function globalRulesAckParam(z) {
   return z.string().describe('Required global-rules acknowledgement key from get_enfyra_required_knowledge. Call that tool, read the global Enfyra MCP rules, then pass globalRulesAckKey exactly.');
@@ -84,6 +84,15 @@ export function buildRequiredKnowledgePayload() {
           'Never fabricate ids, field names, relation names, paths, package names, or permission scopes.',
         ],
       },
+      {
+        id: 'schema-constraints',
+        rules: [
+          'For table schema, a field that appears in any uniques group must not appear in indexes.',
+          'A unique constraint already creates the indexed unique lookup for its fields.',
+          'Use uniques for data integrity and indexes only for non-unique query-performance fields that are not already unique.',
+          'Before create_table or update_table with indexes/uniques, inspect the current table and remove indexes that reference unique fields.',
+        ],
+      },
       {
         id: 'security-first',
         rules: [
@@ -166,6 +175,7 @@ export function buildRequiredKnowledgePayload() {
         id: 'extension-runtime-contract',
         rules: [
           'Save extensions as enfyra_extension Vue SFC records; no static import statements in extension code.',
+          'Do not call resolveComponent() in extension SFCs. Use auto-injected components such as <UButton>, <UBadge>, <PermissionGate>, and <Widget> directly in the template so the app/compiler resolves them correctly.',
           'Load app packages with getPackages(["package-name"]) inside extension runtime code.',
           'Prefer FormEditor/FormEditorLazy for direct table-backed forms when the form maps to metadata fields.',
           'For long admin setup workflows, open CommonDrawer immediately and show loading/error/content inside it.',

package/src/lib/table-tools.js

@@ -125,6 +125,37 @@ function normalizeConstraintGroups(name, groups) {
   });
 }
 
+function parseConstraintGroupsParam(name, value) {
+  return normalizeConstraintGroups(name, parseJsonArrayParam(name, value));
+}
+
+function normalizeConstraintGroupsValue(name, value) {
+  if (value == null) return [];
+  const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${name} must be a JSON array.`);
+  }
+  return normalizeConstraintGroups(name, parsed);
+}
+
+export function assertIndexesDoNotReferenceUniqueFields(indexes, uniques) {
+  const uniqueFields = new Set(uniques.flat());
+  const conflicts = indexes
+    .map((group) => ({
+      index: group,
+      uniqueFields: group.filter((field) => uniqueFields.has(field)),
+    }))
+    .filter((conflict) => conflict.uniqueFields.length > 0);
+  if (conflicts.length > 0) {
+    const groups = conflicts
+      .map((conflict) => `${JSON.stringify(conflict.index)} uses unique field(s) ${JSON.stringify(conflict.uniqueFields)}`)
+      .join('; ');
+    throw new Error(
+      `Invalid schema constraints: indexes must not include fields that are already unique. Conflict(s): ${groups}. Unique constraints already create indexed lookups; remove unique fields from indexes and keep those fields only in uniques.`,
+    );
+  }
+}
+
 export function normalizeRelationForTablePatch(relation) {
   for (const key of FORBIDDEN_RELATION_KEYS) {
     if (Object.prototype.hasOwnProperty.call(relation, key)) {
@@ -566,6 +597,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       '**Not** for adding a custom API path or handler only — for that use **`create_route`** without `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
       'PREFERRED: pass `columns` and `relations` params as JSON arrays to create a table WITH columns and relations in one call (cascade). Only use create_column/create_relation separately when adding to an existing table later.',
       'Indexes and uniques are first-class table metadata. Use `indexes` for query performance and `uniques` for data integrity. Each entry is a logical field group such as [["member","isRead","conversation"]] or [{"value":["message","member"]}]. Relation property names are allowed; Enfyra resolves them to physical FK columns.',
+      'A field that appears in any `uniques` group must not appear in `indexes`; unique constraints already create indexed unique lookups.',
       'Relations are supported in this same create_table call when the target table already exists. Each relation uses { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete? }; targetTable may be a table id, {id}, or an exact table name that MCP resolves to an id before mutation. Omit inversePropertyName unless a concrete parent-to-child query or UI surface needs it.',
       'Do NOT provide physical FK/junction columns. Never include fkCol, fkColumn, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn. Enfyra derives and hides those physical columns from relation propertyName/table metadata.',
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
@@ -583,7 +615,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record tables such as settings/config. This is passed directly to enfyra_table create.'),
       columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, isPublished?, isUpdatable?, isEncrypted?, defaultValue?, description?, options? }. Set isEncrypted=true for values encrypted at rest; set isUpdatable=false separately only when the field should be immutable. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"api_key","type":"varchar","isEncrypted":true,"isPublished":false}]'),
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id, {"id": <id>}, or an exact table name that MCP resolves to an id before mutation. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Omit inversePropertyName unless a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal needs the reverse field. Example only when parent posts are queried: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
-      indexes: z.string().optional().describe('JSON array of logical index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Example: [["member","isRead","conversation"],["conversation","member","isRead"]]'),
+      indexes: z.string().optional().describe('JSON array of logical non-unique index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Do not include any field that appears in uniques; unique constraints already create indexed unique lookups. Example: [["status","createdAt"]]'),
       uniques: z.string().optional().describe('JSON array of logical unique field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Example: [["message","member"]]'),
       globalRulesAckKey: globalRulesAckParam(z),
     },
@@ -596,8 +628,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       const userRelations = metadata
         ? resolveRelationTargetsFromMetadata(metadata, parsedRelations)
         : parsedRelations;
-      const indexes = normalizeConstraintGroups('indexes', parseJsonArrayParam('indexes', indexesJson));
-      const uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
+      const indexes = parseConstraintGroupsParam('indexes', indexesJson);
+      const uniques = parseConstraintGroupsParam('uniques', uniquesJson);
+      assertIndexesDoNotReferenceUniqueFields(indexes, uniques);
       const body = { name, description, columns: [idColumn, ...userColumns], relations: userRelations };
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
       if (indexesJson !== undefined) body.indexes = indexes;
@@ -654,6 +687,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       'Update table properties: name (rename), alias, description, isSingleRecord, graphqlEnabled, indexes, and uniques.',
       'Does NOT modify columns or relations — use create_column, update_column, delete_column, create_relation for those.',
       'When passing `indexes` or `uniques`, pass the complete desired array of logical field groups; omitted fields are preserved. Relation property names are allowed and are resolved by Enfyra. Example indexes: [["member","isRead","conversation"],["conversation","member","isRead"]].',
+      'A field that appears in any `uniques` group must not appear in `indexes`; unique constraints already create indexed unique lookups.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     {
@@ -663,7 +697,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('New description.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record table (e.g., settings/config).'),
       graphqlEnabled: z.boolean().optional().describe('Enable or disable GraphQL for this table by syncing enfyra_graphql.isEnabled. GraphQL table data still requires Bearer auth; anonymous root or schema probes may return 200.'),
-      indexes: z.string().optional().describe('Complete JSON array of logical index field groups to store on enfyra_table.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear.'),
+      indexes: z.string().optional().describe('Complete JSON array of logical non-unique index field groups to store on enfyra_table.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear. Do not include any field that appears in uniques; unique constraints already create indexed unique lookups.'),
       uniques: z.string().optional().describe('Complete JSON array of logical unique field groups to store on enfyra_table.uniques. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current uniques; pass [] to clear.'),
       globalRulesAckKey: globalRulesAckParam(z),
     },
@@ -675,8 +709,19 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       if (description !== undefined) body.description = description;
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
       if (graphqlEnabled !== undefined) body.graphqlEnabled = graphqlEnabled;
-      if (indexesJson !== undefined) body.indexes = normalizeConstraintGroups('indexes', parseJsonArrayParam('indexes', indexesJson));
-      if (uniquesJson !== undefined) body.uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
+      if (indexesJson !== undefined) body.indexes = parseConstraintGroupsParam('indexes', indexesJson);
+      if (uniquesJson !== undefined) body.uniques = parseConstraintGroupsParam('uniques', uniquesJson);
+
+      if (indexesJson !== undefined || uniquesJson !== undefined) {
+        let indexes = body.indexes;
+        let uniques = body.uniques;
+        if (indexes === undefined || uniques === undefined) {
+          const existing = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
+          if (indexes === undefined) indexes = normalizeConstraintGroupsValue('indexes', existing.indexes);
+          if (uniques === undefined) uniques = normalizeConstraintGroupsValue('uniques', existing.uniques);
+        }
+        assertIndexesDoNotReferenceUniqueFields(indexes ?? [], uniques ?? []);
+      }
 
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, body);
       return jsonContent({