Npm Run MCP Server

🚀 npm-run-mcp-server

既存のpackage.jsonスクリプトを使用して、AIエージェントにプロジェクトのビルド、テスト、デプロイを行う機能を付与します。

npm-run-mcp-server は、Model Context Protocol (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 を自動検出し、AIアシスタントとの橋渡しを行います。
• 複数のパッケージマネージャー（npm、pnpm、yarn、bun）に対応しています。
• 特定のスクリプトをホワイトリストに登録することで、安全に使用できます。
• ゼロコンフィグですぐに使え、詳細な設定も可能です。

📦 インストール

グローバルインストールは不要で、npx を使って直接実行できます。

📚 ドキュメント

🛠️ 設定

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フラグにマッピングされます）。

📖 動作原理

1. 自動検出：サーバーが起動すると、現在のワークスペース内の package.json を探します。標準的な形式と npm、pnpm、yarn、bun の規則に対応しています。
2. ツール作成：スクリプトをMCPツールに変換します。
   • test:unit のようなスクリプトは test_unit のようなツールになります。
   • ツールの説明には実際のコマンド（例：vitest run）が含まれるため、AIは実行する内容を知ることができます。
3. 実行：AIがツールを呼び出すと、サーバーは検出されたパッケージマネージャーを使用してプロジェクトのルートディレクトリでスクリプトを実行します。

🔧 高度な使用法 / 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