Get Config Schema

Instructions

Implementation Reference

• src/tools/setup/get-config-schema.ts:7-170 (handler)

  Main handler function that registers the 'setup_get_config_schema' tool. Checks precondition (restforgejs installed), runs 'npx restforge-cli config:schema', parses JSON output, and returns formatted schema result.

  export function registerSetupGetConfigSchema(server: McpServer): void {
    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-cli config:schema in the given cwd.
  The schema is sourced from restforge-cli (single source of truth) so it stays
  in sync with the restforge runtime version installed in the project.
  Requires restforgejs >= 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 installed in node_modules)'),
        },
        annotations: {
          title: 'Get Config Schema',
          readOnlyHint: true,
          idempotentHint: true,
        },
      },
      async ({ cwd }) => {
        const projectCwd = resolve(cwd);
  
        // Precondition check: restforgejs 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'));
        } 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
  
  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-cli', '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 >= 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: unknown;
        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 >= 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-cli (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.`,
            },
          ],
        };
      }
    );

• src/tools/setup/get-config-schema.ts:39-46 (schema)

  Input schema definition using Zod: requires a single 'cwd' (string) parameter. Annotations mark the tool as read-only and idempotent.

  inputSchema: {
    cwd: z.string().min(1).describe('Absolute path of the project folder (must have restforgejs installed in node_modules)'),
  },
  annotations: {
    title: 'Get Config Schema',
    readOnlyHint: true,
    idempotentHint: true,
  },

• src/tools/setup/index.ts:12-22 (registration)

  Registration entry point: exports registerSetupTools which calls registerSetupGetConfigSchema(server) as part of setup tool registration.

  export function registerSetupTools(server: McpServer): void {
    registerSetupCreateFolder(server);
    registerSetupInstallPackage(server);
    registerSetupInitConfig(server);
    registerSetupWriteEnv(server);
    registerSetupReadEnv(server);
    registerSetupUpdateEnv(server);
    registerSetupValidateConfig(server);
    registerSetupGetConfigSchema(server);
    registerSetupGetInitTemplate(server);
  }

• src/lib/exec.ts:33-69 (helper)

  Helper execProcess used by the handler to run 'npx restforge-cli config:schema' as a subprocess with timeout and structured result.

  export async function execProcess(
    command: string,
    args: string[],
    options: ExecOptions = {}
  ): Promise<ExecResult> {
    const { cwd = process.cwd(), timeout = 60_000, env, stripFinalNewline = true } = options;
    const fullCommand = `${command} ${args.join(' ')}`;
  
    // Merge env: parent env first, custom env overrides
    const mergedEnv = env ? { ...process.env, ...env } : undefined;
  
    try {
      const result = await execa(command, args, {
        cwd,
        timeout,
        reject: false,
        stripFinalNewline,
        ...(mergedEnv ? { env: mergedEnv } : {}),
      });
      return {
        success: result.exitCode === 0,
        stdout: result.stdout,
        stderr: result.stderr,
        exitCode: result.exitCode ?? -1,
        command: fullCommand,
      };
    } catch (error) {
      const e = error as ExecaError;
      return {
        success: false,
        stdout: e.stdout?.toString() ?? '',
        stderr: e.stderr?.toString() ?? e.message,
        exitCode: e.exitCode ?? -1,
        command: fullCommand,
      };
    }
  }