S1MCP：附表I的模型上下文协议
一个全面的系统，使LLM代理能够通过模型上下文协议（MCP）与调度I游戏进行交互。此存储库包含游戏模块（S1MCPServer）和MCP服务器客户端（S1MCPClient），它们协同工作以提供代理调试和游戏状态检查功能。
概述
S1MCP将LLM代理（如Claude、GPT）与Schedule I Unity游戏连接起来，实现：
- 实时游戏状态检查 -查询NPC、物品、建筑、车辆和玩家数据
- 游戏对象操纵 -传送实体、修改健康状况、生成项目
- 代理调试 -允许LLM诊断mod问题并提出修复建议
- 开发工具 -为改装者提供强大的调试和开发工具
建筑
┌─────────────────────────────────────────────────────────────┐
│ 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
│
├── S1MCPClientRust/ # Rust MCP server (side-by-side migration)
│ ├── src/ # MCP server, TCP client, tools, lifecycle/docs modules
│ ├── config.json.example
│ └── README.md
│
└── README.md # This file项目
S1MCP服务器
在附表I中运行的MelonLoader mod，通过TCP/IP提供游戏API访问。使用C#（.NET 6）构建，支持IL2CPP和Mono后端。
主要特点：
- 用于外部通信的TCP服务器（端口8765）
- 线程安全命令/响应排队系统
- 跨运行时支持（Mono/IL2CPP）
- 直接访问Schedule One本地课程
- 使用UniverseLib的反射实用程序
- 可选的UnityExplorer集成
请参阅： S1MCP服务器/README.md 详细文档。
S1MCP客户端
一个基于Python的MCP服务器，连接到S1MCPServer模块，并将游戏操作作为LLM代理的MCP工具公开。执行官方MCP协议。
主要特点：
- MCP协议实现（官方SDK）
- 用于mod通信的TCP客户端
- 游戏操作的综合工具集
- 自动重新连接和错误处理
- 可通过JSON配置文件进行配置
请参阅： S1MCPClient/README.md 详细文档。
S1MCPClientRust
基于Rust的并行MCP服务器实现，旨在作为客户端运行时的原生二进制目标。
请参阅： S1MCPClientRust/README.md 用于当前状态、命令和奇偶校验注释。
快速开始
先决条件
- 第一类 游戏已安装
- Melon加载器 为附表I安装
- Python 3.10+ 安装
- 视窗 （游戏需要，TCP跨平台工作）
安装
1.安装S1MCPServer模块
- 构建mod：
cd S1MCPServer
# Open S1MCPServer.sln in Visual Studio or Rider
# Build for your target backend (IL2CPP or Mono)
# Configuration: Debug IL2CPP or Release IL2CPP- 安装已编译的DLL：
- 复制已编译的 .dll 从 bin/Debug IL2CPP/net6/ （或 Debug Mono) - 把它放在你的日程表I中 Mods 文件夹 - mod将自动启动端口8765上的TCP服务器
2.安装S1MCPClient
- 导航到客户端目录：
cd S1MCPClient- 安装Python依赖项：
pip install -r requirements.txt- （可选）创建配置文件：
# Create config.json in S1MCPClient/
{
"host": "localhost",
"port": 8765,
"log_level": "INFO",
"connection_timeout": 5.0,
"reconnect_delay": 1.0
}3.配置MCP客户端
配置您的MCP客户端（例如Claude Desktop）以使用S1MCPClient：
克劳德桌面版 (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文件夹
跑步
- 开始时间表I 已加载mod
- 等待主场景 加载（您将看到日志：“主场景已加载-S1MCPServer处于活动状态”）
- 启动您的MCP客户端 （Claude Desktop、Cline等）-它将自动连接到mod
可用工具
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-Teleport播放器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
}发展
构建S1MCP服务器
该项目支持多种构建配置：
- 调试单声道 -Mono后端的调试构建
- 发布单声道 -发布Mono版本
- 调试IL2CPP -IL2CPP后端的调试版本（建议大多数用户使用）
- 发布IL2CPP -IL2CPP的发布版本（生产）
打开 S1MCPServer.sln 在Visual Studio、Rider或您首选的IDE中，为您的目标配置进行构建。
项目依赖项
S1MCP服务器：
- Melon加载器
- UniverseLib（用于反射实用程序）
- .NET 6.0
- 直接访问Schedule One本地课程
S1MCP客户端：
- Python 3.10+
mcp>=0.9.0（官方MCP SDK）pywin32>=306（Windows命名管道支持-传统，现在使用TCP）pydantic>=2.0.0（数据验证）
添加新工具
- 添加命令处理程序 在
S1MCPServer/Handlers/ - 注册处理程序 在
CommandRouter.cs - 添加工具定义 在
S1MCPClient/src/tools/ - 注册工具 在
S1MCPClient/src/main.py
有关详细的开发指南，请参阅单个项目的README。
故障排除
连接问题
问题： 无法连接到mod
解决：
- 确保日程表I在加载mod的情况下运行
- 检查主场景是否已加载（等待日志消息）
- 验证TCP服务器正在侦听端口8765（检查mod日志）
- 检查本地主机连接的防火墙设置
- 验证mod和客户端配置中的端口是否匹配（默认值：8765）
问题： 操作过程中连接丢失
解决：
- 检查mod日志是否有错误
- 确保游戏没有崩溃
- 客户端会自动重试连接错误
- 检查网络连接（尽管本地主机应始终正常工作）
模块未加载
问题： 模块未出现在MelonLoader中
解决：
- 验证DLL是否正确
Mods文件夹 - 检查MelonLoader日志中的加载错误
- 确保为正确的后端构建（IL2CPP与Mono）
- 验证所有依赖项是否存在（UniverseLib等）
工具错误
问题： 工具从mod返回错误
解决：
- 检查响应中的错误消息和代码
- 验证参数是否符合API规范
- 检查mod日志以获取详细的错误信息
- 确保游戏对象存在（例如，NPC ID有效）
- 在拨打电话之前，等待主场景完全加载
调试
启用DEBUG登录 S1MCPClient/config.json:
{
"log_level": "DEBUG"
}查看Schedule I游戏目录中的mod日志，了解详细的服务器端日志。
用例
1.代理调试
允许LLM代理诊断mod问题：
- 当模组不工作时检查游戏状态
- 检查NPC是否正确产卵
- 验证项目注册
- 检查mod交互
- 捕获和分析游戏日志以跟踪错误
例子：
User: "My mod isn't spawning NPCs correctly. Can you check what NPCs are currently in the game?"
LLM: [Calls s1_list_npcs] I found 15 NPCs. Here are the ones that might be relevant...
User: "The mod crashed at startup. Can you check the logs?"
LLM: [Calls s1_capture_logs with keyword="error"] I found several errors in the logs around the startup time.
The issue appears to be...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仅限（无法从网络访问） - 单一客户端：一次只能连接一个MCP客户端
- 验证：所有参数在执行前都经过验证
- 错误处理：优雅的错误处理可防止游戏崩溃
- 速率限制：操作自然受到游戏帧率的速率限制
相关文件
- S1MCP服务器自述 -详细的mod文档
- S1MCP客户端自述 -详细的客户文件
- API规范 -完整的API参考
- 愿景文件 -架构和设计决策
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 彻底测试
- 提交拉取请求
许可证
\[在此处添加您的许可证\]
积分
- 泰勒 -项目创建者和维护者
- 专为Schedule I改装社区打造
- 使用官方的模型上下文协议SDK
- 灵感来自UnityExplorer的反射技术
- 使用UniverseLib实现跨运行时兼容性
支持
对于问题和疑问：
- 检查上面的故障排除部分
- 查看单个项目的自述文件
- 检查附表I中的mod日志
- 启用DEBUG日志记录以获取详细信息
- 查看API工具使用规范
______________________________________________________________________
版本： 1.0.0\ 最后更新时间： 2025-01-27\ 作者 泰勒