Stellaris Modding MCP Server
[!WARNING] これは実験的なプロジェクトです。APIの仕様変更や、予期せぬエラーが発生する可能性があります。
ステラリスのmodding支援用MCPサーバーです。SteamCMD APIとGitHub APIを使用して、mod開発者に必要な最新情報を提供します。
機能
- ゲームバージョン情報: SteamCMD APIからステラリスの最新バージョン、ビルドID、更新日時を取得
- CWToolsコンフィグ: Stellaris modding用の検証ルール(.cwt files)を取得
- ドキュメント検索: triggers、effects、modifiers、scopes、localizationsの最新ドキュメントをキーワードで検索
- 要素検証: trigger, effectなどが最新バージョンで有効か検証
- リアルタイム更新: 常に最新の情報を提供
- エラーハンドリング: リトライ機能付きで安定した動作
利用可能なツール
1. stellaris-version
ステラリスの現在のバージョン情報を包括的に取得します。
取得情報:
- 現在のPublicブランチのビルドIDと更新日時
- 最新バージョン番号とその詳細情報
- 利用可能なバージョン一覧（最新10件）
- 特別なブランチ情報
- ゲームの基本情報（App ID、開発者、対応OS等）
2. cwtools-config
CWToolsのStellarisコンフィグルール(.cwt files)を取得します。
パラメータ:
version:"stable"(最新タグ) または"latest"(開発版) - デフォルト:"stable"file: 特定のファイル名またはパス（例:"common.cwt","common/agreements.cwt"）listOnly:trueの場合、ファイル一覧のみを表示 - デフォルト:false
機能:
- config/直下およびサブディレクトリ内の.cwtファイルを取得
- 特定ファイルの内容取得または全ファイル一覧表示
- 安定版または開発版の選択可能
3. stellaris-search
OldEnt/stellaris-triggers-modifiers-effects-listリポジトリから最新のゲームドキュメントをキーワード検索します。
パラメータ:
docType:"triggers","effects","modifiers","scopes","localizations"のいずれかkeyword: 検索キーワードcontextLines: 前後に表示する行数（デフォルト: 2）
機能:
- 最新バージョンのドキュメントを自動で検索
- 一致した箇所をコードスニペットとして表示
4. stellaris-validate
指定した要素が最新バージョンのドキュメントに存在するかを検証します。
パラメータ:
docType:"triggers","effects","modifiers","scopes","localizations"のいずれかelement: 検証する要素名（例:has_technology）
機能:
- 要素の完全一致、部分一致をチェック
- modの互換性確認に利用可能
開発
セットアップ
git clone <this-repository>
cd stellaris-modding-mcp-server
npm install
開発モードで起動
npm run dev
これにより、MCPサーバーが起動し、CLIで対話的にテストできます。
本番モードで起動
npm run start
テスト実行
npm run test
コードフォーマット
npm run format
リント実行
npm run lint
使用API・データソース
SteamCMD API
SteamCMD API を使用してゲームバージョン情報を取得：
- 認証不要: APIキーや認証は必要ありません
- リアルタイム更新: Steamでの変更が数秒以内に反映されます
- 無料: 完全に無料で使用できます
- オープンソース: APIのソースコードも公開されています
GitHub API
以下のリポジトリからmodding関連情報を取得：
- cwtools/cwtools-stellaris-config: Stellaris modding用の検証ルール(.cwt files)
- OldEnt/stellaris-triggers-modifiers-effects-list: ゲームエンジンから自動抽出されたドキュメント
信頼性機能
- リトライ機能: ネットワークエラーやレート制限に対する自動リトライ
- 指数バックオフ: 適切な間隔でのリトライ実行
- フォールバック: 最新バージョンが利用できない場合の代替バージョン取得
ライセンス
MIT License
貢献
バグ報告や機能要求は、GitHubのIssuesでお知らせください。プルリクエストも歓迎します。
技術スタック
- FastMCP - MCPサーバーフレームワーク
- TypeScript - 型安全な開発
- Zod - スキーマバリデーション
- Vitest - テストフレームワーク
使用例
バージョン情報の取得
# MCPクライアントでの使用例
stellaris-version
CWToolsコンフィグの取得
# 利用可能なファイル一覧を表示
cwtools-config --listOnly true
# 特定のファイルを取得
cwtools-config --file "common.cwt"
# サブディレクトリのファイルを取得
cwtools-config --file "common/agreements.cwt"
# 開発版を取得
cwtools-config --version "latest"
ドキュメントの検索
# triggersから "fleet" を検索
stellaris-search --docType "triggers" --keyword "fleet"
要素の検証
# effect "add_modifier" が有効か検証
stellaris-validate --docType "effects" --element "add_modifier"
対応バージョン
- Node.js: 22以上
- Stellaris: 全バージョン対応（SteamCMD APIから自動取得）
- CWTools: 安定版および開発版
- ゲームドキュメント: 常に最新バージョンを自動取得
トラブルシューティング
よくある問題
-
GitHub API レート制限
- 認証なしの場合、1時間あたり60リクエストの制限があります
- 大量のファイルを取得する場合は時間をおいて実行してください
-
ネットワークエラー
- 自動リトライ機能が組み込まれているため、一時的なエラーは自動的に回復します
- 継続的な問題がある場合は、インターネット接続を確認してください
-
バージョンが見つからない
- ゲームドキュメントは利用可能な最新バージョンに自動的にフォールバックします
- CWToolsコンフィグは安定版と開発版を選択できます
ログの確認
開発モードで実行すると詳細なログが表示されます：
npm run dev
Installing via Smithery
To install stellaris-modding-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @kongyo2/stellaris-modding-mcp-server --client claude