npm-run-mcp-server

npm-run-mcp-server

npm-run-mcp-server は、プロジェクトの npm スクリプトを AI アシスタントに自動的に橋渡しする Model Context Protocol (MCP) サーバーです。

• 🔍 プロジェクトの 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. 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 はすぐに使えますが、eject や publish など、すべてのスクリプトに AI がアクセスできるようにしたくない場合もあるでしょう。プロジェクトのルートに 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 に出力します。

---

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

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