@restforgejs/mcp-server 1.2.0

package/dist/tools/runtime/validate-preflight.js

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import { access, readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { createServer } from 'node:net';
+import { execProcess } from '../../lib/exec.js';
+async function checkPortAvailable(port) {
+    return new Promise((resolveFn) => {
+        const tester = createServer()
+            .once('error', () => resolveFn(false))
+            .once('listening', () => {
+            tester.close(() => resolveFn(true));
+        })
+            .listen(port);
+    });
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ESRCH')
+            return false;
+        if (e.code === 'EPERM')
+            return true;
+        return null;
+    }
+}
+function truncate(s, n) {
+    return s.length > n ? s.substring(0, n) + '...' : s;
+}
+export function registerRuntimeValidatePreflight(server) {
+    server.registerTool('runtime_validate_preflight', {
+        title: 'Validate RESTForge Runtime Preflight',
+        description: `Run a runtime preflight check before generating a launcher. Wraps 'npx restforge validate --config=<config>' (license + database + redis/kafka) and additionally inspects: (1) .restforge/server.pid to detect a possibly-running server, (2) optional local port availability via Node net binding.
+
+USE WHEN:
+- Before invoking 'runtime_generate_launcher' — to verify the project is ready to launch
+- The user asks "is this ready to run?", "preflight check", "cek apakah server bisa dijalankan"
+- After changing config or installing a new license — to verify everything still works
+- The user reports the server fails to start — to identify the failing component
+
+DO NOT USE FOR:
+- Validating ONLY the config (license/database) without runtime context -> use 'setup_validate_config'
+- Listing or reading config values -> use 'setup_read_env'
+- Generating launcher files -> use 'runtime_generate_launcher'
+
+This tool runs: npx restforge validate --config=<config> in the given cwd, plus filesystem checks (PID file, optional port).
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules.
+- The config file must exist in the config/ folder.
+
+PRESENTATION GUIDANCE:
+- Match the user's language.
+- Never mention internal tool names.
+- Summarise by component: license, database, optional redis/kafka, PID file presence, port availability.
+- Do not echo license keys, passwords, or full connection URIs from the CLI output.
+- Preflight failure is informational, not a blocker. The user can still proceed to generate the launcher (with a warning recorded).
+- Port check is best-effort: a "free" result on this machine does not guarantee the port is free for the eventual server bind address (which may differ).`,
+        inputSchema: {
+            cwd: z.string().min(1).describe('Absolute path of the project folder root'),
+            config: z
+                .string()
+                .min(1)
+                .default('db-connection.env')
+                .describe('Config file name in the config/ folder (default: db-connection.env)'),
+            port: z
+                .number()
+                .int()
+                .min(1)
+                .max(65535)
+                .optional()
+                .describe('Port to check availability (optional). When set, the tool tries to bind locally to detect if the port is free.'),
+        },
+        annotations: {
+            title: 'Validate Runtime Preflight',
+            readOnlyHint: true,
+            idempotentHint: false,
+        },
+    }, async ({ cwd, config, port }) => {
+        const projectCwd = resolve(cwd);
+        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 user needs to install the RESTForge package before runtime preflight can run.
+- Suggest installing the package first, then retry preflight.
+- Match the user's language. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const result = {
+            config_validation: {
+                ran: false,
+                success: false,
+                cli_command: '',
+                cli_exit_code: -1,
+                cli_stdout: '',
+                cli_stderr: '',
+            },
+            pid_file: { path: '', exists: false, pid: null, process_alive: null },
+            port_check: {
+                requested: port !== undefined,
+                port: port ?? null,
+                available: null,
+            },
+            warnings: [],
+            errors: [],
+        };
+        const cliResult = await execProcess('npx', ['restforge', 'validate', `--config=${config}`], { cwd: projectCwd, timeout: 30_000 });
+        result.config_validation = {
+            ran: true,
+            success: cliResult.success,
+            cli_command: cliResult.command,
+            cli_exit_code: cliResult.exitCode,
+            cli_stdout: truncate(cliResult.stdout || '', 500),
+            cli_stderr: truncate(cliResult.stderr || '', 500),
+        };
+        if (!cliResult.success) {
+            result.warnings.push('Config validation did not pass — see config_validation.cli_stderr for details.');
+        }
+        const pidPath = join(projectCwd, '.restforge', 'server.pid');
+        result.pid_file.path = pidPath;
+        try {
+            const raw = await readFile(pidPath, 'utf8');
+            const pid = parseInt(raw.trim(), 10);
+            result.pid_file.exists = true;
+            if (Number.isFinite(pid) && pid > 0) {
+                result.pid_file.pid = pid;
+                result.pid_file.process_alive = isProcessAlive(pid);
+                if (result.pid_file.process_alive === true) {
+                    result.warnings.push(`A server appears to be already running with PID ${pid}. Stop it first or it may conflict on the port.`);
+                }
+            }
+            else {
+                result.warnings.push('PID file exists but contains an invalid value.');
+            }
+        }
+        catch {
+            result.pid_file.exists = false;
+        }
+        if (port !== undefined) {
+            result.port_check.available = await checkPortAvailable(port);
+            if (result.port_check.available === false) {
+                result.warnings.push(`Port ${port} is already in use on this machine.`);
+            }
+        }
+        const envelope = result;
+        const prettyJson = JSON.stringify(envelope, null, 2);
+        const allPassed = result.config_validation.success && result.warnings.length === 0;
+        const summary = allPassed
+            ? 'Runtime preflight passed: config valid, no PID file conflict, port available.'
+            : 'Runtime preflight completed with warnings — see details below.';
+        const pidFileSummary = result.pid_file.exists
+            ? `exists (pid=${result.pid_file.pid}, alive=${result.pid_file.process_alive})`
+            : 'absent';
+        const portSummary = result.port_check.requested
+            ? result.port_check.available
+                ? 'yes'
+                : 'no'
+            : '(not checked)';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${summary}
+
+Project path: ${projectCwd}
+Config: ${config}
+Port checked: ${port ?? '(not requested)'}
+Config validation: ${result.config_validation.success ? 'OK' : 'FAILED'}
+PID file: ${pidFileSummary}
+Port available: ${portSummary}
+Warnings: ${result.warnings.length}
+
+--- Preflight Result (JSON) ---
+${prettyJson}
+--- end Preflight Result (JSON) ---
+
+For the assistant:
+- ${allPassed
+                        ? 'All preflight checks passed. The user can proceed to generate the launcher.'
+                        : 'Some checks reported warnings. Summarise them in plain language to the user. The user can still choose to proceed (the launcher will be generated regardless).'}
+- Config validation runs the same checks as the standalone validator: license, database connection, and any enabled feature dependencies (redis, kafka).
+- PID file check inspects .restforge/server.pid: if a process is alive, warn the user that another server may be running.
+- Port check is best-effort: it tries to bind locally to the port. A port may still be in use by another machine on the same address — this only checks the local machine.
+- Do not echo full CLI stdout/stderr unless explicitly asked. Do not echo license keys or credentials.
+- Match the user's language. Do not mention internal tool names.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+//# sourceMappingURL=validate-preflight.js.map

package/dist/tools/runtime/validate-preflight.js.map

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

package/dist/tools/setup/create-folder.d.ts

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

package/dist/tools/setup/create-folder.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { mkdir, access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+export function registerSetupCreateFolder(server) {
+    server.registerTool('setup_create_folder', {
+        title: 'Create Project Folder',
+        description: `Create a new folder to serve as the root of a RESTForge project. The folder will host node_modules (@restforgejs/platform), config/, payload/, and generated src/.
+
+USE WHEN:
+- The user wants to set up a new RESTForge project working folder
+- Starting a RESTForge project from scratch in a specific location
+- The user says things like "buat folder project baru", "create a new project folder",
+  "siapkan folder untuk project baru", "make a directory for my new RESTForge project",
+  "bikinkan project baru di folder X", "scaffold a new restforge project"
+- A safe mkdir with collision detection is needed
+
+DO NOT USE FOR:
+- Installing the @restforgejs/platform package -> use 'setup_install_package'
+- Generating skeleton config -> use 'setup_init_config'
+- Writing credentials -> use 'setup_write_env'
+
+This is typically the very first step in setting up a new RESTForge project.
+The natural next step after this is 'setup_install_package' to install the
+RESTForge package into the new folder. // per §5.2
+
+This tool runs: fs.mkdir(<parentCwd>/<folderName>, { recursive: true })
+Output: absolute path of the created folder. Pass this path as 'cwd' to subsequent setup_* tools.
+
+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", "set up the initial config").
+- Speak in plain language. Confirm the folder was created and state the absolute path.
+- When the folder already exists and force was not set, frame it as a choice or question, not as a hard error.`,
+        inputSchema: {
+            folderName: z
+                .string()
+                .min(1)
+                .regex(/^[a-zA-Z0-9_-]+$/, 'Only alphanumeric, underscore, and dash are allowed')
+                .default('backend-server')
+                .describe('Project folder name. Default: backend-server'),
+            parentCwd: z
+                .string()
+                .optional()
+                .describe('Parent directory where the folder is created. Default: process.cwd()'),
+            force: z
+                .boolean()
+                .default(false)
+                .describe('Continue even if the folder already exists (mkdir recursive remains idempotent)'),
+        },
+        annotations: {
+            title: 'Create Project Folder',
+            readOnlyHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ folderName, parentCwd, force }) => {
+        const parent = parentCwd ? resolve(parentCwd) : process.cwd();
+        const targetPath = join(parent, folderName);
+        // Pre-check: detect whether the target folder already exists.
+        let alreadyExists = false;
+        try {
+            await access(targetPath);
+            alreadyExists = true;
+        }
+        catch {
+            /* not present, OK to create */
+        }
+        // Already-exists collision (force=false): non-error precondition per §3.4.
+        if (alreadyExists && !force) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: a folder with this name already exists.
+
+Parent directory: ${parent}
+Folder name: ${folderName}
+Existing path: ${targetPath}
+
+For the assistant:
+- The user asked to create a new project folder, but one with this name already exists.
+- Offer the user a choice in plain words: pick a different folder name, reuse the existing folder (continue with force enabled, since recursive mkdir is idempotent), or cancel.
+- Do not present this as a hard error. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Real I/O failure: surface as error per §3.4.
+        try {
+            await mkdir(targetPath, { recursive: true });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to create the project folder.
+
+Parent directory: ${parent}
+Folder name: ${folderName}
+Target path: ${targetPath}
+Reason: ${msg}
+
+For the assistant:
+- Tell the user that the folder could not be created.
+- Summarise the likely cause in plain language (permissions, parent missing, disk full); do not paste the raw error unless the user explicitly asks.
+- Offer to retry once the underlying issue is resolved. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Success: one-line summary + labeled facts per §3.5.
+        const stateNote = alreadyExists
+            ? 'State: the folder already existed and was reused (force=true).'
+            : 'State: a new folder was created.';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Project folder ready.
+
+Parent directory: ${parent}
+Folder name: ${folderName}
+Absolute path: ${targetPath}
+${stateNote}
+
+For the assistant:
+- Confirm to the user that the project folder is ready and state its absolute path.
+- Suggest the next step in plain words: installing the RESTForge package into this folder so the project can be configured.
+- Pass the absolute path above as the working-directory argument for subsequent setup actions. Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=create-folder.js.map

package/dist/tools/setup/create-folder.js.map

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

package/dist/tools/setup/get-config-schema.d.ts

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

package/dist/tools/setup/get-config-schema.js

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerSetupGetConfigSchema(server) {
+    server.registerTool('setup_get_config_schema', {
+        title: 'Get Config Schema',
+        description: `Get JSON schema of all parameters available in db-connection.env template.
+Schema includes parameter name, section, type (string/integer/boolean), default value,
+description, and required status.
+
+USE WHEN:
+- The agent needs to know what parameters are configurable before writing config
+- Listing available config options for user reference
+- Building a dynamic UI or validator from the schema
+- The user asks things like "what parameters are available", "list all config options",
+  "parameter apa saja yang bisa di-set", "tampilkan schema config", "what can I configure",
+  "show me the configurable fields", "field apa saja yang valid"
+
+DO NOT USE FOR:
+- Reading actual current config values -> use 'setup_read_env'
+- Writing config -> use 'setup_write_env' or 'setup_update_env'
+- Getting raw template text -> use 'setup_get_init_template'
+
+This tool runs: npx restforge config:schema in the given cwd.
+The schema 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.3.1.
+
+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", "fill in the credentials").
+- Speak in plain language. Summarise the schema (number of parameters, sections present, key required fields); 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 have @restforgejs/platform installed in node_modules)'),
+        },
+        annotations: {
+            title: 'Get Config Schema',
+            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 schema can only be retrieved once the RESTForge package is installed locally.
+- Suggest installing the package first, then retry getting the schema.
+- 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
+        const result = await execProcess('npx', ['restforge', 'config', 'schema'], {
+            cwd: projectCwd,
+            timeout: 15_000,
+            env: { NODE_ENV: 'production' },
+        });
+        // CLI failure: real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve the configuration schema.
+
+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 schema could not be retrieved.
+- A common cause is an older RESTForge version that does not yet expose the schema command (requires @restforgejs/platform >= 2.3.1). 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 the schema JSON returned by the CLI.
+
+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.3.1). Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Re-stringify for consistent pretty formatting
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Success: one-line summary + labeled facts + fenced JSON output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Configuration schema retrieved successfully.
+
+Project path: ${projectCwd}
+Source: restforge (single source of truth for the installed runtime version)
+
+--- Schema (JSON) ---
+${prettyJson}
+--- end Schema (JSON) ---
+
+For the assistant:
+- Confirm to the user that the schema is available.
+- Summarise in plain language: how many parameters there are, which sections are present (e.g. database, license, optional Live Sync / Redis / Kafka / Logging), and which fields are required.
+- Do not paste the full JSON block unless the user explicitly asks for it. Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=get-config-schema.js.map

package/dist/tools/setup/get-config-schema.js.map

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

package/dist/tools/setup/get-init-template.d.ts

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