npm-run-mcp-server 0.2.9 → 0.2.11

package/README.md

@@ -18,19 +18,28 @@
 
 - [Install](#install)
 - [Usage](#usage)
+  - [As an MCP Server](#as-an-mcp-server)
+  - [As a CLI Tool](#as-a-cli-tool)
 - [Configuration](#configuration)
-  - [GitHub Copilot Chat (VS Code)](#github-copilot-chat-vs-code)
-  - [Claude Code (VS Code extension)](#claude-code-vs-code-extension)
-  - [Claude Code (terminal / standalone)](#claude-code-terminal--standalone)
+  - [GitHub Copilot (VS Code)](#github-copilot-vs-code)
   - [Cursor](#cursor)
+  - [Claude Code](#claude-code)
+  - [Multi-Project Workflow](#multi-project-workflow)
+  - [Auto-Restart on Script Changes](#auto-restart-on-script-changes)
+  - [Script Exposure Config](#script-exposure-config)
   - [Install from source](#install-from-source)
 - [Testing with MCP Inspector](#testing-with-mcp-inspector)
 - [CLI Options](#cli-options)
 - [Contributing](#contributing)
+  - [Reporting Issues](#reporting-issues)
+  - [Submitting Changes](#submitting-changes)
+  - [Development Setup](#development-setup)
 - [License](#license)
 
 ## Install
 
+Installation options.
+
 ```bash
 npm i -D npm-run-mcp-server
 # or globally
@@ -41,17 +50,21 @@ npx npm-run-mcp-server
 
 ## Usage
 
+MCP server and CLI tool usage.
+
 ### As an MCP Server
 
 Add this server to your MCP host configuration. It uses stdio and automatically detects your project's `package.json` using workspace environment variables or by walking up from the current working directory.
 
 **Key Features:**
 - **Automatic Workspace Detection**: Works seamlessly across different projects without configuration changes
-- **Smart Tool Names**: Script names with colons (like `install:discord`) are automatically converted to valid tool names (`install_discord`)
+- **Smart Tool Names**: Script names with colons (like `test:unit`) are automatically converted to valid tool names (`test_unit`)
 - **Rich Descriptions**: Each tool includes the actual script command in its description
 - **Package Manager Detection**: Automatically detects npm, pnpm, yarn, or bun
-- **Optional Arguments**: Each tool accepts an optional `args` string that is appended after `--` when running the script
-- **Auto-Restart on Changes**: Automatically restarts when `package.json` scripts are modified, ensuring tools are always up-to-date
+- **Optional Arguments**: Each tool accepts optional `args` (`string` or `string[]`) appended after `--` when running the script
+- **Auto-Restart on Changes**: Automatically restarts when `package.json` or config changes, ensuring tools are always up-to-date
+
+Note: scripts run inside the target project. If they rely on local dependencies (eslint, vitest, tsc), install them first (for example, `npm install`).
 
 ### As a CLI Tool
 
@@ -69,12 +82,23 @@ npx npm-run-mcp-server --cwd /path/to/project --list-scripts
 
 # Override package manager detection
 npx npm-run-mcp-server --pm yarn --list-scripts
+
+# Use an explicit config file (relative to the project directory, or absolute)
+npx npm-run-mcp-server --cwd /path/to/project --config npm-run-mcp.config.json --verbose
 ```
 
 ## Configuration
 
-### Install in GitHub Copilot Chat (VS Code)
+Setup instructions for AI agents.
+
+### GitHub Copilot (VS Code)
+
+#### Via UI
+1. Open VS Code settings
+2. Search for "MCP"
+3. Add server configuration in settings.json
 
+#### Via Config File
 Option A — per-workspace via `.vscode/mcp.json` (recommended for multi-project use):
 
 ```json
@@ -101,39 +125,23 @@ Option B — user settings (`settings.json`):
 }
 ```
 
-**Note**: The server automatically detects the current project's `package.json` using workspace environment variables (like `WORKSPACE_FOLDER_PATHS`) or by walking up from the current working directory. No hardcoded paths are needed - it works seamlessly across all your projects.
-
 Then open Copilot Chat, switch to Agent mode, and start the `npm-scripts` server from the tools panel.
 
-### Multi-Project Workflow
-
-The MCP server is designed to work seamlessly across multiple projects without configuration changes:
-
-- **VS Code/Cursor**: The server automatically detects the current workspace using environment variables like `WORKSPACE_FOLDER_PATHS`
-- **Claude Desktop**: The server uses the working directory where Claude is launched
-- **No Hardcoded Paths**: All examples use `npx npm-run-mcp-server` without `--cwd` flags
-- **Smart Detection**: The server first tries workspace environment variables, then falls back to walking up the directory tree to find the nearest `package.json`
-- **Cross-Platform**: Handles Windows/WSL path conversions automatically
-
-This means you can use the same MCP configuration across all your projects, and the server will automatically target the correct project based on your current workspace.
-
-### Auto-Restart on Script Changes
-
-The MCP server automatically monitors your `package.json` file for changes. When you add, remove, or modify scripts, the server will:
-
-1. **Detect the change** and log it (with `--verbose` flag)
-2. **Gracefully exit** to allow the MCP client to restart the server
-3. **Reload with new tools** based on the updated scripts
+### Cursor
 
-This ensures your MCP tools are always synchronized with your current `package.json` scripts without manual intervention.
+#### Via UI
+1. Open Settings -> MCP Servers -> Add MCP Server
+2. Type: NPX Package
+3. Command: `npx`
+4. Arguments: `-y npm-run-mcp-server`
+5. Save and start the server from the tools list
 
-### Install in Claude Code (VS Code extension)
-
-Add to VS Code user/workspace settings (`settings.json`):
+#### Via Config File
+Add to Cursor's MCP configuration:
 
 ```json
 {
-  "claude.mcpServers": {
+  "servers": {
     "npm-scripts": {
       "command": "npx",
       "args": ["-y", "npm-run-mcp-server"]
@@ -142,20 +150,19 @@ Add to VS Code user/workspace settings (`settings.json`):
 }
 ```
 
-**Note**: Workspace settings (`.vscode/settings.json`) are recommended for multi-project use, as they automatically target the current project.
-
-Restart the extension and confirm the server/tools appear.
+### Claude Code
 
-### Install in Claude Code (terminal / standalone)
-
-Add this server to Claude's global config file (paths vary by OS). Create the file if it doesn't exist.
+#### Via Terminal
+```bash
+claude mcp add npm-scripts npx -y npm-run-mcp-server
+```
 
+#### Via Config File
+Add to Claude Code's config file:
 - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
 
-**Recommended approach** - Using npx (works across all projects):
-
 ```json
 {
   "mcpServers": {
@@ -167,48 +174,58 @@ Add this server to Claude's global config file (paths vary by OS). Create the fi
 }
 ```
 
-**Alternative** - Using a local build (requires absolute path):
+Restart Claude Code after editing the config.
 
-```json
-{
-  "mcpServers": {
-    "npm-scripts": {
-      "command": "node",
-      "args": ["/absolute/path/to/npm-run-mcp-server/dist/index.js"]
-    }
-  }
-}
-```
+### Multi-Project Workflow
+
+The MCP server automatically detects your project's `package.json` using workspace environment variables or by walking up from the current working directory. No hardcoded paths needed - it works seamlessly across all your projects.
+
+### Auto-Restart on Script Changes
 
-**Note**: The npx approach is recommended as it automatically targets the current working directory where Claude is launched.
+The server automatically monitors your `package.json` file (and `npm-run-mcp.config.json` if present) for changes. When you modify scripts or config, the server gracefully exits to allow the MCP client to restart with updated tools.
 
-Optional: include environment variables
+### Script Exposure Config
+
+You can make the tool surface more deterministic by explicitly choosing which scripts are exposed and by defining per-script tool metadata.
+
+Create `npm-run-mcp.config.json` (or `.npm-run-mcp.json`) next to your project's `package.json`:
 
 ```json
 {
-  "mcpServers": {
-    "npm-scripts": {
-      "command": "npx",
-      "args": ["-y", "npm-run-mcp-server"],
-      "env": {
-        "NODE_ENV": "production"
+  "include": ["build", "lint", "test:unit"],
+  "exclude": ["dev", "test:e2e"],
+  "scripts": {
+    "test:unit": {
+      "toolName": "test_unit",
+      "description": "Run unit tests",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "watch": { "type": "boolean" },
+          "run": { "type": "boolean" }
+        }
+      }
+    },
+    "lint": {
+      "description": "Lint the codebase",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "fix": { "type": "boolean" }
+        }
       }
     }
   }
 }
 ```
 
-Restart Claude after editing the config so it picks up the new server.
-
-### Install in Cursor
-
-- Open Settings → MCP Servers → Add MCP Server
-- Type: NPX Package
-- Command: `npx`
-- Arguments: `-y npm-run-mcp-server`
-- Save and start the server from the tools list
-
-**Note**: This configuration automatically works across all your projects. The server will target the current project's `package.json` wherever Cursor is opened.
+Notes:
+- `include` and `exclude` are exact script names.
+- `toolName` lets you resolve naming collisions after sanitization.
+- `inputSchema` extends the default input model (and `args` is always available).
+- Tool input fields (other than `args`) are converted to CLI flags, e.g. `{ "watch": true }` becomes `--watch` and `{ "port": 3000 }` becomes `--port 3000`.
+- If filters result in zero tools, the server logs a warning so misconfigurations are easy to spot.
+- Config files support JSONC (comments + trailing commas). A JSON Schema is published as `npm-run-mcp.config.schema.json`.
 
 ### Install from source (for testing in another project)
 
@@ -255,7 +272,7 @@ Optional CLI flags you can pass in `args`:
 
 ## Testing with MCP Inspector
 
-Test the server locally before integrating with AI agents:
+Test the server locally.
 
 ```bash
 # Start MCP Inspector
@@ -272,16 +289,17 @@ You should see your package.json scripts listed as available tools. Try running
 
 ## CLI Options
 
-Available command-line flags:
+Command-line flags.
 
 - `--cwd <path>` - Specify working directory (defaults to current directory)
+- `--config <path>` - Use an explicit config file path (relative to the project directory, or absolute)
 - `--pm <manager>` - Override package manager detection (npm|pnpm|yarn|bun)
 - `--verbose` - Enable detailed logging to stderr
 - `--list-scripts` - List available scripts and exit
 
 ## Contributing
 
-We welcome contributions! Here's how you can help:
+Contributions welcome! How to help with development, reporting issues, and submitting changes.
 
 ### Reporting Issues
 
@@ -311,15 +329,7 @@ npm run test
 
 The project uses a custom build script located in `scripts/build.cjs` that handles TypeScript compilation and shebang injection for the executable.
 
-### Guidelines
-
-- Follow the existing code style
-- Add tests for new features
-- Update documentation as needed
-- Keep commits focused and descriptive
 
 ## License
 
-MIT
-
-
+MIT License.

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -3,11 +3,192 @@ import { readFileSync, existsSync, watch } from 'fs';
 import { promises as fsp } from 'fs';
 import { dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
-import { exec as nodeExec } from 'child_process';
-import { promisify } from 'util';
+import spawn from 'cross-spawn';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-const exec = promisify(nodeExec);
+import { z } from 'zod';
+const MCP_CONFIG_FILES = ['npm-run-mcp.config.json', '.npm-run-mcp.json'];
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function parseMcpConfig(raw) {
+    if (!isPlainObject(raw))
+        return {};
+    const include = Array.isArray(raw.include) ? raw.include.filter((v) => typeof v === 'string') : undefined;
+    const exclude = Array.isArray(raw.exclude) ? raw.exclude.filter((v) => typeof v === 'string') : undefined;
+    let scripts;
+    if (isPlainObject(raw.scripts)) {
+        scripts = {};
+        for (const [name, value] of Object.entries(raw.scripts)) {
+            if (!isPlainObject(value))
+                continue;
+            scripts[name] = {
+                toolName: typeof value.toolName === 'string' ? value.toolName : undefined,
+                description: typeof value.description === 'string' ? value.description : undefined,
+                inputSchema: isPlainObject(value.inputSchema) ? value.inputSchema : undefined,
+                argsDescription: typeof value.argsDescription === 'string' ? value.argsDescription : undefined,
+            };
+        }
+    }
+    return { include, exclude, scripts };
+}
+function parseJsonOrJsonc(text, filePathForErrors) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const errors = [];
+        const parsed = parseJsonc(text, errors, { allowTrailingComma: true, disallowComments: false });
+        if (errors.length > 0) {
+            const formatted = errors
+                .slice(0, 3)
+                .map((e) => `code=${e.error} offset=${e.offset} length=${e.length}`)
+                .join(', ');
+            throw new Error(`Invalid JSON/JSONC in ${filePathForErrors} (${formatted})`);
+        }
+        return parsed;
+    }
+}
+async function readProjectMcpConfig(projectDir, verbose, configArg) {
+    if (typeof configArg === 'string' && configArg.length > 0) {
+        const candidate = resolve(projectDir, configArg);
+        if (!existsSync(candidate)) {
+            console.error(`npm-run-mcp-server: Config file not found: ${candidate}`);
+            process.exit(1);
+        }
+        try {
+            const raw = await fsp.readFile(candidate, 'utf8');
+            const parsed = parseJsonOrJsonc(raw, candidate);
+            const config = parseMcpConfig(parsed);
+            if (verbose) {
+                console.error(`[mcp] using config file: ${candidate}`);
+            }
+            return { config, configPath: candidate };
+        }
+        catch (error) {
+            const message = error?.message ? String(error.message) : String(error);
+            console.error(`npm-run-mcp-server: Failed to read config file ${candidate}: ${message}`);
+            process.exit(1);
+        }
+    }
+    for (const filename of MCP_CONFIG_FILES) {
+        const candidate = resolve(projectDir, filename);
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const raw = await fsp.readFile(candidate, 'utf8');
+            const parsed = parseJsonOrJsonc(raw, candidate);
+            const config = parseMcpConfig(parsed);
+            if (verbose) {
+                console.error(`[mcp] using config file: ${candidate}`);
+            }
+            return { config, configPath: candidate };
+        }
+        catch (error) {
+            const message = error?.message ? String(error.message) : String(error);
+            console.error(`npm-run-mcp-server: Failed to read config file ${candidate}: ${message}`);
+            process.exit(1);
+        }
+    }
+    return { config: {}, configPath: null };
+}
+function normalizeToolName(name) {
+    const normalized = name.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+    return normalized.length > 0 ? normalized : 'script';
+}
+function jsonSchemaToZod(schema) {
+    if (!isPlainObject(schema))
+        return z.any();
+    if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === 'string')) {
+        const values = schema.enum;
+        const [first, ...rest] = values;
+        let base = first ? z.literal(first) : z.string();
+        for (const v of rest)
+            base = z.union([base, z.literal(v)]);
+        return typeof schema.description === 'string' ? base.describe(schema.description) : base;
+    }
+    const type = schema.type;
+    let zod;
+    switch (type) {
+        case 'string':
+            zod = z.string();
+            break;
+        case 'boolean':
+            zod = z.boolean();
+            break;
+        case 'number':
+            zod = z.number();
+            break;
+        case 'integer':
+            zod = z.number().int();
+            break;
+        case 'array': {
+            const items = schema.items;
+            if (isPlainObject(items) && items.type === 'string')
+                zod = z.array(z.string());
+            else
+                zod = z.array(z.any());
+            break;
+        }
+        case 'object': {
+            const properties = isPlainObject(schema.properties) ? schema.properties : {};
+            const requiredSet = new Set(Array.isArray(schema.required) ? schema.required.filter((v) => typeof v === 'string') : []);
+            const shape = {};
+            for (const [key, value] of Object.entries(properties)) {
+                let prop = jsonSchemaToZod(value);
+                if (!requiredSet.has(key))
+                    prop = prop.optional();
+                shape[key] = prop;
+            }
+            const obj = z.object(shape);
+            zod = schema.additionalProperties === false ? obj.strict() : obj.passthrough();
+            break;
+        }
+        default:
+            zod = z.any();
+            break;
+    }
+    if (typeof schema.description === 'string')
+        zod = zod.describe(schema.description);
+    return zod;
+}
+function buildToolInputSchema(configForScript) {
+    const base = z
+        .object({
+        _: z.array(z.string()).optional(),
+        args: z
+            .union([z.string(), z.array(z.string())])
+            .optional()
+            .describe(configForScript?.argsDescription ?? 'Optional arguments appended after -- to the script'),
+    })
+        .passthrough();
+    if (!configForScript?.inputSchema)
+        return base;
+    const converted = jsonSchemaToZod(configForScript.inputSchema);
+    if (converted instanceof z.ZodObject) {
+        const merged = converted.extend({
+            _: base.shape._,
+            args: base.shape.args,
+        });
+        return configForScript.inputSchema && isPlainObject(configForScript.inputSchema) && configForScript.inputSchema.additionalProperties === false
+            ? merged.strict()
+            : merged.passthrough();
+    }
+    return base;
+}
+function filterScriptNames(scriptNames, config) {
+    const include = config.include && config.include.length > 0 ? new Set(config.include) : null;
+    const exclude = config.exclude && config.exclude.length > 0 ? new Set(config.exclude) : null;
+    const filtered = scriptNames.filter((name) => {
+        if (include && !include.has(name))
+            return false;
+        if (exclude && exclude.has(name))
+            return false;
+        return true;
+    });
+    return filtered.sort();
+}
 function parseCliArgs(argv) {
     const args = {};
     for (let i = 2; i < argv.length; i += 1) {
@@ -64,24 +245,150 @@ function detectPackageManager(projectDir, pkg, override) {
     return 'npm';
 }
 function buildRunCommand(pm, scriptName, extraArgs) {
-    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}`;
+    const command = pm;
+    const baseArgs = ['run', scriptName];
+    const args = extraArgs.length > 0 ? [...baseArgs, '--', ...extraArgs] : baseArgs;
+    return { command, args };
+}
+function parseArgString(input) {
+    const result = [];
+    let current = '';
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    let tokenActive = false;
+    const pushCurrent = () => {
+        if (!tokenActive)
+            return;
+        result.push(current);
+        current = '';
+        tokenActive = false;
+    };
+    for (let i = 0; i < input.length; i += 1) {
+        const ch = input[i];
+        if (escaping) {
+            current += ch;
+            escaping = false;
+            tokenActive = true;
+            continue;
+        }
+        if (!inSingle && ch === '\\') {
+            escaping = true;
+            tokenActive = true;
+            continue;
+        }
+        if (!inDouble && ch === "'" && !escaping) {
+            inSingle = !inSingle;
+            tokenActive = true;
+            continue;
+        }
+        if (!inSingle && ch === '"' && !escaping) {
+            inDouble = !inDouble;
+            tokenActive = true;
+            continue;
+        }
+        if (!inSingle && !inDouble && /\s/.test(ch)) {
+            pushCurrent();
+            continue;
+        }
+        current += ch;
+        tokenActive = true;
     }
+    if (escaping) {
+        current += '\\';
+        tokenActive = true;
+    }
+    pushCurrent();
+    return result;
 }
-function trimOutput(out, limit = 12000) {
-    if (out.length <= limit)
+function toolInputToExtraArgs(input) {
+    if (!isPlainObject(input))
+        return [];
+    const rawArgsValue = input.args;
+    let rawArgs = [];
+    if (typeof rawArgsValue === 'string') {
+        rawArgs = parseArgString(rawArgsValue);
+    }
+    else if (Array.isArray(rawArgsValue)) {
+        rawArgs = rawArgsValue.map((v) => String(v));
+    }
+    const positionalValue = input._;
+    const positional = Array.isArray(positionalValue) ? positionalValue.map((v) => String(v)) : [];
+    const keys = Object.keys(input)
+        .filter((k) => k !== 'args' && k !== '_' && input[k] !== undefined)
+        .sort();
+    const flags = [];
+    for (const key of keys) {
+        const value = input[key];
+        const flag = key.startsWith('-') ? key : `--${key}`;
+        if (value === null || value === undefined)
+            continue;
+        if (typeof value === 'boolean') {
+            if (value)
+                flags.push(flag);
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item === null || item === undefined)
+                    continue;
+                if (typeof item === 'boolean') {
+                    if (item)
+                        flags.push(flag);
+                }
+                else {
+                    flags.push(flag, String(item));
+                }
+            }
+            continue;
+        }
+        if (typeof value === 'object') {
+            flags.push(flag, JSON.stringify(value));
+            continue;
+        }
+        flags.push(flag, String(value));
+    }
+    return [...flags, ...positional, ...rawArgs];
+}
+function trimOutput(out, limit = 12000, totalLength) {
+    const total = typeof totalLength === 'number' ? totalLength : out.length;
+    if (total <= limit)
         return { text: out, truncated: false };
-    return { text: out.slice(0, limit) + `\n...[truncated ${out.length - limit} chars]`, truncated: true };
+    return { text: out.slice(0, limit) + `\n...[truncated ${total - limit} chars]`, truncated: true };
+}
+async function runProcess(command, args, options) {
+    const outputCaptureLimit = 120000;
+    let stdout = '';
+    let stderr = '';
+    let stdoutTotal = 0;
+    let stderrTotal = 0;
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const capture = (kind, chunk) => {
+        const text = chunk.toString('utf8');
+        if (kind === 'stdout') {
+            stdoutTotal += text.length;
+            if (stdout.length < outputCaptureLimit)
+                stdout += text.slice(0, outputCaptureLimit - stdout.length);
+        }
+        else {
+            stderrTotal += text.length;
+            if (stderr.length < outputCaptureLimit)
+                stderr += text.slice(0, outputCaptureLimit - stderr.length);
+        }
+    };
+    child.stdout?.on('data', (chunk) => capture('stdout', chunk));
+    child.stderr?.on('data', (chunk) => capture('stderr', chunk));
+    const exit = await new Promise((resolvePromise, rejectPromise) => {
+        child.on('error', (err) => rejectPromise(err));
+        child.on('close', (code, signal) => resolvePromise({ exitCode: code, signal }));
+    });
+    const totalLength = stdoutTotal + stderrTotal + (stdoutTotal > 0 && stderrTotal > 0 ? 1 : 0);
+    return { stdout, stderr, exitCode: exit.exitCode, signal: exit.signal, totalLength };
 }
 async function main() {
     const args = parseCliArgs(process.argv);
@@ -211,40 +518,69 @@ async function main() {
     if (scriptNames.length === 0) {
         console.error(`npm-run-mcp-server: No scripts found in ${pkgJsonPath}`);
     }
+    const { config: mcpConfig, configPath: mcpConfigPath } = await readProjectMcpConfig(projectDir, verbose, typeof args.config === 'string' ? String(args.config) : undefined);
+    const filteredScriptNames = filterScriptNames(scriptNames, mcpConfig);
+    if (filteredScriptNames.length === 0) {
+        const hint = mcpConfig.include?.length
+            ? 'Check your config "include"/"exclude" settings.'
+            : 'Check your package.json "scripts" section.';
+        console.error(`npm-run-mcp-server: No scripts selected for exposure. ${hint}`);
+    }
+    if (verbose && mcpConfig.include?.length) {
+        const missing = mcpConfig.include.filter((name) => !scripts[name]);
+        if (missing.length > 0) {
+            console.error(`[mcp] include list references missing scripts: ${missing.join(', ')}`);
+        }
+    }
+    const toolNameToScripts = new Map();
+    for (const scriptName of filteredScriptNames) {
+        const overrideName = mcpConfig.scripts?.[scriptName]?.toolName;
+        const toolName = normalizeToolName(overrideName ?? scriptName);
+        const existing = toolNameToScripts.get(toolName) ?? [];
+        existing.push(scriptName);
+        toolNameToScripts.set(toolName, existing);
+    }
+    const collisions = Array.from(toolNameToScripts.entries()).filter(([, names]) => names.length > 1);
+    if (collisions.length > 0) {
+        console.error('npm-run-mcp-server: Tool name collisions detected. Set "scripts.<name>.toolName" in npm-run-mcp.config.json to disambiguate.');
+        for (const [toolName, names] of collisions) {
+            console.error(`  ${toolName}: ${names.join(', ')}`);
+        }
+        process.exit(1);
+    }
     if (args['list-scripts']) {
-        for (const name of scriptNames) {
+        for (const name of filteredScriptNames) {
             console.error(`${name}: ${scripts[name]}`);
         }
         process.exit(0);
     }
     // Register a tool per script
-    for (const scriptName of scriptNames) {
+    for (const scriptName of filteredScriptNames) {
         // Sanitize tool name - MCP tools can only contain [a-z0-9_-]
-        const toolName = scriptName.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+        const configForScript = mcpConfig.scripts?.[scriptName];
+        const toolName = normalizeToolName(configForScript?.toolName ?? scriptName);
         // 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 }) => {
-            const command = buildRunCommand(pm, scriptName, extraArgs);
+        const description = configForScript?.description ?? `Run npm script "${scriptName}": ${scriptCommand}`;
+        server.registerTool(toolName, {
+            description,
+            inputSchema: buildToolInputSchema(configForScript),
+        }, async (input) => {
+            const extraArgs = toolInputToExtraArgs(input);
+            const { command, args: runArgs } = buildRunCommand(pm, scriptName, extraArgs);
             try {
-                const { stdout, stderr } = await exec(command, {
+                const { stdout, stderr, exitCode, signal, totalLength } = await runProcess(command, runArgs, {
                     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);
+                const succeeded = exitCode === 0;
+                const failurePrefix = succeeded
+                    ? ''
+                    : `Command failed (exit=${exitCode}${signal ? `, signal=${signal}` : ''}): ${command} ${runArgs.join(' ')}`;
+                const combinedWithStatus = failurePrefix ? [failurePrefix, combined].filter(Boolean).join('\n') : combined;
+                const totalLengthWithStatus = failurePrefix ? totalLength + failurePrefix.length + (combined ? 1 : 0) : totalLength;
+                const { text } = trimOutput(combinedWithStatus, 12000, totalLengthWithStatus);
                 return {
                     content: [
                         {
@@ -255,11 +591,8 @@ async function main() {
                 };
             }
             catch (error) {
-                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);
+                const { text } = trimOutput(message);
                 return {
                     content: [
                         {
@@ -273,33 +606,43 @@ async function main() {
     }
     const transport = new StdioServerTransport();
     if (verbose) {
-        console.error(`[mcp] registered ${scriptNames.length} tools; awaiting stdio client...`);
+        console.error(`[mcp] registered ${filteredScriptNames.length} tools; awaiting stdio client...`);
     }
     await server.connect(transport);
     if (verbose) {
         console.error(`[mcp] stdio transport connected (waiting for initialize)`);
     }
-    // Set up file watcher for package.json changes
-    if (pkgJsonPath) {
+    // Set up file watcher for package/config changes
+    const watchers = [];
+    const watchPath = (pathToWatch, label) => {
         if (verbose) {
-            console.error(`[mcp] setting up file watcher for: ${pkgJsonPath}`);
+            console.error(`[mcp] setting up file watcher for ${label}: ${pathToWatch}`);
         }
-        const watcher = watch(pkgJsonPath, (eventType) => {
-            if (eventType === 'change') {
-                if (verbose) {
-                    console.error(`[mcp] package.json changed, restarting server...`);
-                }
-                // Gracefully exit to allow the MCP client to restart the server
-                process.exit(0);
+        watchers.push(watch(pathToWatch, (eventType) => {
+            if (eventType !== 'change')
+                return;
+            if (verbose) {
+                console.error(`[mcp] ${label} changed, restarting server...`);
             }
-        });
-        // Handle cleanup on process exit
+            // Gracefully exit to allow the MCP client to restart the server
+            process.exit(0);
+        }));
+    };
+    if (pkgJsonPath)
+        watchPath(pkgJsonPath, 'package.json');
+    if (mcpConfigPath)
+        watchPath(mcpConfigPath, 'config');
+    if (watchers.length > 0) {
+        const cleanup = () => {
+            for (const watcher of watchers)
+                watcher.close();
+        };
         process.on('SIGINT', () => {
-            watcher.close();
+            cleanup();
             process.exit(0);
         });
         process.on('SIGTERM', () => {
-            watcher.close();
+            cleanup();
             process.exit(0);
         });
     }

package/npm-run-mcp.config.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/fstubner/npm-run-mcp-server/main/npm-run-mcp.config.schema.json",
+  "title": "npm-run-mcp-server config",
+  "description": "Controls which package.json scripts are exposed as MCP tools, plus optional per-script metadata.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Exact script names to include. If omitted, all scripts are eligible (subject to exclude)."
+    },
+    "exclude": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Exact script names to exclude."
+    },
+    "scripts": {
+      "type": "object",
+      "description": "Per-script tool metadata overrides.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "toolName": {
+            "type": "string",
+            "description": "Override the generated tool name (after sanitization)."
+          },
+          "description": {
+            "type": "string",
+            "description": "Override the tool description."
+          },
+          "argsDescription": {
+            "type": "string",
+            "description": "Description shown for the `args` input field."
+          },
+          "inputSchema": {
+            "type": "object",
+            "description": "JSON Schema for additional tool inputs; keys are converted to CLI flags. `args` is always available."
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "npm-run-mcp-server",
-  "version": "0.2.9",
+  "version": "0.2.11",
+  "mcpName": "io.github.fstubner/npm-run-mcp-server",
   "description": "An MCP server that exposes package.json scripts as tools for agents.",
   "bin": {
     "npm-run-mcp-server": "dist/index.js"
@@ -11,19 +12,24 @@
   },
   "files": [
     "dist/index.js",
-    "dist/index.d.ts"
+    "dist/index.d.ts",
+    "dist/index.d.ts.map",
+    "npm-run-mcp.config.schema.json"
   ],
   "scripts": {
     "build": "node scripts/build.cjs",
     "start": "node ./dist/index.js",
-    "test": "node dist/index.js --list-scripts && echo 'MCP server test completed successfully'",
+    "test:integration": "node scripts/integration-test.mjs",
+    "test": "node dist/index.js --list-scripts && node scripts/integration-test.mjs && echo 'MCP server test completed successfully'",
     "prepublishOnly": "npm run build"
   },
   "engines": {
     "node": ">=18.18.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "cross-spawn": "^7.0.5",
+    "jsonc-parser": "^3.3.1",
     "zod": "^3.23.8"
   },
   "bundledDependencies": [
@@ -31,7 +37,8 @@
   ],
   "devDependencies": {
     "typescript": "^5.4.0",
-    "@types/node": "^20.14.9"
+    "@types/node": "^20.14.9",
+    "@types/cross-spawn": "^6.0.6"
   },
   "keywords": [
     "mcp",