ICCPlus MCP

English | 한국어

一个 schema 感知的 Model Context Protocol 服务器，用于创建、检查、编辑、验证和打包 ICC Plus 项目。

本项目是通过与 AI 编码代理协作的 vibe coding 方式创建的。

该服务器为 AI 代理提供完整的 ICC Plus 项目模型，该模型直接从上游源码生成并建立索引：

• 项目 schema 和当前默认值均从 ICC Plus 源码生成；

• 所有 59 个已声明模型类型和 893 个唯一字段均可发现；

• 创建器和独立查看器中的全部 227 个作者编写的源码/构建/配置/补丁文件以及 1,411 个命名函数/方法均已建立索引，包含精确源码、SHA-256 证据、签名、模型字段使用情况和行跨度；

• 所请求部署仓库中的全部 75 个文件及其官方查看器压缩包内的 34 个文件均具有字节数和 SHA-256 清单；

• 高层工具保留 ID、顺序、父链接和双向成员关系；

• 通用 RFC 6902 补丁使新的或不常见的上游字段保持可访问；

• 结构和语义验证在保存前捕获悬空引用；

• 基于源码的 Custom CSS 工具公开官方查看器类、解析项目选择器，并在保存前诊断语法/级联风险；

• ICC Plus v2.10 的行宽保留、构建表单可见性/调试标题、拆分分数重算控件、隐藏行菜单和 addon 状态 CSS 类均已建模且可发现；

• 无需打开创建器 UI 即可构建官方 web 和本地查看器压缩包。

兼容性目前基于 ICC Plus v2.10.1 生成，源码提交为 b33bfb9b29e0a84a035a56d7e1827e42fe0f7000。

这是什么

ICCPlus MCP 是围绕 ICC Plus 项目 JSON 的创作和构建适配器。它不重新实现浏览器查看器。选择效果、音频播放、对话框、渲染和其他交互行为仍在官方查看器中执行。该服务器理解并验证驱动这些行为的配置，可以针对提供的状态评估需求树，并可以将结果打包到官方查看器模板中。

该设计有意分为两层：

agent
  ├─ discover: capabilities, schema, resources, prompts
  ├─ author: create/update/move/duplicate/import entities
  ├─ complete field access: atomic JSON Patch for every schema field
  └─ verify: normalize, validate, evaluate, save, build viewer
                           │
                           ▼
             revisioned in-memory project session
                           │
                           ▼
                ICC Plus JSON / viewer ZIP

Related MCP server: ts-language-mcp

要求

• Node.js 20 或更高版本

• 一个 ICC Plus 项目工作区

• 对于查看器构建，需要来自 ICC Plus 部署仓库 的 web_viewer.zip 或 local_viewer.zip

安装与构建

git clone https://github.com/Kz2g1ew-commits/ICCPlus-MCP.git
cd ICCPlus-MCP
npm ci
npm run build

可执行文件为 dist/index.js，通过 stdio 通信。协议输出使用 stdout；诊断信息使用 stderr。

连接代理

将 ICCPLUS_WORKSPACE 设置为服务器唯一可读写的目录。相对的项目、资源、模板和输出路径都在此目录内解析。现有符号链接会被解析，且无法逃逸该目录。

Codex

codex mcp add iccplus \
  --env ICCPLUS_WORKSPACE=/absolute/path/to/iccplus-workspace \
  -- node /absolute/path/to/ICCPlus-MCP/dist/index.js

使用 codex mcp list 验证，如果客户端已打开则重新启动。等效的用户或受信任项目 config.toml 条目为：

[mcp_servers.iccplus]
command = "node"
args = ["/absolute/path/to/ICCPlus-MCP/dist/index.js"]
env = { ICCPLUS_WORKSPACE = "/absolute/path/to/iccplus-workspace" }
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true

Codex CLI、IDE 扩展和 ChatGPT 桌面 Codex 界面共享此配置。项目级条目可以放在 .codex/config.toml 中，并且仅对受信任项目加载。

其他 stdio MCP 客户端

使用客户端的本地服务器配置，命令如下：

{
  "command": "node",
  "args": ["/absolute/path/to/ICCPlus-MCP/dist/index.js"],
  "env": {
    "ICCPLUS_WORKSPACE": "/absolute/path/to/iccplus-workspace"
  }
}

可选环境变量：

• ICCPLUS_WORKSPACE：文件系统边界；默认为服务器进程的 CWD。

• ICCPLUS_MAX_ASSET_BYTES：本地资源的最大大小；默认为 26,214,400 字节（25 MiB）。

• ICCPLUS_DUPLICATED_TEXT_LIMIT_BYTES：复制到工具结果文本回退中的最大大小；默认为 8,192 字节。更大的精确结果仍可在 structuredContent 中获取。设置为 -1 以使用旧版无限制文本。

推荐的代理工作流程

1. 调用 iccplus_capabilities 获取相关的功能族或字段。

2. 创建或打开项目，并保留其 project_id 和 revision。

3. 首先创建被引用的顶层实体：points、variables、words、groups、designs 和 global requirements。

4. 然后创建 rows，接着是 choices，最后是 scores/addons/requirements。

5. 向变更操作传递 expected_revision。对于大规模更改，使用 dry_run。

6. 对于高级样式，使用 iccplus_css_catalog 发现精确选择器，分析候选 CSS，然后使用 iccplus_css_set 应用。

7. 调用 iccplus_validate，并在有用时调用 iccplus_evaluate_requirements。

8. 显式保存或构建官方查看器压缩包。

代理还可以请求捆绑的 author-iccplus-project 或 audit-iccplus-project 提示词。

示例用户请求：

创建一个 CYOA，具有 10 个起始积分、三个互斥的起源选择，以及一个通过选择起源解锁的武器行。验证它，将其保存为 projects/origins.json，然后使用 templates/web_viewer.zip 构建 web 查看器。

工具

实体工具涵盖 row、backpack_row、choice、addon、selectable_addon、score、requirement、point、variable、word、group、row_design_group、choice_design_group、global_requirement、sound_effect 和 category。

资源和提示词

安全与数据完整性

• 变更在克隆数据上进行，并原子提交。

• expected_revision 提供乐观并发控制。

• dry_run 返回预期的验证报告，而不更改会话。

• no_new_errors 是默认的变更策略；strict 要求完全有效的结果；none 可用于分阶段修复。

• JSON Patch 阻止原型污染指针段。

• 保存使用临时文件加重命名。

• 除非 overwrite=true，否则不会替换现有文件。

• 资源值会从普通查询输出中编辑掉，并按媒体类型和近似字节大小报告。

• 精确路径读取避免返回完整项目，大型工具结果不会同时复制到文本和结构化输出中。

• 未知字段在加载、编辑、规范化和保存后仍然保留，以实现前向兼容。

验证覆盖

验证器将生成的 App schema 与以下检查相结合：

• 重复或缺失的 ID 以及位置索引不匹配；

• addon 父级链接；

• 每个已建模的行、选项、分数、组、变量、单词、设计、声音和全局需求引用；

• 分数到分数点以及分数点激活引用；

• 嵌套需求、阈值和全局需求循环；

• 组和设计组的互惠成员关系；

• 不兼容的查看器导出模式；

• 自定义 CSS 语法、危险的遗留结构、未解析的 ICC Plus ID 选择器、过大的作用域、外部资源以及可能的内联样式冲突；

• 分数整数/浮点数和初始化不变量。

需求求值器实现了 id（包括 /ON#N）、points、pointCompare、or、selFromGroups、selFromRows、selFromWhole、gid、word、否定、运算符和嵌套前置条件。它返回可解释的跟踪信息，而不仅仅是布尔值。

高级自定义 CSS

ICC Plus 将 CSS 存储在最顶层的 customCSS 字段中，并在官方创建器/查看器中通过 textContent 将其注入为 style#customCSS。MCP 从固定的独立查看器标记中派生其目录，包括 row-{id}、row-{id}-bg、row-{id}-header、choice-{id}、选项状态类、addon 和可选择的 addon-{id}。

iccplus_css_catalog 可以返回所有打开项目行、选项和可选择 addon 的 CSS 转义选择器。iccplus_css_analyze 解析嵌套规则，报告特异性并匹配的实体，并在声明可能输给 ICC Plus 内联样式时发出警告。iccplus_css_set 通过与项目其他变更相同的版本化事务和验证策略持久化结果。

对于 v2.10+，目录还涵盖 .row-bg-{rowId}、.row-header-{rowId}、.choice、.addon-selectable 以及 .addon-enabled、.addon-disabled、.addon-selected 和 .addon-unselected 状态类，同时保留旧的行选择器拼写。

这有意采用静态分析。计算样式、响应式布局和交互状态渲染仍由官方查看器负责；不捆绑浏览器自动化运行时或无关的浏览工具。

查看器构建

iccplus_build_viewer 接受工作区内的官方模板 ZIP。

• Web 模式写入 project.json。

• 本地模式将项目嵌入 js/app.js 中。

• 加载标题、文本、颜色、收藏图标、背景、字体和项目自定义 CSS 都会保留在打包的项目中。

• 可选的图像分离功能从全局样式、行、背包行、设计组和查看器设置中提取数据 URL；相同的资源会进行去重。

模板的查看器 JavaScript 仍然是运行时的事实来源。

上游同步

项目模型直接从上游源生成。针对 ICC-Plus-Svelte 的检出重新运行分析器：

npm run analyze:upstream -- --source ../ICC-Plus-Svelte --deployment ../ICCPlus
npm test
npm run check
npm run build

分析器使用 TypeScript AST 重新生成：

• src/generated/iccplus.schema.json

• src/generated/default-project.json

• src/generated/source-analysis.json

• src/generated/deployment-manifest.json

• src/generated/third-party-licenses.json

• analysis/CODEBASE_INVENTORY.md

如果新声明的上游模型类型未分配给功能族，则测试失败。source-analysis.json 还记录声明、导入、完整的 SHA-256 寻址源文件、组件标签、每个命名的源函数/方法、精确的函数体以及源出现位置。部署清单涵盖 wahaha303/ICCPlus 中的每个文件以及每个官方查看器存档条目。代理可以通过 iccplus_capabilities 查询 field:<name>、type:<name>、function:<name> 或 source:<relative-path>；deployment:<relative-path> 返回部署证据。函数查询支持 file、offset 和 limit，以便管理重复的本地名称；include_source=false 返回紧凑的元数据。

开发

npm test
npm run test:stdio
npm run verify:upstream -- --source ../ICC-Plus-Svelte --deployment ../ICCPlus
npm run check
npm run build
npm run inspect
npm pack --dry-run

测试套件涵盖生成的模型覆盖、模型图变更、规范化、引用重写、所有需求族、RFC 6902 原子性、查看器打包以及内存中的 MCP 客户端/服务器交换。

有关完整的语义功能映射，请参阅 analysis/FEATURE_ANALYSIS.md。生成的字段/函数/组件证据位于 analysis/CODEBASE_INVENTORY.md。逐需求验证记录位于 analysis/COMPLETION_AUDIT.md。

归属

ICC Plus 由 wahaha303 开发。此 MCP 服务器是一个独立的集成，不会替换或修改官方创建器/查看器。两个项目均根据 MIT 许可证分发；请参阅 LICENSE。上游和捆绑的依赖声明保留在 THIRD_PARTY_NOTICES.md 和 iccplus://licenses 资源中。