npm-advisor-mcp

npm-advisor-mcp

インテリジェントな npm パッケージアドバイザーとして機能する、Model Context Protocol（MCP）サーバーです。必要な機能を説明すると、レジストリを検索して候補を比較し、脆弱性を監査したうえで、バンドルサイズ、人気度、メンテナンス状況、TypeScript のサポートなどを基に最適なライブラリをおすすめします。

---

特長

• 機能で検索 — 必要な機能（例：「日付の操作」「PDF 生成」）を説明すると、ランキング形式の検索結果が表示されます
• 並べて比較 — 主要な指標で 2～5 個のパッケージを、見やすい表形式で比較します
• パッケージの詳細情報 — 単一のパッケージについて、README、依存関係、スコア、リンクなどを詳しく確認できます
• 重み付けによるおすすめ — 用途（ブラウザー、Node.js、React、CLI）ごとに重みを動的に調整し、アルゴリズムに基づいて選定します
• セキュリティ監査 — 既知の CVE を重大度の内訳と修正プログラムの提供状況とともに確認します
• 非推奨チェック — 非推奨、放棄、またはメンテナンスされていないパッケージを検出し、明確な判定を示します
• 代替候補を検索 — 非推奨ライブラリから移行する際に、競合するパッケージを見つけます
• インストールコマンドの生成 — peer dependencies を含む、npm、yarn、pnpm、bun 用のコピー＆ペースト可能なコマンドを生成します
• 変更履歴ビューアー — GitHub、GitLab（クラウド版とセルフホスト版）、または Bitbucket から最近のリリースノートを取得します
• 技術的な Q&A — パッケージについて具体的な質問をすると、メタデータに基づいた回答が得られます
• メモリー内キャッシュ — すべての API レスポンスを TTL 付きでキャッシュし、重複したネットワーク呼び出しをなくします

---

アーキテクチャ

npm-advisor-mcp/
├── package.json                  # Project manifest (ESM, Node 18+)
├── tsconfig.json                 # TypeScript strict config (ES2022/Node16)
├── mcp-config.json               # Ready-to-use Kiro MCP configuration snippet
├── src/
│   ├── index.ts                  # MCP server entry point (stdio transport)
│   ├── models/
│   │   └── types.ts              # Shared interfaces and scoring weights
│   ├── services/
│   │   ├── cache.ts              # In-memory TTL cache (2/5/10 min tiers)
│   │   ├── npm-registry.ts       # registry.npmjs.org client
│   │   ├── npm-audit.ts          # npm security advisory API client
│   │   ├── bundlephobia.ts       # Bundle size data (bundlephobia.com)
│   │   ├── npms-io.ts            # Quality/maintenance/popularity scores
│   │   └── scoring.ts            # Weighted recommendation engine + license checker
│   └── tools/
│       ├── search-packages.ts
│       ├── compare-packages.ts
│       ├── package-details.ts
│       ├── recommend.ts
│       ├── resolve-doubt.ts
│       ├── audit-package.ts
│       ├── find-alternatives.ts
│       ├── check-deprecation.ts
│       ├── generate-install-command.ts
│       └── get-changelog.ts
└── dist/                         # Compiled output (generated by `npm run build`)

---

前提条件

• Node.js 18 以降（ネイティブの fetch を使用）
• npm 9 以降

API キーは不要です。すべてのデータソースは公開されており、無料で利用できます。

---

インストール

cd C:\Users\617500221\Projects\AI-Tools\npm-advisor-mcp
npm install
npm run build

---

設定（Kiro MCP）

"mcpServers" オブジェクト内の ~/.kiro/settings/mcp.json に以下を追加します。

"npm-advisor": {
  "command": "node",
  "args": [
    "C:\\Users\\617500221\\Projects\\AI-Tools\\npm-advisor-mcp\\dist\\index.js"
  ],
  "disabled": false,
  "autoApprove": [
    "search_packages",
    "compare_packages",
    "get_package_details",
    "recommend_package",
    "resolve_technical_doubt",
    "audit_package",
    "find_alternatives",
    "check_deprecation",
    "generate_install_command",
    "get_changelog"
  ]
}

保存すると、サーバーが Kiro MCP パネルに表示され、自動的に再接続されます。

---

ツールのリファレンス

1. search_packages

機能やキーワードに一致するパッケージを npm で検索します。

パラメーター	型	必須	説明
query	string	はい	機能またはキーワード（例：「フォーム検証」「状態管理」）
limit	number	いいえ	返す結果の最大数（デフォルト：8、最大：15）

プロンプトの例：

「Node.js で PDF 生成を処理するパッケージを検索して」

戻り値： 説明、週間ダウンロード数、gzip サイズ、品質／メンテナンス／人気度のスコア、ツリーシェイキングのサポートを含むランキング形式のリストです。

---

2. compare_packages

主要な指標を使って、2～5 個のパッケージを並べて比較します。

パラメーター	型	必須	説明
packages	string[]	はい	パッケージ名の配列（2～5 個）

プロンプトの例：

「日付操作に使う dayjs、date-fns、moment を比較して」

戻り値： バージョン、gzip サイズ、最小化後のサイズ、週間ダウンロード数、TypeScript サポート、ツリーシェイキング、依存関係の数、メンテナンススコア、品質スコア、最終公開日、ライセンスを含む Markdown 表です。

---

3. get_package_details

単一のパッケージについて、すべてのメタデータを詳しく確認できます。

パラメーター	型	必須	説明
package_name	string	はい	npm パッケージ名

プロンプトの例：

「zod パッケージの詳細を取得して」

戻り値： バージョン、説明、基本統計の表（ダウンロード数、サイズ、依存関係、TypeScript サポート、ライセンス、公開日）、品質スコア、依存関係の一覧、peer dependencies、リンク、キーワード、README の抜粋です。

---

4. recommend_package

候補リストから重み付けされたおすすめを取得します。スコアの重みは、対象環境に応じて自動的に調整されます。

パラメーター	型	必須	説明
packages	string[]	はい	評価するパッケージ名の配列（2～10 個）
max_size_kb	number	いいえ	許容する gzip サイズの上限（KB）。これを超えるパッケージは減点されます
require_typescript	boolean	いいえ	true の場合、TS 型定義のないパッケージはさらに減点されます
use_case	string	いいえ	browser、node、react、cli、または general。スコアの重みを調整します

プロンプトの例：

「dayjs、date-fns、moment、luxon の中から、gzip 圧縮後 10KB 未満でブラウザーアプリに使える日付ライブラリをおすすめしてください」

返される内容： おすすめの理由、次点の候補、詳細なスコア内訳表、ライセンスの互換性列。

デフォルトのスコアリングの重み（general）

基準	重み	評価内容
バンドルサイズ（gzip）	25%	小さいほど高評価。比較対象グループ内で相対評価します
週間ダウンロード数	20%	コミュニティでの採用状況（対数スケーリング）
メンテナンス状況	20%	npms.io のメンテナンススコア
TypeScript サポート	15%	組み込み型定義（100）＞ @types（60）＞ なし（20）
依存関係の数	10%	実行時依存関係が少ないほどリスクが低くなります
更新状況	10%	公開日が新しいほど高評価です

ユースケースごとの重みの調整

基準	browser	node	react	cli
バンドルサイズ	40%	10%	30%	5%
ダウンロード数	15%	20%	20%	20%
メンテナンス状況	15%	25%	15%	30%
TypeScript	15%	15%	20%	10%
依存関係	10%	20%	10%	20%
更新状況	5%	10%	5%	15%

---

5. resolve_technical_doubt

パッケージに関する具体的な技術的質問に回答します。

パラメーター	型	必須	説明
package_name	string	はい	npm パッケージ名
question	string	はい	技術的な質問

プロンプトの例：

「dayjs は標準でタイムゾーン変換に対応していますか？」 「lodash はツリーシェイキングできますか？」 「@angular/material のピア依存関係は何ですか？」 「chalk は現在も積極的にメンテナンスされていますか？」

返される内容： メタデータ、バンドル分析、依存関係ツリー、スコア、README の内容をもとにした、文脈に応じた回答です。質問のカテゴリー（サイズ、TypeScript、依存関係、メンテナンス状況、ツリーシェイキング）を自動判定し、関連するデータを提示します。

---

6. audit_package

既知のセキュリティ脆弱性がないか、パッケージを確認します。

パラメーター	型	必須	説明
package_name	string	はい	監査する npm パッケージ名

プロンプトの例：

「lodash に既知の脆弱性はありますか？」

返される内容： 脆弱性の総数、深刻度別の内訳（critical／high／moderate／low）、影響を受けるバージョン範囲を含む CVE ごとの詳細、パッチの提供状況、アドバイザリーへのリンク、該当する場合は非推奨の警告です。

---

7. find_alternatives

指定したパッケージに類似するパッケージや競合パッケージを、代替候補として検索します。

パラメーター	型	必須	説明
package_name	string	はい	代替候補を検索する対象のパッケージ
limit	number	いいえ	返す代替候補の上限（デフォルト：6、最大：10）

プロンプトの例：

「moment.js の代替候補を探してください」 「request の代わりに何を使えますか？」

返される内容： 説明、週間ダウンロード数、バンドルサイズ、品質スコア、ツリーシェイキングへの対応状況を含む、順位付けされた代替候補のリストです。元のパッケージが非推奨の場合は、その旨を示します。

---

8. check_deprecation

パッケージが非推奨、メンテナンスされていない、または放棄された可能性があるかを検出します。

Parameter	Type	Required	Description
package_name	string	Yes	確認する npm パッケージ名

プロンプトの例：

「request は現在もメンテナンスされていますか？」 「moment.js は非推奨ですか？」

戻り値： npm の非推奨フラグ、最終公開からの日数、メンテナンススコア、週間ダウンロード数、および「積極的にメンテナンス中」「やや古い」「放棄された可能性あり」「正式に非推奨」の明確な判定です。

---

9. generate_install_command

主要なすべてのパッケージマネージャー向けに、そのまま貼り付けて使えるインストールコマンドを生成します。

Parameter	Type	Required	Description
package_name	string	Yes	npm パッケージ名
include_peer_deps	boolean	No	ピア依存関係を含めます（デフォルト：true）
dev	boolean	No	開発用依存関係としてインストールします（デフォルト：false）

プロンプトの例：

「@tanstack/react-query のインストールコマンドを教えてください」 「pnpm で eslint を開発用依存関係としてインストールするにはどうすればよいですか？」

戻り値： npm、yarn、pnpm、bun 向けのインストールコマンドです。ピア依存関係を自動的に追加し、パッケージに TypeScript 型が組み込まれていない場合は、別途 @types/ のインストールブロックを追加します。

---

10. get_changelog

パッケージの git リポジトリから最近のリリースノートを取得します。GitHub、GitLab（クラウド版とセルフホスト版）、Bitbucket に対応しています。

Parameter	Type	Required	Description
package_name	string	Yes	npm パッケージ名
limit	number	No	表示する最近のリリース数（デフォルト：5、最大：10）

プロンプトの例：

「zod の直近数バージョンでは何が変わりましたか？」 「vite の最近のリリースを見せてください」 「@ATLAS/info-panel の新機能を教えてください」

戻り値： バージョンタグ、公開日、整形されたリリースノート（リリースごとに800文字で切り捨て）を含むリリース履歴です。

Git ホストの検出

このツールはパッケージの package.json から repository フィールドを読み取り、ホストを自動検出します。

Pattern in repository URL	Detected as	API used
github.com/...	GitHub	GitHub Releases API
gitlab.com/...	GitLab クラウド	GitLab Releases API
gitlab.yourcompany.com/...	セルフホスト版 GitLab	GitLab Releases API（パスは同じで、ベース URL が異なります）
git.yourcompany.com/...	セルフホスト版 GitLab	GitLab Releases API
bitbucket.org/...	Bitbucket	Bitbucket Tags API
上記以外	—	npm versions ページへのリンクにフォールバックします

プライベート／社内パッケージに関する注意： このツールは、レジストリから取得したパッケージメタデータの repository フィールドを読み取ります。社内の package.json に repository フィールドがない場合や、git@internal-git:atlas/info-panel のように認識可能なホスト名を含まない SSH URL を使用している場合、ホストを検出できません。次のように完全な HTTPS URL を追加してください。

"repository": "https://gitlab.yourcompany.com/atlas/info-panel"

---

11. check_registry (診断)

~/.npmrc に基づいて、指定したパッケージ名に対してサーバーが解決するレジストリ URL と認証情報を表示します。プライベートレジストリへのアクセスをデバッグする際は、まずこのツールを実行してください。

Parameter	Type	Required	Description
package_name	string	Yes	解決先を確認するパッケージ名

プロンプトの例：

「@ATLAS/info-panel のレジストリを確認してください」

戻り値： 解決されたレジストリ URL、認証トークンが見つかったかどうか、および意図せずパブリックレジストリに解決されている場合のガイダンスです。

---

データソース

API	ベース URL	提供内容	認証
npm Registry	.npmrc から解決（デフォルト：registry.npmjs.org）	パッケージのメタデータ、バージョン、README、依存関係、非推奨情報	.npmrc 経由
npm Downloads	api.npmjs.org/downloads	週間ダウンロード数	なし
npm Audit	.npmrc + /-/npm/v1/security/audits から解決	既知の CVE とアドバイザリ	.npmrc 経由
npms.io	api.npms.io/v2	検索 + 品質／保守状況／人気度のスコア	なし
Bundlephobia	bundlephobia.com/api	圧縮後のサイズ、gzip サイズ、ツリーシェイキング、副作用	なし
GitHub API	api.github.com	リリースノートと変更履歴	なし
GitLab API	gitlab.com/api/v4 またはセルフホストの /api/v4	リリースノートと変更履歴	なし（公開）／プライベートの場合はトークン
Bitbucket API	api.bitbucket.org/2.0	リリース履歴として使用されるタグ	なし

すべてのリクエストにはタイムアウト（10～15 秒）が設定され、API が遅い、または利用できない場合も適切にフォールバックします。ツールは失敗するのではなく、部分的な結果を返します。セッション内での重複した呼び出しを避けるため、レスポンスはメモリ内にキャッシュされます。

---

プライベートレジストリのサポート（.npmrc）

サーバーは ~/.npmrc を直接読み取り、各パッケージのレジストリ URL と認証トークンを解決します。シェルのサブプロセスは使用しません。npm と同じ方法でファイルを解析するため、MCP サーバープロセスの起動方法にかかわらず動作します。

つまり、.npmrc が正しく設定されていれば、@your-company/some-lib のようなスコープ付きプライベートパッケージをそのまま利用できます。たとえば、次のように設定します。

@ATLAS:registry=https://your-company-registry.example.com/
//your-company-registry.example.com/:_authToken=your-token

.npmrc 内のスコープ名は大文字と小文字を区別せずに照合されます。@ATLAS、@atlas、@Atlas はすべて同じエントリに一致します。

レジストリの解決ロジック

パッケージを取得するたびに、サーバーは次の処理を行います。

1. ~/.npmrc を読み取り、パッケージのスコープに一致するスコープ付きレジストリのオーバーライド（例：@ATLAS:registry=...）を探します
2. 見つかった場合は、対応する認証トークンとともにそのレジストリ URL を使用します
3. 見つからない場合は、.npmrc のデフォルトの registry 値を使用します（設定されていない場合は registry.npmjs.org）
4. 解決されたレジストリで失敗し、それがすでに公開レジストリではない場合は、registry.npmjs.org に対して自動的に再試行します。そのため、カスタムのデフォルトレジストリを設定していても、公開パッケージは常に利用できます

ほかのツールを実行する前に、check_registry ツールを使って、任意のパッケージに対してサーバーが解決するレジストリと認証情報を確認してください。

公開パッケージとプライベートパッケージのサポート

ソース	公開パッケージ	プライベートレジストリのパッケージ
レジストリのメタデータ	✅ 完全対応	✅ 完全対応（.npmrc 認証経由）
週間ダウンロード数	✅	✅（npm downloads API は公開されています）
バンドルサイズ	✅	❌ Bundlephobia は公開 npm のみをインデックス化しています
npms.io のスコア	✅	❌ npms.io は公開 npm のみをインデックス化しています
セキュリティ監査	✅	⚠️ フォールバックとして公開 npm のアドバイザリデータベースも確認します
変更履歴	✅ GitHub / GitLab / Bitbucket	✅ repository フィールドに完全な HTTPS URL がある場合

プライベートパッケージの場合、Bundlephobia または npms.io に依存するツール（search_packages、find_alternatives、比較時のバンドルサイズ）は、該当フィールドに N/A を表示しますが、レジストリのメタデータはすべて正しく返します。

---

キャッシュ

すべての API レスポンスは、段階的な TTL を設定してメモリ内にキャッシュされます。

種別	TTL	対象
短期	2 分	ダウンロード数、npms.io のスコア、検索結果
中期	5 分	npm レジストリのメタデータ、GitHub のリリース
長期	10 分	バンドルサイズ、セキュリティ監査の結果

キャッシュの有効範囲はプロセス単位です。MCP サーバーを再起動するとリセットされます。

---

開発

# Watch mode (recompiles on save)
npm run dev

# Single build
npm run build

# Run directly
npm start

プロジェクトのスクリプト

スクリプト	コマンド	説明
build	tsc	TypeScript を dist/ にコンパイルします
start	node dist/index.js	MCP サーバーを実行します
dev	tsc --watch	開発用のウォッチモード

---

技術スタック

技術	バージョン	用途
Node.js	18+	ランタイム（ネイティブの fetch）
TypeScript	~5.5	型安全性
@modelcontextprotocol/sdk	^1.12	MCP サーバーのフレームワーク
zod	^3.23	ツール入力のスキーマ検証

MCP SDK と zod 以外のランタイム依存関係はありません。データベースも外部認証もありません。

---

仕組み

1. ユーザーが Kiro で質問します（例：「CSV の解析用ライブラリを探してください」）
2. Kiro はプロンプトに基づいて適切なツールに振り分けます
3. ツールはメモリ内キャッシュを確認します — データが新しければ即座に返します
4. キャッシュミスの場合、npm レジストリ、npms.io、bundlephobia、GitHub から並行して最新データを取得します
5. 結果をスコアリングしてフォーマットし、構造化された Markdown として返します
6. Kiro はテーブル、スコア、具体的な推奨事項を含む回答をチャットに表示します

サーバーは stdio プロセスとして実行されます。Kiro は必要に応じて起動し、stdin/stdout 経由で JSON-RPC を使って通信します。

---

拡張

新しいツールを追加するには：

1. src/tools/your-tool.ts を作成し、ハンドラー関数を実装します
2. server.tool(name, description, zodSchema, handler) を使って src/index.ts に登録します
3. mcp-config.json の autoApprove にツール名を追加します
4. 再ビルドします：npm run build

新しいデータソースを追加するには：

1. src/services/your-source.ts を作成し、取得関数を実装します
2. services/cache.ts の cache.set / cache.get でレスポンスをラップします
3. 関連するツールハンドラーにインポートして使用します
4. 堅牢性を確保するため、タイムアウトと適切なフォールバックを追加します

---

トラブルシューティング

問題	解決策
Kiro にサーバーが表示されない	mcp.json のパスが正しいことを確認し、dist/index.js が存在することを確認します
「Cannot find module」エラー	ソースを変更した後は npm run build を実行します
API のタイムアウトエラー	企業プロキシ環境では通常発生します — 結果が一部になることがあります
バンドルサイズが「N/A」と表示される	Bundlephobia ですべてのパッケージを解析できるわけではありません（ネイティブアドオンなど）
監査結果が返されない	npm アドバイザリー API に、そのパッケージバージョンのデータがない可能性があります
変更履歴にリリースが表示されない	パッケージが GitHub/GitLab のリリースを使用していないか、package.json の repository フィールドが存在しない、または SSH のみの可能性があります
プライベートパッケージが「not found」を返す	check_registry を実行して、~/.npmrc からレジストリ URL と認証トークンが正しく解決されていることを確認します
check_registry に誤ったレジストリが表示される	~/.npmrc に @SCOPE:registry=https://... と //host/:_authToken=... のエントリがあることを確認します

HTTPS を傍受する企業プロキシ（Zscaler など）の背後で実行する場合は、MCP 設定に企業 CA 証明書を追加します：

"env": {
  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem"
}

これが推奨される修正方法です。Node のネイティブ fetch はすべての場合に NODE_TLS_REJECT_UNAUTHORIZED=0 を尊重するわけではなく、TLS 検証を完全に無効にすることはセキュリティリスクです。NODE_EXTRA_CA_CERTS を使用すると、ほかのすべての検証を無効にすることなく、企業 CA を Node の信頼ストアに追加できます。

企業 CA 証明書のパスを確認するには、IT チームに問い合わせるか、システムの証明書ストアを確認してください。Windows では通常、certmgr.msc → 信頼されたルート証明機関からエクスポートできます。

明示的なプロキシも必要な場合：

"env": {
  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem",
  "HTTPS_PROXY": "http://your-proxy:8080"
}

---

ライセンス

ISC