ICCPlus MCP

English | 한국어

Сервер Model Context Protocol с поддержкой схемы для создания, просмотра, редактирования, проверки и упаковки проектов ICC Plus.

Этот проект был создан с помощью виб-кодинга в сотрудничестве с ИИ-агентом по кодингу.

Сервер предоставляет ИИ-агенту полную модель проекта ICC Plus, сгенерированную и проиндексированную непосредственно из исходного кода вышестоящего проекта:

• схема проекта и текущие значения по умолчанию генерируются из исходного кода ICC Plus;

• все 59 объявленных типов моделей и 893 уникальных поля доступны для обнаружения;

• все 227 авторских файлов исходного кода/сборки/конфигурации/патчей и 1 411 именованных функций/методов в создателе и автономном просмотрщике индексируются с точным исходным кодом, SHA-256-доказательствами, сигнатурами, использованием полей модели и диапазонами строк;

• все 75 файлов в запрошенном репозитории развертывания и 34 файла внутри его официальных архивов просмотрщика имеют байтовые счетчики и SHA-256-манифесты;

• высокоуровневые инструменты сохраняют идентификаторы, порядок, родительские ссылки и взаимные членства;

• универсальное патчирование RFC 6902 сохраняет доступ к новым или необычным полям вышестоящего проекта;

• структурная и семантическая проверка выявляет висячие ссылки до сохранения;

• инструменты Custom CSS на основе исходного кода раскрывают официальные классы просмотрщика, разрешают селекторы проекта и диагностируют риски синтаксиса/каскада до сохранения;

• сохранение ширины строк ICC Plus v2.10, видимость форм сборки/отладочные заголовки, раздельные элементы управления пересчетом оценок, скрытые меню строк и CSS-классы состояний аддонов моделируются и доступны для обнаружения;

• официальные веб- и локальные архивы просмотрщика можно собрать без открытия пользовательского интерфейса создателя.

Совместимость в настоящее время генерируется из ICC Plus v2.10.1, коммита исходного кода b33bfb9b29e0a84a035a56d7e1827e42fe0f7000.

Что это такое

ICCPlus MCP — это адаптер для авторства и сборки вокруг JSON-проекта ICC Plus. Он не перереализует браузерный просмотрщик. Эффекты выбора, воспроизведение аудио, диалоги, рендеринг и другое интерактивное поведение по-прежнему выполняются в официальном просмотрщике. Сервер понимает и проверяет конфигурацию, которая управляет этими поведениями, может оценивать деревья требований для заданного состояния и может упаковывать результат в официальные шаблоны просмотрщика.

Дизайн намеренно имеет два уровня:

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

• Для сборок просмотрщика: web_viewer.zip или local_viewer.zip из репозитория развертывания ICC Plus

Установка и сборка

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 и поверхность Codex в настольном ChatGPT используют эту конфигурацию. Запись, ограниченная проектом, может находиться в .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: граница файловой системы; по умолчанию — текущий рабочий каталог процесса сервера.

• ICCPLUS_MAX_ASSET_BYTES: максимальный размер локального ресурса; по умолчанию — 26 214 400 байт (25 МиБ).

• ICCPLUS_DUPLICATED_TEXT_LIMIT_BYTES: максимальный размер, дублируемый в текстовый запасной вариант результата инструмента; по умолчанию — 8 192 байта. Более крупные точные результаты остаются доступными в structuredContent. Установите -1 для неограниченного текста в старом стиле.

Рекомендуемый рабочий процесс агента

1. Вызовите iccplus_capabilities для соответствующего семейства функций или поля.

2. Создайте или откройте проект и сохраните его project_id и revision.

3. Сначала создайте ссылочные сущности верхнего уровня: точки, переменные, слова, группы, дизайны и глобальные требования.

4. Создайте строки, затем выборы, затем оценки/аддоны/требования.

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.

Инструменты

Инструменты сущностей охватывают 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 с проверками на:

• дублирующиеся или отсутствующие ID и несоответствия позиционных индексов;

• родительские ссылки аддонов;

• все смоделированные ссылки на строки, выборы, очки, группы, переменные, слова, дизайны, звуки и глобальные требования;

• ссылки на преобразование очков в баллы и активацию очков;

• вложенные требования, пороговые значения и циклы глобальных требований;

• взаимные членства групп и дизайн-групп;

• несовместимые режимы экспорта просмотрщика;

• синтаксис Custom CSS, опасные устаревшие конструкции, неразрешённые селекторы ID ICC Plus, широкий охват, внешние ресурсы и вероятные конфликты с инлайн-стилями;

• инварианты целочисленности/плавающих значений очков и инициализации.

Оценщик требований реализует id (включая /ON#N), points, pointCompare, or, selFromGroups, selFromRows, selFromWhole, gid, word, отрицание, операторы и вложенные предварительные условия. Он возвращает объяснимый след, а не только логическое значение.

Расширенный Custom CSS

ICC Plus хранит CSS в поле верхнего уровня customCSS и внедряет его как style#customCSS в официальный создатель/просмотрщик с помощью textContent. MCP получает свой каталог из закреплённой разметки автономного просмотрщика, включая row-{id}, row-{id}-bg, row-{id}-header, choice-{id}, классы состояний выбора, addon и выбираемый addon-{id}.

iccplus_css_catalog может возвращать 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-шаблон в рабочей области.

• Веб-режим записывает project.json.

• Локальный режим встраивает проект в js/app.js.

• Заголовок загрузки, текст, цвета, фавикон, фон, шрифты и Custom 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 плюс каждую запись официального архива просмотрщика. Агенты могут запрашивать field:<name>, type:<name>, function:<name> или source:<relative-path> через iccplus_capabilities; 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.