@restforgejs/mcp-server 1.2.0

package/dist/tools/codegen/get-field-validation-catalog.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenGetFieldValidationCatalog(server) {
+    server.registerTool('codegen_get_field_validation_catalog', {
+        title: 'Get Field Validation Catalog',
+        description: `Get authoritative JSON catalog of field validation spec (data types, constraints, format presets, audit columns convention, message override pattern) used in payload \`fieldValidation\` arrays.
+
+USE WHEN:
+- The user asks about valid field validation constraints, types, format presets, or audit columns convention in payload JSON
+- The user asks things like "constraint apa yang valid untuk tipe X", "list field validation constraints", "tampilkan catalog validasi", "what validation rules can I use", "format preset apa saja", "show me the validation spec"
+- Before generating or editing the \`fieldValidation\` array in a payload file — to ground constraint names, scope correctness, and the message override pattern. Often called before 'codegen_generate_payload' for grounding the initial generation, or before manual editing of an existing payload.
+- The user mentions adding validation to a payload field but is unsure which constraint name to use
+- The user asks about audit columns convention (\`auditColumns: false\`, override custom names, valid/rejected values, etc.)
+- The user asks about the message override pattern (\`{constraintName}Message\`)
+- The user reports a typo-like error such as \`maxLenght\` or wonders whether \`minLength\` works on a number field — fetch the catalog to ground the answer
+- The user wants to add validation rules at APPLICATION LAYER in payload JSON (validation runs in generated model code, returns HTTP 400 with structured error before the request reaches the database), NOT native SQL DDL constraints (NOT NULL, UNIQUE, CHECK at database level)
+
+DO NOT USE FOR:
+- Validating actual payload files against the database schema -> use 'codegen_validate_payload'
+- Validating config (license, database connection) -> use 'setup_validate_config'
+- Reading the active database connection config schema -> use 'setup_get_config_schema'
+- Generating a payload from scratch -> use 'codegen_generate_payload'
+- Applying changes to payload files -> use 'codegen_sync_payload'
+- Generating SQL DDL constraints (NOT NULL, UNIQUE, CHECK, REFERENCES, ALTER TABLE, CREATE INDEX) — these are database-level and out of scope for RESTForge field validation. They require direct SQL or a database migration tool.
+
+This tool runs: npx restforge field-validation:catalog in the given cwd.
+The catalog is sourced from restforge (single source of truth) so it stays in sync with
+the restforge runtime version installed in the project.
+Requires @restforgejs/platform >= 2.4.0.
+
+PRESENTATION GUIDANCE:
+- Match the user's language. If the user writes in Indonesian, respond in Indonesian.
+- Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "install the package", "generate the payload", "edit the validation rules").
+- Speak in plain language. Summarise the catalog (number of types, constraints, format presets); do not paste the entire JSON unless the user explicitly asks for it.
+- If the user uses SQL DDL terminology (NOT NULL, UNIQUE, CHECK, ALTER TABLE, REFERENCES, CREATE INDEX), do not silently map it to payload validation. First clarify which layer the user wants: application-layer validation in payload (this catalog applies, response 400 with structured error) versus database-level DDL constraints (out of scope here, requires direct SQL or migration tool). The two layers can co-exist for the same field but behave differently.
+- When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform, version >= 2.4.0)'),
+        },
+        annotations: {
+            title: 'Get Field Validation Catalog',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be installed before this CLI command can run.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+
+For the assistant:
+- The field validation catalog can only be retrieved once the RESTForge package is installed locally.
+- Suggest installing the package first, then retry getting the catalog.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Run subprocess with NODE_ENV=production to suppress legacy banner output
+        // (mirrors the pattern used by setup_get_config_schema).
+        const result = await execProcess('npx', ['restforge', 'catalog', 'field-validation'], {
+            cwd: projectCwd,
+            timeout: 15_000,
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // CLI failure: real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve the field validation catalog.
+
+Project path: ${projectCwd}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that the field validation catalog could not be retrieved.
+- A common cause is an older RESTForge version that does not yet expose this command (requires @restforgejs/platform >= 2.4.0). If the CLI output mentions an unknown command, suggest upgrading the package as a likely fix.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Validate JSON output. Parse failure is a real error per §3.4 (CLI succeeded but produced invalid output).
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to parse field validation catalog JSON.
+
+Project path: ${projectCwd}
+Reason: ${msg}
+
+--- Raw stdout ---
+${result.stdout}
+--- end Raw stdout ---
+
+For the assistant:
+- The CLI returned output that is not valid JSON.
+- Summarise this to the user in plain language; do not paste the raw stdout unless they explicitly ask.
+- Suggest checking that the installed package version is compatible (requires @restforgejs/platform >= 2.4.0). Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Extract summary counts for labeled facts. Use defensive access — if the catalog shape
+        // changes upstream, we still produce a sensible response rather than crash.
+        const root = (parsed ?? {});
+        const summary = (root.summary ?? {});
+        const totalTypes = typeof summary.totalTypes === 'number' ? summary.totalTypes : 'unknown';
+        const totalConstraints = typeof summary.totalConstraints === 'number' ? summary.totalConstraints : 'unknown';
+        const totalFormatPresets = typeof summary.totalFormatPresets === 'number' ? summary.totalFormatPresets : 'unknown';
+        const sourceLabel = typeof root.source === 'string' ? root.source : 'field-validation-catalog';
+        // Re-stringify for consistent pretty formatting (independent of CLI --pretty flag).
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Success: one-line summary + labeled facts + fenced JSON output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Field validation catalog retrieved successfully.
+
+Project path: ${projectCwd}
+Source: restforge (${sourceLabel}) — single source of truth for the installed runtime version
+totalTypes: ${totalTypes}
+totalConstraints: ${totalConstraints}
+totalFormatPresets: ${totalFormatPresets}
+
+--- Field Validation Catalog (JSON) ---
+${prettyJson}
+--- end Field Validation Catalog (JSON) ---
+
+For the assistant:
+- Confirm to the user that the catalog is available. Summarise in plain language: how many data types, constraints, and format presets are included.
+- Do not paste the full JSON block unless the user explicitly asks for it. If the user only asked to "see the catalog", offer to drill into a specific type or constraint instead of dumping everything.
+- When the user is generating or editing a payload's \`fieldValidation\` array, use this catalog as ground truth to:
+  * Validate constraint names spelling (e.g. reject typos like \`maxLenght\`).
+  * Validate scope correctness (e.g. \`minLength\` is only valid for type \`string\`, not \`number\`). Use each type's \`applicableConstraints\` list as the shortcut for "which constraints are valid for type X" without iterating the full constraints array.
+  * Suggest constraints that fit the column's database type (e.g. CHAR/VARCHAR -> \`maxLength\`, \`pattern\`; INT/BIGINT -> \`min\`, \`max\`, \`positive\`).
+- Filter notes to disambiguate name collisions in the catalog:
+  * \`format\` constraint appears twice — scope=\`string\` (format presets such as email/phone/url/uuid) and scope=\`date\` (date format pattern). Filter by \`name + scope\` or \`name + applicableTypes\` to pick the right one.
+  * \`integer\` appears twice — once as a data type (\`types[].name === "integer"\`) and once as a number constraint (\`constraints[].name === "integer"\` with scope \`number\`). Disambiguate by context.
+  * \`uuid\` appears twice — once as a data type (\`VARCHAR(36)\` field type) and once as a format preset (validator format string). Choose by what the user is trying to express.
+- Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=get-field-validation-catalog.js.map

package/dist/tools/codegen/get-field-validation-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-field-validation-catalog.js","sourceRoot":"","sources":["../../../src/tools/codegen/get-field-validation-catalog.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/get-query-declarative-catalog.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenGetQueryDeclarativeCatalog(server: McpServer): void;

package/dist/tools/codegen/get-query-declarative-catalog.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenGetQueryDeclarativeCatalog(server) {
+    server.registerTool('codegen_get_query_declarative_catalog', {
+        title: 'Get Query Declarative Catalog',
+        description: `Get authoritative JSON catalog of query declarative spec (5 query properties, 7 endpoint resolution rules, file reference convention with database-specific placeholders) used in payload query declarations such as \`datatablesQuery\`, \`viewQuery\`, \`viewName\`, \`exportQuery\`, and \`masterDetail.detailConfig.detailQuery\`.
+
+USE WHEN:
+- The user asks about query declaration in payload, query properties, or how endpoints resolve queries
+- The user mentions specific property names: \`datatablesQuery\`, \`viewQuery\`, \`viewName\`, \`exportQuery\`, \`detailQuery\`, atau \`masterDetail\`
+- Pertanyaan dalam bentuk seperti "bagaimana cara declare query di payload", "what's the difference between viewQuery and viewName", "kapan pakai viewName vs tableName"
+- The user asks about endpoint query resolution: "query apa yang dipakai untuk /datatables", "what query does /export use", "resolusi query untuk /read-composite"
+- The user asks about \`file:\` prefix convention or SQL file references in payload
+- The user asks about database placeholder differences (PostgreSQL \`$1\`, MySQL \`?\`, Oracle \`:1\`) in detailQuery or other file-referenced SQL
+- Before generating or editing query-related properties in payload JSON — to ground property naming, resolution priority, and file reference convention. Often called before 'codegen_generate_payload' for grounding the initial generation, or before manual editing of an existing payload. Sibling of 'codegen_get_field_validation_catalog' (catalog-style tool, different scope).
+- The user asks about master-detail composite read query setup (\`detailQuery\` placement, foreign key placeholder)
+
+DO NOT USE FOR:
+- Validating actual payload files against the database schema -> use 'codegen_validate_payload'
+- Generating a payload from scratch -> use 'codegen_generate_payload'
+- Applying changes to payload files -> use 'codegen_sync_payload'
+- Validating fieldValidation array -> use 'codegen_get_field_validation_catalog'
+- Reading the active database connection config schema -> use 'setup_get_config_schema'
+- Auto SQL conversion details (PostgreSQL -> MySQL/Oracle) — not in catalog scope; refer to the documentationUrl returned in the response
+- Subquery wrapping behavior for JOIN/CTE queries — not in catalog scope; refer to documentationUrl
+- Master-detail full structure outside \`detailQuery\` (e.g. \`enabled\`, \`detailTable\`, \`foreignKey\`, \`detailConfig.tableName\`) — not in catalog scope; refer to documentationUrl
+- Use case examples and decision guides ("kapan pakai X vs Y") — refer to documentationUrl for narrative explanation
+
+This tool runs: npx restforge query-declarative:catalog in the given cwd.
+The catalog is sourced from restforge (single source of truth) so it stays in sync with
+the restforge runtime version installed in the project.
+
+PRESENTATION GUIDANCE:
+- Match the user's language. If the user writes in Indonesian, respond in Indonesian.
+- Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "look up the query catalog", "edit the query declaration", "install the package").
+- Speak in plain language. Summarise the catalog (number of query properties, endpoints, database placeholders); do not paste the entire JSON unless the user explicitly asks for it.
+- When a precondition is not met (e.g. the package is not installed), frame it as a question or next-step suggestion rather than an error.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform)'),
+        },
+        annotations: {
+            title: 'Get Query Declarative Catalog',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be installed before this CLI command can run.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+
+For the assistant:
+- The query declarative catalog can only be retrieved once the RESTForge package is installed locally.
+- Suggest installing the package first, then retry getting the catalog.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Run subprocess with NODE_ENV=production to suppress legacy banner output
+        // (mirrors the pattern used by setup_get_config_schema and get_field_validation_catalog).
+        const result = await execProcess('npx', ['restforge', 'catalog', 'query-declarative'], {
+            cwd: projectCwd,
+            timeout: 15_000,
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // CLI failure: real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve the query declarative catalog.
+
+Project path: ${projectCwd}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that the query declarative catalog could not be retrieved.
+- A common cause is an older RESTForge version that does not yet expose this command. If the CLI output mentions an unknown command, suggest upgrading the package as a likely fix.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Validate JSON output. Parse failure is a real error per §3.4 (CLI succeeded but produced invalid output).
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to parse query declarative catalog JSON.
+
+Project path: ${projectCwd}
+Reason: ${msg}
+
+--- Raw stdout ---
+${result.stdout}
+--- end Raw stdout ---
+
+For the assistant:
+- The CLI returned output that is not valid JSON.
+- Summarise this to the user in plain language; do not paste the raw stdout unless they explicitly ask.
+- Suggest checking that the installed package version is compatible. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Extract summary counts for labeled facts. Use defensive access — if the catalog shape
+        // changes upstream, we still produce a sensible response rather than crash.
+        const root = (parsed ?? {});
+        const summary = (root.summary ?? {});
+        const totalQueryProperties = typeof summary.totalQueryProperties === 'number' ? summary.totalQueryProperties : 'unknown';
+        const totalEndpoints = typeof summary.totalEndpoints === 'number' ? summary.totalEndpoints : 'unknown';
+        const totalDatabasePlaceholders = typeof summary.totalDatabasePlaceholders === 'number' ? summary.totalDatabasePlaceholders : 'unknown';
+        const totalFileReferenceCapableProperties = typeof summary.totalFileReferenceCapableProperties === 'number'
+            ? summary.totalFileReferenceCapableProperties
+            : 'unknown';
+        const sourceLabel = typeof root.source === 'string' ? root.source : 'query-declarative-catalog';
+        // Re-stringify for consistent pretty formatting (independent of CLI --pretty flag).
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Success: one-line summary + labeled facts + fenced JSON output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Query declarative catalog retrieved successfully.
+
+Project path: ${projectCwd}
+Source: restforge (${sourceLabel}) — single source of truth for the installed runtime version
+totalQueryProperties: ${totalQueryProperties}
+totalEndpoints: ${totalEndpoints}
+totalDatabasePlaceholders: ${totalDatabasePlaceholders}
+totalFileReferenceCapableProperties: ${totalFileReferenceCapableProperties}
+
+--- Query Declarative Catalog (JSON) ---
+${prettyJson}
+--- end Query Declarative Catalog (JSON) ---
+
+For the assistant:
+- Confirm to the user that the catalog is available. Summarise in plain language: how many query properties, endpoints, and database placeholders are included.
+- Do not paste the full JSON block unless the user explicitly asks for it. If the user only asked to "see the catalog", offer to drill into a specific property or endpoint instead of dumping everything.
+- When the user is generating or editing query-related properties in a payload (\`datatablesQuery\`, \`viewQuery\`, \`viewName\`, \`exportQuery\`, \`masterDetail.detailConfig.detailQuery\`), use this catalog as ground truth to:
+  * Validate property names spelling (e.g. reject typos like \`viewQueryName\`, \`dataTablesQuery\`).
+  * Validate \`supportsFileReference\` when the user uses a \`file:\` prefix. \`viewName\` does NOT support \`file:\` prefix because it holds a database VIEW name, not SQL content. Only the four properties listed in \`fileReferenceConvention.applicableProperties\` accept \`file:\`.
+  * Validate endpoint resolution priority when the user is unsure which query a given endpoint uses (e.g. \`/lookup\` does NOT use \`viewQuery\` — only \`viewName\` or \`tableName\`).
+  * Validate database placeholders when the user uses file mode. There is no auto-conversion in file mode: PostgreSQL \`$1\`, MySQL \`?\`, Oracle \`:1\` must be native to the target database.
+- Filter notes for catalog consumers (avoid common pitfalls):
+  * \`queryProperties[].name\` is the last segment of the property path. For nested properties such as \`detailQuery\`, use the \`nestedPath\` field for the full path (\`masterDetail.detailConfig.detailQuery\`). The four top-level properties have \`nestedPath: null\`.
+  * \`endpointResolution[]\` has two entries for \`/read-composite\`: \`"/read-composite (header)"\` and \`"/read-composite (detail)"\`. Pick the one matching the user's question context.
+  * \`fileReferenceConvention.applicableProperties\` lists the four properties that accept the \`file:\` prefix. \`viewName\` is intentionally excluded.
+  * \`fileReferenceConvention.placeholderConversionRules\` distinguishes inline mode (auto-converts \`$1\` -> \`?\` / \`:1\` for backward compatibility) from file mode (no auto-conversion — placeholders must be native to the target database).
+  * Each property has a \`requires\` array listing prerequisites that must be met for the property to be active — \`exportQuery\` requires \`action.export = true\`, \`detailQuery\` requires \`masterDetail.enabled = true\` AND \`action.readComposite = true\`.
+- Knowledge boundary — the catalog does NOT cover the following; refer the user to \`documentationUrl\` (in the response JSON) instead of fabricating from training data:
+  * Auto SQL conversion behavior (PostgreSQL syntax adapted to MySQL / Oracle).
+  * Auto subquery wrapping for JOIN / CTE queries.
+  * \`\${tableName}\` placeholder substitution inside query strings.
+  * Interaction with \`fieldName\` whitelisting (JOIN columns absent from \`fieldName\` get dropped).
+  * Concrete use case examples (when to pick \`viewName\` vs \`viewQuery\` vs \`tableName\`).
+- Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=get-query-declarative-catalog.js.map

package/dist/tools/codegen/get-query-declarative-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-query-declarative-catalog.js","sourceRoot":"","sources":["../../../src/tools/codegen/get-query-declarative-catalog.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenTools(server: McpServer): void;

package/dist/tools/codegen/index.js

@@ -0,0 +1,43 @@
+import { registerCodegenGeneratePayload } from './generate-payload.js';
+import { registerCodegenValidatePayload } from './validate-payload.js';
+import { registerCodegenDiffPayload } from './diff-payload.js';
+import { registerCodegenSyncPayload } from './sync-payload.js';
+import { registerCodegenGetFieldValidationCatalog } from './get-field-validation-catalog.js';
+import { registerCodegenGetQueryDeclarativeCatalog } from './get-query-declarative-catalog.js';
+import { registerCodegenGetDashboardCatalog } from './get-dashboard-catalog.js';
+import { registerCodegenCreateEndpoint } from './create-endpoint.js';
+import { registerCodegenCreateDashboard } from './create-dashboard.js';
+import { registerCodegenValidateDashboardPayload } from './validate-dashboard-payload.js';
+import { registerCodegenListTables } from './list-tables.js';
+import { registerCodegenDescribeTable } from './describe-table.js';
+import { registerCodegenValidateSql } from './validate-sql.js';
+import { registerCodegenGetDbschemaCatalog } from './get-dbschema-catalog.js';
+import { registerCodegenDbschemaInit } from './dbschema-init.js';
+import { registerCodegenDbschemaValidate } from './dbschema-validate.js';
+import { registerCodegenDbschemaModels } from './dbschema-models.js';
+import { registerCodegenDbschemaGenerateDdl } from './dbschema-generate-ddl.js';
+import { registerCodegenDbschemaIntrospect } from './dbschema-introspect.js';
+import { registerCodegenDbschemaMigrate } from './dbschema-migrate.js';
+export function registerCodegenTools(server) {
+    registerCodegenGeneratePayload(server);
+    registerCodegenValidatePayload(server);
+    registerCodegenDiffPayload(server);
+    registerCodegenSyncPayload(server);
+    registerCodegenGetFieldValidationCatalog(server);
+    registerCodegenGetQueryDeclarativeCatalog(server);
+    registerCodegenGetDashboardCatalog(server);
+    registerCodegenCreateEndpoint(server);
+    registerCodegenCreateDashboard(server);
+    registerCodegenValidateDashboardPayload(server);
+    registerCodegenListTables(server);
+    registerCodegenDescribeTable(server);
+    registerCodegenValidateSql(server);
+    registerCodegenGetDbschemaCatalog(server);
+    registerCodegenDbschemaInit(server);
+    registerCodegenDbschemaValidate(server);
+    registerCodegenDbschemaModels(server);
+    registerCodegenDbschemaGenerateDdl(server);
+    registerCodegenDbschemaIntrospect(server);
+    registerCodegenDbschemaMigrate(server);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/codegen/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,wCAAwC,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAAE,yCAAyC,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,kCAAkC,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,uCAAuC,EAAE,MAAM,iCAAiC,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,iCAAiC,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACvC,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACnC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACnC,wCAAwC,CAAC,MAAM,CAAC,CAAC;IACjD,yCAAyC,CAAC,MAAM,CAAC,CAAC;IAClD,kCAAkC,CAAC,MAAM,CAAC,CAAC;IAC3C,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACtC,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACvC,uCAAuC,CAAC,MAAM,CAAC,CAAC;IAChD,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACrC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACnC,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAC1C,2BAA2B,CAAC,MAAM,CAAC,CAAC;IACpC,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACxC,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACtC,kCAAkC,CAAC,MAAM,CAAC,CAAC;IAC3C,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAC1C,8BAA8B,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/dist/tools/codegen/list-tables.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenListTables(server: McpServer): void;