@restforgejs/mcp-server 1.2.0

package/dist/tools/runtime/detect-project.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { readdir } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+export function registerRuntimeDetectProject(server) {
+    server.registerTool('runtime_detect_project', {
+        title: 'Detect RESTForge Project Names',
+        description: `Detect RESTForge project names by scanning the conventional 'src/modules/' folder. Each .js file in that folder represents one RESTForge project; the filename without extension is the project name.
+
+USE WHEN:
+- The user asks "which projects are available?", "what RESTForge projects are in this folder?", "list project saya"
+- Before generating a launcher script — to confirm the project name to pass as --project=<name>
+- Before invoking 'runtime_generate_launcher' — to determine whether the user must specify a project name or one can be auto-detected
+- The user requests to run the server but the project name is unknown or ambiguous
+
+DO NOT USE FOR:
+- Listing config files -> use 'runtime_detect_config'
+- Listing payload spec files -> use generic Read or filesystem tools
+- Listing database tables -> use 'codegen_list_tables'
+- Validating runtime preflight -> use 'runtime_validate_preflight'
+
+Preconditions:
+- The 'src/modules/' folder must exist at <cwd>/src/modules/. If missing, the precondition response will say so.
+
+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.
+- When exactly one project is found, proceed without asking. When multiple are found, ask the user to pick one before generating the launcher.
+- The project name comes from the filename in src/modules/ (without the .js extension); explain this in plain language if asked.
+- When a precondition is not met (folder missing), 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 root (must contain src/modules/)'),
+        },
+        annotations: {
+            title: 'Detect Project Names',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd }) => {
+        const projectCwd = resolve(cwd);
+        const modulesDir = join(projectCwd, 'src', 'modules');
+        let entries;
+        try {
+            entries = await readdir(modulesDir);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the modules folder does not exist.
+
+Project path: ${projectCwd}
+Expected folder: ${modulesDir}
+
+For the assistant:
+- The user is trying to detect RESTForge projects, but the conventional location 'src/modules/' is missing in this directory.
+- Suggest verifying that the user is at the correct project root, or ask the user where the project files are located.
+- Match the user's language. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const projects = entries
+            .filter((name) => name.endsWith('.js'))
+            .map((name) => name.replace(/\.js$/, ''));
+        const envelope = {
+            cwd: projectCwd,
+            modules_dir: modulesDir,
+            projects,
+            count: projects.length,
+        };
+        const prettyJson = JSON.stringify(envelope, null, 2);
+        if (projects.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No RESTForge project files were found in src/modules/.
+
+Project path: ${projectCwd}
+Modules folder: ${modulesDir}
+Count: 0
+
+--- Detection Result (JSON) ---
+${prettyJson}
+--- end Detection Result (JSON) ---
+
+For the assistant:
+- The src/modules/ folder exists but contains no .js files.
+- A RESTForge project is conventionally a single .js file inside src/modules/ (e.g. mini-inventory.js -> project name 'mini-inventory').
+- Suggest the user creates a project file there first, or verify they are at the right project root.
+- Match the user's language. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const isSingle = projects.length === 1;
+        const summary = isSingle
+            ? `One RESTForge project detected: '${projects[0]}'.`
+            : `${projects.length} RESTForge projects detected: ${projects.map((p) => `'${p}'`).join(', ')}.`;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${summary}
+
+Project path: ${projectCwd}
+Modules folder: ${modulesDir}
+Count: ${projects.length}
+
+--- Detection Result (JSON) ---
+${prettyJson}
+--- end Detection Result (JSON) ---
+
+For the assistant:
+- ${isSingle
+                        ? `Only one project was found, so the runtime can use '${projects[0]}' without further input.`
+                        : `Multiple projects were found. Ask the user which one to launch before proceeding.`}
+- The project name comes from the filename in src/modules/ (without the .js extension). It is the value passed as --project=<name> when invoking the RESTForge runtime.
+- Match the user's language. Do not mention internal tool names.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+//# sourceMappingURL=detect-project.js.map

package/dist/tools/runtime/detect-project.js.map

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

package/dist/tools/runtime/generate-launcher.d.ts

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

package/dist/tools/runtime/generate-launcher.js

@@ -0,0 +1,438 @@
+import { z } from 'zod';
+import { access, writeFile, stat } 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';
+const TEMPLATE_WINDOWS_HOST_START = `@echo off
+REM RESTForge Server Launcher
+REM Generated by restforge-mcp
+REM Project: {{PROJECT}}
+REM Config:  {{CONFIG}}
+REM Port:    {{PORT}}
+
+echo Starting RESTForge Server...
+echo Project: {{PROJECT}}
+echo Config:  {{CONFIG}}
+echo Port:    {{PORT}}
+echo.
+echo To stop: press Ctrl+C in this window, or run server-stop.bat in another terminal.
+echo.
+
+npx restforge --project={{PROJECT}} --port={{PORT}} --config={{CONFIG}}{{EXTRA_ARGS_SH}}
+`;
+const TEMPLATE_WINDOWS_HOST_STOP = `@echo off
+REM RESTForge Server Stopper
+REM Generated by restforge-mcp
+
+set PORT={{PORT}}
+echo Stopping RESTForge Server on port %PORT%...
+
+set FOUND=0
+for /f "tokens=5" %%a in ('netstat -ano ^| findstr :%PORT% ^| findstr LISTENING') do (
+    echo Killing PID %%a
+    taskkill /F /PID %%a /T
+    set FOUND=1
+    goto :done
+)
+
+:done
+if "%FOUND%"=="0" (
+    echo No process found listening on port %PORT%.
+    exit /b 1
+)
+`;
+const TEMPLATE_LINUX_HOST_START = `#!/bin/bash
+# RESTForge Server Launcher
+# Generated by restforge-mcp
+# Project: {{PROJECT}}
+# Config:  {{CONFIG}}
+# Port:    {{PORT}}
+
+echo "Starting RESTForge Server..."
+echo "Project: {{PROJECT}}"
+echo "Config:  {{CONFIG}}"
+echo "Port:    {{PORT}}"
+echo ""
+echo "To stop: press Ctrl+C, or run ./server-stop.sh in another terminal."
+echo ""
+
+exec npx restforge --project={{PROJECT}} --port={{PORT}} --config={{CONFIG}}{{EXTRA_ARGS_SH}}
+`;
+const TEMPLATE_LINUX_HOST_STOP = `#!/bin/bash
+# RESTForge Server Stopper
+# Generated by restforge-mcp
+
+PORT={{PORT}}
+echo "Stopping RESTForge Server on port $PORT..."
+
+PID=""
+if command -v lsof >/dev/null 2>&1; then
+    PID=$(lsof -ti:$PORT 2>/dev/null | head -1)
+fi
+if [ -z "$PID" ] && command -v fuser >/dev/null 2>&1; then
+    PID=$(fuser \${PORT}/tcp 2>/dev/null | awk '{print $1}')
+fi
+
+if [ -z "$PID" ]; then
+    echo "No process found listening on port $PORT."
+    exit 1
+fi
+
+echo "Killing PID $PID..."
+kill -TERM "$PID" 2>/dev/null
+sleep 1
+if kill -0 "$PID" 2>/dev/null; then
+    kill -KILL "$PID" 2>/dev/null
+fi
+echo "Done."
+`;
+const TEMPLATE_PM2_ECOSYSTEM = `// ============================================================
+// PM2 Ecosystem Configuration — {{PROJECT}}
+// Generated by restforge-mcp
+// ============================================================
+// Usage:
+//   pm2 start ecosystem.config.js
+//   pm2 restart {{PROJECT}}
+//   pm2 stop {{PROJECT}}
+//   pm2 delete {{PROJECT}}
+// ============================================================
+
+module.exports = {
+  apps: [
+    {
+      name: '{{PROJECT}}',
+      script: './node_modules/@restforgejs/platform/server.js',
+      args: '--project={{PROJECT}} --port={{PORT}} --config={{CONFIG}}{{EXTRA_ARGS_SH}}',
+      cwd: __dirname,
+
+      // Process
+      exec_mode: 'fork',
+      instances: 1,
+      autorestart: true,
+      watch: false,
+      kill_timeout: 5000,
+
+      // Memory
+      max_memory_restart: '512M',
+      exp_backoff_restart_delay: 100,
+
+      // Environment
+      env: {
+        NODE_ENV: 'production',
+      },
+
+      // Logging
+      log_date_format: 'YYYY-MM-DD HH:mm:ss',
+      error_file: './logs/pm2-error.log',
+      out_file: './logs/pm2-out.log',
+      merge_logs: true,
+    },
+  ],
+};
+`;
+const TEMPLATE_WINDOWS_PM2_START = `@echo off
+REM RESTForge Server Launcher (PM2 Mode)
+REM Generated by restforge-mcp
+
+if not exist logs mkdir logs
+
+pm2 start ecosystem.config.js
+pm2 save
+
+echo Server started under PM2. Run "pm2 logs {{PROJECT}}" to see logs.
+echo To stop: run server-stop.bat
+`;
+const TEMPLATE_WINDOWS_PM2_STOP = `@echo off
+REM RESTForge Server Stopper (PM2 Mode)
+pm2 stop ecosystem.config.js
+pm2 delete ecosystem.config.js
+`;
+const TEMPLATE_LINUX_PM2_START = `#!/bin/bash
+# RESTForge Server Launcher (PM2 Mode)
+# Generated by restforge-mcp
+
+mkdir -p logs
+
+pm2 start ecosystem.config.js
+pm2 save
+
+echo "Server started under PM2. Run 'pm2 logs {{PROJECT}}' to see logs."
+echo "To stop: run ./server-stop.sh"
+`;
+const TEMPLATE_LINUX_PM2_STOP = `#!/bin/bash
+# RESTForge Server Stopper (PM2 Mode)
+pm2 stop ecosystem.config.js
+pm2 delete ecosystem.config.js
+`;
+function buildExtraArgs(opts) {
+    const parts = [];
+    if (opts.cluster) {
+        parts.push('--cluster');
+    }
+    else if (opts.workers !== undefined) {
+        parts.push(`--workers=${opts.workers}`);
+    }
+    if (opts.watch) {
+        parts.push('--watch');
+    }
+    return parts.length > 0 ? ' ' + parts.join(' ') : '';
+}
+function applyTemplate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+export function registerRuntimeGenerateLauncher(server) {
+    server.registerTool('runtime_generate_launcher', {
+        title: 'Generate RESTForge Launcher Script',
+        description: `Generate a launcher script for the RESTForge Server in the project root. This tool does NOT run the server — it produces a .bat or .sh script that the user must execute themselves. This is intentional: a server launched by the AI session would terminate when the session ends; a script executed by the user lives in the user's terminal/session and persists independently.
+
+Files produced (depending on os + mode) — file names are FIXED, not user-customisable:
+- windows + host: server-start.bat, server-stop.bat
+- windows + pm2:  server-start.bat (calls 'pm2 start ecosystem.config.js'), server-stop.bat, ecosystem.config.js
+- linux + host:   server-start.sh, server-stop.sh
+- linux + pm2:    server-start.sh (calls 'pm2 start ecosystem.config.js'), server-stop.sh, ecosystem.config.js
+
+For host mode the start script runs 'npx restforge ...' in the foreground (or 'exec' on Linux). The stop script kills the process by port via netstat/taskkill on Windows or lsof/fuser+kill on Linux — no PID file is required. For PM2 mode the ecosystem points 'script' directly at './node_modules/@restforgejs/platform/server.js' to bypass the npx shim and avoid PM2's default node interpreter mis-parsing a .cmd file.
+
+USE WHEN:
+- The user asks "run the server", "jalankan server", "start RESTForge"
+- After confirming OS, mode, project, config, and port with the user (typically via 'runtime_detect_project', 'runtime_detect_config', and direct questions)
+- After 'runtime_check_launcher_exists' returned no conflicts, OR the user confirmed overwrite
+
+DO NOT USE FOR:
+- Actually starting or stopping the server -> the user runs the generated script themselves
+- Modifying database schema or payload files -> out of scope
+- Running one-off commands -> out of scope; this tool is launcher-scaffolding only
+
+Preconditions:
+- The cwd must exist.
+- 'cluster' and 'workers' are mutually exclusive.
+- 'watch' is not allowed with mode=pm2.
+
+PRESENTATION GUIDANCE:
+- Match the user's language.
+- Never mention internal tool names. Refer to the produced files by their visible names (e.g. 'server-start.bat').
+- Tell the user clearly that the AI does NOT execute the script — they must run it themselves so the server keeps running after the AI session ends.
+- For PM2 mode: warn the user that PM2 must be installed globally first (npm install -g pm2). Do not auto-install.
+- After generation, summarise: location, files produced, how to start, how to stop. Do not paste the JSON envelope unless explicitly asked.
+- If the user asks for a different mode (Windows Service, Docker, systemd) — those are out of scope V1; suggest using host or pm2 instead.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder root (output goes here)'),
+            os: z
+                .enum(['windows', 'linux'])
+                .describe('Target OS: windows produces .bat, linux produces .sh'),
+            mode: z
+                .enum(['host', 'pm2'])
+                .describe('Runtime mode: host runs npx restforge directly; pm2 uses ecosystem.config.js'),
+            project: z
+                .string()
+                .min(1)
+                .describe('Project name (filename in src/modules/ without .js). Passed as --project=<name>'),
+            config: z
+                .string()
+                .min(1)
+                .describe('Config file name in config/ folder (e.g. db-connection.env). Passed as --config=<filename>'),
+            port: z.number().int().min(1).max(65535).describe('Server port'),
+            overwrite: z
+                .boolean()
+                .default(false)
+                .describe('If true, overwrite existing files. If false, skip existing.'),
+            cluster: z
+                .boolean()
+                .optional()
+                .describe('If true, append --cluster flag. Mutually exclusive with workers.'),
+            workers: z
+                .number()
+                .int()
+                .min(1)
+                .max(64)
+                .optional()
+                .describe('If set, append --workers=N flag. Mutually exclusive with cluster.'),
+            watch: z
+                .boolean()
+                .optional()
+                .describe('If true, append --watch flag. Not allowed with mode=pm2 (PM2 has its own watch via ecosystem).'),
+        },
+        annotations: {
+            title: 'Generate Launcher Script',
+            readOnlyHint: false,
+            idempotentHint: false,
+            destructiveHint: true,
+        },
+    }, async (input) => {
+        const { cwd, os, mode, project, config, port, overwrite, cluster, workers, watch } = input;
+        if (cluster && workers !== undefined) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Conflicting options: 'cluster' and 'workers' cannot both be set.
+
+For the assistant:
+- Ask the user to pick one. Cluster auto-detects CPU count; workers=N is explicit.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        if (mode === 'pm2' && watch) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Conflicting options: 'watch' is not allowed when mode=pm2 (PM2 manages watch internally via ecosystem.config.js).
+
+For the assistant:
+- Suggest setting watch only with mode=host.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const projectCwd = resolve(cwd);
+        try {
+            await access(projectCwd);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: cwd does not exist: ${projectCwd}
+
+For the assistant:
+- The target folder is missing. Suggest creating it first or verifying the path.
+- Match the user's language. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const extra = buildExtraArgs({ cluster, workers, watch });
+        const vars = {
+            PROJECT: project,
+            CONFIG: config,
+            PORT: String(port),
+            EXTRA_ARGS_SH: extra,
+        };
+        const startFile = LAUNCHER_FILES[os].start;
+        const stopFile = LAUNCHER_FILES[os].stop;
+        const filesToWrite = [];
+        if (os === 'windows' && mode === 'host') {
+            filesToWrite.push({ fileName: startFile, content: applyTemplate(TEMPLATE_WINDOWS_HOST_START, vars) }, { fileName: stopFile, content: applyTemplate(TEMPLATE_WINDOWS_HOST_STOP, vars) });
+        }
+        else if (os === 'windows' && mode === 'pm2') {
+            filesToWrite.push({ fileName: startFile, content: applyTemplate(TEMPLATE_WINDOWS_PM2_START, vars) }, { fileName: stopFile, content: applyTemplate(TEMPLATE_WINDOWS_PM2_STOP, vars) }, { fileName: ECOSYSTEM_FILE, content: applyTemplate(TEMPLATE_PM2_ECOSYSTEM, vars) });
+        }
+        else if (os === 'linux' && mode === 'host') {
+            filesToWrite.push({ fileName: startFile, content: applyTemplate(TEMPLATE_LINUX_HOST_START, vars) }, { fileName: stopFile, content: applyTemplate(TEMPLATE_LINUX_HOST_STOP, vars) });
+        }
+        else if (os === 'linux' && mode === 'pm2') {
+            filesToWrite.push({ fileName: startFile, content: applyTemplate(TEMPLATE_LINUX_PM2_START, vars) }, { fileName: stopFile, content: applyTemplate(TEMPLATE_LINUX_PM2_STOP, vars) }, { fileName: ECOSYSTEM_FILE, content: applyTemplate(TEMPLATE_PM2_ECOSYSTEM, vars) });
+        }
+        const generated = [];
+        const skipped = [];
+        for (const f of filesToWrite) {
+            const fullPath = join(projectCwd, f.fileName);
+            let existed = false;
+            try {
+                await stat(fullPath);
+                existed = true;
+            }
+            catch {
+                existed = false;
+            }
+            if (existed && !overwrite) {
+                skipped.push({ path: fullPath, reason: 'already exists, overwrite=false' });
+                continue;
+            }
+            try {
+                await writeFile(fullPath, f.content, 'utf8');
+                generated.push({
+                    path: fullPath,
+                    size_bytes: Buffer.byteLength(f.content, 'utf8'),
+                    overwritten: existed,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: 'text', text: `Failed to write ${fullPath}: ${msg}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        const pm2Warning = mode === 'pm2'
+            ? 'PM2 must be installed globally on the user machine (npm install -g pm2). This tool does not auto-install. If PM2 is missing, the launcher will fail at runtime.'
+            : null;
+        const stopMethod = mode === 'pm2'
+            ? `pm2 stop ecosystem.config.js (invoked by ${stopFile})`
+            : `kill the process listening on port ${port} (invoked by ${stopFile})`;
+        const envelope = {
+            cwd: projectCwd,
+            os,
+            mode,
+            project,
+            config,
+            port,
+            generated_files: generated,
+            skipped_files: skipped,
+            stop_method: stopMethod,
+            pm2_warning: pm2Warning,
+        };
+        const prettyJson = JSON.stringify(envelope, null, 2);
+        const summary = generated.length === filesToWrite.length
+            ? `Generated ${generated.length} launcher file${generated.length === 1 ? '' : 's'}.`
+            : `Generated ${generated.length}; skipped ${skipped.length} (already exist, overwrite=false).`;
+        const startCommand = os === 'windows' ? `.\\${startFile}` : `./${startFile}`;
+        const stopCommand = os === 'windows' ? stopFile : `./${stopFile}`;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${summary}
+
+Project path: ${projectCwd}
+OS: ${os}
+Mode: ${mode}
+Project: ${project}
+Config: ${config}
+Port: ${port}
+Generated: ${generated.length}
+Skipped: ${skipped.length}
+PM2 warning: ${pm2Warning ?? 'n/a'}
+
+--- Generation Result (JSON) ---
+${prettyJson}
+--- end Generation Result (JSON) ---
+
+For the assistant:
+- ${generated.length > 0
+                        ? `Tell the user the launcher was generated at the project root. To start: ${startCommand}. To stop: ${stopCommand}.`
+                        : `Nothing was generated because all files already exist and overwrite=false. Ask the user whether to overwrite (call again with overwrite=true) or pick a different base name.`}
+- ${pm2Warning
+                        ? `Warn the user that PM2 must be installed globally on their machine before running the launcher.`
+                        : ``}
+- The server will run in the user's terminal — when launched manually, the process belongs to the user's session, NOT to this AI session.
+- For host mode the stop script kills the process listening on port ${port} (cross-platform port-based lookup). For PM2 mode the stop script delegates to pm2.
+- Match the user's language. Do not mention internal tool names.`,
+                },
+            ],
+            isError: false,
+        };
+    });
+}
+//# sourceMappingURL=generate-launcher.js.map

package/dist/tools/runtime/generate-launcher.js.map

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

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

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

package/dist/tools/runtime/index.js

@@ -0,0 +1,15 @@
+import { registerRuntimeDetectProject } from './detect-project.js';
+import { registerRuntimeDetectConfig } from './detect-config.js';
+import { registerRuntimeValidatePreflight } from './validate-preflight.js';
+import { registerRuntimeCheckLauncherExists } from './check-launcher-exists.js';
+import { registerRuntimeGenerateLauncher } from './generate-launcher.js';
+import { registerRuntimeCheckStatus } from './check-status.js';
+export function registerRuntimeTools(server) {
+    registerRuntimeDetectProject(server);
+    registerRuntimeDetectConfig(server);
+    registerRuntimeValidatePreflight(server);
+    registerRuntimeCheckLauncherExists(server);
+    registerRuntimeGenerateLauncher(server);
+    registerRuntimeCheckStatus(server);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/runtime/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,kCAAkC,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAE/D,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACrC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IACpC,gCAAgC,CAAC,MAAM,CAAC,CAAC;IACzC,kCAAkC,CAAC,MAAM,CAAC,CAAC;IAC3C,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACxC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/tools/runtime/validate-preflight.d.ts

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