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: 安定版および開発版
• ゲームドキュメント: 常に最新バージョンを自動取得

トラブルシューティング

よくある問題

1. GitHub API レート制限

   • 認証なしの場合、1時間あたり60リクエストの制限があります
   • 大量のファイルを取得する場合は時間をおいて実行してください

2. ネットワークエラー

   • 自動リトライ機能が組み込まれているため、一時的なエラーは自動的に回復します
   • 継続的な問題がある場合は、インターネット接続を確認してください

3. バージョンが見つからない

   • ゲームドキュメントは利用可能な最新バージョンに自動的にフォールバックします
   • 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