S1mcpserver

🚀 S1MCP: Schedule I用モデルコンテキストプロトコル

S1MCPは、Model Context Protocol (MCP) を介してLLMエージェントがSchedule Iゲームと対話できる包括的なシステムです。このリポジトリには、ゲームモッド (S1MCPServer) とMCPサーバークライアント (S1MCPClient) の両方が含まれており、これらが連携してエージェント型デバッグとゲーム状態の検査機能を提供します。

🚀 クイックスタート

前提条件

1. Schedule I ゲームがインストールされていること
2. MelonLoader がSchedule Iにインストールされていること
3. Python 3.10以上 がインストールされていること
4. Windows（ゲームに必要ですが、TCPはクロスプラットフォームで動作します）

インストール

1. S1MCPServerモッドのインストール

1. モッドをビルドします：

   cd S1MCPServer
   # Visual StudioまたはRiderでS1MCPServer.slnを開く
   # ターゲットバックエンド (IL2CPPまたはMono) 用にビルドする
   # 構成: Debug IL2CPPまたはRelease IL2CPP
   

2. コンパイルされたDLLをインストールします：
   • bin/Debug IL2CPP/net6/（または Debug Mono）からコンパイルされた .dll をコピーします。
   • それをSchedule Iの Mods フォルダに配置します。
   • モッドは自動的にポート8765でTCPサーバーを起動します。

2. S1MCPClientのインストール

1. クライアントディレクトリに移動します：

   cd S1MCPClient
   

2. Pythonの依存関係をインストールします：

   pip install -r requirements.txt
   

3. （オプション）構成ファイルを作成します：

   # S1MCPClient/にconfig.jsonを作成する
   {
     "host": "localhost",
     "port": 8765,
     "log_level": "INFO",
     "connection_timeout": 5.0,
     "reconnect_delay": 1.0
   }
   

3. MCPクライアントの設定

MCPクライアント（例: Claude Desktop）をS1MCPClientを使用するように設定します。

Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "s1mcp": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "C:\\path\\to\\S1MCPServer\\S1MCPClient"
    }
  }
}

Clineまたはその他のMCPクライアント：

• コマンド: python -m src.main
• 作業ディレクトリ: S1MCPClient フォルダへのパス

実行

1. Schedule I をモッドを読み込んで起動します。
2. メインシーン が読み込まれるのを待ちます（ログに "Main scene loaded - S1MCPServer is active" が表示されます）。
3. MCPクライアント（Claude Desktop、Clineなど）を起動します - 自動的にモッドに接続します。

✨ 主な機能

S1MCPは、LLMエージェント（Claude、GPTなど）とSchedule I Unityゲームを橋渡しし、以下のことを可能にします：

• リアルタイムのゲーム状態検査 - NPC、アイテム、建物、車両、およびプレイヤーデータを照会する
• ゲームオブジェクトの操作 - エンティティをテレポートさせる、体力を変更する、アイテムを生成する
• エージェント型デバッグ - LLMにモッドの問題を診断させ、修正案を提案させる
• 開発ツール - モッダー向けの強力なデバッグと開発ツール

📦 インストール

上記のクイックスタートのインストール手順を参照してください。

💻 使用例

基本的な使用法

# ここに基本的な使用法のコード例を記載する予定ですが、元のREADMEに具体的な基本使用法のコード例がないため省略します。

高度な使用法

# ここに高度な使用法のコード例を記載する予定ですが、元のREADMEに具体的な高度使用法のコード例がないため省略します。

📚 ドキュメント

概要

S1MCPは、LLMエージェント（Claude、GPTなど）とSchedule I Unityゲームを橋渡しし、以下の機能を提供します。

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    LLM Agent (Claude/GPT)                     │
│                    (Claude Desktop, Cline, etc.)              │
└────────────────────────────┬──────────────────────────────────┘
                             │ MCP Protocol (JSON-RPC over stdio)
                             │
┌────────────────────────────▼──────────────────────────────────┐
│              S1MCPClient (Python MCP Server)                 │
│  - Handles MCP protocol (JSON-RPC over stdio)                  │
│  - Translates MCP tools → Game API calls                     │
│  - Manages LLM interactions                                  │
│  - Language: Python 3.10+                                    │
└────────────────────────────┬──────────────────────────────────┘
                             │ TCP/IP Communication
                             │ (localhost:8765)
┌────────────────────────────▼──────────────────────────────────┐
│              S1MCPServer (MelonLoader Mod)                   │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  TCP Server (Background Thread)                      │  │
│  │  - Listens for commands from MCP server (port 8765)   │  │
│  │  - Receives JSON-RPC requests                         │  │
└──────────────┬───────────────────────────────────────────┘  │
│                 │ Enqueue Commands                            │
│  ┌──────────────▼───────────────────────────────────────────┐  │
│  │  Command Queue (Thread-Safe)                            │  │
│  │  - Queues game operations                               │  │
└──────────────┬───────────────────────────────────────────┘  │
│                 │ Process on Main Thread                      │
│  ┌──────────────▼───────────────────────────────────────────┐  │
│  │  Command Handlers (Main Thread)                         │  │
│  │  - Accesses Unity game objects                          │  │
│  │  - Executes game operations safely                      │  │
└──────────────┬───────────────────────────────────────────┘  │
│                 │ Results                                     │
│  ┌──────────────▼───────────────────────────────────────────┐  │
│  │  Response Queue (Thread-Safe)                          │  │
│  │  - Queues operation results                            │  │
└──────────────┬───────────────────────────────────────────┘  │
│                 │ Send via TCP                                │
│                 └──────────────────────────────────────────────┘
└────────────────────────────┬──────────────────────────────────┘
                             │
┌────────────────────────────▼──────────────────────────────────┐
│              Schedule I Game (Unity)                          │
│  - Game objects (NPCs, Items, Vehicles, Buildings)           │
│  - Player state and inventory                                 │
│  - Network state (multiplayer)                                │
│  - Game systems (native Unity/Schedule One classes)         │
└───────────────────────────────────────────────────────────────┘

リポジトリ構造

S1MCPServer/
├── S1MCPServer/          # C# MelonLoader mod (game-side)
│   ├── Core/             # Core systems (queues, protocol, router)
│   ├── Handlers/         # Command handlers (NPC, Player, Item, etc.)
│   ├── Server/           # TCP server implementation
│   ├── Models/           # Data models
│   ├── Utils/            # Utilities (reflection, logging)
│   └── MainMod.cs        # Main mod entry point
│
├── S1MCPClient/          # Python MCP server (client-side)
│   ├── src/
│   │   ├── main.py       # MCP server entry point
│   │   ├── tcp_client.py # TCP client for mod communication
│   │   ├── tools/        # MCP tool definitions
│   │   ├── models/       # Data models
│   │   └── utils/        # Utilities (logger, config)
│   └── requirements.txt  # Python dependencies
│
└── README.md             # This file

プロジェクト

S1MCPServer

Schedule I内で実行され、TCP/IPを介してゲームAPIにアクセスできるMelonLoaderモッドです。C# (.NET 6) で構築され、IL2CPPとMonoの両方のバックエンドをサポートしています。

主要な機能:

• 外部通信用のTCPサーバー（ポート8765）
• スレッドセーフなコマンド/レスポンスキューイングシステム
• クロスランタイムサポート（Mono/IL2CPP）
• Schedule Oneのネイティブクラスへの直接アクセス
• UniverseLibを使用したリフレクションユーティリティ
• オプションのUnityExplorer統合

詳細ドキュメントは S1MCPServer/README.md を参照してください。

S1MCPClient

S1MCPServerモッドに接続し、ゲーム操作をLLMエージェント向けのMCPツールとして公開するPythonベースのMCPサーバーです。公式のMCPプロトコルを実装しています。

主要な機能:

• MCPプロトコルの実装（公式SDK）
• モッド通信用のTCPクライアント
• ゲーム操作のための包括的なツールセット
• 自動再接続とエラーハンドリング
• JSON構成ファイルでの設定可能

詳細ドキュメントは S1MCPClient/README.md を参照してください。

利用可能なツール

S1MCPClientは、ゲームとの対話のための包括的なツールセットを公開しています。

NPCツール

• s1_get_npc - IDでNPC情報を取得する
• s1_list_npcs - すべてのNPCをリストする（オプションのフィルター付き）
• s1_get_npc_position - NPCの位置を取得する
• s1_teleport_npc - NPCを位置にテレポートさせる
• s1_set_npc_health - NPCの体力を変更する

プレイヤーツール

• s1_get_player - プレイヤー情報を取得する
• s1_get_player_inventory - プレイヤーのインベントリを取得する
• s1_teleport_player - プレイヤーをテレポートさせる
• s1_add_item_to_player - インベントリにアイテムを追加する

アイテムツール

• s1_list_items - すべてのアイテム定義をリストする
• s1_get_item - IDでアイテム情報を取得する
• s1_spawn_item - 世界にアイテムを生成する

建物ツール

• s1_list_buildings - すべての建物をリストする
• s1_get_building - 建物情報を取得する

車両ツール

• s1_list_vehicles - すべての車両をリストする
• s1_get_vehicle - 車両情報を取得する

ゲーム状態ツール

• s1_get_game_state - 現在のゲーム状態（シーン、ネットワーク、モッド、バージョン）を取得する

ログツール

• s1_capture_logs - MelonLoaderからのゲームログをキャプチャし、フィルタリングしてデバッグする
  • キーワード、タイムスタンプ範囲、正規表現パターンでフィルタリングする
  • 最初/最後のN行を取得する
  • エージェント型デバッグに不可欠

デバッグツール

• s1_inspect_object - リフレクションを使用してUnity GameObjectを検査する

詳細なツールドキュメントは S1MCPClient/README.md を参照してください。

プロトコル

システムは、S1MCPClientとS1MCPServerの間の通信にTCP/IP上のJSON-RPC 2.0を使用しています。

メッセージ形式:

• 4バイトの長さプレフィックス（リトルエンディアンのint32）
• UTF-8でエンコードされたJSONペイロード

リクエスト形式:

{
  "id": 1,
  "method": "get_npc",
  "params": {
    "npc_id": "kyle_cooley"
  }
}

レスポンス形式:

{
  "id": 1,
  "result": {
    "npc_id": "kyle_cooley",
    "name": "Kyle Cooley",
    "position": {"x": 10.5, "y": 1.0, "z": 20.3},
    "health": 100.0,
    "is_conscious": true
  },
  "error": null
}

開発

S1MCPServerのビルド

プロジェクトは複数のビルド構成をサポートしています。

• Debug Mono - Monoバックエンド用のデバッグビルド
• Release Mono - Mono用のリリースビルド
• Debug IL2CPP - IL2CPPバックエンド用のデバッグビルド（ほとんどのユーザーに推奨）
• Release IL2CPP - IL2CPP用のリリースビルド（本番環境）

Visual Studio、Rider、またはお好みのIDEで S1MCPServer.sln を開き、ターゲット構成でビルドしてください。

プロジェクトの依存関係

S1MCPServer:

• MelonLoader
• UniverseLib（リフレクションユーティリティ用）
• .NET 6.0
• Schedule Oneのネイティブクラスへの直接アクセス

S1MCPClient:

• Python 3.10以上
• mcp>=0.9.0（公式MCP SDK）
• pywin32>=306（Windows Named Pipesサポート - レガシー、現在はTCPを使用）
• pydantic>=2.0.0（データ検証）

新しいツールの追加

1. S1MCPServer/Handlers/ でコマンドハンドラーを追加します。
2. CommandRouter.cs でハンドラーを登録します。
3. S1MCPClient/src/tools/ でツール定義を追加します。
4. S1MCPClient/src/main.py でツールを登録します。

詳細な開発ガイドは個々のプロジェクトのREADMEを参照してください。

トラブルシューティング

接続問題

問題: モッドに接続できない

解決策:

• Schedule Iがモッドを読み込んで実行されていることを確認します。
• メインシーンが読み込まれたことを確認します（ログメッセージを待ちます）。
• TCPサーバーがポート8765で待機していることを確認します（モッドのログを確認します）。
• ローカルホスト接続のファイアウォール設定を確認します。
• モッドとクライアントの構成でポートが一致していることを確認します（デフォルト: 8765）。

問題: 操作中に接続が失われる

解決策:

• モッドのログをエラーを確認します。
• ゲームがクラッシュしていないことを確認します。
• クライアントは接続エラー時に自動的に再試行します。
• ネットワーク接続を確認します（ただし、ローカルホストは常に動作するはずです）。

モッドが読み込まれない

問題: モッドがMelonLoaderに表示されない

解決策:

• DLLが正しい Mods フォルダにあることを確認します。
• MelonLoaderのログを読み込みエラーを確認します。
• 正しいバックエンド（IL2CPP vs Mono）用にビルドされていることを確認します。
• すべての依存関係（UniverseLibなど）が存在することを確認します。

ツールエラー

問題: ツールがモッドからエラーを返す

解決策:

• レスポンスのエラーメッセージとコードを確認します。
• パラメータがAPI仕様に一致していることを確認します。
• モッドのログを詳細なエラー情報を確認します。
• ゲームオブジェクトが存在することを確認します（例: NPC IDが有効であること）。
• 呼び出しを行う前にメインシーンが完全に読み込まれるのを待ちます。

デバッグ

S1MCPClient/config.json でDEBUGロギングを有効にします：

{
  "log_level": "DEBUG"
}

詳細なサーバー側のログはSchedule Iゲームディレクトリのモッドログを確認してください。

使用例

1. エージェント型デバッグ

LLMエージェントにモッドの問題を診断させます：

• モッドが正常に動作しないときにゲーム状態を検査する
• NPCが正しく生成されているかを確認する
• アイテムの登録を検証する
• モッドの相互作用を検査する
• エラーを追跡するためにゲームログをキャプチャし、分析する

例:

ユーザー: "私のモッドがNPCを正しく生成していません。現在ゲーム内にあるNPCを確認してくれますか？"

LLM: [s1_list_npcsを呼び出す] 15個のNPCが見つかりました。関連する可能性のあるものはこちら...

ユーザー: "モッドが起動時にクラッシュしました。ログを確認してくれますか？"

LLM: [キーワード="error"でs1_capture_logsを呼び出す] 起動時付近のログにいくつかのエラーが見つかりました。
問題は...のようです。

2. ゲーム状態検査

現在のゲーム状態を理解します：

• すべてのNPCとその状態をリストする
• プレイヤーのインベントリを確認する
• 建物の占有状況を検査する
• 関係性を確認する

3. テストシナリオ

テストシナリオを作成します：

• 特定の場所にNPCを生成する
• インベントリにアイテムを追加する
• 関係性を変更する
• イベントをトリガーする

4. 開発支援

モッド開発を支援します：

• 利用可能なゲームオブジェクトを検査する
• ゲームAPIの機能をテストする
• モッドの統合を検証する
• モッドの動作をデバッグする

🔧 技術詳細

スレッディングモデル

モッドは、Unityのシングルスレッド性と外部通信を安全に橋渡しするために、洗練されたスレッディングモデルを使用しています。

Background Thread (TCP Server)
    ↓ Enqueue Request
Command Queue (Thread-Safe)
    ↓ Process on Main Thread (Unity Update)
Command Handlers (Main Thread)
    ↓ Enqueue Result
Response Queue (Thread-Safe)
    ↓ Send via TCP
Background Thread (TCP Server)

これにより、以下のことが保証されます：

• すべてのUnity操作はメインスレッドで行われます。
• 外部通信がゲームの実行をブロックしません。
• スレッド間でスレッドセーフなメッセージのやり取りが行われます。

セキュリティに関する考慮事項

• ローカルホストのみ: TCPサーバーは 127.0.0.1 にのみバインドされています（ネットワークからはアクセスできません）。
• 単一クライアント: 一度に1つのMCPクライアントのみが接続できます。
• 検証: すべてのパラメータは実行前に検証されます。
• エラーハンドリング: ゲームのクラッシュを防ぐための適切なエラーハンドリングが行われます。
• レート制限: 操作は自然にゲームのフレームレートによってレート制限されます。

📄 ライセンス

[ここにライセンスを追加してください]

クレジット

• Tyler - プロジェクトの作成者およびメンテナ
• Schedule Iモッディングコミュニティ向けに構築されました
• 公式のModel Context Protocol SDKを使用しています
• UnityExplorerのリフレクション技術に触発されています
• クロスランタイム互換性のためにUniverseLibを使用しています

サポート

問題や質問については、以下を参照してください。

• 上記のトラブルシューティングセクションを確認する
• 個々のプロジェクトのREADMEを確認する
• Schedule Iのモッドログを確認する
• 詳細情報のためにDEBUGロギングを有効にする
• ツールの使用方法についてはAPI仕様を確認する

バージョン: 1.0.0
最終更新日: 2025-01-27
作成者: Tyler