ICCPlus MCP

English | 한국어

スキーマ対応のModel Context Protocolサーバーで、 ICC Plusプロジェクトの作成、検査、編集、検証、パッケージングを行います。

このプロジェクトは、AIコーディングエージェントとの共同作業によるvibe codingを通じて作成されました。

このサーバーは、AIエージェントに、アップストリームのソースから直接生成・索引付けされた完全なICC Plusプロジェクトモデルを提供します：

• プロジェクトスキーマと現在のデフォルト値はICC Plusソースから生成されます；

• 宣言された59のモデル型と893の一意なフィールドのすべてが検出可能です；

• クリエイターとスタンドアロンビューアにわたる227の作成済みソース/ビルド/設定/パッチファイルと1,411の名前付き関数/メソッドが、正確なソース、SHA-256エビデンス、シグネチャ、モデルフィールド使用状況、行スパンとともに索引付けされています；

• 要求されたデプロイリポジトリ内の75ファイルすべてと、公式ビューアアーカイブ内の34ファイルに、バイト数とSHA-256マニフェストがあります；

• 高レベルツールは、ID、順序、親リンク、相互メンバーシップを保持します；

• 汎用RFC 6902パッチにより、新規または一般的でないアップストリームフィールドにもアクセスできます；

• 構造的および意味的検証により、保存前にダングリング参照を検出します；

• ソース連携のCustom CSSツールは、公式ビューアクラスを公開し、プロジェクトセレクタを解決し、保存前に構文/カスケードリスクを診断します；

• ICC Plus v2.10の行幅保持、ビルドフォームの可視性/デバッグタイトル、分割スコア再計算コントロール、非表示行メニュー、アドオン状態CSSクラスがモデル化され、検出可能です；

• 公式のWebおよびローカルビューアアーカイブは、クリエイターUIを開かずにビルドできます。

互換性は現在、ICC Plus v2.10.1、ソースコミットb33bfb9b29e0a84a035a56d7e1827e42fe0f7000から生成されています。

これは何か

ICCPlus MCPは、ICC PlusプロジェクトJSONを中心としたオーサリングおよびビルドアダプターです。ブラウザビューアを再実装するものではありません。選択効果、オーディオ再生、ダイアログ、レンダリング、その他のインタラクティブな動作は、公式ビューアで実行されます。このサーバーは、それらの動作を駆動する設定を理解し検証し、提供された状態に対する要件ツリーを評価し、結果を公式ビューアテンプレートにパッケージングできます。

設計は意図的に2つのレイヤーを持っています：

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. 参照されるトップレベルエンティティを最初に作成します：ポイント、変数、ワード、グループ、デザイン、グローバル要件。

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プロンプトを要求することもできます。

ユーザーリクエストの例：

10の開始クレジット、3つの相互排他的なオリジン選択肢、オリジンを選択するとロック解除される武器行を持つCYOAを作成してください。検証し、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パッチはプロトタイプ汚染ポインタセグメントをブロックします。

• 保存は一時ファイルとリネームを使用します。

• overwrite=trueでない限り、既存ファイルは置き換えられません。

• アセット値は通常のクエリ出力から編集され、メディアタイプとおおよそのバイトサイズで報告されます。

• 正確なパス読み取りは完全なプロジェクトの返却を回避し、大きなツール結果はテキストと構造化出力の両方に複製されません。

• 不明なフィールドは、前方互換性のために読み込み、編集、正規化、保存を生き残ります。

検証カバレッジ

バリデータは、生成されたAppスキーマと次のチェックを組み合わせます：

• 重複または欠落したIDと位置インデックスの不一致;

• addonの親リンク;

• モデル化されたすべての行、選択肢、ポイント、グループ、変数、ワード、デザイン、サウンド、および グローバル要件参照;

• スコアからポイントへの参照とポイント活性化参照;

• ネストされた要件、しきい値、およびグローバル要件の循環;

• グループとデザイングループの相互メンバーシップ;

• 互換性のないビューアのエクスポートモード;

• Custom CSS構文、危険なレガシー構造、未解決のICC Plus ID セレクタ、広範なスコープ、外部アセット、およびインラインスタイル競合の可能性;

• ポイントの整数/浮動小数点数と初期化の不変条件。

要件評価器は、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は、開いているプロジェクトのすべての 行、選択肢、および選択可能な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に埋め込みます。

• 読み込みタイトル、テキスト、色、ファビコン、背景、フォント、およびプロジェクトの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リソースに保存されています。