@restforgejs/mcp-server 1.2.0 → 1.2.2

package/README.md

@@ -1,12 +1,28 @@
 # @restforgejs/mcp-server
 
-MCP (Model Context Protocol) server for the RESTForge framework. Exposes RESTForge capabilities to AI Agents (Claude Desktop, Cursor, Claude CLI, and other MCP clients) so agents can operate RESTForge through natural language without manually invoking CLI commands.
+MCP (Model Context Protocol) server for the RESTForge Platform. Exposes RESTForge capabilities to AI Agents (Claude Desktop, Cursor, Claude CLI, and other MCP clients) so agents can operate RESTForge through natural language without manually invoking CLI commands.
+
+> **Scope Notice:** This MCP server is a thin orchestrator that exposes RESTForge Platform commands to AI agents via the Model Context Protocol. It is not a generic MCP framework, an API testing tool, an API client, or an HTTP request proxy. Its tools strictly invoke RESTForge Platform CLI commands; it does not consume or test arbitrary third-party APIs.
 
 ## Requirements
 
 - Node.js >= 18
 - npm >= 9
-- For full setup workflow: PostgreSQL / MySQL / Oracle / SQLite, RESTForge license key
+- For full setup workflow: PostgreSQL / MySQL / Oracle, RESTForge license key
+
+## Access & License
+
+This MCP server package (`@restforgejs/mcp-server`) is distributed under the **MIT License** and may be installed and inspected freely.
+
+The MCP server orchestrates the **RESTForge Platform** (`@restforgejs/platform`), which is **commercial software currently in closed evaluation**. Full workflow execution (setup validation, code generation, runtime launch) requires a valid RESTForge license key.
+
+License key acquisition:
+
+- **Early Access Program** — Limited slots for volunteer evaluators. Apply at [restforge.dev](https://restforge.dev)
+- **Commercial Trial** — Coming soon. Register interest at [restforge.dev](https://restforge.dev)
+- **Commercial License** — Available upon general release
+
+Without a valid license key, MCP tools that depend on the platform runtime (e.g. `setup_validate_config`, `codegen_*`, `runtime_*`) will return authentication errors.
 
 ## Installation
 
@@ -24,7 +40,7 @@ After installation, the `restforge-mcp` command is available in PATH.
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | restforge-mcp
 ```
 
-Output should list 29 tools across the `health_*`, `setup_*`, `codegen_*`, and `runtime_*` domains.
+Output should list 39 tools across the `health_*`, `setup_*`, `codegen_*`, and `runtime_*` domains.
 
 ### 2. Register with MCP Client
 
@@ -66,13 +82,13 @@ In your AI client chat, type prompts like:
 
 > Generate a CRUD endpoint for the `customer` table
 
-> Run my RESTForge server (the agent generates a launcher script for the user to execute)
+> Start my RESTForge project (the agent generates a launcher script for the user to execute)
 
 The agent orchestrates the appropriate tools to fulfill the request end-to-end.
 
 ## Available Tools
 
-29 tools organized by domain. AI agents call these via the MCP protocol; end users do not invoke them directly.
+39 tools organized by domain. AI agents call these via the MCP protocol; end users do not invoke them directly.
 
 ### Health Domain (1 tool)
 
@@ -94,12 +110,33 @@ The agent orchestrates the appropriate tools to fulfill the request end-to-end.
 | `setup_get_config_schema` | Get JSON schema of all 63 parameters available in `db-connection.env` |
 | `setup_get_init_template` | Get raw `db-connection.env` template content |
 
-### Codegen Domain (13 tools)
+### Codegen Domain (23 tools)
+
+Live database introspection:
 
 | Tool | Description |
 |------|-------------|
 | `codegen_list_tables` | List all tables in the project's database (live introspection) |
 | `codegen_describe_table` | Describe columns, primary key, and foreign keys of a specific table |
+
+Schema-as-code (dbschema-kit / SDF):
+
+| Tool | Description |
+|------|-------------|
+| `codegen_dbschema_init` | Create a new dbschema-kit schema definition skeleton file (minimal starter) |
+| `codegen_dbschema_template` | Browse, preview, and generate from the Schema Reference collection (87 templates across 30+ domains) |
+| `codegen_dbschema_validate` | Validate dbschema-kit definition files (single-model structure + cross-model FK checks) |
+| `codegen_dbschema_models` | List dbschema-kit models with a structural summary (fields, keys, indexes, relations) |
+| `codegen_dbschema_introspect` | Reverse-engineer an existing database into dbschema-kit definition files |
+| `codegen_dbschema_generate_ddl` | Generate dialect-specific DDL (CREATE TABLE/INDEX, optional DROP) from dbschema-kit files |
+| `codegen_dbschema_migrate` | Apply dbschema-kit files to a live database (load → validate → DDL → apply; DESTRUCTIVE with `drop=true`) |
+| `codegen_dbschema_diff` | Detect schema drift between dbschema-kit files and the live database (read-only, bidirectional) |
+| `codegen_dbschema_apply` | Resolve schema drift to the live database via incremental `ALTER` (additive-only by default; opt-in destructive) |
+
+Payload, scaffolding, and SQL:
+
+| Tool | Description |
+|------|-------------|
 | `codegen_generate_payload` | Generate payload JSON from a database table |
 | `codegen_validate_payload` | Validate payload JSON structure and constraints |
 | `codegen_validate_dashboard_payload` | Validate dashboard payload structure |
@@ -108,9 +145,15 @@ The agent orchestrates the appropriate tools to fulfill the request end-to-end.
 | `codegen_create_endpoint` | Scaffold an endpoint module from a payload spec |
 | `codegen_create_dashboard` | Scaffold a dashboard module from a payload spec |
 | `codegen_validate_sql` | Validate a SELECT or WITH (CTE) SQL statement via EXPLAIN against the live database |
+
+Grounding catalogs:
+
+| Tool | Description |
+|------|-------------|
 | `codegen_get_field_validation_catalog` | Get the field validation catalog (for grounding payload constraints) |
 | `codegen_get_query_declarative_catalog` | Get the query declarative catalog (for grounding query JSON) |
 | `codegen_get_dashboard_catalog` | Get the dashboard widget catalog (for grounding dashboard config) |
+| `codegen_get_dbschema_catalog` | Get the dbschema (SDF) catalog: model options, field types, and the soft-delete contract (for grounding schema definition files) |
 
 ### Runtime Domain (6 tools)
 
@@ -141,8 +184,8 @@ The model used (Claude, GPT, Gemini, etc.) depends on the client configuration.
 
 ## Repository
 
-- Source: [https://github.com/restforge-dev/mcp-server](https://github.com/restforge-dev/mcp-server)
-- Issues: [https://github.com/restforge-dev/mcp-server/issues](https://github.com/restforge-dev/mcp-server/issues)
+- Source: [https://github.com/restforge/restforge-mcp](https://github.com/restforge/restforge-mcp)
+- Issues: [https://github.com/restforge/restforge-mcp/issues](https://github.com/restforge/restforge-mcp/issues)
 
 ## License
 

package/dist/server.js

@@ -1,11 +1,20 @@
+import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerHealthTools } from './tools/health/index.js';
 import { registerSetupTools } from './tools/setup/index.js';
 import { registerCodegenTools } from './tools/codegen/index.js';
 import { registerRuntimeTools } from './tools/runtime/index.js';
+import { registerDesignerTools } from './tools/designer/index.js';
 const SERVER_NAME = 'restforge-mcp';
-const SERVER_VERSION = '1.0.0';
+// Read the version from package.json at runtime so the advertised server version
+// never drifts from the published package version. createRequire resolves the JSON
+// relative to this module's location (dist/server.js -> ../package.json, and
+// src/server.ts -> ../package.json under tsx), so the path holds in both build and
+// dev. createRequire is used instead of a static JSON import because rootDir is
+// ./src and package.json lives outside it; a static import would break the build.
+const require = createRequire(import.meta.url);
+const { version: SERVER_VERSION } = require('../package.json');
 const SERVER_INSTRUCTIONS = `
 This MCP server manages RESTForge backend project configuration.
 
@@ -116,6 +125,14 @@ route them as follows:
   for 'schema migrate' (apply DDL to database) and produced by
   'schema introspect' (reverse-engineer database).
   Example: <project>/schema/category.js
+  An SDF may declare a soft-delete block: softDelete { enabled, reusable }.
+  When enabled, the three contract columns is_deleted (boolean),
+  deleted_at (timestamp), and deleted_by (string) are mandatory and
+  biconditional: declaring the columns without enabled=true, or
+  enabled=true with missing/wrongly-typed columns, is a validation ERROR.
+  Soft-delete is PostgreSQL-only in Phase 1. The generated DDL emits a
+  consistency CHECK (chk_<table>_soft_delete_consistency) and partial
+  indexes (WHERE is_deleted = FALSE) for non-unique indexes.
 
 - RDF (Resource Definition File): JSON file (.json) at
   payload/<resource>.json that declares a backend REST API endpoint (CRUD +
@@ -129,12 +146,21 @@ route them as follows:
 
 Routing for SDF requests:
 - create / init / scaffold -> codegen_dbschema_init
+- browse/preview/generate schema templates (87-template reference collection) -> codegen_dbschema_template
 - validate -> codegen_dbschema_validate
 - list models / show structural summary -> codegen_dbschema_models
 - generate DDL (preview or to file) -> codegen_dbschema_generate_ddl
 - reverse-engineer from database -> codegen_dbschema_introspect
+  WARNING: on PostgreSQL, a table whose soft-delete columns do not meet
+  the contract (partial column set, wrong types, or missing consistency
+  CHECK) BLOCKS introspect with an error whose message lists concrete
+  mitigation options. Relay that message and its options to the user;
+  do not swallow it as a generic failure.
+- check drift / compare SDF vs database -> codegen_dbschema_diff
+- resolve drift incrementally via ALTER (additive-safe, opt-in destructive) -> codegen_dbschema_apply
 - apply to database (DESTRUCTIVE) -> codegen_dbschema_migrate
 - lookup syntax / defineModel API spec -> codegen_get_dbschema_catalog
+- lookup soft-delete contract/rules -> codegen_get_dbschema_catalog (section=softDelete)
 
 Routing for RDF requests:
 - generate from database table -> codegen_generate_payload
@@ -202,6 +228,49 @@ documentationUrl returned by each catalog points to narrative
 documentation which may lag behind the most recent npm release; trust
 the catalog data over the URL for property reference, but use the URL
 for use case examples and decision guides.
+
+DESIGNER (FRONTEND) DOMAIN:
+The codegen/setup/runtime tools above all wrap the backend CLI
+('restforge', the @restforgejs/platform package). A separate family of
+tools — the 'designer_*' tools — wraps a DIFFERENT command-line product,
+'restforge-designer' (the RESTForge Designer frontend generator). Keep
+the two straight: backend payload/schema/API work goes through the
+'restforge' tools; frontend application work goes through the
+'designer_*' tools.
+
+Prefer the 'designer_*' tools when the user wants to:
+- Generate, validate, or preview a FRONTEND application (not a backend
+  API) from a UI Definition File (UDF) payload
+- Work with a frontend/designer PLUGIN (list, inspect, scaffold) — plugin
+  ids look like 'vanilla-js-basic', 'vanilla-js-auth', 'vanilla-js-custom'
+- Initialise a new frontend project from a designer plugin
+- Phrases like "generate frontend", "build the UI from this payload",
+  "generate aplikasi frontend", "preview file frontend", "buat project
+  frontend dari plugin", "validate UDF", or any mention of
+  "restforge-designer", "designer", "rfd", or "frontend generation"
+
+Detection signals that this is RESTForge Designer (frontend) work:
+- The 'restforge-designer' binary (alias 'rfd') is installed and on PATH
+- The user mentions UDF (UI Definition File), frontend generation, or a
+  designer plugin ('vanilla-js-*')
+- A frontend project folder with a UDF payload (payload/NN-<name>.json
+  in the frontend project) is in play
+
+Boundaries for the designer domain:
+- The 'designer_*' tools wrap the 'restforge-designer' binary, which is a
+  product SEPARATE from the backend 'restforge' CLI. They are not
+  interchangeable; do not route a backend RDF/SDF request to a
+  'designer_*' tool, or a UDF/frontend request to a 'codegen_*' tool.
+- Designer LICENSE management and activation/deactivation are NOT
+  available through this MCP server (consistent with the backend, which
+  also does not manage per-machine license here). When a license-gated
+  designer operation (init, generate) fails because the license is not
+  active, relay that and tell the user to activate their RESTForge
+  Designer license through the Designer desktop application or its own
+  CLI — this server cannot activate it.
+- If the 'restforge-designer' binary is not installed or not on PATH, the
+  designer tools return a non-error precondition; relay it as a setup
+  step (install RESTForge Designer), not a failure.
 `.trim();
 export async function startServer() {
     const server = new McpServer({
@@ -214,6 +283,7 @@ export async function startServer() {
     registerSetupTools(server);
     registerCodegenTools(server);
     registerRuntimeTools(server);
+    registerDesignerTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,GAAG,eAAe,CAAC;AACpC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoM3B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,EACD;QACE,YAAY,EAAE,mBAAmB;KAClC,CACF,CAAC;IAEF,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,WAAW,GAAG,eAAe,CAAC;AAEpC,iFAAiF;AACjF,mFAAmF;AACnF,6EAA6E;AAC7E,mFAAmF;AACnF,gFAAgF;AAChF,kFAAkF;AAClF,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtF,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgQ3B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,EACD;QACE,YAAY,EAAE,mBAAmB;KAClC,CACF,CAAC;IAEF,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAE9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools/codegen/dbschema-apply.d.ts

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

package/dist/tools/codegen/dbschema-apply.js

@@ -0,0 +1,324 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+// Pull one labelled block (e.g. 'Warnings:' or 'Summary:') out of the structured
+// human-readable stdout. The CLI prints the header on its own line and the block
+// ends at the first blank line. Defensive: returns null when the header is absent
+// or the shape is unexpected — the caller then falls back to the full stdout.
+function extractBlock(stdout, header) {
+    const lines = stdout.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.trim() === header);
+    if (start === -1)
+        return null;
+    const block = [lines[start]];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i].trim() === '')
+            break;
+        block.push(lines[i]);
+    }
+    return block.join('\n');
+}
+// Compose the Warnings + Summary excerpt for the opt-in branch. Falls back to a
+// pointer line when neither block is found, so the response never loses signal.
+function extractWarningsAndSummary(stdout) {
+    const parts = [];
+    const warnings = extractBlock(stdout, 'Warnings:');
+    if (warnings)
+        parts.push(warnings);
+    const summary = extractBlock(stdout, 'Summary:');
+    if (summary)
+        parts.push(summary);
+    if (parts.length === 0) {
+        return '(no Warnings:/Summary: blocks recognised — see the full CLI output above)';
+    }
+    return parts.join('\n\n');
+}
+export function registerCodegenDbschemaApply(server) {
+    server.registerTool('codegen_dbschema_apply', {
+        title: 'Apply Schema Drift Incrementally via ALTER',
+        description: `Resolve schema drift from dbschema-kit SDF files to the live database via incremental ALTER TABLE statements, by wrapping restforge schema apply. This is the incremental complement of 'codegen_dbschema_diff' (which only detects drift) and the SAFE alternative to 'codegen_dbschema_migrate' with drop=true (which destroys and recreates tables). By default the apply is ADDITIVE-ONLY: ADD COLUMN, CREATE INDEX, ADD UNIQUE, and ADD FOREIGN KEY are emitted; every destructive change is skipped with a warning unless explicitly opted in (allowDrop for DROP COLUMN/INDEX/UNIQUE/FOREIGN KEY, allowModify for ALTER COLUMN length/nullable and FOREIGN KEY action changes).
+
+RECOMMENDED WORKFLOW:
+1. Run 'codegen_dbschema_diff' first to see the drift.
+2. Run this tool with dryRun=true to preview the exact ALTER statements.
+3. Show the preview to the user and ask for confirmation.
+4. Only then run with dryRun=false to apply. Pass allowDrop/allowModify ONLY when the user explicitly asked for that destructive change — never to "make a warning go away".
+
+EXIT CODE SEMANTICS (important):
+- Exit 0 = success: every applicable drift was applied (or previewed in dry-run, or there was no drift). The output may still contain warnings for operations the platform defers (see below) — relay those.
+- Exit 1 = some drift was SKIPPED because it requires allowDrop or allowModify. This is a NORMAL, meaningful result — NOT a failure. In a real apply the additive statements WERE applied; only the skipped items remain. NEVER retry automatically with allowDrop/allowModify: those options drop or mutate data and need explicit user confirmation first.
+- Exit 2 = system error (invalid config, SDF load failure, connection failure, or apply failure). ROLLBACK means the database is unchanged; PARTIAL means some statements were applied and the database needs manual inspection.
+
+USE WHEN:
+- 'codegen_dbschema_diff' reported drift and the user wants to bring the database in sync incrementally
+- The user asks "apply the drift", "sinkronkan database dengan schema", "tambahkan kolom yang kurang ke database", "apply perubahan schema tanpa drop"
+- Evolving an existing populated database without recreating tables (data preserved)
+- The user wants a preview of the ALTER statements first — pass dryRun=true (safe path)
+
+DO NOT USE FOR:
+- Detecting drift without changing anything -> use 'codegen_dbschema_diff' (read-only)
+- Full CREATE/DROP deployment of a schema or initial setup of an empty database -> use 'codegen_dbschema_migrate'
+- Retrofitting the soft-delete consistency CHECK -> not supported here (detection-only); goes through 'codegen_dbschema_migrate' with drop (destructive) or manual SQL
+- Type changes, PK changes, default value changes, CHECK constraint changes -> not supported by the platform yet (always skipped); suggest a manual SQL migration
+- Validating SDF file correctness -> use 'codegen_dbschema_validate'
+- Reverse-engineering SDF files from the database -> use 'codegen_dbschema_introspect'
+
+This tool runs: npx restforge schema apply --path=<path> --config=<config> [--table=<name>] [--dry-run] [--allow-drop] [--allow-modify] in the given cwd. The output is a structured human-readable report (DDL preview or per-statement progress, Warnings, Summary) — there is no JSON mode.
+
+OPERATIONS NOT SUPPORTED by the platform yet (always skipped with a 'deferred' warning, regardless of opt-in flags):
+- ALTER COLUMN type change (needs a data conversion strategy per dialect)
+- ALTER COLUMN precision/scale change
+- DEFAULT value change
+- PRIMARY KEY changes (need a table rebuild)
+- CHECK constraint add/drop
+On SQLite, MODIFY/DROP COLUMN and ALL foreign key changes are additionally skipped ('sqlite limitation') even with opt-in flags; the sqlite dialect is rejected entirely by the default introspector.
+
+Soft-delete note: drift in the soft-delete consistency CHECK is detection-only. It is reported as a warning (never auto-applied) and does NOT by itself cause exit 1; the warning text suggests retrofitting via 'schema migrate --drop' (recreate) or adding the CHECK manually.
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules.
+- The config file (default 'db-connection.env') must exist and contain valid database credentials.
+- SDF files must exist at the given path. The --path flag is required by the CLI.
+
+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. "apply the missing columns", "preview the ALTER statements").
+- Exit 1 is NOT an error. Present it as: "these changes were applied/previewed, these were skipped because they would drop or modify existing data". Then ask the user whether they want the destructive part — do not decide for them.
+- This tool MUTATES the live database when dryRun=false. Prefer dryRun=true on the first call and confirm with the user before the real apply.
+- Speak in plain language. Summarise the applied/skipped items; do not paste raw CLI output unless the user explicitly asks.
+- When a precondition is not met, 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 and the config file)'),
+            config: z
+                .string()
+                .min(1)
+                .default('db-connection.env')
+                .describe('Config file name relative to the project, used by the CLI to connect to the database'),
+            path: z
+                .string()
+                .min(1)
+                .describe('Path to schema file or folder relative to cwd (e.g. "./schema" or "schema/users.js"). Required by the CLI.'),
+            table: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Apply only one specific table. When omitted, all models in the schema path are processed.'),
+            dryRun: z
+                .boolean()
+                .default(false)
+                .describe('Default false. When true, preview the ALTER statements without applying. Safe path: prefer this on the first call.'),
+            allowDrop: z
+                .boolean()
+                .default(false)
+                .describe('Default false. Opt-in for DROP COLUMN/INDEX/UNIQUE/FOREIGN KEY (destroys data or constraints). Require explicit user confirmation before passing true.'),
+            allowModify: z
+                .boolean()
+                .default(false)
+                .describe('Default false. Opt-in for ALTER COLUMN length/nullable and FOREIGN KEY action changes (potential data loss). Require explicit user confirmation before passing true.'),
+        },
+        annotations: {
+            title: 'Apply Schema Drift Incrementally via ALTER',
+            destructiveHint: true, // mutates the live database; with opt-in flags also drops columns/constraints
+            idempotentHint: false, // re-running applies whatever drift remains; state-dependent
+        },
+    }, async ({ cwd, config, path, table, dryRun, allowDrop, allowModify }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be present in node_modules. per §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
+Requested config: ${config}
+Requested schema path: ${path}
+Requested table filter: ${table ?? 'all tables'}
+Requested dryRun: ${dryRun}
+
+For the assistant:
+- The user needs to install the RESTForge package before drift can be applied to the database.
+- Suggest installing the package first, then retry the apply.
+- 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
+            };
+        }
+        // Boolean flags are only forwarded when true, following the migrate/introspect
+        // pattern. There is no JSON output mode for schema apply. per §3.5
+        const cliArgs = [
+            'restforge',
+            'schema',
+            'apply',
+            `--path=${path}`,
+            `--config=${config}`,
+        ];
+        if (table !== undefined)
+            cliArgs.push(`--table=${table}`);
+        if (dryRun === true)
+            cliArgs.push('--dry-run');
+        if (allowDrop === true)
+            cliArgs.push('--allow-drop');
+        if (allowModify === true)
+            cliArgs.push('--allow-modify');
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 120_000, // introspection + ALTER execution on a populated DB can be slow
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // Exit code semantics are part of the CLI spec: 0 = all applicable drift
+        // applied (or no drift), 1 = some drift skipped pending opt-in (a meaningful
+        // result, NOT an error), 2 = system error. Deliberately NO "exit 2 = dry-run
+        // success" sentinel here: a successful apply dry-run exits 0 or 1.
+        const optInRequired = result.exitCode === 1;
+        // Branch C: system error (exit 2 or any other non-0/1 exit). per §3.4
+        if (!result.success && !optInRequired) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to apply schema drift to the database.
+
+Project path: ${projectCwd}
+Config: ${config}
+Schema path: ${path}
+Table filter: ${table ?? 'all tables'}
+Mode: ${dryRun ? 'dry-run' : 'apply'}
+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 apply could not complete. This is a system error, not a drift result.
+- Check the CLI output for ROLLBACK or PARTIAL status first:
+  * ROLLBACK applied — the database state is UNCHANGED; the failed statement is reported. Safe to fix the cause and retry.
+  * Partial apply detected — SOME statements were applied before the failure and were NOT reverted. The user must inspect the database state manually before any retry.
+- Other common causes, in plain language:
+  * Config file not found or invalid — suggest verifying the config path and its content.
+  * Database connection failed — suggest verifying credentials, host, and port.
+  * Schema path not found or no models in it — suggest verifying the folder or file name passed via --path.
+  * SDF load error — a schema file has invalid syntax or violates the defineModel contract. Suggest running the validate action first.
+  * Table filter not found in SDF — the --table value does not match any model.
+  * Unsupported dialect — schema apply does not support sqlite. Suggest checking DB_TYPE in the config.
+  * Unknown command 'schema apply' — the installed RESTForge version may be older than this CLI subcommand; suggest upgrading the package.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.
+- Offer to retry once the underlying issue is resolved (after manual inspection in the PARTIAL case).`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Branch B (opt-in required): exit 1 — part of the drift was skipped because
+        // it needs --allow-drop / --allow-modify. A meaningful result, NOT an error.
+        if (optInRequired) {
+            const excerpt = extractWarningsAndSummary(result.stdout);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Schema apply ${dryRun ? 'dry-run ' : ''}completed with skipped drift: some changes require explicit opt-in (this is a result, not an error).
+
+Project path: ${projectCwd}
+Config: ${config}
+Schema path: ${path}
+Table filter: ${table ?? 'all tables'}
+Mode: ${dryRun ? 'dry-run (nothing applied)' : 'apply (additive statements WERE applied)'}
+
+--- Warnings and Summary (from the CLI) ---
+${excerpt}
+--- end Warnings and Summary ---
+
+--- Full CLI output ---
+${result.stdout}
+--- end Full CLI output ---
+
+For the assistant:
+- Present this as a two-part factual result: (1) what was ${dryRun ? 'previewed' : 'applied'} — see the ${dryRun ? 'DDL preview' : 'progress lines'} in the full output; (2) what was SKIPPED — the Warnings above list each skipped item with its reason ('requires --allow-drop' or 'requires --allow-modify').
+- ${dryRun ? 'This was a preview only. Nothing was applied to the database.' : 'The additive statements were applied to the live database; only the skipped items remain outstanding.'}
+- Do NOT retry with allowDrop/allowModify on your own. Those options drop columns/constraints or alter existing columns — explain to the user what would be dropped or modified, and only proceed after the user explicitly confirms.
+- Warnings with reason 'deferred', 'detection-only', or 'sqlite limitation' cannot be resolved by opt-in flags at all — those need a manual migration or a full recreate; say so plainly.
+- Do not paste the full CLI output unless the user asks; the Warnings/Summary excerpt is usually enough.
+- Match the user's language.`,
+                    },
+                ],
+                isError: false, // exit 1 = drift pending opt-in, a normal result per CLI spec
+            };
+        }
+        // Branch B (dry-run success): exit 0 with --dry-run — preview only.
+        if (dryRun) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Schema apply dry-run completed (no changes applied).
+
+Project path: ${projectCwd}
+Config: ${config}
+Schema path: ${path}
+Table filter: ${table ?? 'all tables'}
+Mode: dry-run
+
+--- DDL preview ---
+${result.stdout}
+--- end DDL preview ---
+
+For the assistant:
+- Confirm to the user that this was a preview only. No ALTER statement was applied to the database.
+- The statements shown above are exactly what would run if the same action is repeated without dry-run. "No applicable ALTER statements." means schema and database are already in sync for the applicable operations.
+- If a Warnings block is present, relay it: warnings with reason 'deferred', 'detection-only', or 'sqlite limitation' are operations the platform cannot apply incrementally yet (they do not block the rest).
+- Encourage the user to review the preview, then confirm before running the real apply.
+- Match the user's language.`,
+                    },
+                ],
+            };
+        }
+        // Branch B (apply success): exit 0 — every applicable drift applied (or no drift).
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Schema apply completed successfully: all applicable drift was applied.
+
+Project path: ${projectCwd}
+Config: ${config}
+Schema path: ${path}
+Table filter: ${table ?? 'all tables'}
+Mode: apply
+allowDrop: ${allowDrop}
+allowModify: ${allowModify}
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Confirm to the user that the incremental changes were applied to the live database. "No drift to apply." means schema and database were already in sync.
+- Read the Summary in the CLI output and mention the number of statements applied in plain language.
+- If skipped warnings are present (reason 'deferred', 'detection-only', or 'sqlite limitation'), relay them: those operations cannot be applied incrementally yet and need a manual migration or a full recreate. They did not block this apply.
+- Suggest verifying the result with a drift check (read-only) if the user wants confirmation that everything is now in sync.
+- Do not paste the raw CLI output unless the user explicitly asks.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=dbschema-apply.js.map

package/dist/tools/codegen/dbschema-apply.js.map

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

package/dist/tools/codegen/dbschema-diff.d.ts

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