packwarden

PackWarden — Thunderstore Mod-Pack MCP Server (v0.1.0)

PackWarden は Thunderstore と提携しておらず、Thunderstore からの推奨も受けていません。 「Thunderstore」は互換性を説明する目的でのみ使用しています。 Mod データは公開されている Thunderstore API（https://thunderstore.io）から取得しています。

AI アシスタントが Thunderstore の Mod パック（Lethal Company、Risk of Rain 2、Valheim、およびその他すべての Thunderstore コミュニティ向け）の作成と管理を行えるよう支援する MCP サーバーです。

ツール

ツール	機能
list_communities	Thunderstore のゲームコミュニティ（識別子＋名前）を一覧表示します。
search_mods	コミュニティを名前／所有者／説明／カテゴリで検索し、関連度、ダウンロード数、評価、更新日時で並べ替えます。
resolve_dependencies	1 つ以上のパッケージ／バージョンについて、推移的な依存関係をすべて解決します。最終的なインストール対象、不足している依存関係、複数バージョンの固定、オプションのツリーを確認できます。
check_pack_health	Mod リストを監査します。見つからない Mod、削除されたバージョン、非推奨、古いバージョン、不足している依存関係、依存関係のバージョン競合、重複、NSFW を確認します。
export_r2modman_profile	.r2z プロファイルを書き出します（r2modman／Thunderstore Mod Manager の「Import profile → From file」）。依存関係と設定ファイルを含めることもできます。アップロードは行われません。

Mod は Owner-Name（最新）または Owner-Name-1.2.3 として指定します。

インストール

Node.js ≥ 18.17 が必要です。

git clone <repo> thunderstore-mcp && cd thunderstore-mcp
npm install && npm run build

Claude Desktop

claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。

{
  "mcpServers": {
    "thunderstore": {
      "command": "node",
      "args": ["/absolute/path/to/thunderstore-mcp/dist/main.js"],
      "env": { "TSMCP_EXPORT_DIR": "/absolute/path/for/profiles" }
    }
  }
}

Claude Desktop を再起動します。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）を使用します。

{
  "mcpServers": {
    "thunderstore": {
      "command": "node",
      "args": ["/absolute/path/to/thunderstore-mcp/dist/main.js"]
    }
  }
}

Streamable HTTP（リモート／セルフホスト可能）

npm run start:http            # http://127.0.0.1:3333/mcp
PORT=8080 HOST=0.0.0.0 node dist/main.js --http

Cursor：{ "mcpServers": { "thunderstore": { "url": "http://127.0.0.1:3333/mcp" } } }。 HTTP モードはステートレス（POST のみ、JSON レスポンス）で、認証機能はありません。外部に公開する前に、TLS と認証を設定したリバースプロキシの背後に配置してください。

設定（環境変数）

変数	デフォルト	説明
TSMCP_CACHE_DIR	~/.cache/thunderstore-mcp	軽量なパッケージインデックスのキャッシュ
TSMCP_LIST_TTL_MS	3600000 (1h)	パッケージ一覧の有効期間
TSMCP_MIN_INTERVAL_MS	1000	外部リクエスト間の最小間隔
TSMCP_EXPORT_DIR	./exports	.r2z ファイルの書き出し先
TSMCP_CONTACT	[email protected]	User-Agent に含める連絡先。独自のコピーを実行する場合は上書きしてください。
TSMCP_BRAND	PackWarden	サーバー名／User-Agent に含めるブランド
TSMCP_BASE_URL	https://thunderstore.io	API のベース URL

API を適切に利用するために

• 各コミュニティのパッケージ一覧を TTL ごとに 1 回ダウンロードし、その後は条件付きリクエスト（If-Modified-Since）を使用します。結果は軽量なインデックスとしてディスクにキャッシュされます。
• 外部リクエストは直列化され（同時実行数 1）、1 秒以上の間隔を空けて送信されます。429／5xx の場合、クライアントはバックオフし、Retry-After に従います。
• 連絡先アドレスを含む識別可能な User-Agent を使用します。
• ネットワークに障害が発生した場合も、サーバーは古いキャッシュを提供し続けます。

テスト（ライブ API）

npm test                         # default community: valheim
TEST_COMMUNITY=valheim npm test

ライブ Thunderstore API に対する stdio と Streamable HTTP のエンドツーエンドテストが含まれています。

制限事項

• 大規模なコミュニティでは負荷が大きくなります。Lethal Company の初回読み込みでは約 330 MB の JSON をダウンロードし、約 14 秒かかり、約 1.4 GB の RAM を使用します。その後、キャッシュからの読み込みには約 3 秒かかります。
• 依存関係の解決は r2modman の動作に従い、要求されたバージョンのうち最も高いものを優先します。Thunderstore では正確なバージョンが固定されるため、semver の範囲解決は行いません。
• プロファイルの コード 共有には対応していません。Thunderstore へのアップロードが必要になるためです。ファイルの書き出しのみ対応しています。
• 検索はローカルでのキーワードスコアリングを使用し、Thunderstore 独自の検索順位は使用しません。