A
licenseNot graded
qualityD
maintenanceEnables LLM-driven text game state management by exposing MCP tools for managing players, locations, items, entities, and abstract concepts.
MIT
emptysock-mcp
by eleferrets
emptysock-mcp
Model Context Protocol 服务器，用于 EmptySock 游戏引擎。将引擎系统 — NavMesh、Physics、Scene、Save 和 Actor — 暴露为可由 Claude Desktop、AI 代理和 Claude API 使用的 MCP 工具。
环境要求
Node.js 20+
npm 9+
Related MCP server: Hayba
安装
git clone https://github.com/eleferrets/emptysock-mcp.git
cd emptysock-mcp
npm install
npm run build配置
复制示例环境变量文件，并填写你需要的任何值：
cp .env.example .env变量 | 必填 | 描述 |
| 否 | 用于经过身份验证的引擎 API 调用的 Bearer 令牌。 |
| 否 | SSE 传输请求所需的 Bearer 令牌。留空以禁用身份验证。 |
| 否 | 存档工具可读写的绝对路径。默认是进程的工作目录。生产环境中请显式设置。 |
切勿提交
.env— 它已被 gitignore。将密钥存放在 CI/CD 的密钥管理器中，而不是仓库中。
运行服务器
stdio（推荐用于本地使用和 Claude Desktop）
npm run dev # development — tsx, no build step
# or after building:
node dist/server.js服务器通过 stdin/stdout 通信。没有网络端口，也没有身份验证暴露面。
Claude Desktop
将服务器添加到你的 Claude Desktop 配置中（在 macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：
{
"mcpServers": {
"emptysock": {
"command": "node",
"args": ["/absolute/path/to/emptysock-mcp/dist/server.js"],
"env": {
"SAVE_BASE_DIR": "/absolute/path/to/your/saves"
}
}
}
}重启 Claude Desktop。EmptySock 工具将出现在工具选择器中。
可用工具
NavMesh
工具 | 描述 |
| 在已加载的导航网格上，计算两个 2D 世界点之间的 A* 路径。返回有序路点；若不存在路径，则返回 |
| 距离给定世界点最近的可行走导航网格节点。 |
示例 — 查找路径：
{
"from": { "x": 0, "y": 0 },
"to": { "x": 100, "y": 50 },
"mapId": "level1"
}Physics
工具 | 描述 |
| 在 2D 物理空间中发射一条射线；返回第一个命中的实体、命中点和法线。 |
| 在 3D 物理空间（Rapier3D）中发射一条射线；返回第一个命中结果。 |
| 所有 2D 碰撞体与一个圆形相交的实体 ID。 |
| 按实体 ID 获取物理体的当前位置、速度和角速度。 |
示例 — 圆形重叠：
{
"center": { "x": 50, "y": 50 },
"radius": 20,
"layerMask": 3
}Scene
工具 | 描述 |
| 场景中所有处于活动状态的实体 ID。 |
| 指定实体的标签、活动状态和组件列表。 |
| 实体上某个组件的序列化状态。 |
示例 — 获取组件：
{
"sceneId": "gameplay",
"entityId": "player-001",
"componentType": "Transform"
}Save
所有存档工具均被沙箱限制在 SAVE_BASE_DIR 内。路径穿越（..、绝对路径）会在 schema 层被拒绝，并在解析时再次被拒绝。
工具 | 描述 |
| 从磁盘读取一个存档槽，并返回其 JSON 数据。 |
| 将一个 JSON 对象写入指定的存档槽。 |
| 删除一个存档槽。 |
| 列出所有可用的存档槽。 |
示例 — 写入：
{
"slot": "autosave",
"data": { "level": 3, "score": 4200, "checkpoint": "bridge" }
}存档槽名称仅由字母数字和连字符/下划线组成（例如 slot1、autosave、new-game-plus）。
Actor
工具 | 描述 |
| 将消息排队到指定 actor 的邮箱中。在下次 ActorSystem flush 时处理。 |
| 向所有已注册的 actor 广播一条消息。 |
| actor 邮箱中待处理消息的数量。 |
示例 — 发送消息：
{
"actorId": "enemy-spawner",
"message": { "type": "SPAWN_WAVE", "payload": { "wave": 3 } }
}顺序说明： ActorSystem 会在调用
update()之前清空每个 actor 的邮箱。在第 N 帧期间发送的消息会在第 N 帧的更新逻辑运行之前全部处理完毕。
开发
npm run lint # TypeScript type-check (no emit)
npm test # run Vitest suite
npm run test:watch # watch mode测试位于 src/tests/。它们涵盖输入验证、工具分发和安全不变量（路径穿越、shell 元字符注入、未知工具名）。
添加工具
创建
src/tools/<domain>.ts— 导出toolDef数组条目和一个handler函数。通过
buildRegistry()中的register()调用，将两者注册到src/tools/index.ts。在
emptysock-engine中的api-reference.json中添加一个条目。向
eleferrets/emptysock-ai-skills添加一个技能文件。
使用 src/lib/ 中共享的辅助工具：
parse(schema, raw)— Zod 解析，失败时抛出McpError(InvalidParams)SafeRelPath、SafeId、Vec2、Vec3、GameNum— 可复用的 Zod schematextResponse(data)— 构建标准 MCP 文本内容响应wrapError(err)— 记录到 stderr，并以McpError(InternalError)重新抛出
安全模型
关注点 | 缓解措施 |
参数格式错误 | 对每个输入执行 Zod |
路径穿越 | 在存档处理器中使用 |
Shell 注入 | 不使用带模板字符串的 |
凭据泄漏 | 密钥仅来自 |
输入过大 | 每个 schema 字段的字符串长度均设上限 |
未知工具 |
|
Available Tools
21 toolsactor_broadcastB
Broadcast a message to all registered actors in the current ActorSystem.
Inputs: message (required).
actor_inbox_sizeB
Return the number of pending messages in an actor's inbox.
Inputs: actorId (required).
actor_send_messageA
Enqueue a message in a specific actor's inbox. The actor processes it on the next flush pass.
Inputs: actorId (required), message (required).
emptysock_layer_infoA
Return reference documentation for the EmptySock LayerSystem API: defineLayer, addToLayer, setVisible, setParallax, and RenderSystem integration.
Inputs: no named parameters.
gms2_inspect_projectA
Read a GameMaker Studio 2 .yyp project file and return a JSON summary: project name, asset counts by type, and lists of object and script names. Read-only — does not modify any files.
Inputs: yypPath (required).
particle_emitter_configA
Get or set a ParticleSystem emitter configuration by emitter ID. Omit config to read; provide config to write.
Inputs: emitterId (required), config.
physics_body_stateA
Return the current position, velocity, and angular velocity of a physics body by entity ID.
Inputs: entityId (required).
physics_overlap_circleB
Return all entity IDs whose 2D colliders overlap a circle.
Inputs: center (required), radius (required), layerMask.
physics_raycast_2dB
Cast a ray in 2D physics space and return the first hit entity, hit point, and normal.
Inputs: origin (required), direction (required), maxDistance (required), layerMask.
physics_raycast_3dC
Cast a ray in 3D physics space (Rapier3D) and return the first hit.
Inputs: origin (required), direction (required), maxDistance (required), layerMask.
save_deleteA
Delete a save slot from disk.
Inputs: slot (required).
save_listA
List all available save slots.
Inputs: subdir.
save_readA
Read a save slot from disk and return its JSON data.
Inputs: slot (required).
save_writeA
Write JSON data to a save slot on disk.
Inputs: data (required), slot (required).
scene_create_entityC
Add a new entity to a scene. Returns the new entity's ID.
Inputs: sceneId (required), tag, components.
scene_entity_infoC
Return the tag, active state, and component list for a specific entity.
Inputs: sceneId (required), entityId (required).
scene_get_componentB
Retrieve the serialised state of a specific component on an entity.
Inputs: sceneId (required), entityId (required), componentType (required).
scene_list_entitiesB
List all entity IDs currently active in a scene.
Inputs: sceneId (required).
story_graph_exportA
Export the Story Graph (VNSystem) for a named scene as a JSON object containing nodes and edges.
Inputs: sceneId (required), graphId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.4/5.0
Scored across 21 tools
Disambiguation5/5
Tools are clearly separated by domain (navmesh, physics, scene, save, actor, etc.) and each tool targets a distinct action or query. Even within physics, 2D and 3D raycasts are explicitly differentiated. No two tools appear to do the same thing.
Naming Consistency5/5
All tools follow a consistent domain_verb_noun pattern (e.g., scene_create_entity, save_list, actor_send_message). Suffixes like _2d and _3d are uniform, and the one odd name (emptysock_layer_info) still adheres to the same style. Naming is predictable and coherent.
Tool Count3/5
With 21 tools, the count falls in the 16-25 range, which is borderline heavy. However, the server covers many distinct subsystems, so each tool arguably earns its place, but the overall number feels slightly excessive for a single MCP server.
Completeness3/5
The set covers core read/query operations across multiple domains, but there are notable gaps: scene entities can be created and inspected but not updated or deleted, physics only offers queries (no manipulation), and particle control is limited to configuration. This leaves some lifecycle operations incomplete.
Maintenance
ActivitySlowing
ResponsivenessNo recent community issues
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server enabling AI agents to author Unreal Engine 5 scenes directly, with tools for spawning actors, building PCG graphs, validating physics, generating terrain, and more through a single MCP connection.13MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude Code to the Unity Editor via MCP, enabling AI-driven control of scenes, assets, components, UI, animations, and more through 91 tools.2MIT
- AlicenseCqualityCmaintenanceEnables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.2814 npmMIT