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