@restforgejs/mcp-server 1.2.0 → 1.2.2

package/dist/tools/designer/validate-payload.js

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { resolve } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerDesignerValidatePayload(server) {
+    server.registerTool('designer_validate_payload', {
+        title: 'Validate Designer Payload',
+        description: `Validate a frontend UI Definition File (UDF) payload against the schema of the RESTForge Designer plugin it targets, by running restforge-designer validate.
+
+USE WHEN:
+- The user asks to validate, check, or verify a frontend designer payload / UI definition (UDF) file
+- The user asks things like "validasi UDF", "cek payload frontend", "is this UI definition valid", "validate designer payload", "apakah payload UDF benar", "check the frontend payload against the plugin schema"
+- Before previewing or generating frontend code from a UDF, to confirm the payload is structurally valid against the plugin schema
+- The user mentions a designer/frontend payload JSON and wants to know whether it conforms to the plugin it targets
+- Routine pre-generation sanity check on a UDF file
+
+DO NOT USE FOR:
+- Validating a backend RDF payload against the database schema -> use 'codegen_validate_payload'
+- Validating an SDF (database schema definition) -> use 'codegen_dbschema_validate'
+- Validating raw SQL -> use 'codegen_validate_sql'
+- Generating the frontend code itself (this only validates, it does not write files)
+
+This tool wraps the RESTForge Designer CLI command: restforge-designer validate --payload=<payload> [--plugins-dir=<pluginsDir>], run in the given cwd.
+The CLI reads the UDF payload JSON, resolves the target plugin (auto-detected or from --plugins-dir), and reports whether
+the payload is valid against that plugin's schema, listing structural errors when it is not. It does not modify any file and
+does not require a license.
+
+Preconditions:
+- The 'restforge-designer' binary must be installed and reachable on PATH. This tool pre-checks that by running
+  'restforge-designer --version'; if the binary is missing, the response will surface that as a non-error precondition.
+
+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 UI definition", "preview the generated files", "generate the frontend code").
+- Speak in plain language. Summarise the result; 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 working directory where the binary is run'),
+            payload: z
+                .string()
+                .min(1)
+                .describe('Path to the UDF payload JSON file (relative to cwd or absolute)'),
+            pluginsDir: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Override path to the plugins folder. When omitted, the binary auto-detects the plugins directory.'),
+        },
+        annotations: {
+            title: 'Validate Designer Payload',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, payload, pluginsDir }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: the restforge-designer binary must be reachable on PATH.
+        // Treated as a non-error precondition per the authoring guide §3.4. The probe
+        // distinguishes "binary missing" (precondition) from "binary ran and reported
+        // something" (which falls through to the real execution below).
+        const probe = await execProcess('restforge-designer', ['--version'], {
+            cwd: projectCwd,
+            timeout: 10_000,
+        });
+        if (!probe.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge Designer command-line tool is not installed or not on PATH.
+
+Working directory: ${projectCwd}
+Payload: ${payload}
+Plugins dir: ${pluginsDir ?? 'auto-detect'}
+Probe command: ${probe.command}
+Exit code: ${probe.exitCode}
+
+For the assistant:
+- The user needs to install RESTForge Designer (and ensure it is on the system PATH) before a frontend payload can be validated.
+- When explaining to the user, say something like "the RESTForge Designer tool isn't installed or isn't on your PATH yet — please install it and try again". Do not mention internal tool names.
+- Once it is installed, retry validating the payload.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Forward only the arguments the user supplied. The plugins directory is
+        // auto-detected by the binary when --plugins-dir is omitted. per §3.5
+        const args = ['validate', `--payload=${payload}`];
+        if (pluginsDir)
+            args.push(`--plugins-dir=${pluginsDir}`);
+        const result = await execProcess('restforge-designer', args, {
+            cwd: projectCwd,
+            timeout: 30_000,
+        });
+        // D7: this is a read-only tool. The pre-flight already confirmed the binary
+        // spawns, so an unexpected crash/timeout (no real exit code -> -1) is the only
+        // real error here -> isError: true. Any genuine exit code is a verdict to relay.
+        if (result.exitCode === -1) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Designer payload validation did not complete — the command crashed or timed out.
+
+Working directory: ${projectCwd}
+Payload: ${payload}
+Plugins dir: ${pluginsDir ?? 'auto-detect'}
+Command: ${result.command}
+
+--- stderr ---
+${result.stderr}
+--- end stderr ---
+
+For the assistant:
+- The Designer CLI did not finish (likely a crash or timeout), so there is no validation verdict to report.
+- Tell the user the check could not be completed and offer to retry. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4 — unexpected crash/timeout
+            };
+        }
+        // D7: single response for ANY real exit code (success branch no longer split on
+        // result.success). A non-zero exit means the CLI reported an actionable negative
+        // verdict (invalid payload, plugin/file not found), which is a legitimate result
+        // to relay — NOT a tool failure. The model classifies from the fenced output.
+        const stderrBlock = result.stderr
+            ? `\n--- stderr ---\n${result.stderr}\n--- end stderr ---\n`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Designer payload validation ran.
+
+Working directory: ${projectCwd}
+Payload: ${payload}
+Plugins dir: ${pluginsDir ?? 'auto-detect'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- stdout ---
+${result.stdout}
+--- end stdout ---
+${stderrBlock}
+For the assistant:
+- The Designer CLI ran to completion. Read the CLI output above and classify the result:
+  (a) Positive result — the payload is VALID against the target plugin schema. Confirm this in plain language and suggest the next step: preview the files that would be generated from this payload, or generate the frontend code. Describe steps by what they do.
+  (b) Actionable negative verdict — the payload is INVALID (the output lists structural errors), or the payload file was not found, or the target plugin / plugins directory could not be resolved. These are legitimate results to RELAY to the user, not tool malfunctions. Summarise the concrete problems (which fields, components, or paths are wrong) and offer to re-check after the user fixes them.
+- A non-zero exit code here means the CLI reported a negative verdict (case b), NOT that the tool failed. Never tell the user "the tool failed" for case (b).
+- Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names. Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=validate-payload.js.map

package/dist/tools/designer/validate-payload.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@restforgejs/mcp-server",
-  "version": "1.2.0",
-  "description": "MCP server for RESTForge - enables AI agents to interact with RESTForge via natural language",
+  "version": "1.2.2",
+  "description": "RESTForge MCP Server — Model Context Protocol server that exposes RESTForge Platform commands to AI agents (Claude Desktop, Cursor, Claude CLI, and other MCP clients). Orchestrates project setup, code generation, and runtime launch via natural language. A thin orchestrator for the RESTForge Platform CLI, not a generic MCP framework or API testing tool.",
   "type": "module",
   "bin": {
     "restforge-mcp": "./dist/index.js"