Generate Payload

Instructions

Implementation Reference

• src/tools/codegen/generate-payload.ts:63-157 (handler)

  The async handler function that executes the 'codegen_generate_payload' tool logic. It checks for the restforgejs package in node_modules, then runs 'npx restforge-cli payload --table=<table> --config=<config>' to introspect the database table and generate a payload spec file.

      async ({ cwd, table, config }) => {
        const projectCwd = resolve(cwd);
  
        // Precondition check: restforgejs must be present in node_modules.
        // 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
  Requested table: ${table}
  Requested config: ${config}
  
  For the assistant:
  - The user needs to install the RESTForge package before a payload can be generated from a table schema.
  - Use the appropriate package-installation tool to do this, then retry generating the payload.
  - 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
          };
        }
  
        const result = await execProcess(
          'npx',
          ['restforge-cli', 'payload', `--table=${table}`, `--config=${config}`],
          { cwd: projectCwd, timeout: 30_000 }
        );
  
        // CLI failure: real error per §3.4; structured per §3.5.
        if (!result.success) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to generate payload.
  
  Project path: ${projectCwd}
  Table: ${table}
  Config: ${config}
  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 generating the payload did not complete successfully.
  - Summarise the likely cause from the CLI output in plain language (common causes: the config file is missing or has incomplete credentials, the database is unreachable, or the requested table does not exist in the database). Do not paste the raw stdout/stderr 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 + fenced raw output per §3.5.
        // The CLI itself prints the output filename in stdout; we do not try to re-derive it here.
        return {
          content: [
            {
              type: 'text',
              text: `Payload generated successfully.
  
  Project path: ${projectCwd}
  Table: ${table}
  Config: ${config}
  Output: payload file generated by restforge-cli (see CLI output below for the exact filename; underscores in the table name are mapped to hyphens, e.g. 'guest_book' -> 'guest-book.json').
  
  --- CLI output ---
  ${result.stdout}
  --- end CLI output ---
  
  For the assistant:
  - Confirm to the user that the payload spec for the requested table is ready.
  - Mention in plain language that the payload is the input for the next codegen step (generating the project and endpoint code from this payload). That follow-up step is part of the CLI workflow but is not wrapped as a tool yet.
  - Suggest that the user can review or edit the generated payload file before the next step.
  - Keep the reply concise. Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names.`,
            },
          ],
        };
      }
    );
  }

• src/tools/codegen/generate-payload.ts:42-56 (schema)

  Input schema for the tool using Zod: cwd (string, required), table (string, required), config (string, default 'db-connection.env').

  inputSchema: {
    cwd: z
      .string()
      .min(1)
      .describe('Absolute path of the project folder (must contain node_modules/restforgejs and the config file)'),
    table: z
      .string()
      .min(1)
      .describe('Name of the database table to introspect (e.g. guest_book)'),
    config: z
      .string()
      .min(1)
      .default('db-connection.env')
      .describe('Config file name (relative to project) used by the CLI to connect to the database'),
  },

• src/tools/codegen/index.ts:16-17 (registration)

  Registration of the tool via registerCodegenGeneratePayload(server) in the codegen tools aggregator.

  export function registerCodegenTools(server: McpServer): void {
    registerCodegenGeneratePayload(server);

• src/tools/codegen/generate-payload.ts:7-9 (registration)

  The registerCodegenGeneratePayload function that calls server.registerTool('codegen_generate_payload', ...).

  export function registerCodegenGeneratePayload(server: McpServer): void {
    server.registerTool(
      'codegen_generate_payload',

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

  The execProcess helper utility used by the handler to run the npx CLI command.

  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,
      };
    }
  }