📦 NPM Helper - A tool to help your ai assistant with npm package management.🤖

📦 NPM Helper - AI アシスタントの npm パッケージ管理を支援するツールです。🤖

NPM 依存関係管理のための Model Context Protocol サーバーです。このサーバーは、NPM パッケージの検索や npm パッケージの更新に役立つツールを提供します。プロジェクトの依存関係を競合や面倒な手間なく最新の互換バージョンに更新し、常に最新の状態に保てます。

安全にプロジェクトの package.json をアップグレードするための基本的な方法として、アシスタントは 'peer' パラメーターを true に設定して upgradePackagets ツールを呼び出せます。この方法では、すべての依存関係が最新バージョンに更新されるとは限りませんが、エラーを起こすことなく、最新の互換バージョンに安全にアップグレードできます。

すべての依存関係を完全にアップグレードしたい場合、アシスタントは安全に調査するための多くのツールとパラメーターを利用できます。パラメーターのオプションと例は、以下の「利用可能なツール」セクションに記載されています。詳しくは「docs」ディレクトリもご覧ください。

プロジェクトに追加する新しいパッケージを検討している場合や、特定のパッケージについて情報を調べたい場合に、npmjs の情報を検索・取得するツールも利用できます。

✨ 機能

npm-check-updates ツール

• 🔍 checkUpdates：package.json をスキャンして古い依存関係を確認します
• 🚀 upgradePackages：依存関係を最新バージョンにアップグレードします
• 🔎 filterUpdates：特定のパッケージの更新を確認します
• 🔄 resolveConflicts：依存関係の競合を解決します
• ⚙️ setVersionConstraints：バージョンアップグレードのルールを設定します
• 🩺 runDoctor：アップグレードとテストを反復的に実行し、破壊的変更を検出します

NPM 検索ツール

• 🔍 searchPackages：npmjs.org レジストリでパッケージを検索します
• 📝 fetchPackageContent：npm パッケージページをスクレイピングし、コンテンツを抽出します
• 📋 getPackageVersions：パッケージのバージョン履歴を取得します
• 📝 getPackageDetails：パッケージの詳細なメタデータを取得します

🚀 npm-helper-mcp インストールガイド

このガイドでは、npm-helper-mcp サーバーのセットアップと実行方法を説明します。

📋 前提条件

始める前に、以下がインストールされていることを確認してください。

• Node.js（バージョン 18.x 以降）
• npm（バージョン 8.x 以降）

🔧 設定

npm-helper-mcp サーバーは Model Context Protocol を実装しており、このプロトコルに対応する LLM アプリケーションと通信できます。

設定方法はアプリケーションによって異なります。一般的に、ほとんどの MCP クライアントアプリケーションには .json 設定ファイルがあるか、サーバーを実行するコマンドを入力する場所があります。通常は、この 2 つの方法のいずれかで設定できます。

オプション 1：npx で実行

サーバーを使用する最も簡単な方法は、ローカルへのインストールが不要な npx で実行することです。お使いの MCP クライアントに応じて、次の 2 つの方法のいずれかを使用してください。

1. json 設定をコピーして、アプリケーションの MCP 設定ファイルに貼り付けます。

{
    "mcpServers": {
      "npm-helper": {
        "command": "npx",
        "args": [
            "-y",
            "@pinkpixel/npm-helper-mcp"
        ]
      }
    }
  }

2. アプリケーションの MCP 設定画面で、サーバーを実行するコマンドを入力します。

  npx -y @pinkpixel/npm-helper-mcp

オプション 2：ローカルインストール

サーバーをローカルにインストールする場合は、次のコマンドを実行します。

# Install the package globally
npm install -g npm-helper-mcp

設定：

1. json 設定をコピーして、アプリケーションの MCP 設定ファイルに貼り付けます。

{
    "mcpServers": {
      "npm-helper": {
        "command": "npx",
        "args": [
            "-y",
            "@pinkpixel/npm-helper-mcp"
        ]
      }
    }
  }

2. アプリケーションの MCP 設定画面で、サーバーを実行するコマンドを入力します。

  npm-helper-mcp

オプション 3：ソースからインストール

# Clone the repository
git clone https://github.com/pinkpixel-dev/npm-helper-mcp.git
cd npm-helper-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Optionally run/test the server
npm start

設定：

1. JSON 設定をコピーして、アプリケーションの MCP 設定ファイルに貼り付けます。

{
    "mcpServers": {
      "npm-helper": {
        "command": "node",
        "args": [
            "/path/to/npm-helper-mcp/dist/index.js"
        ]
      }
    }
  }

2. アプリケーションの MCP 設定で、サーバーを実行するコマンドを入力します。

 node /path/to/npm-helper-mcp/dist/index.js

LLM での使用

このサーバーは Model Context Protocol に準拠しているため、Claude などの LLM で使用できます。LLM はサーバーのツールを使用して、さまざまな npm 操作を実行できます。

利用可能なツール

ツール：check_updates

package.json をスキャンして、古くなった依存関係を確認します。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• filter（任意）：確認するパッケージ名のリスト
• reject（任意）：除外するパッケージ名のリスト
• target（任意）：アップグレード先のバージョン（latest、newest、greatest、minor、patch、semver）
• interactive（任意）：更新を選択するための対話モードを有効にします
• peer（任意）：インストール済みパッケージのピア依存関係を確認します
• minimal（任意）：バージョン範囲をすでに満たしている新しいバージョンにはアップグレードしません
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "check_updates",
  "arguments": {
    "packagePath": "./package.json",
    "filter": ["react", "lodash"],
    "peer": true,
    "minimal": true,
    "packageManager": "npm"
  }
}

ツール：upgrade_packages

依存関係を最新バージョンにアップグレードします。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• upgradeType（任意）：アップグレード先のバージョン（latest、newest、greatest、minor、patch、semver）
• interactive（任意）：更新を選択するための対話モードを有効にします
• peer（任意）：インストール済みパッケージのピア依存関係を確認します
• minimal（任意）：バージョン範囲をすでに満たしている新しいバージョンにはアップグレードしません
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "upgrade_packages",
  "arguments": {
    "upgradeType": "minor",
    "peer": true,
    "minimal": true,
    "packageManager": "yarn"
  }
}

ツール：filter_updates

指定したパッケージの更新を確認します。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• filter（必須）：確認するパッケージ名のリスト
• upgrade（任意）：package.json ファイルをアップグレードするか、確認のみ行うかを指定します
• minimal（任意）：バージョン範囲をすでに満たしている新しいバージョンにはアップグレードしません
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "filter_updates",
  "arguments": {
    "filter": ["react", "react-dom"],
    "upgrade": false,
    "minimal": true
  }
}

ツール：resolve_conflicts

ピア依存関係を使用して、依存関係の競合を処理します。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• upgrade（任意）：package.json ファイルをアップグレードするか、確認のみ行うかを指定します
• minimal（任意）：バージョン範囲をすでに満たしている新しいバージョンにはアップグレードしません
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "resolve_conflicts",
  "arguments": {
    "upgrade": true,
    "packageManager": "npm"
  }
}

ツール：set_version_constraints

バージョンアップグレードのルールを設定します。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• target（必須）：対象バージョンの制約戦略（latest、newest、greatest、minor、patch、semver）
• removeRange（任意）：最終的なパッケージバージョンからバージョン範囲を削除します
• upgrade（任意）：package.json ファイルをアップグレードするか、確認のみ行うかを指定します
• minimal（任意）：バージョン範囲をすでに満たしている新しいバージョンにはアップグレードしません
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "set_version_constraints",
  "arguments": {
    "target": "minor",
    "removeRange": false,
    "upgrade": true,
    "packageManager": "pnpm"
  }
}

ツール：run_doctor

アップグレードを反復的にインストールしてテストを実行し、破壊的なアップグレードを特定します。破壊的なアップグレードは自動的に元に戻し、問題のないアップグレードは維持します。

パラメーター：

• packagePath（任意）：package.json ファイルへのパス（デフォルト：./package.json）
• doctorInstall（任意）：使用するカスタムインストールスクリプト（デフォルト：'npm install' または 'yarn'）
• doctorTest（任意）：使用するカスタムテストスクリプト（デフォルト：'npm test'）
• packageManager（任意）：使用するパッケージマネージャー（npm、yarn、pnpm、deno、bun、staticRegistry）

例：

{
  "name": "run_doctor",
  "arguments": {
    "packagePath": "./package.json",
    "doctorInstall": "npm ci",
    "doctorTest": "npm run test:ci",
    "packageManager": "npm"
  }
}

ツール：search_npm

npm パッケージを検索します。

パラメーター：

• query（必須）：npm パッケージの検索クエリ
• maxResults（任意）：返す結果の最大数（デフォルト：10）

例：

{
  "name": "search_npm",
  "arguments": {
    "query": "react state management",
    "maxResults": 5
  }
}

ツール：fetch_package_content

npm パッケージのページから詳細なコンテンツを取得して解析します。

パラメーター：

• url（必須）：npm パッケージのページの URL

例：

{
  "name": "fetch_package_content",
  "arguments": {
    "url": "https://www.npmjs.com/package/react"
  }
}

ツール：get_package_versions

npm パッケージで利用可能なバージョンを取得します。

パラメーター：

• packageName（必須）：npm パッケージの名前

例：

{
  "name": "get_package_versions",
  "arguments": {
    "packageName": "react"
  }
}

ツール：get_package_details

npm パッケージの詳細情報を取得します。

パラメーター：

• packageName（必須）：npm パッケージの名前

例：

{
  "name": "get_package_details",
  "arguments": {
    "packageName": "react"
  }
}

📝 レスポンス形式

すべてのツールは標準形式でレスポンスを返します。

{
  "status": "success" | "error",
  "data": {}, // Tool-specific data
  "message": "Human-readable message"
}

🆘 トラブルシューティング

接続の問題**：

• LLM アプリケーションが Model Context Protocol を使用するよう正しく設定されていることを確認してください。
• .json ファイルにエラーがないか確認するか、起動コマンドが正しいことを確認してください。
• ローカルで実行している場合は、index.js ファイルへのパスを確認してください。必要に応じて絶対パスを使用してください。

ヘルプを受ける

ここに記載されていない問題が発生した場合：

• 同様の問題と解決策がないか、GitHub の issueを確認してください。
• 問題の詳細な説明を添えて、新しい issue を作成してください。

📄 ライセンス

MIT

🙏 クレジット

• npm-check-updates
• @modelcontextprotocol/sdk

❤️ を込めて Pink Pixel が作成