@restforgejs/mcp-server 1.2.0

package/dist/tools/codegen/validate-sql.js

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+function truncateSql(sql) {
+    return sql.length > 100 ? `${sql.substring(0, 100)}...` : sql;
+}
+export function registerCodegenValidateSql(server) {
+    server.registerTool('codegen_validate_sql', {
+        title: 'Validate SQL Query',
+        description: `Validate a SELECT (or WITH/CTE) SQL statement against the live database — checks syntax, column references, function existence, type compatibility, and JOIN resolution — by wrapping restforge query:validate. Live introspection — the CLI runs EXPLAIN against the configured database without executing any rows.
+
+USE WHEN:
+- The user asks "is this SQL valid?", "check my SQL", "validate this query", "cek SQL ini bener atau salah"
+- Before invoking 'codegen_create_dashboard' with widget queries — to verify each widget SQL passes against the live database before committing the payload file
+- After authoring a complex SQL (multi-table JOIN, CTE, window function) — to catch column reference errors, ambiguous columns, dialect-specific function mismatches before runtime
+- The user reports a dashboard widget failed at runtime with a database error — to confirm whether the SQL is the cause and identify the specific error code/message
+- Iterating on SQL: validate, fix, re-validate (the tool is idempotent and read-only)
+- After 'codegen_describe_table' suggested column names but the user wants a final correctness check on a draft SQL
+
+DO NOT USE FOR:
+- Validating the JSON shape of a payload file -> use 'codegen_validate_payload' or 'codegen_validate_dashboard_payload'
+- Checking whether the SQL result shape matches a widget query key's expected shape (scalar/object/array) -> out of scope; that is checked by the dashboard payload validator separately
+- Running INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE — these statements are rejected before any database connection is opened (this tool is read-only)
+- Listing tables in the database -> use 'codegen_list_tables'
+- Describing a table's columns/PK/FK -> use 'codegen_describe_table'
+- Performance/query plan analysis -> out of scope; the tool only reports validation pass/fail, not the query plan
+
+Cross-reference: this tool complements 'codegen_list_tables' and 'codegen_describe_table'. Use list/describe to ground SQL on the live schema, then validate-sql to confirm the composed SQL is correct before commit.
+
+This tool runs: npx restforge query:validate --config=<config> --sql=<sql> --pretty=false in the given cwd.
+The CLI runs EXPLAIN (PostgreSQL/MySQL) or EXPLAIN PLAN FOR (Oracle) against the configured database, without executing any rows.
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules (>= 2.4.8 for query:validate support).
+- The config file (default 'db-connection.env') must exist in the project (or in cwd/config/) and contain valid database credentials. The CLI auto-fallbacks to the config/ subfolder if the file is not found at the top level.
+
+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. "validate the SQL", "list the database tables").
+- Speak in plain language. For success: confirm the SQL is valid in one sentence. For failure: summarise the error category in plain language (e.g. "the column 'x' doesn't exist in this table"), and suggest the next action (revise SQL based on error, re-validate).
+- This is a live introspection: the tool actively runs EXPLAIN against the database. The result reflects the database state at query time. Zero rows are executed; the planner only parses and resolves references.
+- For SELECT-only rejection (when the SQL starts with INSERT/UPDATE/DELETE/etc), explain that the validator is read-only by design and ask the user to revise to a SELECT statement.
+- Error codes are dialect-specific: Postgres uses 5-char SQLSTATE (e.g. '42703'), MySQL uses ER_* names or numeric errno, Oracle uses 'ORA-XXXXX'. When relevant, mention the category in plain language (column not found, ambiguous reference, function mismatch, etc) instead of citing the raw code.
+- 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 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'),
+            sql: z
+                .string()
+                .min(1)
+                .describe('SQL string to validate. Must be a SELECT or WITH (CTE) statement. Other statements (INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE) are rejected before any database connection is opened.'),
+        },
+        annotations: {
+            title: 'Validate SQL Query',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, config, sql }) => {
+        const projectCwd = resolve(cwd);
+        const sqlPreview = truncateSql(sql);
+        // Branch A: Precondition check — @restforgejs/platform must be present in node_modules.
+        // 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
+Requested config: ${config}
+Requested sql (first 100 chars): ${sqlPreview}
+
+For the assistant:
+- The user needs to install the RESTForge package before SQL validation can run.
+- Suggest installing the package first, then retry validating the SQL.
+- 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,
+            };
+        }
+        // Run CLI with --pretty=false (compact); the MCP layer re-formats JSON for output.
+        const cliArgs = [
+            'restforge',
+            'query:validate',
+            `--config=${config}`,
+            `--sql=${sql}`,
+            '--pretty=false',
+        ];
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 30_000,
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // Branch D: SELECT-only rejection — non-error guidance per Q6.
+        // Detected via stderr substring (CLI exits 1 with stable error prefix).
+        if (!result.success && result.stderr.includes('Only SELECT or WITH')) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `SQL was rejected before validation: only SELECT or WITH (CTE) statements are allowed.
+
+Project path: ${projectCwd}
+Config: ${config}
+Submitted SQL (first 100 chars): ${sqlPreview}
+
+For the assistant:
+- The validator only accepts read-only SELECT or WITH statements. Statements like INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE are rejected before any database connection is opened.
+- This is a guardrail to prevent accidental data mutation during validation.
+- Tell the user that the SQL is not a SELECT/WITH statement. Suggest revising to a SELECT statement and retry.
+- If the user actually intended to run a non-SELECT statement (e.g. data migration), this validator is the wrong tool — they should run the SQL directly via their database client. Do not attempt to bypass this check.
+- Match the user's language. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        // Branch E: Other CLI failure — real error per §3.4.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to validate the SQL.
+
+Project path: ${projectCwd}
+Config: ${config}
+Submitted SQL (first 100 chars): ${sqlPreview}
+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 SQL validation did not complete successfully.
+- Summarise the most likely cause from the CLI output in plain language. Common causes:
+  * Config file not found — suggest verifying the path and that the file exists in the project (or in cwd/config/).
+  * Database connection failed — suggest verifying the credentials, that the host is reachable, and that the port is open.
+  * Unknown command 'query:validate' — the installed RESTForge version may be older than this CLI subcommand; suggest upgrading the package (requires @restforgejs/platform >= 2.4.8).
+- 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.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Branch F: JSON parse failure — 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 the SQL validation result as JSON.
+
+Project path: ${projectCwd}
+Config: ${config}
+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 RESTForge package version is compatible (requires @restforgejs/platform >= 2.4.8). Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Defensive labeled facts: if the JSON shape changes upstream, fall back to 'unknown' / 'n/a'
+        // rather than crashing. Mirror the catalog tools pattern.
+        const root = (parsed ?? {});
+        const ok = root.ok === true;
+        const databaseType = typeof root.database === 'string' ? root.database : 'unknown';
+        const errorObj = (root.error ?? {});
+        const errorCode = typeof errorObj.code === 'string' ? errorObj.code : 'n/a';
+        const errorMessage = typeof errorObj.message === 'string' ? errorObj.message : 'n/a';
+        const errorHint = typeof errorObj.hint === 'string' ? errorObj.hint : 'n/a';
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Branch B: success — SQL valid (ok: true).
+        if (ok) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `SQL validation succeeded — the statement is syntactically and semantically valid against the live database schema.
+
+Project path: ${projectCwd}
+Config: ${config}
+Database: ${databaseType}
+ok: true
+
+--- Validation Result (JSON) ---
+${prettyJson}
+--- end Validation Result (JSON) ---
+
+For the assistant:
+- Confirm to the user that the SQL is valid. Mention the database type in plain language.
+- This is a read-only operation: it ran EXPLAIN against the database without executing the query (zero rows touched).
+- The validation only checks: syntax, column references, function existence, type compatibility, JOIN resolution. It does NOT check business semantics (e.g. whether the result shape matches a widget query key's expected shape — that is checked by the dashboard payload validator separately).
+- Match the user's language.`,
+                    },
+                ],
+            };
+        }
+        // Branch C: success — SQL invalid (ok: false). Tool ran successfully; negative validation result is normal.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `SQL validation reported an error — the statement is not valid against the live database schema.
+
+Project path: ${projectCwd}
+Config: ${config}
+Database: ${databaseType}
+ok: false
+errorCode: ${errorCode}
+errorMessage: ${errorMessage}
+errorHint: ${errorHint}
+
+--- Validation Result (JSON) ---
+${prettyJson}
+--- end Validation Result (JSON) ---
+
+For the assistant:
+- Tell the user that the SQL did not pass validation. Summarise the error in plain language.
+- Common error categories (Postgres SQLSTATE prefix):
+  * 42703 (undefined_column) — a referenced column does not exist; suggest using the table-describe action to verify column names
+  * 42702 (ambiguous_column) — column reference is ambiguous between multiple tables; suggest qualifying with table alias
+  * 42883 (undefined_function) — function does not exist or argument types do not match; check dialect-specific function names
+  * 42P01 (undefined_table) — referenced table does not exist; suggest using the table-list action
+  * 42601 (syntax_error) — SQL syntax issue
+- For MySQL/Oracle, error.code uses different conventions (MySQL ER_*/errno, Oracle ORA-XXXXX).
+- Do not paste the raw JSON unless the user explicitly asks. Do not mention internal tool names.
+- Suggest revising the SQL based on the error and re-validating.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=validate-sql.js.map

package/dist/tools/codegen/validate-sql.js.map

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

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

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

package/dist/tools/health/index.js

@@ -0,0 +1,5 @@
+import { registerHealthPing } from './ping.js';
+export function registerHealthTools(server, version) {
+    registerHealthPing(server, version);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/health/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,OAAe;IACpE,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/tools/health/ping.d.ts

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

package/dist/tools/health/ping.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export function registerHealthPing(server, version) {
+    server.registerTool('health_ping', {
+        title: 'Health Ping',
+        description: `Simple smoke test tool to verify the MCP server is up and responsive.
+Not related to RESTForge operations — purely for verifying MCP transport.
+
+USE WHEN:
+- Verifying that the MCP server itself is reachable and responsive
+- Checking if the server can receive and respond to tool calls
+- Diagnosing whether a problem is in the MCP transport layer or in a specific tool
+- The user asks things like "ping the MCP server", "is the MCP server alive",
+  "cek MCP server", "MCP server jalan tidak", "test the MCP connection",
+  "apakah MCP-nya nyala", "smoke test the server"
+
+DO NOT USE FOR:
+- Validating the RESTForge license or database connection -> use 'setup_validate_config'
+- Reading the active configuration of a project -> use 'setup_read_env'
+- Anything related to RESTForge state, configuration, or project setup
+
+This tool runs in-process: it does not touch the filesystem, network, or any RESTForge component.
+Output: "pong" with ISO 8601 timestamp and server version, plus the optional echoed message.
+
+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. "verify the MCP server is responsive", "validate the configuration").
+- Speak in plain language. Confirm that the MCP server is responsive and report the timestamp and server version.
+- Keep the reply concise; this is a smoke test, not a diagnostic dump.`,
+        inputSchema: {
+            message: z
+                .string()
+                .optional()
+                .describe('Optional message to echo back in the response'),
+        },
+        annotations: {
+            title: 'Health Ping',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ message }) => {
+        const timestamp = new Date().toISOString();
+        // Success: one-line summary + labeled facts per §3.5.
+        const facts = [
+            `Response: pong`,
+            `Timestamp: ${timestamp}`,
+            `Server version: ${version}`,
+        ];
+        if (message) {
+            facts.push(`Echo: ${message}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `MCP server is up and responsive.
+
+${facts.join('\n')}
+
+For the assistant:
+- Confirm to the user that the MCP server is reachable and report the timestamp and server version in plain language.
+- ${message ? 'The optional message was echoed back; mention it briefly if relevant.' : 'No echo message was supplied.'}
+- Keep the reply concise. Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=ping.js.map

package/dist/tools/health/ping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.js","sourceRoot":"","sources":["../../../src/tools/health/ping.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,OAAe;IACnE,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;uEAuBoD;QACjE,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,+CAA+C,CAAC;SAC7D;QACD,WAAW,EAAE;YACX,KAAK,EAAE,aAAa;YACpB,YAAY,EAAE,IAAI;YAClB,cAAc,EAAE,IAAI;SACrB;KACF,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACpB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE3C,sDAAsD;QACtD,MAAM,KAAK,GAAG;YACZ,gBAAgB;YAChB,cAAc,SAAS,EAAE;YACzB,mBAAmB,OAAO,EAAE;SAC7B,CAAC;QACF,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;QACjC,CAAC;QAED,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;EAEhB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;;;;IAId,OAAO,CAAC,CAAC,CAAC,uEAAuE,CAAC,CAAC,CAAC,+BAA+B;8DACzD;iBACnD;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/runtime/check-launcher-exists.d.ts

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

package/dist/tools/runtime/check-launcher-exists.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+const LAUNCHER_FILES = {
+    windows: {
+        start: 'server-start.bat',
+        stop: 'server-stop.bat',
+    },
+    linux: {
+        start: 'server-start.sh',
+        stop: 'server-stop.sh',
+    },
+};
+const ECOSYSTEM_FILE = 'ecosystem.config.js';
+function getLauncherFiles(os, mode) {
+    const files = [LAUNCHER_FILES[os].start, LAUNCHER_FILES[os].stop];
+    if (mode === 'pm2') {
+        files.push(ECOSYSTEM_FILE);
+    }
+    return files;
+}
+export function registerRuntimeCheckLauncherExists(server) {
+    server.registerTool('runtime_check_launcher_exists', {
+        title: 'Check Launcher File Existence',
+        description: `Check whether the launcher files that would be produced by 'runtime_generate_launcher' already exist in the project root. Read-only — does not create or overwrite anything.
+
+USE WHEN:
+- Before invoking 'runtime_generate_launcher' — to detect potential overwrites and ask the user for confirmation
+- The user wants to know which files would be created without committing
+- The user is debugging an existing setup and wants to confirm what files exist
+
+DO NOT USE FOR:
+- Generating launcher files -> use 'runtime_generate_launcher'
+- Reading the content of an existing launcher -> use generic Read tools
+- Checking if the server is currently running -> use 'runtime_check_status'
+
+The list of files depends on os + mode (file names are FIXED, not user-customisable):
+- windows + host: server-start.bat, server-stop.bat
+- windows + pm2:  server-start.bat, server-stop.bat, ecosystem.config.js
+- linux + host:   server-start.sh, server-stop.sh
+- linux + pm2:    server-start.sh, server-stop.sh, ecosystem.config.js
+
+PRESENTATION GUIDANCE:
+- Match the user's language.
+- Never mention internal tool names.
+- When at least one file already exists, ask the user whether to overwrite (then call generate with overwrite=true).
+- Do not echo the JSON unless explicitly asked.`,
+        inputSchema: {
+            cwd: z.string().min(1).describe('Absolute path of the project folder root'),
+            os: z.enum(['windows', 'linux']).describe('Target OS for the launcher'),
+            mode: z.enum(['host', 'pm2']).describe('Runtime mode'),
+        },
+        annotations: {
+            title: 'Check Launcher Files',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, os, mode }) => {
+        const projectCwd = resolve(cwd);
+        const files = getLauncherFiles(os, mode);
+        const checked = await Promise.all(files.map(async (f) => {
+            const path = join(projectCwd, f);
+            let exists = false;
+            try {
+                await access(path);
+                exists = true;
+            }
+            catch {
+                exists = false;
+            }
+            return { path, exists };
+        }));
+        const anyExists = checked.some((c) => c.exists);
+        const envelope = {
+            cwd: projectCwd,
+            os,
+            mode,
+            files: checked,
+            any_exists: anyExists,
+        };
+        const prettyJson = JSON.stringify(envelope, null, 2);
+        const summary = anyExists
+            ? 'One or more launcher files already exist in the project root.'
+            : 'No conflicting launcher files. Safe to generate.';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${summary}
+
+Project path: ${projectCwd}
+OS: ${os}
+Mode: ${mode}
+
+--- Existence Check (JSON) ---
+${prettyJson}
+--- end Existence Check (JSON) ---
+
+For the assistant:
+- ${anyExists
+                        ? 'Some files would be overwritten. Ask the user whether to overwrite (then call generate with overwrite: true).'
+                        : 'No files would be overwritten. The user can proceed to generate.'}
+- File names are fixed: server-start.{bat|sh}, server-stop.{bat|sh}, plus ecosystem.config.js for PM2 mode.
+- Match the user's language.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+//# sourceMappingURL=check-launcher-exists.js.map

package/dist/tools/runtime/check-launcher-exists.js.map

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

package/dist/tools/runtime/check-status.d.ts

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