Install restforgejs Package

Instructions

Implementation Reference

• src/tools/setup/install-package.ts:1-145 (handler)

  Full implementation of the 'setup_install_package' tool. The registerSetupInstallPackage function registers the tool on the MCP server with: schema (lines 9-57) defining 'cwd' (required string) and 'version' (optional string defaulting to 'beta'), and handler (lines 58-143) which checks the folder exists, then runs 'npm install restforgejs@<version>' using execProcess, returning structured success/error/precondition messages.

  import { z } from 'zod';
  import { access } from 'node:fs/promises';
  import { resolve } from 'node:path';
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  import { execProcess } from '../../lib/exec.js';
  
  export function registerSetupInstallPackage(server: McpServer): void {
    server.registerTool(
      'setup_install_package',
      {
        title: 'Install restforgejs Package',
        description: `Install the restforgejs package into the project's node_modules via npm.
  
  USE WHEN:
  - The user wants to install RESTForge (restforgejs) into a project
  - The project folder exists but does not yet have restforgejs in node_modules
  - Setting up a new project before the configuration stage
  - Updating restforgejs to a specific tag or version
  - The user says things like "install restforge", "tambahkan restforgejs",
    "pasang package restforge", "set up the package", "siapkan project ini",
    "upgrade restforgejs", "ganti versi restforge"
  
  DO NOT USE FOR:
  - Creating a new project folder -> use 'setup_create_folder'
  - Generating config skeleton -> use 'setup_init_config'
  - Filling in credentials -> use 'setup_write_env'
  - Validating the configuration -> use 'setup_validate_config'
  
  This tool sits in the middle of the new-project setup chain: typically run
  after 'setup_create_folder' creates the project folder, and before
  'setup_init_config' which generates the configuration skeleton. 'setup_init_config'
  will return a precondition message if this tool has not been run first. // per §5.2
  
  This tool runs: npm install restforgejs@<version> in the given cwd (local install, not global).
  Default version is "beta" because RESTForge is currently a public pre-release. Use "latest" once stable, or a specific version (e.g. "1.2.3").
  
  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. "create the project folder", "generate the initial config", "fill in the credentials").
  - Speak in plain language. Summarise the result; do not paste raw npm output unless the user explicitly asks.
  - When a precondition is not met (e.g. the project folder is 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 (must exist before this tool runs)'),
          version: z
            .string()
            .default('beta')
            .describe('npm version or tag: "beta" (default), "latest", or a specific version (e.g. "1.2.3")'),
        },
        annotations: {
          title: 'Install restforgejs',
          readOnlyHint: false,
          idempotentHint: true,
        },
      },
      async ({ cwd, version }) => {
        const projectCwd = resolve(cwd);
  
        // Precondition check: the project folder must exist.
        // Treated as a non-error precondition per the authoring guide §3.4.
        try {
          await access(projectCwd);
        } catch {
          return {
            content: [
              {
                type: 'text',
                text: `Precondition not met: the project folder does not exist yet.
  
  Project path: ${projectCwd}
  
  For the assistant:
  - The user is trying to install the RESTForge package into a folder that has not been created yet.
  - Suggest creating the project folder first, then retry the installation.
  - When explaining to the user, say something like "the project folder isn't there yet — should I create it first?". Do not mention internal tool names.`,
              },
            ],
            isError: false, // per §3.4
          };
        }
  
        const result = await execProcess(
          'npm',
          ['install', `restforgejs@${version}`],
          { cwd: projectCwd, timeout: 180_000 }
        );
  
        // CLI failure: real error per §3.4; structured per §3.5.
        if (!result.success) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to install the RESTForge package.
  
  Project path: ${projectCwd}
  Requested version: ${version}
  Command: ${result.command}
  Exit code: ${result.exitCode}
  
  --- npm output ---
  stdout:
  ${result.stdout}
  
  stderr:
  ${result.stderr}
  --- end npm output ---
  
  For the assistant:
  - Tell the user that the installation did not complete successfully.
  - Summarise the likely cause from the npm output in plain language (network, registry, version not found, peer dependency); 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.
        return {
          content: [
            {
              type: 'text',
              text: `RESTForge package installed successfully.
  
  Project path: ${projectCwd}
  Installed version: restforgejs@${version}
  Install location: node_modules/restforgejs
  
  --- npm output ---
  ${result.stdout}
  --- end npm output ---
  
  For the assistant:
  - Confirm to the user that the RESTForge package is installed in this project.
  - Suggest the next step in plain words: generating the initial configuration skeleton (config and payload templates) so the project can be configured.
  - Keep the reply concise. Do not paste the raw npm output unless the user explicitly asks. Do not mention internal tool names.`,
            },
          ],
        };
      }
    );
  }

• src/tools/setup/install-package.ts:9-57 (schema)

  Input schema for the tool, defined inline in registerTool call. Uses Zod for 'cwd' (required string) and 'version' (string with default 'beta') validation, plus annotations and description.

      'setup_install_package',
      {
        title: 'Install restforgejs Package',
        description: `Install the restforgejs package into the project's node_modules via npm.
  
  USE WHEN:
  - The user wants to install RESTForge (restforgejs) into a project
  - The project folder exists but does not yet have restforgejs in node_modules
  - Setting up a new project before the configuration stage
  - Updating restforgejs to a specific tag or version
  - The user says things like "install restforge", "tambahkan restforgejs",
    "pasang package restforge", "set up the package", "siapkan project ini",
    "upgrade restforgejs", "ganti versi restforge"
  
  DO NOT USE FOR:
  - Creating a new project folder -> use 'setup_create_folder'
  - Generating config skeleton -> use 'setup_init_config'
  - Filling in credentials -> use 'setup_write_env'
  - Validating the configuration -> use 'setup_validate_config'
  
  This tool sits in the middle of the new-project setup chain: typically run
  after 'setup_create_folder' creates the project folder, and before
  'setup_init_config' which generates the configuration skeleton. 'setup_init_config'
  will return a precondition message if this tool has not been run first. // per §5.2
  
  This tool runs: npm install restforgejs@<version> in the given cwd (local install, not global).
  Default version is "beta" because RESTForge is currently a public pre-release. Use "latest" once stable, or a specific version (e.g. "1.2.3").
  
  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. "create the project folder", "generate the initial config", "fill in the credentials").
  - Speak in plain language. Summarise the result; do not paste raw npm output unless the user explicitly asks.
  - When a precondition is not met (e.g. the project folder is 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 (must exist before this tool runs)'),
          version: z
            .string()
            .default('beta')
            .describe('npm version or tag: "beta" (default), "latest", or a specific version (e.g. "1.2.3")'),
        },
        annotations: {
          title: 'Install restforgejs',
          readOnlyHint: false,
          idempotentHint: true,
        },
      },

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

  Registration of the tool via registerSetupTools() which calls registerSetupInstallPackage(server) to register it on the McpServer.

  export function registerSetupTools(server: McpServer): void {
    registerSetupCreateFolder(server);
    registerSetupInstallPackage(server);

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

  execProcess helper function used by the handler to run 'npm install' as a subprocess. Returns a structured ExecResult with success, stdout, stderr, exitCode, and command fields.

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