# Stellaris Modding MCP Server

[![smithery badge](https://smithery.ai/badge/@kongyo2/stellaris-modding-mcp-server)](https://smithery.ai/server/@kongyo2/stellaris-modding-mcp-server)

<a href="https://deepwiki.com/kongyo2/Stellaris-Modding-MCP-Server"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>

<a href="https://glama.ai/mcp/servers/@kongyo2/Stellaris-Modding-MCP-Server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kongyo2/Stellaris-Modding-MCP-Server/badge" />
</a>

> [!WARNING]
> これは実験的なプロジェクトです。APIの仕様変更や、予期せぬエラーが発生する可能性があります。

ステラリスのmodding支援用MCPサーバーです。[SteamCMD API](https://api.steamcmd.net/)と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の互換性確認に利用可能

## 開発

### セットアップ

```bash
git clone <this-repository>
cd stellaris-modding-mcp-server
npm install
```

### 開発モードで起動

```bash
npm run dev
```

これにより、MCPサーバーが起動し、CLIで対話的にテストできます。

### 本番モードで起動

```bash
npm run start
```

### テスト実行

```bash
npm run test
```

### コードフォーマット

```bash
npm run format
```

### リント実行

```bash
npm run lint
```


## 使用API・データソース

### SteamCMD API

[SteamCMD API](https://api.steamcmd.net/) を使用してゲームバージョン情報を取得：

- **認証不要**: APIキーや認証は必要ありません
- **リアルタイム更新**: Steamでの変更が数秒以内に反映されます
- **無料**: 完全に無料で使用できます
- **オープンソース**: APIのソースコードも公開されています

### GitHub API

以下のリポジトリからmodding関連情報を取得：

- **[cwtools/cwtools-stellaris-config](https://github.com/cwtools/cwtools-stellaris-config)**: Stellaris modding用の検証ルール(.cwt files)
- **[OldEnt/stellaris-triggers-modifiers-effects-list](https://github.com/OldEnt/stellaris-triggers-modifiers-effects-list)**: ゲームエンジンから自動抽出されたドキュメント

### 信頼性機能

- **リトライ機能**: ネットワークエラーやレート制限に対する自動リトライ
- **指数バックオフ**: 適切な間隔でのリトライ実行
- **フォールバック**: 最新バージョンが利用できない場合の代替バージョン取得

## ライセンス

MIT License

## 貢献

バグ報告や機能要求は、GitHubのIssuesでお知らせください。プルリクエストも歓迎します。

## 技術スタック

- [FastMCP](https://github.com/punkpeye/fastmcp) - MCPサーバーフレームワーク
- [TypeScript](https://www.typescriptlang.org/) - 型安全な開発
- [Zod](https://zod.dev/) - スキーマバリデーション
- [Vitest](https://vitest.dev/) - テストフレームワーク

## 使用例

### バージョン情報の取得

```bash
# MCPクライアントでの使用例
stellaris-version
```

### CWToolsコンフィグの取得

```bash
# 利用可能なファイル一覧を表示
cwtools-config --listOnly true

# 特定のファイルを取得
cwtools-config --file "common.cwt"

# サブディレクトリのファイルを取得
cwtools-config --file "common/agreements.cwt"

# 開発版を取得
cwtools-config --version "latest"
```

### ドキュメントの検索

```bash
# triggersから "fleet" を検索
stellaris-search --docType "triggers" --keyword "fleet"
```

### 要素の検証

```bash
# 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コンフィグは安定版と開発版を選択できます

### ログの確認

開発モードで実行すると詳細なログが表示されます：

```bash
npm run dev

```
### Installing via Smithery

To install stellaris-modding-mcp-server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kongyo2/stellaris-modding-mcp-server):

```bash
npx -y @smithery/cli install @kongyo2/stellaris-modding-mcp-server --client claude
```