npm-run-mcp-server

Implementation Reference

• src/index.ts:258-292 (handler)

  The handler function that executes the 'build' npm script (and all others). It constructs the command using buildRunCommand, runs it with exec, captures output or error, trims if necessary, and returns as MCP content.
  async ({ args: extraArgs }: { args?: string }) => { const command = buildRunCommand(pm, scriptName, extraArgs); try { const { stdout, stderr } = await exec(command, { cwd: projectDir, env: process.env, maxBuffer: 16 * 1024 * 1024, // 16MB windowsHide: true, }); const combined = stdout && stderr ? `${stdout}\n${stderr}` : stdout || stderr || ''; const { text } = trimOutput(combined); return { content: [ { type: 'text', text, }, ], }; } catch (error: any) { const stdout = error?.stdout ?? ''; const stderr = error?.stderr ?? ''; const message = error?.message ? String(error.message) : 'Script failed'; const combined = [message, stdout, stderr].filter(Boolean).join('\n'); const { text } = trimOutput(combined); return { content: [ { type: 'text', text, }, ], }; } }
• src/index.ts:247-256 (schema)

  The input schema for the 'build' tool (shared by all script tools), accepting optional 'args' for extra command-line arguments.
  { inputSchema: { type: 'object', properties: { args: { type: 'string', description: 'Optional arguments appended after -- to the script' } } },
• src/index.ts:234-294 (registration)

  Dynamic registration of MCP tools for each npm script in package.json. For a 'build' script, registers a tool named 'build' (or sanitized) with description, schema, and handler.
  // Register a tool per script for (const scriptName of scriptNames) { // Sanitize tool name - MCP tools can only contain [a-z0-9_-] const toolName = scriptName.toLowerCase().replace(/[^a-z0-9_-]/g, '_'); // Create a more descriptive description const scriptCommand = scripts[scriptName]; const description = `Run npm script "${scriptName}": ${scriptCommand}`; server.tool( toolName, description, { inputSchema: { type: 'object', properties: { args: { type: 'string', description: 'Optional arguments appended after -- to the script' } } }, }, async ({ args: extraArgs }: { args?: string }) => { const command = buildRunCommand(pm, scriptName, extraArgs); try { const { stdout, stderr } = await exec(command, { cwd: projectDir, env: process.env, maxBuffer: 16 * 1024 * 1024, // 16MB windowsHide: true, }); const combined = stdout && stderr ? `${stdout}\n${stderr}` : stdout || stderr || ''; const { text } = trimOutput(combined); return { content: [ { type: 'text', text, }, ], }; } catch (error: any) { const stdout = error?.stdout ?? ''; const stderr = error?.stderr ?? ''; const message = error?.message ? String(error.message) : 'Script failed'; const combined = [message, stdout, stderr].filter(Boolean).join('\n'); const { text } = trimOutput(combined); return { content: [ { type: 'text', text, }, ], }; } } ); }
• src/index.ts:72-86 (helper)

  Helper function to construct the shell command string for running a script with the detected package manager, handling quoting and extra args. Used in the 'build' handler.
  function buildRunCommand(pm: PackageManager, scriptName: string, extraArgs?: string): string { const quoted = scriptName.replace(/"/g, '\\"'); const suffix = extraArgs && extraArgs.trim().length > 0 ? ` -- ${extraArgs}` : ''; switch (pm) { case 'pnpm': return `pnpm run "${quoted}"${suffix}`; case 'yarn': return `yarn run "${quoted}"${suffix}`; case 'bun': return `bun run "${quoted}"${suffix}`; case 'npm': default: return `npm run "${quoted}"${suffix}`; } }
• src/index.ts:88-90 (helper)

  Helper to trim long output strings before returning in tool response, used in handler.
  function trimOutput(out: string, limit = 12000): { text: string; truncated: boolean } { if (out.length <= limit) return { text: out, truncated: false }; return { text: out.slice(0, limit) + `\n...[truncated ${out.length - limit} chars]`, truncated: true };