S1mcpserver

🚀 S1MCP：一級管制物品遊戲的模型上下文協議

S1MCP是一個全面的系統，它使大語言模型（LLM）智能體能夠通過模型上下文協議（MCP）與一級管制物品（Schedule I）遊戲進行交互。此倉庫包含遊戲模組（S1MCPServer）和MCP服務器客戶端（S1MCPClient），二者協同工作，為智能體調試和遊戲狀態檢查提供支持。

🚀 快速開始

前提條件

1. 已安裝一級管制物品（Schedule I）遊戲。
2. 已為一級管制物品遊戲安裝MelonLoader。
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文件。
   • 將其放置在一級管制物品遊戲的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. 啟動加載了模組的一級管制物品遊戲。
2. 等待主場景加載完成（你會看到日誌信息："Main scene loaded - S1MCPServer is active"）。
3. 啟動MCP客戶端（如Claude Desktop、Cline等），它將自動連接到模組。

✨ 主要特性

• 即時遊戲狀態檢查：可查詢非玩家角色（NPC）、物品、建築、載具和玩家數據。
• 遊戲對象操作：可傳送實體、修改生命值、生成物品。
• 智能體調試：允許大語言模型診斷模組問題並提出修復建議。
• 開發工具：為模組開發者提供強大的調試和開發工具。

📦 安裝指南

安裝S1MCPServer模組

1. 構建模組：

   cd S1MCPServer
   # 在Visual Studio或Rider中打開S1MCPServer.sln
   # 為目標後端（IL2CPP或Mono）進行構建
   # 配置：Debug IL2CPP或Release IL2CPP
   

2. 安裝編譯後的DLL文件：
   • 從bin/Debug IL2CPP/net6/（或Debug Mono）目錄複製編譯好的.dll文件。
   • 將其放置在一級管制物品遊戲的Mods文件夾中。
   • 模組將自動在端口8765上啟動TCP服務器。

安裝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
   }
   

配置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文件夾的路徑

💻 使用示例

基礎用法

# 以下是使用S1MCPClient工具的示例代碼
# 假設已經正確配置和啟動了S1MCPClient
from src.main import S1MCPClient

client = S1MCPClient()
# 獲取所有NPC信息
npcs = client.s1_list_npcs()
print(npcs)

高級用法

# 高級場景說明：在特定位置生成一個NPC並獲取其信息
from src.main import S1MCPClient

client = S1MCPClient()
# 生成一個NPC
spawned_npc = client.s1_spawn_npc(position=(10, 0, 20))
# 獲取生成的NPC信息
npc_info = client.s1_get_npc(spawned_npc['id'])
print(npc_info)

📚 詳細文檔

項目結構

S1MCPServer/
├── S1MCPServer/          # C# MelonLoader模組（遊戲端）
│   ├── Core/             # 核心系統（隊列、協議、路由器）
│   ├── Handlers/         # 命令處理程序（NPC、玩家、物品等）
│   ├── Server/           # TCP服務器實現
│   ├── Models/           # 數據模型
│   ├── Utils/            # 實用工具（反射、日誌記錄）
│   └── MainMod.cs        # 模組主入口點
│
├── S1MCPClient/          # Python MCP服務器（客戶端）
│   ├── src/
│   │   ├── main.py       # MCP服務器入口點
│   │   ├── tcp_client.py # 用於與模組通信的TCP客戶端
│   │   ├── tools/        # MCP工具定義
│   │   ├── models/       # 數據模型
│   │   └── utils/        # 實用工具（日誌記錄器、配置）
│   └── requirements.txt  # Python依賴項
│
└── README.md             # 本文件

項目詳情

S1MCPServer

一個運行在一級管制物品遊戲內的MelonLoader模組，通過TCP/IP提供遊戲API訪問。使用C#（.NET 6）構建，支持IL2CPP和Mono後端。

主要特性：

• 用於外部通信的TCP服務器（端口8765）。
• 線程安全的命令/響應隊列系統。
• 跨運行時支持（Mono/IL2CPP）。
• 直接訪問一級管制物品原生類。
• 使用UniverseLib的反射實用工具。
• 可選的UnityExplorer集成。

詳情請見：S1MCPServer/README.md。

S1MCPClient

一個基於Python的MCP服務器，連接到S1MCPServer模組，並將遊戲操作作為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遊戲對象。

詳情請見：S1MCPClient/README.md。

協議

系統使用基於TCP/IP的JSON-RPC 2.0協議在S1MCPClient和S1MCPServer之間進行通信：

消息格式：

• 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
• 直接訪問一級管制物品原生類

S1MCPClient：

• Python 3.10及以上版本
• mcp>=0.9.0（官方MCP SDK）
• pywin32>=306（Windows命名管道支持 - 舊版，現使用TCP）
• pydantic>=2.0.0（數據驗證）

添加新工具

1. 在S1MCPServer/Handlers/中添加命令處理程序。
2. 在CommandRouter.cs中註冊處理程序。
3. 在S1MCPClient/src/tools/中添加工具定義。
4. 在S1MCPClient/src/main.py中註冊工具。

詳情請見各個項目的README文件。

故障排除

連接問題

問題：無法連接到模組。 解決方案：

• 確保一級管制物品遊戲已加載模組並正在運行。
• 檢查主場景是否已加載（等待日誌消息）。
• 驗證TCP服務器是否在端口8765上監聽（檢查模組日誌）。
• 檢查本地主機連接的防火牆設置。
• 驗證模組和客戶端配置中的端口是否匹配（默認：8765）。

問題：操作過程中連接丟失。 解決方案：

• 檢查模組日誌中的錯誤信息。
• 確保遊戲沒有崩潰。
• 客戶端會在連接錯誤時自動重試。
• 檢查網絡連接（本地主機連接應始終正常）。

模組未加載

問題：模組未在MelonLoader中顯示。 解決方案：

• 驗證DLL文件是否在正確的Mods文件夾中。
• 檢查MelonLoader日誌中的加載錯誤。
• 確保為正確的後端（IL2CPP vs Mono）進行了構建。
• 驗證所有依賴項是否存在（如UniverseLib）。

工具錯誤

問題：工具從模組返回錯誤。 解決方案：

• 檢查響應中的錯誤消息和代碼。
• 驗證參數是否符合API規範。
• 檢查模組日誌以獲取詳細的錯誤信息。
• 確保遊戲對象存在（如NPC ID有效）。
• 在進行調用前等待主場景完全加載。

調試

在S1MCPClient/config.json中啟用DEBUG日誌：

{
  "log_level": "DEBUG"
}

檢查一級管制物品遊戲目錄中的模組日誌以獲取詳細的服務器端日誌信息。

使用場景

1. 智能體調試

允許大語言模型智能體診斷模組問題：

• 當模組無法正常生成NPC時，檢查當前遊戲中的NPC情況。
• 驗證物品註冊是否正確。
• 檢查模組交互情況。
• 捕獲和分析遊戲日誌以跟蹤錯誤。

示例：

用戶：“我的模組無法正確生成NPC。你能檢查一下當前遊戲中有哪些NPC嗎？”

大語言模型：[調用s1_list_npcs] 我找到了15個NPC。以下是可能相關的NPC...

用戶：“模組在啟動時崩潰了。你能檢查一下日誌嗎？”

大語言模型：[調用s1_capture_logs並指定關鍵字="error"] 我發現在啟動時間附近的日誌中有幾個錯誤。問題似乎是...

2. 遊戲狀態檢查

瞭解當前遊戲狀態：

• 列出所有NPC及其狀態。
• 檢查玩家揹包。
• 檢查建築佔用情況。
• 查看角色關係。

3. 測試場景

創建測試場景：

• 在特定位置生成NPC。
• 向背包添加物品。
• 修改角色關係。
• 觸發事件。

4. 開發輔助

輔助模組開發：

• 檢查可用的遊戲對象。
• 測試遊戲API功能。
• 驗證模組集成情況。
• 調試模組行為。

🔧 技術細節

線程模型

模組使用了一種複雜的線程模型，以安全地將Unity的單線程特性與外部通信進行橋接：

後臺線程（TCP服務器）
    ↓ 入隊請求
命令隊列（線程安全）
    ↓ 在主線程處理（Unity更新）
命令處理程序（主線程）
    ↓ 入隊結果
響應隊列（線程安全）
    ↓ 通過TCP發送
後臺線程（TCP服務器）

這確保了：

• 所有Unity操作都在主線程上進行。
• 外部通信不會阻塞遊戲執行。
• 線程之間的消息傳遞是線程安全的。

安全考慮

• 僅本地訪問：TCP服務器僅綁定到127.0.0.1（無法從網絡訪問）。
• 單客戶端連接：同一時間僅允許一個MCP客戶端連接。
• 參數驗證：所有參數在執行前都會進行驗證。
• 錯誤處理：優雅的錯誤處理可防止遊戲崩潰。
• 速率限制：操作自然受到遊戲幀率的速率限制。

📄 許可證

[此處添加許可證信息]

致謝

• Tyler - 項目創建者和維護者。
• 為一級管制物品遊戲模組社區而構建。
• 使用官方模型上下文協議SDK。
• 受UnityExplorer反射技術的啟發。
• 使用UniverseLib實現跨運行時兼容性。

支持

如有問題或疑問：

• 查看上述故障排除部分。
• 查看各個項目的README文件。
• 檢查一級管制物品遊戲中的模組日誌。
• 啟用DEBUG日誌以獲取詳細信息。
• 查看API規範以瞭解工具使用方法。

版本：1.0.0
最後更新：2025-01-27
作者：Tyler