@enfyra/mcp-server 0.0.18 → 0.0.20

package/package.json

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

package/src/lib/mcp-instructions.js

@@ -28,18 +28,43 @@ 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}\`.`,
     '',
+    '### First-step rule: discover before answering architecture/capability questions',
+    '- If the user asks what Enfyra supports, how to build a feature, which API exists, or whether a tool/schema path can do something, call **`discover_enfyra_system`** first. It reads live metadata, route definitions, method rows, route-backed tables, no-route tables, and capability areas.',
+    '- If the question depends on DB type, primary key convention, cache/reload/runtime state, active GraphQL/flow/websocket/storage counts, or admin surfaces, call **`discover_runtime_context`**.',
+    '- If the question depends on filters, sorting, deep relations, relation property names, field permissions, or table-specific query examples, call **`discover_query_capabilities`**; pass `tableName` when known.',
+    '- If writing or reviewing handler/hook/flow/websocket/extension logic, call **`discover_script_contexts`** first so macros and `$ctx` fields are not mixed across runtime surfaces.',
+    '- Treat hardcoded instructions as operating rules, but use live discovery as the final check for this running instance. Do not infer missing capabilities from a narrow tool schema; check metadata/routes or the relevant specialized tool first.',
+    '- If there is no dedicated MCP tool for a subsystem, use the route-backed metadata table with `query_table` / `create_record` / `update_record` / `delete_record`, after confirming that table has a route. If the table is no-route, use the canonical specialized tool or parent table workflow instead.',
+    '',
+    '### 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.',
+    '- **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.',
+    '- **WebSocket:** `websocket_definition` and `websocket_event_definition` define Socket.IO gateways/events. Use `run_admin_test` for websocket scripts.',
+    '- **Flows:** `flow_definition`, `flow_step_definition`, `flow_execution_definition`; use `test_flow_step`, `run_admin_test`, and `trigger_flow` for runtime checks.',
+    '- **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`.',
     '- GraphQL: `{base}/graphql` and `{base}/graphql-schema` always share this same base.',
     '',
     '### 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.',
+    '- Prefer these REST inspection/operator tools over raw `query_table` on system tables when changing route behavior. They resolve ids, methods, route paths, code previews, and cache reloads for the model.',
     '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** with **`mainTableId`** of an **existing** table (resolve id via **`get_all_tables`**, **`get_all_metadata`**, or **`get_all_routes`**).',
     '- **Wrong pattern:** calling **`create_table`** just to get an HTTP path, then overriding handlers on the **default** auto route `/{table_name}`. That adds unnecessary schema and breaks the usual CRUD surface for that table.',
     '- **`create_table`** is only when the user needs **new persisted data** (new entity + columns). It is **not** the right tool when the goal is only a new path or custom script.',
     '- **Right pattern:** **`create_route`** → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Same underlying table can have **multiple** routes (e.g. default CRUD at `/orders` and custom `/orders/stats` both pointing at `mainTable` orders).',
     '',
     '### After a new table is created',
+    '- MCP **`create_table` supports creating columns and relations in the same call**: pass `columns` and `relations` as JSON arrays. Use `create_relation` only when adding a relation to an existing table later.',
+    '- 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.',
     '- 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.',
     '- **Four REST HTTP operations** on that resource:',
     `  - **GET** \`${getList}\` — list / filter (query: filter, sort, page, limit, fields, meta).`,
@@ -48,7 +73,16 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `  - **DELETE** \`${delOne}\` — delete one row.`,
     `- **No** **GET** \`${base}/<table_name>/<id>\`. For one row by id use **GET** \`${getOneById}\` or MCP \`query_table\` / \`find_one_record\`.`,
     '',
-    '### Auth and publishedMethods (Enfyra server)',
+    '### Relation field format (create_record / update_record)',
+'- Relation fields (mainTable, publishedMethods, availableMethods, handlers, preHooks, postHooks, etc.) use **object references with `id`**:',
+'  - **Many-to-one:** `"mainTable": {"id": 4}` (single object with id)',
+'  - **One-to-many / many-to-many:** `"publishedMethods": [{"id": 1}, {"id": 2}]` (array of objects with id)',
+'- **Method IDs** (for REST route publishedMethods, availableMethods, skipRoleGuardMethods): GET=1, POST=2, PATCH=3, DELETE=4. Query `method_definition` table if unsure.',
+'- **Wrong:** `"publishedMethods": ["GET"]` or `"publishedMethods": [{"method": "GET"}]` — rejected or silently ignored.',
+'- **Right:** `"publishedMethods": [{"id": 1}]` (publishes GET). Multiple: `[{"id": 1}, {"id": 2}]` (publishes GET + POST).',
+'- **To unset:** pass empty array `"publishedMethods": []`.',
+'',
+'### Auth and publishedMethods (Enfyra server)',
     '- Each route has **publishedMethods** (which HTTP verbs are “public”) and **routePermissions** (roles/users for protected access).',
     '- If the **current request method** is listed in **publishedMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
     '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
@@ -82,10 +116,11 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### 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.',
-    '- **`column_definition` has NO route** — do NOT call `query_table("column_definition", …)`. It will always 404.',
+    '- **`column_definition` and `session_definition` have NO route** — do NOT call `query_table("column_definition", …)` or `query_table("session_definition", …)`. They will 404.',
     '- To check which tables are accessible via MCP tools, call `get_all_routes` and look for the route whose `mainTable.id` matches the table you need, or `get_all_metadata` to see all table names.',
-    '- **Tables confirmed to have REST routes (system):** `table_definition`, `route_definition`, `user_definition`, `setting_definition`, `ai_config_definition`, `role_definition`, `menu_definition`, `extension_definition`, `folder_definition`, `file_definition`, `file_permission_definition`, `package_definition`, `bootstrap_script_definition`, `storage_config_definition`, `ai_conversation_definition`, `ai_message_definition`, `websocket_definition`, `websocket_event_definition`, `oauth_config_definition`, `oauth_account_definition`, `method_definition`, `pre_hook_definition`, `post_hook_definition`, `route_handler_definition`, `route_permission_definition`, `flow_definition`, `flow_step_definition`, `flow_execution_definition`.',
-    '- **Tables without REST routes (internal/system only):** `column_definition`, `relation_definition` — these are managed indirectly via cascade on `table_definition` (PATCH /table_definition/{id} with columns/relations array). The `create_column` MCP tool handles this automatically.',
+    '- **Tables confirmed to have REST routes (system):** `bootstrap_script_definition`, `column_rule_definition`, `cors_origin_definition`, `extension_definition`, `field_permission_definition`, `file_definition`, `file_permission_definition`, `flow_definition`, `flow_execution_definition`, `flow_step_definition`, `folder_definition`, `gql_definition`, `guard_definition`, `guard_rule_definition`, `menu_definition`, `method_definition`, `oauth_account_definition`, `oauth_config_definition`, `package_definition`, `post_hook_definition`, `pre_hook_definition`, `relation_definition`, `role_definition`, `route_definition`, `route_handler_definition`, `route_permission_definition`, `schema_migration_definition`, `setting_definition`, `storage_config_definition`, `table_definition`, `user_definition`, `websocket_definition`, `websocket_event_definition`.',
+    '- **Tables without REST routes (internal/system only):** `column_definition`, `session_definition`. Columns are managed indirectly via cascade on `table_definition` (POST/PATCH with columns arrays). The `create_table`, `create_column`, `update_column`, and `delete_column` MCP tools handle this automatically.',
+    '- Prefer `create_relation` / `delete_relation` for relation schema changes because they preserve the full table relation list and handle schema-confirm retry. Direct `create_record` on `relation_definition` only edits metadata and is not the canonical schema migration path.',
     '',
     '### Body validation & column rules',
     '- Each `table_definition` has a **`validateBody`** flag (default `true` for new tables). When on, every `POST /<table>` and `PATCH /<table>/<id>` is validated server-side against the column types + any **column rules** attached to columns of that table.',
@@ -99,7 +134,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Schema / table migration (sequential only)',
     '- When creating, updating, or deleting tables (or columns), run operations **one at a time**. The migration process locks the DB per operation.',
-    '- Do NOT batch multiple schema changes (e.g. create 3 tables in parallel, or create table + add columns simultaneously). Execute each `create_table`, `create_column`, sync, or drop sequentially; wait for completion before the next.',
+    '- Do NOT batch multiple schema changes in parallel (e.g. create 3 tables concurrently, or create a table and separately add columns at the same time). A single `create_table` call may include its own `columns` and `relations`; treat that as one schema operation. Execute each `create_table`, `create_column`, `create_relation`, sync, or drop sequentially; wait for completion before the next.',
     '',
     '### Resolving the real REST path',
     '- Do **not** assume `route_definition.path` always equals `table_definition.name`. Paths are data-driven (custom prefixes, renames, multiple routes per table).',
@@ -107,13 +142,22 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### MongoDB vs SQL primary key',
     '- 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.',
+    '- Use **`discover_runtime_context`** to read live `dbType` and `pkField` from metadata. If an older backend does not expose them, the tool falls back to primary-key inference and labels the source clearly.',
+    '',
+    '### Query DSL and deep relations',
+    '- Use **`discover_query_capabilities`** before building non-trivial filters/deep queries. It returns supported filter operators, field-permission condition operators, deep shape/rules, table columns/relations, table primary key, route paths, and examples.',
+    '- Full filter operators: `_eq`, `_neq`, `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_not_in`, `_nin`, `_contains`, `_starts_with`, `_ends_with`, `_between`, `_is_null`, `_is_not_null`, `_and`, `_or`, `_not`.',
+    '- Field permission condition DSL is narrower and does not support `_contains`, `_starts_with`, `_ends_with`, or `_between`.',
+    '- Deep shape: `{ relationName: { fields?, filter?, sort?, limit?, page?, deep? } }`. Relation keys are relation `propertyName`, not physical FK columns.',
+    '- Deep validation rejects unknown relation keys, unknown subkeys, `limit` on many-to-one/one-to-one, and invalid dotted sort through many-side relations.',
     '',
     '### 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\`.`,
     `- **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).',
+    '- 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).',
-    '- **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`).',
+    '- **Auth:** GraphQL currently requires `Authorization: Bearer <accessToken>`. REST route `publishedMethods` does not make GraphQL anonymous.',
+    '- **Management workflow:** use `update_table` with `graphqlEnabled: true|false`, or create/update `gql_definition` with `table: {id}` and `isEnabled`. Reload GraphQL with `reload_graphql` if the cache has not refreshed yet.',
     '- MCP does not wrap GraphQL; use REST tools or tell users the URLs above.',
     '',
     '### WebSocket (Socket.IO)',
@@ -135,6 +179,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **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.',
     '- **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.',
+    '- Before writing websocket scripts, call **`discover_script_contexts`** to confirm which `@SOCKET` methods are bound in websocket vs HTTP/flow contexts.',
     '',
     '### Flows (Automated Workflows)',
     '- Enfyra supports automated workflows via **`flow_definition`**, **`flow_step_definition`**, and **`flow_execution_definition`** tables.',
@@ -149,7 +195,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **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). `$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}`.',
+    '- MCP wrappers: use **`test_flow_step`** for one step, **`run_admin_test`** with `kind:"flow_step"` for the generic admin tester, and **`trigger_flow`** for saved flows.',
     '- **In handlers/hooks**: Trigger flows via `$ctx.$trigger("flow-name", {payload})` or `$ctx.$trigger(flowId, {payload})`.',
+    '- Before writing flow scripts, call **`discover_script_contexts`** to confirm `@FLOW`, `@FLOW_PAYLOAD`, `@FLOW_LAST`, `#table_name`, `$ctx.$trigger`, and `$socket` behavior.',
     '',
     '### 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.',
@@ -234,6 +282,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Routes:** `create_route` / `create_handler` / `create_pre_hook` / `create_post_hook` persist to `route_definition`, `route_handler_definition`, etc. (REST CRUD on those tables). Prefer **`create_route`** for new paths — not `create_table`.',
     `- \`get_all_metadata\` → GET \`${base}/metadata\``,
     `- \`get_table_metadata\` → GET \`${base}/metadata/<tableName>\``,
+    `- \`discover_runtime_context\` → GET metadata/routes/method/runtime-backed tables and infer live primary key/backend context`,
+    `- \`discover_query_capabilities\` → GET metadata/routes and summarize Query DSL/deep/table-specific query contracts`,
+    `- \`discover_script_contexts\` → static runtime macro/context map for handlers/hooks/flows/websocket/GraphQL/extensions`,
     `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args)`,
     `- \`find_one_record\` (by id) → GET \`${base}/<tableName>?filter=…&limit=1\``,
     `- \`create_record\` → POST \`${base}/<tableName>\``,
@@ -241,6 +292,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\``,
     `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for page pass menuId). \`update_record\` on extension_definition to change code.`,
     `- Flow tables: \`${base}/flow_definition\`, \`${base}/flow_step_definition\`, \`${base}/flow_execution_definition\` — use standard CRUD tools.`,
+    `- \`run_admin_test\` → POST \`${base}/admin/test/run\``,
+    `- \`test_flow_step\` → POST \`${base}/admin/flow/test-step\``,
+    `- \`trigger_flow\` → POST \`${base}/admin/flow/trigger/<flowIdOrName>\``,
     `- Other: \`${base}/menu_definition\`, \`${base}/websocket_definition\`, \`${base}/admin/reload\`, etc.`,
     '',
     'When asked which endpoint the API calls, respond with **HTTP method + full URL** using this base. Call `get_enfyra_api_context` to confirm the resolved base if needed.',

package/src/lib/table-tools.js

@@ -33,6 +33,34 @@ async function patchTableAutoConfirm(ENFYRA_API_URL, tableId, body) {
   return result;
 }
 
+function parseJsonArrayParam(name, value) {
+  if (!value) return [];
+  const parsed = JSON.parse(value);
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${name} must be a JSON array.`);
+  }
+  return parsed;
+}
+
+function normalizeRelationForTablePatch(relation) {
+  const { sourceTable, targetTable, targetTableId, mappedBy, ...rest } = relation;
+  const normalized = { ...rest };
+  const resolvedTargetTable =
+    targetTableId ??
+    (targetTable && typeof targetTable === 'object'
+      ? targetTable.id ?? targetTable._id ?? targetTable
+      : targetTable);
+  if (resolvedTargetTable !== undefined && resolvedTargetTable !== null) {
+    normalized.targetTable = resolvedTargetTable;
+  }
+  if (mappedBy !== undefined && mappedBy !== null && mappedBy !== '') {
+    normalized.mappedBy = typeof mappedBy === 'object'
+      ? mappedBy.propertyName ?? mappedBy.name ?? mappedBy.id ?? mappedBy._id
+      : mappedBy;
+  }
+  return normalized;
+}
+
 /**
  * Register table tools with MCP server
  */
@@ -60,28 +88,32 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       'Create a new table definition with an auto-included `id` primary key column.',
       '**Not** for adding a custom API path or handler only — for that use **`create_route`** with an existing `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
-      'PREFERRED: pass `columns` param as JSON array to create table WITH columns in one call (cascade). Only use create_column separately if adding to an existing table later.',
+      '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.',
+      '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 or {id}.',
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
       'Enfyra auto-creates a default REST route at path `/<table_name>` (same segment as `name`, not alias).',
       'REST surface for that route (matches server route engine): 4 HTTP operations — GET `/<table>` (list/filter), POST `/<table>` (create), PATCH `/<table>/:id` (update), DELETE `/<table>/:id` (delete).',
       'There is NO `GET /<table>/:id`. To fetch one row by id, use GET `/<table>?filter={"id":{"_eq":"<id>"}}&limit=1` or tool query_table / find_one_record.',
       `Full URLs: ${apiBase}/<table_name> (example table post: ${apiBase}/post).`,
-      'GraphQL (GQL_QUERY / GQL_MUTATION) may also be enabled on the route; that is separate from REST paths above.',
+      'GraphQL is enabled separately per table through `gql_definition` or `update_table` with `graphqlEnabled`; it is not controlled by route availableMethods.',
     ].join(' '),
     {
       name: z.string().describe('Table name (e.g., "user_definition", "my_custom_table"). Must be unique, lowercase with underscores.'),
       alias: z.string().optional().describe('Table alias for API. If not provided, the table name will be used.'),
       description: z.string().optional().describe('Description of what this table stores.'),
-      isEnabled: z.boolean().optional().default(true).describe('Enable table. Set to false to disable.'),
       columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, defaultValue?, description?, options? }. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"status","type":"enum","options":["draft","published"]}]'),
+      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 or {"id": <id>}. Example: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
     },
-    async ({ name, alias, description, isEnabled, columns: columnsJson }) => {
+    async ({ name, alias, description, columns: columnsJson, relations: relationsJson }) => {
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
-      const userColumns = columnsJson ? JSON.parse(columnsJson) : [];
+      const userColumns = parseJsonArrayParam('columns', columnsJson);
+      const userRelations = parseJsonArrayParam('relations', relationsJson).map(normalizeRelationForTablePatch);
       const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
         method: 'POST',
-        body: JSON.stringify({ name, alias, description, isEnabled, columns: [idColumn, ...userColumns] }),
+        body: JSON.stringify({ name, alias, description, columns: [idColumn, ...userColumns], relations: userRelations }),
       });
+      const createdTable = Array.isArray(result?.data) ? result.data[0] : result;
+      const createdTableId = createdTable?.id ?? createdTable?._id;
       const base = ENFYRA_API_URL.replace(/\/$/, '');
       const routePath = `/${name}`;
       const restHint = [
@@ -90,9 +122,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       ].join('\n');
       const colHint = userColumns.length
         ? `Table created with ${userColumns.length} column(s) + auto id.`
-        : `Table created. Use create_column to add columns (tableId: ${result.id}).`;
+        : `Table created. Use create_column to add columns (tableId: ${createdTableId}).`;
+      const relHint = userRelations.length
+        ? `Relation(s) created in same call: ${userRelations.length}.`
+        : `No relations were included in this create_table call.`;
       return {
-        content: [{ type: 'text', text: `${colHint}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
+        content: [{ type: 'text', text: `${colHint}\n${relHint}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
     }
   );
@@ -102,7 +137,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   server.tool(
     'update_table',
     [
-      'Update table properties: name (rename), alias, description, isSingleRecord, uniques, indexes.',
+      'Update table properties: name (rename), alias, description, isSingleRecord, graphqlEnabled.',
       'Does NOT modify columns or relations — use create_column, update_column, delete_column, create_relation for those.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
@@ -112,13 +147,15 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       alias: z.string().optional().describe('New table alias.'),
       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 gql_definition.isEnabled. GraphQL still requires Bearer auth.'),
     },
-    async ({ tableId, name, alias, description, isSingleRecord }) => {
+    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled }) => {
       const body = {};
       if (name !== undefined) body.name = name;
       if (alias !== undefined) body.alias = alias;
       if (description !== undefined) body.description = description;
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
+      if (graphqlEnabled !== undefined) body.graphqlEnabled = graphqlEnabled;
 
       const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
         method: 'PATCH',
@@ -289,15 +326,15 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       propertyName: z.string().describe('Property name on source table (e.g., "customer", "items").'),
       inversePropertyName: z.string().optional().describe('Property name on target table for bidirectional relation (e.g., "orders").'),
       isNullable: z.boolean().optional().default(true).describe('Whether the relation is nullable.'),
-      onDelete: z.enum(['CASCADE', 'SET NULL', 'RESTRICT', 'NO ACTION']).optional().default('SET NULL').describe('On delete behavior.'),
+      onDelete: z.enum(['CASCADE', 'SET NULL', 'RESTRICT']).optional().default('SET NULL').describe('On delete behavior.'),
     },
     async ({ sourceTableId, targetTableId, type, propertyName, inversePropertyName, isNullable, onDelete }) => {
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, sourceTableId);
       if (!tableData) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${sourceTableId} not found.` }] };
       }
-      const existingRelations = (tableData.relations || []).map(({ sourceTable, targetTable, ...rel }) => rel);
-      const newRelation = { targetTableId, type, propertyName, inversePropertyName: inversePropertyName || null, isNullable, onDelete };
+      const existingRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+      const newRelation = { targetTable: targetTableId, type, propertyName, inversePropertyName: inversePropertyName || null, isNullable, onDelete };
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, sourceTableId, { relations: [...existingRelations, newRelation] });
       return {
         content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${sourceTableId} → ${targetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
@@ -326,7 +363,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
       const relations = (tableData.relations || [])
         .filter(rel => String(rel.id) !== String(relationId))
-        .map(({ sourceTable, targetTable, ...rel }) => rel);
+        .map(normalizeRelationForTablePatch);
 
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { relations });