npm-run-mcp-server 0.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,308 @@
+# npm-run-mcp-server
+
+<div align="center">
+
+*A Model Context Protocol (MCP) server that exposes your project's `package.json` scripts as tools for AI agents.*
+
+[![Test](https://github.com/fstubner/npm-run-mcp-server/workflows/Test/badge.svg)](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/test.yml)
+[![Build & Publish](https://github.com/fstubner/npm-run-mcp-server/workflows/Build%20&%20Publish/badge.svg)](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/build-and-publish.yml)
+[![NPM Version](https://img.shields.io/npm/v/npm-run-mcp-server.svg)](https://www.npmjs.com/package/npm-run-mcp-server)
+[![NPM Installs](https://img.shields.io/npm/dt/npm-run-mcp-server.svg)](https://www.npmjs.com/package/npm-run-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+
+
+## Table of Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [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)
+  - [Cursor](#cursor)
+  - [Install from source](#install-from-source)
+- [Testing with MCP Inspector](#testing-with-mcp-inspector)
+- [CLI Options](#cli-options)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+```bash
+npm i -D npm-run-mcp-server
+# or globally
+npm i -g npm-run-mcp-server
+# ad-hoc
+npx npm-run-mcp-server
+```
+
+## Usage
+
+### As an MCP Server
+
+Add this server to your MCP host configuration. It uses stdio and dynamically exposes each script from the closest `package.json` (walking up from `process.cwd()`).
+
+The tool names match your script names. Each tool accepts an optional `args` string that is appended after `--` when running the script. The server detects your package manager (npm, pnpm, yarn, bun).
+
+### As a CLI Tool
+
+You can also use this package directly from the command line:
+
+```bash
+# List available scripts in current directory
+npx npm-run-mcp-server --list-scripts
+
+# Run with verbose output
+npx npm-run-mcp-server --verbose
+
+# Specify a different working directory
+npx npm-run-mcp-server --cwd /path/to/project --list-scripts
+
+# Override package manager detection
+npx npm-run-mcp-server --pm yarn --list-scripts
+```
+
+## Configuration
+
+### Install in GitHub Copilot Chat (VS Code)
+
+Option A — per-workspace via `.vscode/mcp.json` (recommended for multi-project use):
+
+```json
+{
+  "servers": {
+    "npm-scripts": {
+      "command": "npx",
+      "args": ["-y", "npm-run-mcp-server"]
+    }
+  }
+}
+```
+
+Option B — user settings (`settings.json`):
+
+```json
+{
+  "mcp.servers": {
+    "npm-scripts": {
+      "command": "npx",
+      "args": ["-y", "npm-run-mcp-server"]
+    }
+  }
+}
+```
+
+**Note**: The server automatically detects the current project's `package.json` using `process.cwd()`, so 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**: Use workspace settings (`.vscode/mcp.json` or `.vscode/settings.json`) - the server automatically targets the current project
+- **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
+- **Automatic Detection**: The server walks up the directory tree to find the nearest `package.json`
+
+This means you can use the same MCP configuration across all your projects, and the server will automatically target the correct project based on where your MCP client is running.
+
+### Install in Claude Code (VS Code extension)
+
+Add to VS Code user/workspace settings (`settings.json`):
+
+```json
+{
+  "claude.mcpServers": {
+    "npm-scripts": {
+      "command": "npx",
+      "args": ["-y", "npm-run-mcp-server"]
+    }
+  }
+}
+```
+
+**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.
+
+### 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.
+
+- 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": {
+    "npm-scripts": {
+      "command": "npx",
+      "args": ["-y", "npm-run-mcp-server"]
+    }
+  }
+}
+```
+
+**Alternative** - Using a local build (requires absolute path):
+
+```json
+{
+  "mcpServers": {
+    "npm-scripts": {
+      "command": "node",
+      "args": ["/absolute/path/to/npm-run-mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+**Note**: The npx approach is recommended as it automatically targets the current working directory where Claude is launched.
+
+Optional: include environment variables
+
+```json
+{
+  "mcpServers": {
+    "npm-scripts": {
+      "command": "npx",
+      "args": ["-y", "npm-run-mcp-server"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+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.
+
+### Install from source (for testing in another project)
+
+Clone, build, and link globally:
+
+```bash
+git clone https://github.com/your-org-or-user/npm-run-mcp-server.git
+cd npm-run-mcp-server
+npm install
+npm run build
+npm link
+```
+
+In your other project, either reference the global binary or the built file directly:
+
+- Using the linked binary:
+
+```json
+{
+  "servers": {
+    "npm-scripts": {
+      "command": "npm-run-mcp-server"
+    }
+  }
+}
+```
+
+- Using an explicit Node command (no global link needed):
+
+```json
+{
+  "servers": {
+    "npm-scripts": {
+      "command": "node",
+      "args": ["/absolute/path/to/npm-run-mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Optional CLI flags you can pass in `args`:
+- `--cwd /path/to/project` to choose which project to read `package.json` from (rarely needed - server auto-detects by default)
+- `--pm npm|pnpm|yarn|bun` to override package manager detection
+
+## Testing with MCP Inspector
+
+Test the server locally before integrating with AI agents:
+
+```bash
+# Start MCP Inspector
+npx @modelcontextprotocol/inspector
+
+# In the Inspector UI:
+# 1. Transport Type: STDIO
+# 2. Command: npx
+# 3. Arguments: npm-run-mcp-server --cwd /path/to/your/project --verbose
+# 4. Click "Connect"
+```
+
+You should see your package.json scripts listed as available tools. Try running one - it executes the script and returns the output.
+
+## CLI Options
+
+Available command-line flags:
+
+- `--cwd <path>` - Specify working directory (defaults to current directory)
+- `--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:
+
+### Reporting Issues
+
+- Use the [issue tracker](https://github.com/fstubner/npm-run-mcp-server/issues) to report bugs
+- Include your Node.js version, package manager, and operating system
+- Provide a minimal reproduction case when possible
+
+### Submitting Changes
+
+1. **Fork** the repository
+2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
+3. **Make** your changes and add tests if applicable
+4. **Test** your changes: `npm run build && npm run test`
+5. **Commit** your changes: `git commit -m 'Add amazing feature'`
+6. **Push** to the branch: `git push origin feature/amazing-feature`
+7. **Submit** a pull request
+
+### Development Setup
+
+```bash
+git clone https://github.com/fstubner/npm-run-mcp-server.git
+cd npm-run-mcp-server
+npm install
+npm run build
+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
+
+

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } 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 { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+const exec = promisify(nodeExec);
+function parseCliArgs(argv) {
+    const args = {};
+    for (let i = 2; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token)
+            continue;
+        if (token.startsWith('--')) {
+            const key = token.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                args[key] = next;
+                i += 1;
+            }
+            else {
+                args[key] = true;
+            }
+        }
+    }
+    return args;
+}
+async function findNearestPackageJson(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        const candidate = resolve(current, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+async function readPackageJson(pathToPackageJson) {
+    const raw = await fsp.readFile(pathToPackageJson, 'utf8');
+    return JSON.parse(raw);
+}
+function detectPackageManager(projectDir, pkg, override) {
+    if (override)
+        return override;
+    // Prefer explicit packageManager field if present
+    if (pkg.packageManager) {
+        const pm = pkg.packageManager.split('@')[0];
+        if (pm === 'npm' || pm === 'pnpm' || pm === 'yarn' || pm === 'bun')
+            return pm;
+    }
+    // Lockfile heuristic
+    if (existsSync(resolve(projectDir, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(resolve(projectDir, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(resolve(projectDir, 'bun.lockb')) || existsSync(resolve(projectDir, 'bun.lock')))
+        return 'bun';
+    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}`;
+    }
+}
+function trimOutput(out, limit = 12000) {
+    if (out.length <= limit)
+        return { text: out, truncated: false };
+    return { text: out.slice(0, limit) + `\n...[truncated ${out.length - limit} chars]`, truncated: true };
+}
+async function main() {
+    const args = parseCliArgs(process.argv);
+    const startCwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+    const pkgJsonPath = await findNearestPackageJson(startCwd);
+    if (!pkgJsonPath) {
+        console.error(`npm-run-mcp-server: No package.json found starting from ${startCwd}`);
+        process.exit(1);
+    }
+    const projectDir = dirname(pkgJsonPath);
+    const projectPkg = await readPackageJson(pkgJsonPath);
+    const verbose = Boolean(args.verbose ||
+        process.env.MCP_VERBOSE ||
+        (process.env.DEBUG && process.env.DEBUG.toLowerCase().includes('mcp')));
+    if (verbose) {
+        console.error(`[mcp] server starting: cwd=${startCwd}`);
+        console.error(`[mcp] using package.json: ${pkgJsonPath}`);
+    }
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const selfPkgPath = resolve(__dirname, '..', 'package.json');
+    let serverName = 'npm-run-mcp-server';
+    let serverVersion = '0.0.0';
+    try {
+        if (existsSync(selfPkgPath)) {
+            const selfPkg = JSON.parse(readFileSync(selfPkgPath, 'utf8'));
+            if (selfPkg.name)
+                serverName = selfPkg.name;
+            if (selfPkg.version)
+                serverVersion = selfPkg.version;
+        }
+    }
+    catch { }
+    const pm = detectPackageManager(projectDir, projectPkg, args.pm);
+    if (verbose) {
+        console.error(`[mcp] detected package manager: ${pm}`);
+    }
+    const server = new McpServer({ name: serverName, version: serverVersion });
+    const scripts = projectPkg.scripts ?? {};
+    const scriptNames = Object.keys(scripts);
+    if (scriptNames.length === 0) {
+        console.error(`npm-run-mcp-server: No scripts found in ${pkgJsonPath}`);
+    }
+    if (args['list-scripts']) {
+        for (const name of scriptNames) {
+            console.error(`${name}: ${scripts[name]}`);
+        }
+        process.exit(0);
+    }
+    // Register a tool per script
+    for (const scriptName of scriptNames) {
+        server.tool(scriptName, {
+            description: `Run package script '${scriptName}' via ${pm} in ${projectDir}`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    args: {
+                        type: 'string',
+                        description: 'Optional arguments appended after -- to the script'
+                    }
+                }
+            },
+        }, async ({ args: extraArgs }) => {
+            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) {
+                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,
+                        },
+                    ],
+                };
+            }
+        });
+    }
+    const transport = new StdioServerTransport();
+    if (verbose) {
+        console.error(`[mcp] registered ${scriptNames.length} tools; awaiting stdio client...`);
+    }
+    await server.connect(transport);
+    if (verbose) {
+        console.error(`[mcp] stdio transport connected (waiting for initialize)`);
+    }
+}
+// Run
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "npm-run-mcp-server",
+  "version": "0.1.1",
+  "description": "An MCP server that exposes package.json scripts as tools for agents.",
+  "bin": {
+    "npm-run-mcp-server": "dist/index.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "scripts": {
+    "build": "node scripts/build.cjs",
+    "start": "node ./dist/index.js",
+    "test": "node dist/index.js --list-scripts && echo 'MCP server test completed successfully'",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.14.9"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "npm",
+    "scripts",
+    "ai",
+    "claude",
+    "cursor",
+    "copilot",
+    "automation"
+  ],
+  "author": "fstubner",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fstubner/npm-run-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fstubner/npm-run-mcp-server/issues"
+  },
+  "homepage": "https://github.com/fstubner/npm-run-mcp-server#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}