run-script

Instructions

Implementation Reference

• src/index.ts:873-890 (handler)

  The handler function for the run-script tool. It builds npm run arguments (optionally with a script name and extra args), appends --json if listing scripts, executes via the `run` helper, and returns the output or an error.

    async ({ path, script, args: scriptArgs }) => {
      const cmdArgs = script ? ["run", script] : ["run"];
      if (scriptArgs && scriptArgs.length > 0) {
        cmdArgs.push("--");
        cmdArgs.push(...scriptArgs);
      }
      if (!script) cmdArgs.push("--json");
      try {
        const { stdout, stderr } = await run(cmdArgs, path);
        return { content: [{ type: "text", text: stdout + stderr }] };
      } catch (e: any) {
        return {
          content: [{ type: "text", text: `Error: ${e.stdout || ""}${e.stderr || e.message}` }],
          isError: true,
        };
      }
    },
  );

• src/index.ts:868-872 (schema)

  Input schema for run-script: path (required), script (optional), and args (optional array of strings).

  {
    path: z.string().describe("Absolute path to the package directory"),
    script: z.string().optional().describe("Script name to run (omit to list available scripts)"),
    args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
  },

• src/index.ts:865-890 (registration)

  Registration of the run-script tool via server.tool() on the MCP server instance.

  server.tool(
    "run-script",
    "Run a script defined in package.json",
    {
      path: z.string().describe("Absolute path to the package directory"),
      script: z.string().optional().describe("Script name to run (omit to list available scripts)"),
      args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
    },
    async ({ path, script, args: scriptArgs }) => {
      const cmdArgs = script ? ["run", script] : ["run"];
      if (scriptArgs && scriptArgs.length > 0) {
        cmdArgs.push("--");
        cmdArgs.push(...scriptArgs);
      }
      if (!script) cmdArgs.push("--json");
      try {
        const { stdout, stderr } = await run(cmdArgs, path);
        return { content: [{ type: "text", text: stdout + stderr }] };
      } catch (e: any) {
        return {
          content: [{ type: "text", text: `Error: ${e.stdout || ""}${e.stderr || e.message}` }],
          isError: true,
        };
      }
    },
  );

• src/index.ts:26-38 (helper)

  The `run` helper function that executes npm commands via child_process.execFile with timeout, maxBuffer, and environment settings.

  async function run(
    args: string[],
    cwd?: string,
  ): Promise<{ stdout: string; stderr: string }> {
    const fullArgs = [...args, ...npmrcArgs];
    const opts: { cwd?: string; timeout: number; env: NodeJS.ProcessEnv; maxBuffer: number } = {
      timeout: 120_000,
      maxBuffer: 10 * 1024 * 1024, // 10MB buffer for large outputs
      env: { ...process.env, NO_COLOR: "1" },
    };
    if (cwd) opts.cwd = cwd;
    return exec(NPM, fullArgs, opts);
  }

• src/index.ts:1383-1387 (registration)

  Sandbox registration of run-script tool (noop handler for sandbox mode).

  sandbox.tool("run-script", "Run a script defined in package.json", {
    path: z.string().describe("Absolute path to the package directory"),
    script: z.string().optional().describe("Script name to run"),
    args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
  }, noop);