金大哥 - s1mcpserver MCP 详情

article

README

🚀 S1MCP：一级管制物品游戏的模型上下文协议

S1MCP是一个全面的系统，它使大语言模型（LLM）智能体能够通过模型上下文协议（MCP）与一级管制物品（Schedule I）游戏进行交互。此仓库包含游戏模组（S1MCPServer）和MCP服务器客户端（S1MCPClient），二者协同工作，为智能体调试和游戏状态检查提供支持。

🚀 快速开始

前提条件

已安装一级管制物品（Schedule I）游戏。
已为一级管制物品游戏安装MelonLoader。
已安装Python 3.10及以上版本。
使用Windows系统（游戏运行必需，TCP通信支持跨平台）。

安装步骤

1. 安装S1MCPServer模组

构建模组：

cd S1MCPServer
# 在Visual Studio或Rider中打开S1MCPServer.sln
# 为目标后端（IL2CPP或Mono）进行构建
# 配置：Debug IL2CPP或Release IL2CPP

安装编译后的DLL文件：
- 从bin/Debug IL2CPP/net6/（或Debug Mono）目录复制编译好的.dll文件。
- 将其放置在一级管制物品游戏的Mods文件夹中。
- 模组将自动在端口8765上启动TCP服务器。

2. 安装S1MCPClient

进入客户端目录：
```
cd S1MCPClient
```
安装Python依赖项：
```
pip install -r requirements.txt
```

（可选）创建配置文件：

# 在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文件夹的路径

运行步骤

启动加载了模组的一级管制物品游戏。
等待主场景加载完成（你会看到日志信息："Main scene loaded - S1MCPServer is active"）。
启动MCP客户端（如Claude Desktop、Cline等），它将自动连接到模组。

✨ 主要特性

实时游戏状态检查：可查询非玩家角色（NPC）、物品、建筑、载具和玩家数据。
游戏对象操作：可传送实体、修改生命值、生成物品。
智能体调试：允许大语言模型诊断模组问题并提出修复建议。
开发工具：为模组开发者提供强大的调试和开发工具。

📦 安装指南

安装S1MCPServer模组

构建模组：

cd S1MCPServer
# 在Visual Studio或Rider中打开S1MCPServer.sln
# 为目标后端（IL2CPP或Mono）进行构建
# 配置：Debug IL2CPP或Release IL2CPP

安装编译后的DLL文件：
- 从bin/Debug IL2CPP/net6/（或Debug Mono）目录复制编译好的.dll文件。
- 将其放置在一级管制物品游戏的Mods文件夹中。
- 模组将自动在端口8765上启动TCP服务器。

安装S1MCPClient

进入客户端目录：
```
cd S1MCPClient
```
安装Python依赖项：
```
pip install -r requirements.txt
```

（可选）创建配置文件：

# 在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（数据验证）

添加新工具

在S1MCPServer/Handlers/中添加命令处理程序。
在CommandRouter.cs中注册处理程序。
在S1MCPClient/src/tools/中添加工具定义。
在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