ICCPlus MCP

English | 한국어

Un servidor Model Context Protocol consciente del esquema para crear, inspeccionar, editar, validar y empaquetar proyectos ICC Plus.

Este proyecto fue creado mediante vibe coding en colaboración con un agente de codificación de IA.

El servidor proporciona a un agente de IA un modelo completo del proyecto ICC Plus generado e indexado directamente desde la fuente original:

• el esquema del proyecto y los valores predeterminados actuales se generan a partir del código fuente de ICC Plus;

• cada uno de los 59 tipos de modelo declarados y los 893 campos únicos es descubrible;

• los 227 archivos de código fuente/compilación/configuración/parche y las 1411 funciones/métodos con nombre del creador y del visor independiente están indexados con la fuente exacta, evidencia SHA-256, firmas, uso de campos de modelo y rangos de línea;

• los 75 archivos del repositorio de despliegue solicitado y los 34 archivos dentro de sus archivos de visor oficiales tienen recuentos de bytes y manifiestos SHA-256;

• las herramientas de alto nivel preservan ID, orden, enlaces de padre y pertenencias recíprocas;

• la aplicación de parches genérica RFC 6902 mantiene accesibles los campos upstream nuevos o poco comunes;

• la validación estructural y semántica detecta referencias colgantes antes de guardar;

• las herramientas de Custom CSS respaldadas por fuente exponen las clases oficiales del visor, resuelven los selectores del proyecto y diagnostican riesgos de sintaxis/cascada antes de guardar;

• la preservación del ancho de fila de ICC Plus v2.10, los títulos de visibilidad/depuración del formulario de compilación, los controles divididos de recálculo de puntuación, los menús de fila ocultos y las clases CSS de estado de addon están modelados y son descubribles;

• los archivos del visor local y web oficiales se pueden compilar sin abrir la interfaz de creación.

La compatibilidad se genera actualmente desde ICC Plus v2.10.1, commit de fuente b33bfb9b29e0a84a035a56d7e1827e42fe0f7000.

Qué es esto

ICCPlus MCP es un adaptador de creación y compilación para el JSON de proyectos ICC Plus. No reimplementa el visor del navegador. Los efectos de selección, la reproducción de audio, los diálogos, el renderizado y otros comportamientos interactivos se siguen ejecutando en el visor oficial. El servidor comprende y valida la configuración que impulsa esos comportamientos, puede evaluar árboles de requisitos para un estado proporcionado y puede empaquetar el resultado en las plantillas del visor oficial.

El diseño tiene deliberadamente dos capas:

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

Requisitos

• Node.js 20 o superior

• Un espacio de trabajo de proyecto ICC Plus

• Para compilaciones de visor, web_viewer.zip o local_viewer.zip del repositorio de despliegue de ICC Plus

Instalación y compilación

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

El ejecutable es dist/index.js y se comunica a través de stdio. La salida del protocolo usa stdout; los diagnósticos usan stderr.

Conectar un agente

Establezca ICCPLUS_WORKSPACE como el único directorio que el servidor puede leer o escribir. Las rutas relativas de proyectos, activos, plantillas y salidas se resuelven dentro de este directorio. Los enlaces simbólicos existentes se resuelven y no pueden escapar de él.

Codex

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

Verifique con codex mcp list y reinicie el cliente si ya estaba abierto. La entrada equivalente de config.toml de usuario o de proyecto de confianza es:

[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

La CLI de Codex, la extensión del IDE y la superficie de Codex de escritorio de ChatGPT comparten esta configuración. Una entrada con ámbito de proyecto puede estar en .codex/config.toml y se carga solo para un proyecto de confianza.

Otros clientes MCP stdio

Use la configuración de servidor local del cliente con este comando:

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

Entorno opcional:

• ICCPLUS_WORKSPACE: límite del sistema de archivos; el valor predeterminado es el CWD del proceso del servidor.

• ICCPLUS_MAX_ASSET_BYTES: tamaño máximo de activo local; el valor predeterminado es 26 214 400 bytes (25 MiB).

• ICCPLUS_DUPLICATED_TEXT_LIMIT_BYTES: tamaño máximo duplicado en el respaldo de texto de un resultado de herramienta; el valor predeterminado es 8192 bytes. Los resultados exactos más grandes siguen disponibles en structuredContent. Establezca -1 para el texto ilimitado heredado.

Flujo de trabajo recomendado para el agente

1. Llame a iccplus_capabilities para la familia de características o el campo relevante.

2. Cree o abra un proyecto y conserve su project_id y revision.

3. Cree primero las entidades de nivel superior referenciadas: puntos, variables, palabras, grupos, diseños y requisitos globales.

4. Cree filas, luego opciones, luego puntuaciones/addons/requisitos.

5. Pase expected_revision a las mutaciones. Use dry_run para cambios amplios.

6. Para estilos avanzados, descubra selectores exactos con iccplus_css_catalog, analice el CSS candidato y luego aplíquelo con iccplus_css_set.

7. Llame a iccplus_validate y, donde sea útil, a iccplus_evaluate_requirements.

8. Guarde explícitamente o compile un archivo de visor oficial.

Un agente también puede solicitar la instrucción author-iccplus-project o audit-iccplus-project incluida.

Ejemplo de solicitud de usuario:

Cree un CYOA con 10 créditos iniciales, tres opciones de origen mutuamente excluyentes y una fila de armas desbloqueada al seleccionar un origen. Valídelo, guárdelo como projects/origins.json y luego compile un visor web usando templates/web_viewer.zip.

Herramientas

Las herramientas de entidades cubren row, backpack_row, choice, addon, selectable_addon, score, requirement, point, variable, word, group, row_design_group, choice_design_group, global_requirement, sound_effect y category.

Recursos y prompts

Seguridad e integridad de los datos

• Las mutaciones ocurren sobre datos clonados y se confirman atómicamente.

• expected_revision proporciona control de concurrencia optimista.

• dry_run devuelve el informe de validación proyectado sin cambiar una sesión.

• no_new_errors es la política de mutación predeterminada; strict requiere un resultado completamente válido; none está disponible para reparaciones por etapas.

• JSON Patch bloquea los segmentos de puntero de contaminación de prototipos.

• El guardado usa un archivo temporal más un renombrado.

• Los archivos existentes no se reemplazan a menos que overwrite=true.

• Los valores de los activos se redactan de la salida de consulta normal y se informan por tipo de medio y tamaño aproximado en bytes.

• Las lecturas de ruta exacta evitan devolver un proyecto completo, y los resultados grandes de herramientas no se duplican en la salida de texto y estructurada.

• Los campos desconocidos sobreviven a la carga, edición, normalización y guardado para compatibilidad futura.

Cobertura de validación

El validador combina el esquema App generado con comprobaciones de:

• IDs duplicados o faltantes y desajustes de índice posicional;

• enlaces de addon principal;

• cada fila, opción, punto, grupo, variable, palabra, diseño, sonido y referencia de requisito global modelado;

• referencias de puntuación a puntos y de activación de puntos;

• requisitos anidados, umbrales y ciclos de requisitos globales;

• membresías recíprocas de grupos y grupos de diseño;

• modos de exportación de visor incompatibles;

• sintaxis de Custom CSS, construcciones heredadas peligrosas, selectores de ID ICC Plus no resueltos, alcance amplio, recursos externos y probables conflictos de estilos en línea;

• invariantes de inicialización y de enteros/flotantes de puntos.

El evaluador de requisitos implementa id (incluido /ON#N), points, pointCompare, or, selFromGroups, selFromRows, selFromWhole, gid, word, negación, operadores y requisitos previos anidados. Devuelve un rastro explicable en lugar de solo un booleano.

Custom CSS avanzado

ICC Plus almacena CSS en el campo de nivel superior customCSS y lo inyecta como style#customCSS en el creador/visor oficial usando textContent. El MCP deriva su catálogo del marcado del visor independiente fijado, incluidos row-{id}, row-{id}-bg, row-{id}-header, choice-{id}, clases de estado de opción, addon y addon-{id} seleccionable.

iccplus_css_catalog puede devolver selectores con escape CSS para cada fila, opción y addon seleccionable del proyecto abierto. iccplus_css_analyze analiza reglas anidadas, informa especificidad y entidades coincidentes, y advierte cuando es probable que una declaración pierda frente a los estilos en línea de ICC Plus. iccplus_css_set persiste el resultado a través de la misma transacción versionada y política de validación que otras mutaciones del proyecto.

Para v2.10+, el catálogo también cubre .row-bg-{rowId}, .row-header-{rowId}, .choice, .addon-selectable y las clases de estado .addon-enabled, .addon-disabled, .addon-selected y .addon-unselected, conservando las grafías de selectores de fila más antiguas.

Esto es intencionalmente análisis estático. Los estilos calculados, el diseño responsivo y la representación de estados de interacción siguen siendo responsabilidad del visor oficial; no se incluye ningún runtime de automatización de navegador ni herramienta de navegación no relacionada.

Compilaciones del visor

iccplus_build_viewer acepta una plantilla ZIP oficial dentro del espacio de trabajo.

• El modo web escribe project.json.

• El modo local incrusta el proyecto en js/app.js.

• El título de carga, el texto, los colores, el favicon, el fondo, las fuentes y el Custom CSS del proyecto se conservan en el proyecto empaquetado.

• La separación opcional de imágenes extrae URL de datos de estilos globales, filas, filas de backpack, grupos de diseño y ajustes del visor; los recursos idénticos se deduplican.

El JavaScript del visor de la plantilla sigue siendo la fuente de verdad del runtime.

Sincronización con upstream

El modelo de proyecto se genera directamente desde la fuente upstream. Vuelva a ejecutar el analizador contra un checkout de ICC-Plus-Svelte:

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

El analizador usa el AST de TypeScript para regenerar:

• 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

Las pruebas fallan si un tipo de modelo upstream recién declarado no se asigna a una familia de características. source-analysis.json también registra declaraciones, importaciones, archivos fuente completos con dirección SHA-256, etiquetas de componentes, cada función/método fuente con nombre, cuerpos de función exactos y ocurrencias en el código fuente. El manifiesto de despliegue cubre cada archivo en wahaha303/ICCPlus más cada entrada de archivo del visor oficial. Los agentes pueden consultar field:<name>, type:<name>, function:<name> o source:<relative-path> a través de iccplus_capabilities; deployment:<relative-path> devuelve evidencia de despliegue. Las consultas de funciones admiten file, offset y limit para que los nombres locales duplicados sigan siendo manejables; include_source=false devuelve metadatos compactos.

Desarrollo

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

La suite de pruebas cubre cobertura del modelo generado, mutación del grafo del modelo, normalización, reescrituras de referencias, todas las familias de requisitos, atomicidad RFC 6902, empaquetado del visor e intercambio de cliente/servidor MCP en memoria.

Para el mapa semántico completo de características, consulte analysis/FEATURE_ANALYSIS.md. La evidencia generada de campos/funciones/componentes está en analysis/CODEBASE_INVENTORY.md. El registro de verificación requisito por requisito es analysis/COMPLETION_AUDIT.md.

Atribución

ICC Plus es desarrollado por wahaha303. Este servidor MCP es una integración independiente y no reemplaza ni modifica el creador/visor oficial. Ambos proyectos se distribuyen bajo la Licencia MIT; consulte LICENSE. Los avisos de dependencias upstream y vendored se conservan en THIRD_PARTY_NOTICES.md y en el recurso iccplus://licenses.