@enfyra/mcp-server 0.1.58 → 0.1.59

package/README.md

@@ -1,171 +1,48 @@
 # Enfyra MCP Server
 
-Manage Enfyra instances from MCP-compatible coding tools such as **Codex**, **Claude Code**, **Cursor**, **VS Code / GitHub Copilot**, **Google Antigravity**, MCP Inspector, and other STDIO MCP hosts.
+Connect Enfyra to MCP-compatible coding tools such as Codex, Claude Code, Cursor, VS Code / GitHub Copilot, Google Antigravity, and other STDIO MCP hosts.
 
-This package is the MCP bridge only. Assistant rules, schema behavior, dynamic script guidance, and examples are served through the MCP server itself from TypeScript source in `src/lib/mcp-instructions.ts`, `src/lib/mcp-examples.ts`, and tool descriptions in `src/mcp-server-entry.ts`. Published packages run the compiled `dist/index.js` entry.
+## Install and Configure
 
-## Quick Start
-
-From your project root:
+Run this from the project that should use Enfyra:
 
 ```bash
 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@latest config --yes \
-  --app-url http://localhost:3000 \
-  -t efy_pat_your-token
-
-# One or more clients
-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:
+The setup asks for:
 
-```bash
-yarn build
-yarn mcp:config
-```
+- the Enfyra app/admin URL, such as `http://localhost:3000` or `https://demo.enfyra.io`;
+- an `ENFYRA_API_TOKEN` created from the Enfyra admin UI `/me` page;
+- the MCP clients to configure.
 
-## Development
-
-This repo uses Yarn 4 through Corepack and TypeScript source compiled to `dist`.
-
-```bash
-yarn typecheck
-yarn build
-yarn test
-```
-
-`yarn test` builds first and then runs Node tests against `dist` while static source assertions read `src/**/*.ts`.
-
-## Choose A Client
+It writes project-local configuration and replaces only the `enfyra` server entry.
 
 | Client | Command | Project config |
-|--------|---------|----------------|
+|---|---|---|
 | 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>
+Non-interactive setup for all supported clients:
 
 ```bash
-npx @enfyra/mcp-server@latest config --codex
-```
-
-Generated project config:
-
-```toml
-[mcp_servers.enfyra]
-command = "npx"
-args = ["-y", "@enfyra/mcp-server@latest"]
-
-[mcp_servers.enfyra.env]
-ENFYRA_API_URL = "http://localhost:3000/api"
-ENFYRA_API_TOKEN = "efy_pat_your-token"
-```
-
-The 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 and approve the project MCP config if prompted. The setup command only writes `.codex/config.toml`; it does not ship or create `.codex/skills`.
-
-Official reference: [Codex config](https://developers.openai.com/codex/config-reference).
-
-</details>
-
-<details>
-<summary><strong>Claude Code setup</strong></summary>
-
-```bash
-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`.
-
-Claude Code also supports its own CLI:
-
-```bash
-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@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.
-
-Official references: [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) and [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
-
-</details>
-
-<details>
-<summary><strong>Cursor setup</strong></summary>
-
-```bash
-npx @enfyra/mcp-server@latest config --cursor
+npx @enfyra/mcp-server@latest config --yes \
+  --app-url http://localhost:3000 \
+  --api-token efy_pat_your-token
 ```
 
-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.
-
-After edits, restart Cursor or reload MCP, then confirm the server under Cursor MCP settings. Use MCP logs if the server fails to start.
-
-Official reference: [Cursor MCP](https://cursor.com/docs/context/mcp).
-
-</details>
-
-<details>
-<summary><strong>VS Code / GitHub Copilot setup</strong></summary>
+Configure more than one selected client:
 
 ```bash
-npx @enfyra/mcp-server@latest config --vscode
-```
-
-VS Code workspace config is written to `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "enfyra": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@enfyra/mcp-server@latest"],
-      "env": {
-        "ENFYRA_API_URL": "http://localhost:3000/api",
-        "ENFYRA_API_TOKEN": "efy_pat_your-token"
-      }
-    }
-  }
-}
+npx @enfyra/mcp-server@latest config --cursor --claude-code
 ```
 
-Use the VS Code command `MCP: List Servers` to inspect or start the server after setup. This is a workspace config, so it stays tied to the current project.
-
-Official references: [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) and [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
+## Manual Configuration
 
-</details>
-
-<details>
-<summary><strong>Google Antigravity setup</strong></summary>
-
-```bash
-npx @enfyra/mcp-server@latest config --antigravity
-```
-
-Antigravity project config is written to `.agents/mcp_config.json`:
+For hosts that accept an `mcpServers` JSON block:
 
 ```json
 {
@@ -182,37 +59,19 @@ Antigravity project config is written to `.agents/mcp_config.json`:
 }
 ```
 
-Antigravity also documents a shared user config at `~/.gemini/config/mcp_config.json`; this helper intentionally writes the project-local `.agents/mcp_config.json` file so Enfyra URL and token stay scoped to the current workspace.
-
-Official reference: [Antigravity MCP](https://antigravity.google/docs/mcp).
+Codex project configuration uses TOML:
 
-</details>
-
-<details>
-<summary><strong>Other MCP hosts and MCP Inspector</strong></summary>
-
-Use the shared STDIO config with any project-scoped host that accepts an `mcpServers` JSON block:
+```toml
+[mcp_servers.enfyra]
+command = "npx"
+args = ["-y", "@enfyra/mcp-server@latest"]
 
-```json
-{
-  "mcpServers": {
-    "enfyra": {
-      "command": "npx",
-      "args": ["-y", "@enfyra/mcp-server@latest"],
-      "env": {
-        "ENFYRA_API_URL": "http://localhost:3000/api",
-        "ENFYRA_API_TOKEN": "efy_pat_your-token"
-      }
-    }
-  }
-}
+[mcp_servers.enfyra.env]
+ENFYRA_API_URL = "http://localhost:3000/api"
+ENFYRA_API_TOKEN = "efy_pat_your-token"
 ```
 
-`ENFYRA_API_TOKEN` is a programmatic token from the Enfyra admin UI `/me`. It is not a JWT; the MCP server exchanges it through `POST {ENFYRA_API_URL}/auth/token/exchange` before calling Enfyra REST APIs.
-
-Official reference: [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
-
-</details>
+Restart or reload the MCP client after writing configuration. Keep the token out of committed files.
 
 ## Config Command
 
@@ -221,11 +80,11 @@ npx @enfyra/mcp-server@latest config [options]
 ```
 
 | Option | Use |
-|--------|-----|
+|---|---|
 | `--app-url` | Set the Enfyra app/admin URL |
 | `--api-token`, `-t` | Set `ENFYRA_API_TOKEN` |
-| `--yes` | Non-interactive mode for CI/scripts |
-| `--reconfig` | Prompt for target clients again and replace the existing `enfyra` entry |
+| `--yes` | Run non-interactively |
+| `--reconfig` | Select clients again and replace the existing `enfyra` entry |
 | `--codex` | Write Codex config |
 | `--claude-code`, `--claude` | Write Claude Code config |
 | `--cursor` | Write Cursor config |
@@ -233,118 +92,38 @@ npx @enfyra/mcp-server@latest config [options]
 | `--antigravity` | Write Google Antigravity config |
 | `-h`, `--help` | Show CLI help |
 
-Without a target flag, interactive mode asks which client to configure. Non-interactive mode defaults to all supported clients.
-
 ## Environment
 
 | Variable | Description | Default |
-|----------|-------------|---------|
+|---|---|---|
 | `ENFYRA_APP_URL` | App/admin URL used by setup | `http://localhost:3000` |
-| `ENFYRA_API_URL` | Runtime API base written into MCP client config | Generated by setup |
+| `ENFYRA_API_URL` | Runtime API base written into MCP config | Derived from the app URL |
 | `ENFYRA_API_TOKEN` | Programmatic token from the Enfyra admin UI `/me` | Required |
-| `ENFYRA_MCP_TOOLSET` | Tool visibility mode: `guided` for curated default tools, or `full` for every low-level escape hatch | `guided` |
-
-For normal apps and demos, enter the app/admin URL such as `http://localhost:3000` or `https://demo.enfyra.io`. Treat the direct Enfyra backend host as private infrastructure unless you are debugging Enfyra core/server internals.
-
-## Metadata Contract
-
-The MCP server uses Enfyra metadata lazily:
-
-- `GET /metadata` returns only `dbType` and `enfyraVersion`.
-- `GET /metadata/{tableName}` returns one permission-projected table schema.
-- `get_all_tables` and normal discovery use a lightweight `enfyra_table` catalog.
-- `get_table_metadata`, `inspect_table`, mutation validation, and schema operations fetch only the table schemas they need.
-- Explicit broad schema searches fan out to per-table metadata with bounded concurrency and reuse the MCP runtime cache.
-
-Use `get_all_tables` for table names, then `get_table_metadata` or `inspect_table` for columns and relations. `get_all_metadata(includeFull=true)` is an explicit broad operation and should not be used as startup discovery.
-
-## Common Examples
-
-Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate implementation patterns. It returns focused examples for:
-
-- SSR app auth and proxy setup
-- OAuth provider setup
-- schema, columns, relations, indexes, and validation
-- query filters, sorting, fields, deep relations, and aggregates
-- handlers, hooks, permissions, and RLS
-- websocket gateways and events
-- flows
-- files and storage
-- Enfyra admin extensions
-
-Use `discover_enfyra_workflows` when an LLM knows the goal but may not know the right Enfyra tool path. It returns progressive-disclosure workflow matches with first tools, required acknowledgements, verification tools, relevant example categories, and `avoidTools` boundaries that prevent near-correct but unsafe tool choices.
-
-Use `get_enfyra_required_knowledge` before asking an LLM to mutate metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or Enfyra extension code. It returns global rules plus acknowledgement keys that write tools verify before saving. Dynamic server code also requires the dynamic-code acknowledgement key, and extension code also requires the extension acknowledgement key.
-
-## Runtime Safety
-
-The MCP server includes safety guards for LLM callers:
-
-- Generic record mutations validate fields against live metadata.
-- 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` 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.
-- JSON responses include `compressionStats` with estimated token savings. Arrays of objects are converted to columnar form only when the compact shape is smaller than raw JSON.
-- Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
-- Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
-- Custom route tools reject `mainTableId` unless the route is the canonical table route.
-- `discover_enfyra_workflows` maps task intent to workflow surfaces before the agent loads detailed examples or guesses between similar tools.
-- Platform operation tools such as `api_endpoint_workflow`, `extension_workflow`, `flow_workflow`, `search_admin_extensions`, `debug_field_exposure`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `set_table_graphql`, `ensure_route_rate_limit`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `ensure_menu`, `reorder_menus`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
-- Schema changes are serialized.
-- Destructive deletes return a preview before requiring `confirm=true`.
+| `ENFYRA_MCP_TOOLSET` | `guided` for the normal curated toolset or `full` for low-level debugging tools | `guided` |
 
-## Query Notes
+The API token is exchanged for a short-lived access token at runtime. It is not sent directly as a Bearer token.
 
-Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every broad list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. Locator searches on `get_all_routes` and `get_all_tables` may omit `limit` when `search` is provided; they return a small bounded lookup window. When a caller needs every matching row, pass `all: true` to `query_table`, `get_all_routes`, or `get_all_tables`; the tool should not choose an arbitrary page size like 30 or 50.
+## Verify the Connection
 
-## Enfyra URL Pattern
+Open a new session in the configured MCP client and ask it to:
 
-Generated apps should use a same-origin proxy:
-
-```js
-export default defineNuxtConfig({
-  routeRules: {
-    "/enfyra/**": {
-      proxy: {
-        to: `${process.env.ENFYRA_API_URL}/**`,
-        fetchOptions: { redirect: "manual" }
-      }
-    }
-  }
-})
+```text
+Use Enfyra MCP to show the connected API context.
 ```
 
-Browser code then calls:
+Then try a read-only request:
 
 ```text
-POST /enfyra/login
-GET  /enfyra/me
-POST /enfyra/logout
-GET  /enfyra/<table>
+Use Enfyra MCP to list the available tables without changing anything.
 ```
 
-Do not create custom login/logout/me routes that manually set Enfyra token cookies when the proxy is enough.
-
-## Tool Summary
-
-By default, the MCP server starts with `ENFYRA_MCP_TOOLSET=guided`, a curated tool surface optimized for weaker LLMs and one-shot success. It exposes workflow routing, focused discovery, runtime zone search, schema tools, query/CRUD envelopes, row-scope pre-hooks, focused extension patching, operation-level route/permission/extension/flow/websocket tools, validation, and narrow verification tools. Set `ENFYRA_MCP_TOOLSET=full` only for expert debugging or compatibility work that needs low-level escape hatches such as raw route construction, cache reloads, method metadata, broad metadata reads, or raw log file reads.
-
-The guided approach has two explicit operating criteria: a fully specified, non-destructive task should complete in one task turn for GLM-5-Turbo or stronger, using the fewest necessary MCP calls; and task-specific knowledge is lazy-loaded, so startup context only routes work and does not preload unrelated schemas, examples, or UI/script contracts. Preview-first destructive changes, explicit user approval, and necessary security checks are deliberate exceptions. When a contract is clear, prefer an operation tool's atomic or `applyAll` path; use plan-only calls only when a decision is genuinely unresolved.
-
-Routes have two separate controls. `isEnabled` controls runtime registration: disabled routes return `404`. Use `enable_route` and `disable_route` for this lifecycle. `publicMethods` controls anonymous access for enabled routes; use `public_route_methods` and `private_route_methods` for that access boundary.
-
-Use `reorder_menus` for menu order or parent changes. It calls the Enfyra 2.2.6 `/admin/menu/reorder` operation route so hierarchy validation and menu cache invalidation are handled by the server instead of PATCHing individual `enfyra_menu` records.
-
-Admin app page paths and API paths are different surfaces. A page extension path such as `/cloud/projects/:id` is a UI route unless an enabled Enfyra API route with that exact path exists. Use `test_rest_endpoint` only for actual API routes under `ENFYRA_API_URL`; verify page extensions through the app URL/browser or extension/menu metadata.
-
-For authenticated route access, use `audit_route_access` before changing permissions and `ensure_route_access` to grant access by route path plus role/user. For production script edits, use `trace_metadata_usage`, `get_script_source`, and `patch_script_source` so changes are targeted, hash-checked, and validated.
+## Development
 
-## Security
+This repository uses Yarn 4 and TypeScript:
 
-Treat permission and security as the first step for every change: decide public/private methods, authenticated route access, owner/tenant scope, and field exposure before creating handlers, flows, extensions, or UI.
+```bash
+yarn typecheck
+yarn test
+```
 
-API calls use exchanged JWTs and Enfyra permissions are still enforced server-side. Keep `ENFYRA_API_TOKEN` out of committed config unless the project intentionally uses environment interpolation or another secret-management path.
+Use [AGENTS.md](./AGENTS.md) for maintainer architecture, tool contracts, verification rules, and backend sync points. LLM runtime guidance is served by the MCP instructions, tool descriptions, workflow discovery, required-knowledge tools, builders, and examples—not by this README.

package/dist/lib/dynamic-repository-builder.d.ts

@@ -0,0 +1,18 @@
+export declare function buildDynamicRepositoryUsage(input: {
+    access: 'secure_main' | 'secure_explicit' | 'trusted_explicit';
+    operation: 'list' | 'find_one' | 'create' | 'update' | 'delete';
+    tableName?: string;
+    fields?: string[];
+    idField?: string;
+    idSource?: 'params' | 'body';
+}): {
+    access: "secure_main" | "secure_explicit" | "trusted_explicit";
+    operation: "delete" | "create" | "update" | "list" | "find_one";
+    tableName: string;
+    repository: string;
+    fieldPermissionsEnforced: boolean;
+    securityBoundary: string;
+    code: string;
+    next: string;
+};
+export declare function registerDynamicRepositoryBuilder(server: any): void;

package/dist/lib/dynamic-repository-builder.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { jsonContent } from './response-format.js';
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function requireIdentifier(value, label) {
+    if (!value || !IDENTIFIER_PATTERN.test(value)) {
+        throw new Error(`${label} must be a valid Enfyra identifier using letters, digits, and underscores.`);
+    }
+    return value;
+}
+function fieldList(fields) {
+    const values = fields?.length ? fields : ['id'];
+    for (const field of values)
+        requireIdentifier(field, 'Each field');
+    return `[${values.map((field) => JSON.stringify(field)).join(', ')}]`;
+}
+export function buildDynamicRepositoryUsage(input) {
+    const tableName = input.access === 'secure_main'
+        ? input.tableName || null
+        : requireIdentifier(input.tableName, 'tableName');
+    const repository = input.access === 'secure_main'
+        ? '@REPOS.main'
+        : input.access === 'secure_explicit'
+            ? `#secure.${tableName}`
+            : `#${tableName}`;
+    const fields = fieldList(input.fields);
+    const idField = requireIdentifier(input.idField || 'id', 'idField');
+    const idExpression = input.idSource === 'body' ? '@BODY.id' : '@PARAMS.id';
+    let code;
+    if (input.operation === 'list') {
+        code = `const result = await ${repository}.find({
+  fields: @QUERY.fields?.length ? @QUERY.fields : ${fields},
+  filter: @QUERY.filter || {},
+  deep: @QUERY.deep,
+  sort: @QUERY.sort,
+  page: @QUERY.page,
+  limit: Math.min(Number(@QUERY.limit) || 50, 100),
+  meta: @QUERY.meta,
+  aggregate: @QUERY.aggregate,
+  debugMode: @QUERY.debugMode
+})
+
+return result`;
+    }
+    else if (input.operation === 'find_one') {
+        code = `const result = await ${repository}.find({
+  filter: { ${idField}: { _eq: ${idExpression} } },
+  fields: ${fields},
+  limit: 1
+})
+
+const record = result.data?.[0] ?? null
+if (!record) @THROW404("Record not found", { ${idField}: ${idExpression} })
+return record`;
+    }
+    else if (input.operation === 'create') {
+        code = `const result = await ${repository}.create({
+  data: @BODY,
+  fields: ${fields}
+})
+
+const record = result.data?.[0] ?? null
+return record`;
+    }
+    else if (input.operation === 'update') {
+        code = `const result = await ${repository}.update({
+  id: ${idExpression},
+  data: @BODY,
+  fields: ${fields}
+})
+
+const record = result.data?.[0] ?? null
+return record`;
+    }
+    else {
+        code = `await ${repository}.delete({ id: ${idExpression} })
+return { ok: true, id: ${idExpression} }`;
+    }
+    const fieldPermissionsEnforced = input.access !== 'trusted_explicit';
+    return {
+        access: input.access,
+        operation: input.operation,
+        tableName,
+        repository,
+        fieldPermissionsEnforced,
+        securityBoundary: fieldPermissionsEnforced
+            ? 'Field permissions are enforced by the selected secure repository. Owner, tenant, membership, and route authorization remain separate checks.'
+            : 'This trusted repository bypasses field permissions. Use it only for intentional internal work, request exact fields, enforce authorization explicitly, and never return raw trusted rows.',
+        code,
+        next: 'Adapt only live field, filter, owner/tenant, and domain error details; keep the repository access class, await, result.data shape, and bounded query contract.',
+    };
+}
+export function registerDynamicRepositoryBuilder(server) {
+    server.tool('build_dynamic_repository_usage', [
+        'Generate validated Enfyra dynamic repository code for list, find-one, create, update, or delete.',
+        'Use secure_main for a canonical route main table, secure_explicit for user-facing explicit-table access, and trusted_explicit only for intentional internal field-permission bypass.',
+    ].join(' '), {
+        access: z.enum(['secure_main', 'secure_explicit', 'trusted_explicit']).describe('Repository security class. Prefer secure_main or secure_explicit for user-facing code.'),
+        operation: z.enum(['list', 'find_one', 'create', 'update', 'delete']).describe('Repository operation pattern to generate.'),
+        tableName: z.string().optional().describe('Required for explicit access. Omit for secure_main when the route main table is already known.'),
+        fields: z.array(z.string()).optional().describe('Exact metadata-backed fields to select or return. Defaults to id.'),
+        idField: z.string().optional().default('id').describe('Primary key field used by find_one. Defaults to id; use _id for Mongo metadata when applicable.'),
+        idSource: z.enum(['params', 'body']).optional().default('params').describe('Read record id from @PARAMS.id or @BODY.id.'),
+    }, async (input) => jsonContent(buildDynamicRepositoryUsage(input)));
+}
+//# sourceMappingURL=dynamic-repository-builder.js.map

package/dist/lib/dynamic-repository-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-repository-builder.js","sourceRoot":"","sources":["../../src/lib/dynamic-repository-builder.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-examples.d.ts

@@ -36,6 +36,15 @@ export declare const EXAMPLE_CATEGORIES: {
             notes: string[];
         }[];
     };
+    graphql: {
+        title: string;
+        useWhen: string;
+        examples: {
+            name: string;
+            code: string;
+            notes: string[];
+        }[];
+    };
     'handlers-hooks': {
         title: string;
         useWhen: string;