npm-run-mcp-server

npm-run-mcp-server

npm-run-mcp-server 是一个 Model Context Protocol (MCP) 服务，可自动将项目的 npm 脚本接入 AI 助手。

• 🔍 自动检测项目的 package.json（无需硬编码路径）。
• 📦 兼容各种工具：npm、pnpm、yarn 和 bun。
• 🔒 安全且可配置：将特定脚本加入白名单，防止意外执行。
• ⚡ 零配置：开箱即用，也可通过详细配置满足更多需求。

---

⚡ 快速开始

几秒钟内即可将 Agent 连接到脚本。无需全局安装，只需让 npx 来处理即可。

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"]
    }
  }
}

Cursor

1. 前往 Settings > Features > MCP Servers。
2. 点击 + Add New MCP Server。
3. 输入详细信息：
   • Type：command
   • Name：npm-scripts
   • Command：npx
   • Args：-y npm-run-mcp-server

VS Code（GitHub Copilot）

将以下内容添加到工作区的 .vscode/settings.json：

{
  "github.copilot.chat.mcpServers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"]
    }
  }
}

---

🛠️ 配置

虽然 npm-run-mcp-server 开箱即用，但你可能不希望 AI 访问所有脚本（例如 eject 或 publish）。你可以在项目根目录中创建 npm-run-mcp.config.json 文件来控制访问权限。

配置示例

在 package.json 旁边创建 npm-run-mcp.config.json：

{
  "include": ["test", "lint", "build", "start"],
  "scripts": {
    "test": {
      "description": "Run the test suite. Use --watch for interactive mode.",
      "inputSchema": {
        "properties": {
          "watch": { "type": "boolean", "description": "Watch files for changes" }
        }
      }
    }
  }
}

配置选项

字段	类型	描述
include	string[]	要公开的脚本名称白名单。若省略，则公开所有脚本。
exclude	string[]	要隐藏的脚本名称黑名单。
scripts	object	特定脚本的详细配置。

每个脚本的选项

在 scripts 对象中，你可以将脚本名称映射到：

• toolName：覆盖 AI 看到的工具名称（例如，将 test:unit 重命名为 run_unit_tests）。
• description：提供自定义描述，帮助 AI 了解何时使用此脚本。
• inputSchema：定义严格类型的参数，供 AI 传入（映射到 CLI 标志）。

---

📖 工作原理

1. 自动检测：服务启动时，会在当前工作区中查找 package.json。它支持标准格式以及 npm、pnpm、yarn 和 bun 约定。
2. 创建工具：它会将你的脚本转换为 MCP 工具。
   • 类似 test:unit 的脚本会变为类似 test_unit 的工具。
   • 工具描述会包含实际命令（例如 vitest run），让 AI 知道它将运行什么。
3. 执行：AI 调用工具时，服务会使用检测到的包管理器，在项目根目录中执行脚本。

---

🔧 高级用法 / CLI 用法

你可以手动运行服务以进行调试，或在需要传递特定标志时手动运行。

# Run directly
npx npm-run-mcp-server --list-scripts

# Run in a specific directory
npx npm-run-mcp-server --cwd /path/to/project

# Force a specific package manager
npx npm-run-mcp-server --pm pnpm

CLI 标志

• --cwd <path>：手动设置工作目录。
• --pm <npm|pnpm|yarn|bun>：强制使用指定的包管理器。
• --config <path>：指定 JSON 配置文件的路径。
• --verbose：将调试日志打印到 stderr。

---

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add some amazing feature'）。
4. 推送到该分支（git push origin feature/amazing-feature）。
5. 发起 Pull Request。

许可证

MIT © Felix Stubner