CLIP STUDIO PAINT 5.1.2 生产版 MCP

[!IMPORTANT] 非官方社区项目。 本仓库与 CELSYS 无关联、未经其认可或支持。它是一个本地 stdio MCP 桥接器，适用于 Windows + CLIP STUDIO PAINT 5.1.2.0 生产版 + zh-CN + DPI 120。其他 CSP 版本、预览版/抢先体验版、区域设置、DPI 值和操作系统不受捆绑的严格配置文件支持。

截至 2026-08-25，为本项目审阅的 CELSYS 公开文档未记录通用的 CSP 文档/图层 API、脚本运行时、MCP 或受支持的无头 CLI；其发布的 SDK 仅限于 EX 滤镜插件。在已验证的 5.1.2 zh-CN 配置文件中，CSP 的自定义绘制区域也未通过 Windows UI Automation 暴露有意义的图层、画笔或菜单对象。因此，本项目提供 33 个经过刻意约束的能力，这些能力基于可见窗口检查、截图、白名单输入、已注册的快捷键/自动动作和文件交换构建。它不是原生图层对象 API，也无法诚实地暴露 CSP 的每个内部功能。

包含内容

• 33 个 MCP 工具；请参阅完整的工具目录。

• CSP 可执行文件认证：固定路径、Authenticode 签名、CELSYS 公司字段、精确文件版本和 SHA-256。

• 每监视器 DPI 感知 V2，带有严格的 zh-CN / DPI 120 生产配置文件。

• 进程、主窗口、前台窗口、对话框、显示、用户活动、截图、像素采样和截图差异检查。

• 截图绑定的指针移动、单击、双击、拖拽、滚动、导航键和 Unicode 文本输入。

• 版本化的快捷键命令、受约束的命令序列和用户注册的自动动作。

• 配置的路径根目录，用于资产列表、文件元数据、导入分发、导出扫描和稳定输出验证。

• 严格的本地 #32770 文件对话框填写/提交，带有明确的覆盖意图。

• 所有 10 个原子输入工具的预检确认协议。

• 仅本地 stdio 传输：无监听端口、shell、注册表、任意进程或不受限制的文件系统工具。

隐私边界

本地 stdio 意味着此服务器不打开网络监听器；这并不意味着所有 MCP 数据都保留在机器上。MCP 主机接收工具输入和输出，包括截图、可见 UI 文本、窗口标题和配置的绝对路径，并可能根据该主机的数据策略将其发送到远程模型。请保持敏感文档关闭，查看主机的隐私控制，并将 CSP 中显示的文本或图像视为不可信数据，而非代理的指令。

Related MCP server: atomic-computer-mcp

支持矩阵

当可执行文件、快捷键文件、区域设置、DPI 或窗口标识不匹配时，严格配置文件会失败关闭。不要移除这些检查以使另一台机器“工作”；请创建并验证新的配置文件。

快速开始：配置 → 安装 → 测试 → 注册

先决条件：Git、CPython 3.13、Codex 和确切支持的 CSP 生产构建。将仓库克隆到受信任的本地目录：

git clone https://github.com/A2pha/clip-studio-paint-5.1.2-production-mcp.git
Set-Location .\clip-studio-paint-5.1.2-production-mcp

1. 配置本地机器

在安装前运行配置助手。它会创建 gitignored 的本地配置；特定于机器的 CSP、快捷键配置文件和资产根路径不得提交。

$CspExecutable = Read-Host 'Absolute path to CLIPStudioPaint.exe 5.1.2 production'
& .\scripts\configure.ps1 -CspExecutable $CspExecutable

配置必须标识：

• 生产版 CLIPStudioPaint.exe；

• 预期的 CELSYS 签名、5.1.2.0 版本和可执行文件 SHA-256；

• 当前用户的 CSP 快捷键设置文件及其 SHA-256 值；

• 三个独立的资产根目录：只读的 Input、读写的 Working 和读写的 Exports。

除非显式覆盖，否则助手会在当前用户的 %APPDATA% 下发现受支持的快捷键文件，并在当前用户的“文档”文件夹下创建资产根目录 CSP-MCP-Assets。当这些位置不同时，请使用 -ShortcutProfileFiles 和 -AssetsRoot。它还会将仓库中惰性的 mcp-dialog-smoke.svg 夹具复制到 Input 根目录（当该文件名不存在时）；它从不覆盖现有文件。

在运行时，配置按以下顺序解析：CSP_MCP_CONFIG 中的绝对路径，然后是 config/config.local.json，然后是跟踪的占位符 config/config.json。跟踪的文件是模板，而非可信任的机器配置文件。

将生成的哈希视为对您已检查过的机器的认证，而非任意可执行文件或快捷键文件可信的证据。

2. 安装锁定依赖项

& .\scripts\install.ps1

安装程序在仓库中创建 .venv，并从 requirements.lock.txt 安装 mcp==1.29.0、pywin32==312 和 Pillow==12.3.0，并强制校验哈希。如果 ACL 审计拒绝不受信任的祖先目录，请将检出/资产移动到受信任的目录，或让管理员审查祖先 ACL。显式的风险接受开关仅跳过初始祖先门；它不会修复 ACL，也不会绕过最终要求（即每个被审计的根目录和文件树都必须受到保护）。

3. 注册前测试

$Python = Join-Path $PWD '.venv\Scripts\python.exe'

& $Python -X utf8 -m compileall -q csp_mcp server.py tests
& $Python -X utf8 -m unittest discover -s tests -p 'test_*.py' -v
& $Python -X utf8 .\tests\smoke_stdio.py

编译和单元测试在 GitHub Actions 的 Windows/Python 3.13 上运行。stdio 冒烟测试还需要有效的本地配置和受支持的 CSP 环境。它有意排除在托管 CI 之外。

可选的交互式验收测试会恢复并聚焦 CSP，打开已知的 Windows 文件对话框，验证配置的夹具路径而不提交，取消该确切对话框，并比较截图：

& $Python -X utf8 .\tests\acceptance_interactive.py

仅在受支持的 CSP 构建打开、没有文档保存提示、且您未同时使用鼠标或键盘时运行它。它不能替代手动审查。

4. 使用 Codex 注册

& .\scripts\register-codex.ps1

注册后重启 Codex，然后调用 csp_health，接着调用 csp_capabilities。要移除注册，请运行：

& .\scripts\unregister-codex.ps1

注册和注销会在 Codex 的 config.toml 旁边保留带时间戳的回滚备份。该备份包含完整的先前 Codex 配置，可能包含敏感的环境值。脚本会拒绝该位置的重解析点或不安全的写入 ACL；请保护该目录，并在确认新注册正常工作后删除过时的备份。

注册将 writes 保留为默认批准模式。它仅自动批准 10 个原子消费者，这些消费者无法在没有服务器颁发的单次预检令牌的情况下运行：移动、单击、拖拽、滚动、文本、导航键、已注册命令、自动动作、命令序列和严格的本地文件对话框。csp_preflight 本身仍受批准门控。

确认令牌流程

对于普通的可见 UI 输入：

1. 调用 csp_health、csp_capabilities 和 csp_get_state。

2. 调用 csp_capture 进行只读规划。

3. 调用 csp_preflight(operation="input", identifier="exact_tool_name", parameters_json="exact JSON parameters")，不带旧的捕获 ID。

4. 用户批准预检后，立即再次调用 csp_capture 并验证目标仍然可见。

5. 使用新鲜的 captureId、返回的 confirmToken 和逐字节等效的业务参数调用确切的原子工具。

6. 检查操作后的捕获；为下一个输入重复预检。

令牌在 45 秒后过期，单次使用，绑定完整参数和确切的 CSP 窗口/对话框标识，并因前台、像素、生成或输入时间变化而失效。参数不匹配会消耗令牌。csp_cancel 是一个狭窄的例外：它仍受主机批准门控，并且仅向确切的 CSP 主窗口或其唯一的已验证标准对话框发送一个 Escape。

MCP 协议不向服务器提供人类已批准主机提示的加密证明。因此，信任边界包括配置的 Codex 主机。以同一用户身份运行的恶意自定义 stdio 客户端不在范围内；请参阅安全模型。

文件操作

接受路径的工具仅在本地配置创建的三个根目录内操作。它们拒绝 UNC/设备路径、备用数据流、通配符、保留设备名称、重解析点、隐式覆盖和其他不支持的情况。现有路径通过句柄检查，现有输入/替换目标检查硬链接，但这些缓解措施无法消除所有检查到使用之间的竞态。

保存或替换文件使用此显式流程：

1. 使用 csp_validate_path 验证确切目标。

2. 预检并运行已注册的 document.save_as_dialog 命令。

3. 获取确切的主/对话框 HWND，然后使用完整路径、意图和提交标志预检 csp_native_file_dialog。

4. 仅通过已验证的文件对话框控件配置文件提交。任何后续的覆盖/格式提示都需要手动处理。

5. 仅在 csp_wait_for_file 验证稳定、非空目标并返回其 SHA-256 后接受完成。

Ctrl+S 未注册，因为 CSP 不通过公共 API 暴露当前文档路径。通用坐标/文本工具不得用于打开/保存/导出、账户、云、商店、社区或发布工作流。

csp_open_document 将 CLIPStudioPaint.exe <path> 作为参数数组分发，因为该行为在参考部署中观察到。CELSYS 未将其记录为稳定的 CLI 契约。成功响应证明分发和 CSP 窗口证据，而非哪个文档选项卡拥有该路径；请使用捕获验证结果。

自动动作

跟踪的自动动作注册表初始为空。在 CSP 中创建并手动验证每个动作，仅绑定 Ctrl+Alt+[Shift]+F1..F12，然后按照自动动作设置中的说明在本地注册。

• 自动动作在 CSP PRO/EX 中可用，而非 DEBUT。

• 每个动作都需要预检和确切的注册 ID。

• 生产配置拒绝 effect: "filesystem"。

• 每个条目必须证明 attested_no_file_io: true。

• 服务器无法解析专有的 .laf 文件，因此该证明是管理员承诺而非技术证明。

对于打开/保存/导出，请使用专用的已验证文件工作流。

项目布局

.
├─ csp_mcp\                 MCP application, policy, controller, Win32 backend
├─ config\                  tracked examples and registries
├─ docs\                    tools, security, research, Auto Actions
├─ scripts\                 configure, install, register, unregister, ACL audit
├─ tests\                   unit, stdio smoke, opt-in interactive acceptance
├─ server.py                stdio entry point
├─ pyproject.toml
├─ requirements.txt
└─ requirements.lock.txt

文档和来源

• 工具目录

• 安全模型

• 自动动作设置

• GitHub 项目比较

• OpenAI Codex MCP 文档

• CELSYS 自动动作手册

• CELSYS 公共 SDK 页面

• CELSYS 支持的打开/导入格式

开发和发布边界

拉取请求应保留默认拒绝的版本/签名/配置文件检查，并为行为变更添加测试。托管 CI 仅执行编译和单元测试；依赖 CSP 的冒烟测试和交互式验证需要在专门准备的 Windows 工作站上进行。请参阅 CONTRIBUTING.md 和安全策略。

捆绑的配置文件仅针对上述确切目标进行验证。CSP 更新、语言变更、DPI 变更、快捷方式编辑或许可证版本变更，都需要在发布新配置文件之前重新进行签名/哈希检查、截图校准、快捷方式验证和非破坏性验收测试。

许可证与商标

本项目基于 MIT 许可证 发布。第三方依赖声明记录在 THIRD_PARTY_NOTICES.md 中。

CLIP STUDIO PAINT 和 CELSYS 是其各自所有者的商标。本仓库不分发 CELSYS 软件、SDK 源代码、私有协议或逆向工程的 .clip 格式代码。