Npm Run MCP Server

🚀 npm-run-mcp-server

借助现有的package.json脚本，让你的AI代理具备构建、测试和部署项目的能力。

npm-run-mcp-server 是一个 模型上下文协议 (MCP) 服务器，它能自动将项目的 npm 脚本与你的AI助手连接起来。

• 🔍 自动检测：自动检测项目的 package.json 文件（无需硬编码路径）。
• 📦 广泛兼容：支持 npm、pnpm、yarn 和 bun。
• 🔒 安全可配置：可设置特定脚本的白名单，防止意外执行。
• ⚡ 零配置：开箱即用，也支持详细配置。

🚀 快速开始

在几秒钟内将你的代理连接到脚本。无需全局安装，让 npx 来处理一切。

Claude Desktop

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

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

Cursor

1. 进入 设置 > 功能 > MCP 服务器。
2. 点击 + 添加新的 MCP 服务器。
3. 输入详细信息：
   • 类型：command
   • 名称：npm-scripts
   • 命令：npx
   • 参数：-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"]
    }
  }
}

✨ 主要特性

• 自动检测：服务器启动时，会在当前工作区中查找 package.json 文件，支持标准格式以及 npm、pnpm、yarn 和 bun 的约定。
• 工具创建：将脚本转换为 MCP 工具，例如 test:unit 会变成 test_unit 工具，工具描述中包含实际命令，方便 AI 了解要运行的内容。
• 执行机制：当 AI 调用工具时，服务器会使用检测到的包管理器在项目根目录中执行脚本。

📦 安装指南

无需全局安装，使用 npx 即可：

npx 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" }
        }
      }
    }
  }
}

配置选项

每个脚本的选项

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

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

🔧 高级 / CLI 使用

你可以手动运行服务器进行调试，或传递特定标志：

# 直接运行
npx npm-run-mcp-server --list-scripts

# 在特定目录中运行
npx npm-run-mcp-server --cwd /path/to/project

# 强制使用特定的包管理器
npx npm-run-mcp-server --pm pnpm

CLI 标志

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

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

1. 分叉仓库。
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add some amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开拉取请求。

📄 许可证

MIT © Felix Stubner