ICCPlus MCP

English | 한국어

스키마 인지형 Model Context Protocol 서버로, ICC Plus 프로젝트를 생성, 검사, 편집, 검증, 패키징하는 데 사용됩니다.

이 프로젝트는 AI 코딩 에이전트와의 협업을 통해 vibe coding으로 만들어졌습니다.

이 서버는 AI 에이전트에게 ICC Plus 소스에서 직접 생성되고 인덱싱된 완전한 ICC Plus 프로젝트 모델을 제공합니다:

• 프로젝트 스키마와 현재 기본값은 ICC Plus 소스에서 생성됩니다;

• 선언된 59개의 모델 유형과 1,893개의 고유 필드가 모두 검색 가능합니다;

• 제작자 및 독립형 뷰어 전반의 227개 소스/빌드/설정/패치 파일과 1,411개의 명명된 함수/메서드가 정확한 소스, SHA-256 증거, 시그니처, 모델 필드 사용 및 줄 범위와 함께 색인됩니다;

• 요청된 배포 저장소의 총 75개 파일과 공식 뷰어 아카이브 내부의 34개 파일에는 바이트 수와 SHA-256 매니페스트가 있습니다;

• 고급 도구는 ID, 순서, 부모 링크, 상호 멤버십을 보존합니다;

• 일반 RFC 6902 패칭으로 새롭거나 흔하지 않은 업스트림 필드에 계속 접근할 수 있습니다;

• 구조적 및 의미적 검증은 저장 전에 잘못된 참조를 잡아냅니다;

• 소스 기반 Custom CSS 도구는 공식 뷰어 클래스를 노출하고, 프로젝트 선택자를 해석하며, 저장 전에 구문/폭포(cascade) 위험을 진단합니다;

• ICC Plus v2.10.1의 행 너비 보존, 빌드 양식 가시성/디버그 제목, 분할 점수 재계산 컨트롤, 숨겨진 행 메뉴, 애드온 상태 CSS 클래스가 모델링되고 검색 가능합니다;

• 공식 웹/로컬 뷰어 아카이브를 제작자 UI를 열지 않고 빌드할 수 있습니다.

현재 호환성은 ICC Plus v2.10.1, 소스 커밋 b33bfb9b29e0a56d7e1827e42fe0f7000 기준입니다.

이 도구의 목적

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

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

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

[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

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

Related MCP server: ts-language-mcp

요구 사항

• Node.js 20 이상

• ICC Plus 프로젝트 워크스페이스

• 뷰어 빌드용: ICC Plus 배포 저장소의 web_viewer.zip 또는 local_viewer.zip

설치 및 빌드

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

실행 파일은 dist/index.js이며 stdio를 통해 통신합니다. 프로토콜 출력은 stdout을 사용하고 진단은 stderr을 사용합니다.

에이전트 연결

ICCPLUS_WORKSPACE에 서버가 읽거나 쓸 수 있는 유일한 디렉터리를 설정합니다. 상대 프로젝트, 에셋, 템플릿 및 출력 경로는 이 디렉터리 내에서 확인됩니다. 기존 심볼릭 링크는 확인되며 이를 벗어날 수 없습니다.

Codex

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

codex mcp list로 확인한 후, 클라이언트가 이미 열려 있었다면 다시 시작하세요. 동등한 사용자 또는 신뢰할 수 있는 프로젝트 config.toml 항목은 다음과 같습니다:

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

Codex CLI, IDE 확장, ChatGPT 데스크톱 Codex 인터페이스는 이 구성을 공유합니다. 프로젝트 범위 항목은 .codex/config.toml에 위치할 수 있으며 신뢰할 수 있는 프로젝트에서만 로드됩니다.

기타 stdio MCP 클라이언트

다음 명령과 함께 클라이언트의 로컬 서버 구성을 사용하세요:

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

선택적 환경 변수:

• ICCPLUS_WORKSPACE: 파일 시스템 경계; 기본값은 서버 프로세스 CWD입니다.

• ICCPLUS_MAX_ASSET_BYTES: 최대 로컬 에셋 크기; 기본값은 26,214,400바이트(25MiB)입니다.

• 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_analyze로 정확한 선택자를 발견하고, 후보 CSS를 분석한 다음 iccplus_css_set으로 적용하세요.

7. iccplus_validate와 유용한 경우 iccplus_evaluate_requirements를 호출하세요.

8. 명시적으로 저장하거나 공식 뷰어 아카이브를 빌드하세요.

번들된 author-iccplus-project 또는 audit-iccplus-project 프롬프트를 요청할 수도 있습니다.

예제 사용자 요청:

10개의 시작 크레딧, 상호 배타적인 세 개의 기원 선택지, 그리고 무기를 선택하면 나타나는 무기 행이 있는 CYOA를 만드세요. projects/origins.json으로 저장하고, 검증한 다음 templates/web_viewer.zip을 사용하여 웹 뷰어를 빌드하세요.

도구

• 중복되거나 누락된 ID 및 위치 인덱스 불일치;

• 애드온 부모 링크;

• 모델링된 모든 행, 선택지, 포인트, 그룹, 변수, 단어, 디자인, 사운드 및 전역 요구사항 참조;

• 점수-포인트 및 포인트 활성화 참조;

• 중첩 요구사항, 임계값 및 전역 요구사항 순환;

• 그룹 및 디자인 그룹 상호 소속;

• 호환되지 않는 뷰어 내보내기 모드;

• Custom CSS 구문, 위험한 레거시 구조, 해결되지 않은 ICC Plus ID 선택자, 광범위한 범위, 외부 자산 및 예상되는 인라인 스타일 충돌;

• 포인트 정수/부동소수점 및 초기화 불변식.

요구사항 평가기는 id(/ON#N 포함), points, pointCompare, or, selFromGroups, selFromRows, selFromWhole, gid, word, 부정, 연산자 및 중첩 전제조건을 구현합니다. 부울 값만 반환하는 대신 설명 가능한 트레이스를 반환합니다.

고급 Custom 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는 열린 프로젝트의 모든 행, 선택지 및 선택 가능한 애드온에 대한 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는 패키징된 프로젝트에 유지됩니다.

• 선택적 이미지 분리는 전역 스타일, 행, 백팩 행, 디자인 그룹 및 뷰어 설정에서 data 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로 배포됩니다. LICENSE를 참조하세요. 업스트림 및 벤더 의존성 고지는 THIRD_PARTY_NOTICES.md와 iccplus://licenses 리소스에 보존됩니다.