Skip to main content
Glama
deenesjakoruzh
erivgout

SC2 Map Editor MCP

by erivgout
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

SC2 Map Editor MCP

一个 MCP 服务器，让编码代理通过直接操作文件内容来检查和编辑 StarCraft II 地图和 Mod，而不是驱动 Galaxy Editor 界面。

状态：预发布。 PLAN.md 的大部分已实现，差距被明确说明而非掩盖。阅读当前能力，或通过 sc2_get_server_info 询问运行中的服务器——那是针对特定构建和机器的权威答案。

当前能力

服务器自身通过 sc2_get_server_info 报告这些——这是针对运行中构建的权威答案。截至目前：

子系统

读取

写入

备注

工作区暂存

✅

✅

仅限解包后的文档目录

组件清单

✅

⚠️

ComponentList 为只读；DocumentInfo 字段和依赖链可写

GameData 目录

✅

✅

搜索、检查、解析继承、查找引用、修补/克隆/创建/删除。仅限自身文档——依赖项不会被加载

MPQ 归档 (.SC2Map, .SC2Mod)

✅

✅

在真实天梯地图上进行字节完全一致的往返处理，且在此处打包的地图可在编辑器中打开——参见 docs/native-helper.md

Galaxy 脚本

✅

✅

解析、符号、语法诊断、安全文本修补。没有类型检查——需要游戏的原生库。需要先构建随附的工具包

触发器

✅

⚠️

结构、名称、搜索。仅支持重命名——刻意不实现结构化编辑

本地化

✅

✅

文本表，精确保留 BOM 和 CRLF

SC2Layout

❌

❌

阶段 10

已放置对象 / 区域

✅

✅

两者都是 XML，而非二进制。放置、移动、删除——通过编辑器往返验证。不参考地形高度

地形

⚠️

❌

仅描述符（地块集、尺寸、悬崖集）。批量数据按魔数/版本/大小报告，从不解码

编辑器启动

✅

n/a

在 Galaxy 编辑器中打开文档；读取其日志。自动测试地图启动不提供——尚无可靠机制验证

为什么这些差距会在这些位置，以及每一行中 "⚠️" 的含义： docs/capabilities.md。

打包归档可以端到端工作：从 .SC2Map 打开的现有地图，在这里扩展，在这里重新打包，然后在 Galaxy 编辑器中打开时会作为真实文档加载，编辑器会按名称解析新增的目录。构建辅助工具需要 C++ 工具链和 Windows SDK（scripts/build-native.ps1）；没有它时，capabilities.mpq 报告 false，并且打包归档会被拒绝，并给出明确错误。

依赖项：本地依赖会加载，Blizzard 的不会。 地图旁的 .SC2Mod 目录会被索引，其中的对象对继承和引用可见——只读，因为此服务器从不修改依赖归档。Blizzard 的官方 Mod 位于安装的 CASC 存储中，此构建无法读取；它们被报告为 in-casc 而不是缺失，因为这与你地图损坏是完全不同的事情。

工具

工具

只读

用途

sc2_get_server_info

是

版本、配置、能力矩阵、限制

sc2_detect_installations

是

在不扫描磁盘的情况下找到 StarCraft II

sc2_open_document

否

暂存文档，获取 workspace_id

sc2_get_document_summary

是

种类、计数、组件、依赖、诊断、已知缺口

sc2_list_workspaces

是

重新连接后恢复 workspace_id

sc2_list_components

是

解析 ComponentList.SC2Components；将每个条目解析为实际文件

sc2_get_document_info

是

名称、作者、模组类型、图标、截图、依赖

sc2_get_dependencies

是

按解析顺序排列的依赖链

sc2_list_component_types

是

组件类型代码的参考表

sc2_list_catalog_domains

是

存在的目录域，附带条目计数

sc2_search_catalog

是

按 id 查找目录对象，可按域过滤

sc2_get_catalog_object

是

单个对象自身的声明，外加逐字 XML

sc2_resolve_catalog_object

是

带继承关系的有效值，以及每个值的来源

sc2_find_catalog_references

是

哪些内容引用了某个对象，以及它是否被共享

sc2_patch_catalog_object

否

按路径进行字段级编辑，并带共享对象警告

sc2_clone_catalog_object

否

以新 id 逐字节复制对象

sc2_create_catalog_object

否

添加新对象，最好带有父对象

sc2_delete_catalog_object

否

删除对象；被引用时拒绝

sc2_list_locales

是

存在的区域设置和文本表

sc2_search_text_keys

是

按键或值搜索文本表

sc2_get_text_value

是

读取一个本地化字符串

sc2_set_text_value

否

创建或更新本地化字符串

sc2_delete_text_key

否

删除本地化字符串

sc2_copy_text_key

否

在键或区域设置之间复制字符串

sc2_find_missing_localization

是

没有显示名称的目录对象

sc2_launch_editor

否

在 Galaxy Editor 中打开文档，以确认其能加载

sc2_get_editor_logs

是

列出或读取编辑器自身的日志

sc2_get_user_maps

是

用户的 Maps 文件夹，通过注册表解析

sc2_list_galaxy_files

是

文档中的脚本；标记生成的 MapScript

sc2_get_galaxy_file

是

读取脚本，可按行范围读取

sc2_get_galaxy_symbols

是

函数、变量、结构体、include

sc2_get_galaxy_diagnostics

是

带行号和列号的语法错误

sc2_apply_galaxy_patch

否

精确文本编辑，若破坏解析则拒绝

sc2_create_galaxy_file

否

添加库，先进行语法检查

sc2_list_triggers

是

触发器树，名称已解析

sc2_get_trigger

是

单个元素：类型、名称、内容、引用者、原始 XML

sc2_search_triggers

是

按名称查找触发器元素

sc2_rename_trigger

否

重命名元素（仅编辑 TriggerStrings）

sc2_list_placed_objects

是

地图上的单位、装饰物和点

sc2_place_object

否

使用下一个空闲 id 放置单位、装饰物或点

sc2_update_object

否

移动、旋转或缩放已放置的对象

sc2_delete_object

否

移除已放置的对象

sc2_list_regions

是

区域及其形状

sc2_create_region

否

使用下一个空闲 id 添加区域

sc2_update_region

否

移动或重命名区域

sc2_delete_region

否

移除区域

sc2_add_dependency

否

追加依赖；在加载顺序中后出现的条目生效

sc2_remove_dependency

否

移除依赖，按其 file: 部分匹配

sc2_set_document_info

否

设置单值 DocInfo 字段，如 ModType

sc2_get_terrain_summary

是

地形描述符及二进制组件头

sc2_create_unit_from_template

否

克隆一个单位，包含名称、属性和自己的武器

sc2_set_unit_weapon_damage

否

更改单个单位的伤害，而不影响共享该武器的单位

sc2_isolate_shared_object

否

让某个所有者拥有共享内容的独立副本

sc2_check_shared_object

是

编辑此内容是否会影响到多个所有者？

sc2_validate_document

是

此构建的所有检查，按类别列出，并指明未执行的检查

sc2_commit_document

否

写出暂存文档，包含备份和预检

sc2_diff_workspace

是

与源文件或快照的统一差异

sc2_get_changes

是

变更历史，每次变更前都有快照

sc2_revert_change

否

撤销最近的更改

sc2_create_snapshot

否

固定一个已知良好的状态

sc2_list_snapshots

是

工作区持有的快照

sc2_restore_snapshot

否

将暂存树回滚到某个快照

sc2_list_files

是

暂存树的分页列表

sc2_read_file

是

读取一个暂存文件（文本，或二进制文件的 base64）

sc2_search_files

是

在暂存文本文件中进行字面子串搜索

sc2_discard_workspace

否

删除暂存副本；源文件不受影响

Related MCP server: loenn-mcp

安全模型

这是一个根据语言模型的指令编辑你的地图的程序，因此默认设置是保守的：

  • 你的源文件永远不会被修改。 sc2_open_document 将文档复制到服务器拥有的暂存目录中。所有编辑都落在那里。sc2_commit_document 是文档离开该目录的唯一方式，并且它会在三个独立理由下拒绝——校验错误、源文件在你操作期间已发生变化、以及目标位置被占用——每一项都必须单独豁免。

  • 路径采用白名单制。 allowedRoots 之外的任何路径都无法读取或写入。路径会先进行规范化处理，因此无法通过符号链接逃逸。

  • 不会运行 shell。 外部程序通过参数数组、超时和精简环境来启动。没有“运行此命令”这样的工具。

  • 未实现就是未实现。 只有当代码存在 并且 其后端存在于本机时，能力标志才会是 true。服务器宁可明确告诉你它无法做某事，也不会去猜测。

  • 共享对象永远不会被意外编辑。 二十个单位共享一件武器。请求更改“这个单位的伤害”会克隆关联链，只重新连接该单位，并明确告诉你复制了什么——除非你明确要求修改共享的原始对象。

  • 编辑是无损、可预览、可逆的。 XML 更改精确拼接字节范围，因此编辑之外的一切——注释、属性顺序、CRLF 行尾、文件是否以换行符结尾——都保持不变。每次变更都会先创建快照，支持 dry_run，生成统一差异，如果任何部分失败则完全回滚，并且之后可以撤销。

要求

  • Node.js 22 或更新版本（针对 26 开发）

  • pnpm 10

  • Windows，用于任何涉及 StarCraft II 本身的操作。核心是跨平台的，但编辑器集成不是。

快速开始

pnpm install
pnpm run verify

verify 会运行 lint、类型检查、构建和完整测试套件——包括一个集成测试，该测试将构建后的服务器作为真实子进程启动，并通过 stdio 与其进行 MCP 通信。

要读取或写入打包的 .SC2Map 存档，你还需要 sc2mpq 辅助程序，它是构建出来的而非随附的——它是一个原生二进制文件，如果提交进去会携带构建机器的路径。获取固定版本的 StormLib 并编译：

pwsh scripts/bootstrap.ps1 -Only StormLib
pwsh scripts/build-native.ps1

这需要 CMake、MSVC 工具集以及 Windows SDK；请参阅 docs/native-helper.md，其中说明了缺少这些工具时会出现什么问题。如果你跳过它，除打包存档支持外的一切都能正常工作——capabilities.mpq 只会报告 false。

创建一个配置文件（参见 docs/configuration.md）：

node apps/sc2-mcp-server/dist/main.js doctor

doctor 会打印解析后的配置、检测到的 StarCraft II 安装以及能力矩阵。当服务器无法执行任何有用操作时（例如未配置任何允许的根目录），它会以非零状态退出。

连接 MCP 客户端

服务器通过 stdio 提供 MCP 服务。将你的客户端指向构建后的入口点：

{
  "mcpServers": {
    "sc2": {
      "command": "node",
      "args": ["C:\\path\\to\\SC2EditorMCP\\apps\\sc2-mcp-server\\dist\\main.js"],
      "env": {
        "SC2MCP_ALLOWED_ROOTS": "C:\\Users\\me\\OneDrive\\Documents\\StarCraft II\\Maps"
      }
    }
  }
}

仓库结构

apps/sc2-mcp-server/     MCP protocol layer: tools, schemas, error translation, stdio entry
packages/sc2-core/       Domain layer: config, path guard, workspace staging, MPQ adapter
packages/sc2-test-utils/ Test fixtures and temp-directory helpers
native/sc2mpq/           C++ MPQ sidecar (StormLib), built separately
docs/                    capabilities.md, sc2-formats.md, native-helper.md, galaxy.md
docs/adr/                Architecture decision records
vendor/PINS.json         Pinned upstream sources (checkouts are gitignored)
scripts/                 bootstrap.ps1 (fetch pins), build-native.ps1 (build the sidecar)
tests/                   Cross-package integration tests

分层规则（PLAN.md §4）：工具处理器验证输入、调用领域服务并转换结果。SC2 解析永远不会出现在工具处理器中。

许可与内容

MIT — 参见 LICENSE。商标和第三方声明见 NOTICE.md；本项目与 Blizzard Entertainment 无关联，也未获得其认可。

本仓库不包含任何 Blizzard 资产、提取的游戏数据或受版权保护的地图内容，将来也不会包含。测试夹具是项目自制的占位内容——适用于测试暂存和事务机制，但无法用于验证格式解析器，格式解析器必须对照真实的编辑器输出进行校验。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • loenn-mcp

    Magedeline
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables AI agents to read, edit, analyze, procedurally generate, and preview Celeste .bin map files without the Lönn editor.
    2
    MIT

  • procmem

    cutlerbenjamin1-cmd
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for Windows process memory inspection/editing and crash dump analysis, enabling live memory scanning, patching, pointer resolution, disassembly, and offline dump examination via structured tool calls.
    MIT