@restforgejs/mcp-server 1.2.1 → 1.2.3

package/dist/tools/designer/get-udf-catalog.js

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+import { resolve } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerDesignerGetUdfCatalog(server) {
+    server.registerTool('designer_get_udf_catalog', {
+        title: 'Get UDF Catalog',
+        description: `Get the authoritative JSON catalog of RESTForge Designer UDF structure and rules (valid field types, editor modes, badge colors, id-generation options, navigation item types/depth limits, required appConfig fields, port range, number format, and dashboard widget/chart/data-source options), by running restforge-designer catalog. The catalog is serialized from the designer's own validator constants (single source of truth), so it stays in sync with the installed designer version and never drifts.
+
+USE WHEN:
+- Before composing or editing a UDF payload — to ground valid field types and required fields against the designer's own rules
+- The user asks things like "tipe field UDF apa yang valid", "valid UDF field types", "struktur appConfig", "required appConfig fields", "aturan UDF designer", "enum UDF", "what badge colors are allowed", "apa yang boleh di dashboard widget", "which dashboard widgets/charts are available", "show me the UDF catalog"
+- 'designer_validate_payload' rejects a UDF payload and you need the authoritative shape (allowed enum values, required fields) to fix it
+- The user wants the catalog of dashboard widget types, chart engines, or data source methods for a designer UDF
+
+DO NOT USE FOR:
+- Validating a concrete UDF payload against a plugin -> use 'designer_validate_payload'
+- Reading the identity/metadata or schema of ONE specific plugin -> use 'designer_inspect_plugin'
+- Listing available designer plugins -> use 'designer_list_plugins'
+- The BACKEND field validation catalog (RDF payload fieldValidation constraints, data types, format presets) -> use 'codegen_get_field_validation_catalog'
+
+This tool wraps the RESTForge Designer CLI command: restforge-designer catalog [--section=<fields|navigation|app-config|dashboard|all>], run in the given cwd.
+The catalog is a static constant (it does not depend on cwd) and the command 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 surfaces that as a non-error precondition.
+- The installed designer must be recent enough to support the 'catalog' command. Older designer builds do not have it; in
+  that case the response surfaces a non-error precondition suggesting the designer be updated.
+
+Cross-reference (read-before-write):
+- Call this tool BEFORE authoring or editing a UDF payload, and before generating frontend code, to ground the payload shape against the designer's own rules.
+
+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. "look up the UDF rules", "validate the payload", "generate the frontend code").
+- Speak in plain language. Summarise the catalog (e.g. how many valid field types, which sections are present); do not paste the entire JSON unless the user explicitly asks for it.
+- When a precondition is not met (binary missing, or too old to support the catalog), frame it as a question or next-step suggestion rather than an error.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Working directory where the binary is run. The catalog does not depend on cwd (it is a static constant); defaults to the process cwd when omitted.'),
+            section: z
+                .enum(['fields', 'navigation', 'app-config', 'dashboard', 'all'])
+                .optional()
+                .describe('Which slice of the catalog to return. The binary defaults to "all" when omitted (forward-only: not sent unless supplied).'),
+        },
+        annotations: {
+            title: 'Get UDF Catalog',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, section }) => {
+        const resolvedCwd = cwd ? resolve(cwd) : process.cwd();
+        // Precondition check: the restforge-designer binary must be reachable on PATH.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        const probe = await execProcess('restforge-designer', ['--version'], {
+            cwd: resolvedCwd,
+            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: ${resolvedCwd}
+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 the UDF catalog can be retrieved.
+- 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 getting the catalog.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Forward only the arguments the user supplied (forward-only per §3.5 / D6).
+        const args = ['catalog'];
+        if (section)
+            args.push(`--section=${section}`);
+        const result = await execProcess('restforge-designer', args, {
+            cwd: resolvedCwd,
+            timeout: 15_000,
+        });
+        // Branch 1 — binary too old: the 'catalog' subcommand does not exist yet.
+        // Best-effort detection: a failed run whose output carries clap's
+        // "unrecognized subcommand" error. Mapped to a NON-error precondition
+        // (binary needs updating), per the campaign note and §3.4.
+        const combinedOutput = `${result.stderr}\n${result.stdout}`.toLowerCase();
+        if (!result.success && combinedOutput.includes('unrecognized subcommand')) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the installed RESTForge Designer does not support the UDF catalog yet.
+
+Working directory: ${resolvedCwd}
+Installed version: ${probe.stdout.trim() || 'unknown'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+For the assistant:
+- The installed RESTForge Designer is too old: it does not recognize the catalog command.
+- When explaining to the user, say something like "your RESTForge Designer is an older version that doesn't expose the UDF catalog yet — please update RESTForge Designer to the latest version and try again". Do not mention internal tool names.
+- Once it is updated, retry getting the catalog.`,
+                    },
+                ],
+                isError: false, // non-error precondition: binary needs updating
+            };
+        }
+        // Branch — unexpected crash/timeout: no real exit code (-1). Pre-flight
+        // already confirmed the binary spawns, so this is a real failure per §3.4.
+        if (result.exitCode === -1) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Getting the UDF catalog did not complete — the command crashed or timed out.
+
+Working directory: ${resolvedCwd}
+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 catalog to report.
+- Tell the user the catalog could not be retrieved and offer to retry. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4 — unexpected crash/timeout
+            };
+        }
+        // Branch 3 — other non-zero exit: the binary recognizes 'catalog' but failed
+        // for another reason. Read-only relay per D7 (isError:false), guide the model
+        // to read the output.
+        if (!result.success) {
+            const stderrBlock = result.stderr
+                ? `\n--- stderr ---\n${result.stderr}\n--- end stderr ---\n`
+                : '';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Getting the UDF catalog ran but reported a non-zero exit.
+
+Working directory: ${resolvedCwd}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- stdout ---
+${result.stdout}
+--- end stdout ---
+${stderrBlock}
+For the assistant:
+- The Designer CLI ran to completion but returned a non-zero exit. Read the output above and relay the situation to the user; this is a verdict to convey, not a tool malfunction.
+- Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names. Match the user's language.`,
+                    },
+                ],
+                isError: false, // read-only relay per D7
+            };
+        }
+        // Branch 2 — success: pass the catalog JSON through untouched, with grounding
+        // guidance for the assistant. We do not reshape or interpret the catalog.
+        let parsed = null;
+        let prettyJson = result.stdout;
+        let catalogVersion = 'unknown';
+        let sectionsLabel = section ?? 'all';
+        try {
+            parsed = JSON.parse(result.stdout);
+            prettyJson = JSON.stringify(parsed, null, 2);
+            const root = (parsed ?? {});
+            if (typeof root.udfCatalogVersion === 'number' || typeof root.udfCatalogVersion === 'string') {
+                catalogVersion = root.udfCatalogVersion;
+            }
+            // When no --section was supplied, the binary returns the full catalog; surface
+            // which top-level sections are present (excluding the version marker).
+            if (!section) {
+                const keys = Object.keys(root).filter((k) => k !== 'udfCatalogVersion');
+                if (keys.length > 0)
+                    sectionsLabel = keys.join(', ');
+            }
+        }
+        catch {
+            // Success exit but unparseable output: relay raw stdout rather than hard-fail
+            // (read-only designer tool, D7). The fenced block below carries the raw text.
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `UDF catalog retrieved successfully.
+
+Working directory: ${resolvedCwd}
+Source: restforge-designer (serialized from validator constants) — single source of truth for the installed designer version
+Installed version: ${probe.stdout.trim() || 'unknown'}
+udfCatalogVersion: ${catalogVersion}
+Section(s): ${sectionsLabel}
+
+--- UDF Catalog (JSON) ---
+${prettyJson}
+--- end UDF Catalog (JSON) ---
+
+For the assistant:
+- Confirm to the user that the catalog is available. Summarise in plain language (e.g. how many valid field types, which sections are present).
+- Do not paste the full JSON block unless the user explicitly asks. If the user only asked to "see the catalog", offer to drill into a specific section (fields, navigation, app-config, dashboard) instead of dumping everything.
+- When authoring or editing a UDF payload, use this catalog as ground truth to:
+  * Restrict field "type" to the values in fields.validFieldTypes; reject anything else as invalid.
+  * Ensure appConfig includes every entry in appConfig.requiredFields, and keep port within appConfig.port range.
+  * Restrict editor modes, badge colors, id-generation modes/formats, navigation item types, and navigation depth to the enums and limits in the catalog.
+  * Restrict dashboard widget types, chart engines, and data source methods to the dashboard section's enums, and respect widgetsRequiringFields / forbiddenFields.
+- This is the DESIGNER (frontend UDF) catalog. Do not confuse it with the backend field validation catalog used for RDF payload fieldValidation constraints.
+- Do not mention internal tool names. Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=get-udf-catalog.js.map

package/dist/tools/designer/get-udf-catalog.js.map

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

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

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

package/dist/tools/designer/index.js

@@ -0,0 +1,19 @@
+import { registerDesignerValidatePayload } from './validate-payload.js';
+import { registerDesignerPreviewFiles } from './preview-files.js';
+import { registerDesignerListPlugins } from './list-plugins.js';
+import { registerDesignerInspectPlugin } from './inspect-plugin.js';
+import { registerDesignerScaffoldPlugin } from './scaffold-plugin.js';
+import { registerDesignerInitProject } from './init-project.js';
+import { registerDesignerGenerate } from './generate.js';
+import { registerDesignerGetUdfCatalog } from './get-udf-catalog.js';
+export function registerDesignerTools(server) {
+    registerDesignerValidatePayload(server);
+    registerDesignerPreviewFiles(server);
+    registerDesignerListPlugins(server);
+    registerDesignerInspectPlugin(server);
+    registerDesignerScaffoldPlugin(server);
+    registerDesignerInitProject(server);
+    registerDesignerGenerate(server);
+    registerDesignerGetUdfCatalog(server);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/designer/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,UAAU,qBAAqB,CAAC,MAAiB;IACrD,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACxC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACrC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IACpC,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACtC,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACvC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IACpC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,6BAA6B,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/tools/designer/init-project.d.ts

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

package/dist/tools/designer/init-project.js

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+import { resolve } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerDesignerInitProject(server) {
+    server.registerTool('designer_init_project', {
+        title: 'Init Designer Project',
+        description: `Initialise a new frontend project from an existing RESTForge Designer plugin, by running restforge-designer init. This WRITES a new project scaffold (config + structure) to disk, ready for generating frontend code.
+
+USE WHEN:
+- The user asks to start/initialise a new frontend project based on a designer plugin
+- The user asks things like "init project frontend baru", "scaffold aplikasi dari plugin designer", "mulai project frontend dengan plugin X", "init a new frontend project", "set up a designer project from plugin <id>", "buat project frontend dari plugin"
+- The user has a plugin id in mind and wants the project skeleton (app config, auth settings, ports) created from it
+
+DO NOT USE FOR:
+- Generating frontend code from an existing UDF payload -> use 'designer_generate'
+- Creating a brand new custom plugin from a template -> use 'designer_scaffold_plugin'
+- Listing or inspecting available plugins -> use 'designer_list_plugins' / 'designer_inspect_plugin'
+
+This tool wraps the RESTForge Designer CLI command: restforge-designer init --plugin=<plugin> --output=<output> [optional flags], run in the given cwd.
+The --plugin and --output flags are always sent so the binary never drops into interactive prompt mode. Optional flags (app name/code, API URLs, auth settings, port, idle timeout, no-auth, overwrite, plugins dir, license) are forwarded only when supplied.
+This operation is license-gated: the RESTForge Designer license must be active for init to succeed.
+
+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.
+- A valid, active RESTForge Designer license is required (the operation is license-gated).
+
+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. "initialise the frontend project", "generate the frontend code", "scaffold a new plugin").
+- Speak in plain language. Confirm what was created and where; 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'),
+            plugin: z
+                .string()
+                .min(1)
+                .describe('The plugin id to initialise the project from (e.g. vanilla-js-basic). Required.'),
+            output: z
+                .string()
+                .min(1)
+                .describe('Path to the output folder where the project will be created (relative to cwd or absolute). Required.'),
+            appName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Human-readable application name for the project.'),
+            appCode: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Short application code/identifier for the project.'),
+            apiBaseUrl: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Base URL of the backend API the frontend will call.'),
+            authAppCode: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Application code used for authentication.'),
+            authApiUrl: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Base URL of the authentication API.'),
+            port: z
+                .number()
+                .int()
+                .min(1024)
+                .max(65535)
+                .optional()
+                .describe('Dev server port for the project (1024-65535).'),
+            idleTimeout: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Idle timeout in seconds for the project.'),
+            noAuth: z
+                .boolean()
+                .optional()
+                .describe('When true, initialise the project without authentication.'),
+            overwrite: z
+                .boolean()
+                .optional()
+                .describe('When true, overwrite the output directory if it already exists.'),
+            pluginsDir: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Override path to the plugins folder. When omitted, the binary auto-detects the plugins directory.'),
+            license: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('License key override for this license-gated operation. When omitted, the binary uses the activated license.'),
+        },
+        annotations: {
+            title: 'Init Designer Project',
+            destructiveHint: false, // creates a new project; overwrites only when overwrite=true is supplied
+            idempotentHint: false, // each call attempts to create/initialise a project
+        },
+    }, async ({ cwd, plugin, output, appName, appCode, apiBaseUrl, authAppCode, authApiUrl, port, idleTimeout, noAuth, overwrite, pluginsDir, license, }) => {
+        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.
+        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}
+Plugin: ${plugin}
+Output: ${output}
+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 project can be initialised.
+- 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 initialising the project.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Always send the required flags (--plugin, --output) so the binary never drops
+        // into interactive prompt mode. Forward optional flags only when supplied. per §3.5 / D6
+        const args = ['init', `--plugin=${plugin}`, `--output=${output}`];
+        if (appName)
+            args.push(`--app-name=${appName}`);
+        if (appCode)
+            args.push(`--app-code=${appCode}`);
+        if (apiBaseUrl)
+            args.push(`--api-base-url=${apiBaseUrl}`);
+        if (authAppCode)
+            args.push(`--auth-app-code=${authAppCode}`);
+        if (authApiUrl)
+            args.push(`--auth-api-url=${authApiUrl}`);
+        if (port !== undefined)
+            args.push(`--port=${port}`);
+        if (idleTimeout !== undefined)
+            args.push(`--idle-timeout=${idleTimeout}`);
+        if (noAuth)
+            args.push('--no-auth');
+        if (overwrite)
+            args.push('--overwrite');
+        if (pluginsDir)
+            args.push(`--plugins-dir=${pluginsDir}`);
+        if (license)
+            args.push(`--license=${license}`);
+        const result = await execProcess('restforge-designer', args, {
+            cwd: projectCwd,
+            timeout: 60_000,
+        });
+        // D9: write tool. A non-zero exit (incl. -1 crash/timeout) means the init did not
+        // complete cleanly — the project may be missing or partial, so the model needs to
+        // recover -> isError: true.
+        if (result.exitCode !== 0) {
+            const stderrBlock = result.stderr
+                ? `\n--- stderr ---\n${result.stderr}\n--- end stderr ---\n`
+                : '';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Initialising the Designer project did not complete.
+
+Working directory: ${projectCwd}
+Plugin: ${plugin}
+Output: ${output}
+Plugins dir: ${pluginsDir ?? 'auto-detect'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- stdout ---
+${result.stdout}
+--- end stdout ---
+${stderrBlock}
+For the assistant:
+- The init did not finish successfully, so the project may not exist or may be partial. Read the CLI output above and explain the most likely cause to the user in plain language. Common causes:
+  * The RESTForge Designer license is not active — this operation is license-gated. Suggest the user activate their RESTForge Designer license through the Designer desktop application or its own CLI, then retry. Do not name any internal tool.
+  * The output directory already exists and overwrite was not enabled — suggest retrying with overwrite, or choosing a different output path.
+  * The plugin id does not exist — suggest listing the available plugins to pick a valid id.
+  * The chosen plugin does not support init — soft note: not every plugin supports the 'init' feature. If the CLI says something like "does not support the init feature", suggest picking a plugin that does (the available plugins can be listed to find one). Do not hardcode or assert a permanent list of which plugins support init — treat it as something to confirm from the current plugin list rather than a fixed claim.
+  * Exit code -1 — the command crashed or timed out; offer to retry.
+- Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names. Match the user's language.`,
+                    },
+                ],
+                isError: true, // per §3.4 / D9 — write did not complete
+            };
+        }
+        // D9: success — exit 0. Labeled facts + fenced raw output per §3.5.
+        const stderrBlock = result.stderr
+            ? `\n--- stderr ---\n${result.stderr}\n--- end stderr ---\n`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Designer project initialised successfully.
+
+Working directory: ${projectCwd}
+Plugin: ${plugin}
+Output: ${output}
+Plugins dir: ${pluginsDir ?? 'auto-detect'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- stdout ---
+${result.stdout}
+--- end stdout ---
+${stderrBlock}
+For the assistant:
+- Confirm to the user that the frontend project was initialised. Mention the plugin and the output location in plain language.
+- Suggest the next step: author or supply a UDF payload and then generate the frontend code into the project. The usual flow is validate the payload, preview the files, then generate.
+- Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names. Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=init-project.js.map

package/dist/tools/designer/init-project.js.map

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

package/dist/tools/designer/inspect-plugin.d.ts

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