ICCPlus MCP

English | 한국어

Ein schema-bewusster Model Context Protocol-Server zum Erstellen, Inspizieren, Bearbeiten, Validieren und Paketieren von ICC Plus-Projekten.

Dieses Projekt wurde durch Vibe Coding in Zusammenarbeit mit einem KI-Codieragenten erstellt.

Der Server gibt einem KI-Agenten ein vollständiges ICC-Plus-Projektmodell, das direkt aus dem Upstream-Quellcode generiert und indexiert wird:

• das Projektschema und die aktuellen Standardwerte werden aus dem ICC-Plus-Quellcode generiert;

• alle 59 deklarierten Modelltypen und 893 eindeutigen Felder sind auffindbar;

• alle 227 verfassten Quell-/Build-/Konfigurations-/Patch-Dateien und 1.411 benannten Funktionen/Methoden im Creator und eigenständigen Viewer sind mit exaktem Quellcode, SHA-256-Nachweis, Signaturen, Modellfeldnutzung und Zeilenspannen indexiert;

• alle 75 Dateien im angeforderten Deployment-Repository und 34 Dateien in dessen offiziellen Viewer-Archiven haben Byte-Anzahl- und SHA-256-Manifeste;

• High-Level-Tools bewahren IDs, Reihenfolge, Elternverknüpfungen und reziproke Mitgliedschaften;

• generisches RFC-6902-Patching hält neue oder ungewöhnliche Upstream-Felder zugänglich;

• strukturelle und semantische Validierung erkennt verwaiste Referenzen vor dem Speichern;

• quellgestützte Custom-CSS-Tools legen offizielle Viewer-Klassen offen, lösen Projekt-Selektoren auf und diagnostizieren Syntax-/Kaskadenrisiken vor dem Speichern;

• ICC-Plus-v2.10.1-Zeilenbreitenerhaltung, Build-Formular-Sichtbarkeits-/Debug-Titel, geteilte Score-Neuberechnungssteuerungen, versteckte Zeilenmenüs und Addon-Zustands-CSS-Klassen sind modelliert und auffindbar;

• offizielle Web- und lokale Viewer-Archive können ohne Öffnen der Creator-Oberfläche erstellt werden.

Die Kompatibilität wird derzeit aus ICC Plus v2.10.1, Quell-Commit b33bfb9b29e0a84a035a56d7e1827e42fe0f7000, generiert.

Was das ist

ICCPlus MCP ist ein Autoren- und Build-Adapter um ICC-Plus-Projekt-JSON. Es implementiert den Browser-Viewer nicht neu. Auswahleffekte, Audiowiedergabe, Dialoge, Rendering und anderes interaktives Verhalten werden weiterhin im offiziellen Viewer ausgeführt. Der Server versteht und validiert die Konfiguration, die diese Verhaltensweisen steuert, kann Anforderungsbäume für bereitgestellte Zustände auswerten und das Ergebnis in die offiziellen Viewer-Vorlagen paketieren.

Das Design hat bewusst zwei Ebenen:

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

Voraussetzungen

• Node.js 20 oder neuer

• Ein ICC-Plus-Projektarbeitsbereich

• Für Viewer-Builds web_viewer.zip oder local_viewer.zip aus dem ICC-Plus-Deployment-Repository

Installieren und erstellen

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

Die ausführbare Datei ist dist/index.js und kommuniziert über stdio. Protokollausgabe erfolgt über stdout; Diagnosen über stderr.

Einen Agenten verbinden

Setzen Sie ICCPLUS_WORKSPACE auf das einzige Verzeichnis, das der Server lesen oder schreiben darf. Relative Projekt-, Asset-, Vorlagen- und Ausgabepfade werden innerhalb dieses Verzeichnisses aufgelöst. Vorhandene Symlinks werden aufgelöst und können es nicht verlassen.

Codex

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

Überprüfen Sie mit codex mcp list und starten Sie den Client neu, falls er bereits geöffnet war. Der entsprechende Benutzer- oder vertrauenswürdige Projekt-config.toml-Eintrag ist:

[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

Die Codex-CLI, die IDE-Erweiterung und die ChatGPT-Desktop-Codex-Oberfläche teilen sich diese Konfiguration. Ein projektspezifischer Eintrag kann in .codex/config.toml leben und wird nur für ein vertrauenswürdiges Projekt geladen.

Andere stdio-MCP-Clients

Verwenden Sie die lokale Serverkonfiguration des Clients mit diesem Befehl:

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

Optionale Umgebungsvariablen:

• ICCPLUS_WORKSPACE: Dateisystemgrenze; standardmäßig das CWD des Serverprozesses.

• ICCPLUS_MAX_ASSET_BYTES: maximale lokale Asset-Größe; standardmäßig 26.214.400 Bytes (25 MiB).

• ICCPLUS_DUPLICATED_TEXT_LIMIT_BYTES: maximale Größe, die in den Text-Fallback eines Tool-Ergebnisses dupliziert wird; standardmäßig 8.192 Bytes. Größere exakte Ergebnisse bleiben in structuredContent verfügbar. Setzen Sie -1 für unbegrenzten Legacy-Text.

Empfohlener Agenten-Workflow

1. Rufen Sie iccplus_capabilities für die relevante Funktionsfamilie oder das Feld auf.

2. Erstellen oder öffnen Sie ein Projekt und behalten Sie dessen project_id und revision.

3. Erstellen Sie zuerst referenzierte Top-Level-Entitäten: Punkte, Variablen, Wörter, Gruppen, Designs und globale Anforderungen.

4. Erstellen Sie Zeilen, dann Auswahlmöglichkeiten, dann Punkte/Addons/Anforderungen.

5. Übergeben Sie expected_revision an Mutationen. Verwenden Sie dry_run für umfangreiche Änderungen.

6. Für erweitertes Styling ermitteln Sie exakte Selektoren mit iccplus_css_catalog, analysieren Sie Kandidaten-CSS und wenden Sie es dann mit iccplus_css_set an.

7. Rufen Sie iccplus_validate und, wo nützlich, iccplus_evaluate_requirements auf.

8. Speichern Sie explizit oder erstellen Sie ein offizielles Viewer-Archiv.

Ein Agent kann auch den gebündelten author-iccplus-project- oder audit-iccplus-project-Prompt anfordern.

Beispiel für eine Benutzeranfrage:

Erstelle ein CYOA mit 10 Startcredits, drei sich gegenseitig ausschließenden Herkunftsauswahlmöglichkeiten und einer Waffenzeile, die durch die Auswahl einer Herkunft freigeschaltet wird. Validiere es, speichere es als projects/origins.json und erstelle dann einen Web-Viewer mit templates/web_viewer.zip.

Tools

Entitätstools decken row, backpack_row, choice, addon, selectable_addon, score, requirement, point, variable, word, group, row_design_group, choice_design_group, global_requirement, sound_effect und category ab.

Ressourcen und Prompts

Sicherheit und Datenintegrität

• Mutationen erfolgen auf geklonten Daten und werden atomar committet.

• expected_revision bietet optimistische Nebenläufigkeitskontrolle.

• dry_run gibt den projizierten Validierungsbericht zurück, ohne eine Sitzung zu ändern.

• no_new_errors ist die Standard-Mutationsrichtlinie; strict erfordert ein vollständig gültiges Ergebnis; none ist für schrittweise Reparaturen verfügbar.

• JSON Patch blockiert Prototyp-Pollution-Pointer-Segmente.

• Speichern verwendet eine temporäre Datei plus Umbenennung.

• Vorhandene Dateien werden nicht ersetzt, außer overwrite=true.

• Asset-Werte werden aus normaler Abfrageausgabe geschwärzt und nach Medientyp und ungefährer Bytegröße gemeldet.

• Exakte Pfadlesevorgänge vermeiden die Rückgabe eines vollständigen Projekts, und große Tool-Ergebnisse werden nicht sowohl in Text als auch in strukturierte Ausgabe dupliziert.

• Unbekannte Felder überleben Laden, Bearbeiten, Normalisierung und Speichern für Vorwärtskompatibilität.

Validierungsabdeckung

Der Validator kombiniert das generierte App-Schema mit Prüfungen auf:

• doppelte oder fehlende IDs und Positionsindex-Abweichungen;

• Addon-Elternverknüpfungen;

• jede Referenz auf modellierte Zeilen, Auswahlmöglichkeiten, Punkte, Gruppen, Variablen, Wörter, Designs, Sounds und globale Anforderungen;

• Score-zu-Punkt- und Punktaktivierungs-Referenzen;

• verschachtelte Anforderungen, Schwellenwerte und Global-Anforderungszyklen;

• reziproke Mitgliedschaften von Gruppen und Design-Gruppen;

• inkompatible Viewer-Exportmodi;

• Custom CSS-Syntax, gefährliche Legacy-Konstrukte, unaufgelöste ICC Plus ID-Selektoren, breiter Geltungsbereich, externe Assets und wahrscheinliche Inline-Stil-Konflikte;

• Punkt-Ganzzahl/Gleitkomma- und Initialisierungsinvarianten.

Der Anforderungsevaluator implementiert id (einschließlich /ON#N), points, pointCompare, or, selFromGroups, selFromRows, selFromWhole, gid, word, Negation, Operatoren und verschachtelte Voraussetzungen. Er gibt einen erklärbaren Trace zurück und nicht nur einen booleschen Wert.

Erweitertes Custom CSS

ICC Plus speichert CSS im Top-Level-Feld customCSS und fügt es im offiziellen Creator/Viewer als style#customCSS über textContent ein. Der MCP-Server leitet seinen Katalog aus dem fixierten Markup des eigenständigen Viewers ab, einschließlich row-{id}, row-{id}-bg, row-{id}-header, choice-{id}, Auswahl-Zustandsklassen, addon und auswählbarem addon-{id}.

iccplus_css_catalog kann CSS-escapte Selektoren für jede Zeile, Auswahl und jedes auswählbare Addon des offenen Projekts zurückgeben. iccplus_css_analyze parst verschachtelte Regeln, meldet Spezifität und übereinstimmende Entitäten und warnt, wenn eine Deklaration voraussichtlich gegenüber ICC Plus Inline-Stilen verliert. iccplus_css_set persistiert das Ergebnis über dieselbe revisionsbasierte Transaktions- und Validierungsrichtlinie wie andere Projektmutationen.

Für v2.10+ deckt der Katalog außerdem .row-bg-{rowId}, .row-header-{rowId}, .choice, .addon-selectable sowie die Zustandsklassen .addon-enabled, .addon-disabled, .addon-selected und .addon-unselected ab, während ältere Schreibweisen der Zeilenselektoren beibehalten werden.

Dies ist bewusst statische Analyse. Berechnete Stile, responsives Layout und die Darstellung von Interaktionszuständen bleiben in der Verantwortung des offiziellen Viewers; es wird keine Browser-Automatisierungslaufzeit und kein unzusammenhängendes Browsing-Werkzeug mitgeliefert.

Viewer-Builds

iccplus_build_viewer akzeptiert eine offizielle Template-ZIP im Workspace.

• Der Webmodus schreibt project.json.

• Der lokale Modus bettet das Projekt in js/app.js ein.

• Ladetitel, Text, Farben, Favicon, Hintergrund, Schriftarten und das Custom CSS des Projekts bleiben im gepackten Projekt erhalten.

• Die optionale Bildtrennung extrahiert Daten-URLs aus globalen Stilen, Zeilen, Backpack-Zeilen, Design-Gruppen und Viewer-Einstellungen; identische Assets werden dedupliziert.

Das Viewer-JavaScript des Templates bleibt die maßgebliche Quelle zur Laufzeit.

Upstream-Synchronisierung

Das Projektmodell wird direkt aus der Upstream-Quelle generiert. Führen Sie den Analyzer erneut gegen einen Checkout von ICC-Plus-Svelte aus:

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

Der Analyzer verwendet das TypeScript-AST, um Folgendes neu zu generieren:

• 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

Tests schlagen fehl, wenn ein neu deklarierter Upstream-Modelltyp keiner Feature-Familie zugeordnet ist. source-analysis.json erfasst außerdem Deklarationen, Importe, vollständige SHA-256-adressierte Quelldateien, Komponentenbezeichnungen, jede benannte Quellfunktion/-methode, exakte Funktionsrümpfe und Quellvorkommen. Das Deployment-Manifest umfasst jede Datei in wahaha303/ICCPlus sowie jeden Eintrag des offiziellen Viewer-Archivs. Agenten können field:<name>, type:<name>, function:<name> oder source:<relative-path> über iccplus_capabilities abfragen; deployment:<relative-path> liefert Deployment-Nachweise. Funktionsabfragen unterstützen file, offset und limit, sodass doppelte lokale Namen handhabbar bleiben; include_source=false liefert kompakte Metadaten.

Entwicklung

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

Die Testsuite umfasst die Abdeckung des generierten Modells, Modellgraphen-Mutation, Normalisierung, Referenzumschreibungen, alle Anforderungsfamilien, RFC-6902-Atomarität, Viewer-Packaging und einen In-Memory-MCP-Client/Server-Austausch.

Die vollständige semantische Feature-Map finden Sie in analysis/FEATURE_ANALYSIS.md. Die erzeugten Feld-/Funktions-/Komponenten-Nachweise befinden sich in analysis/CODEBASE_INVENTORY.md. Der anforderungsweise Verifikationsnachweis ist in analysis/COMPLETION_AUDIT.md.

Namensnennung

ICC Plus wird von wahaha303 entwickelt. Dieser MCP-Server ist eine unabhängige Integration und ersetzt oder verändert den offiziellen Creator/Viewer nicht. Beide Projekte werden unter der MIT-Lizenz verbreitet; siehe LICENSE. Hinweise auf Upstream- und eingebundene Abhängigkeiten sind in THIRD_PARTY_NOTICES.md und der Ressource iccplus://licenses erhalten.