mcp-ikaos-story

Codex 또는 Claude Code에서 iKAOS Story 프로토타입 콘텐츠를 생성하고 수정하기 위한 Stdio MCP 서버입니다.

MCP는 인증된 iKAOS Story API와 통신합니다. 사용자는 ikaos-content-studio-v2026을 클론하거나 로컬 저장소 경로를 구성할 필요가 없습니다. Story 콘텐츠/레이아웃 JSON은 Supabase에 저장되며, 고정된 워크플로 문서와 소스 메타데이터는 API를 통해서만 읽기 전용으로 유지됩니다.

제약 사항

• get_story_context는 현재 콘텐츠 리비전과 공식 docsLink를 반환합니다.

• save_story_content는 content_data만 씁니다. 소스, 문서, Story 식별 정보, 프로덕션 메타데이터는 변경할 수 없습니다.

• 모든 콘텐츠 쓰기에는 정확한 현재 리비전이 필요합니다. 오래된 편집은 최신 콘텐츠를 덮어쓰는 대신 충돌을 반환합니다.

• 이미지 생성은 범위에 포함되지 않습니다. 디자이너는 df-sheet 스토리지를 통해 제공된 이미지 파일을 업로드, 교체, 정리, 삭제할 수 있습니다.

• Supabase 서비스 키는 MCP 사용자에게 배포되지 않습니다.

설치

npm install
npm run build

Story API를 구성하세요:

export IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app
export IKAOS_STORY_API_TOKEN=your-project-scoped-api-token
export IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app

이미지 도구에는 추가로 다음이 필요합니다:

export DF_SHEET_URL=https://your-df-sheet.vercel.app
export DF_SHEET_PROJECT_ID=your-project-uuid
export DF_SHEET_ACCESS_TOKEN=your-df-login-review-access-token

IKAOS_STORY_PREVIEW_URL은 선택 사항이며 기본값은 http://localhost:3000입니다. DF_SHEET_ACCESS_TOKEN은 현재 단기 유효한 df-login 리뷰 액세스 토큰입니다. 어떤 토큰도 커밋하지 마세요.

Codex

codex mcp add ikaos-story \
  --env IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app \
  --env IKAOS_STORY_API_TOKEN=your-project-scoped-api-token \
  --env IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app \
  -- node /absolute/path/to/mcp-ikaos-story/dist/src/index.js

이미지 도구가 필요할 때 동일한 명령에 세 개의 DF_SHEET_* 환경 변수 값을 추가하세요. codex mcp list 또는 /mcp로 확인하세요.

Claude Code

claude mcp add --transport stdio \
  --env IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app \
  --env IKAOS_STORY_API_TOKEN=your-project-scoped-api-token \
  --env IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app \
  ikaos-story -- node /absolute/path/to/mcp-ikaos-story/dist/src/index.js

이미지 도구가 필요할 때 세 개의 DF_SHEET_* 환경 변수 값을 추가하세요. claude mcp list 또는 /mcp로 확인하세요.

도구

콘텐츠 워크플로

1. get_story_context를 호출하세요.

2. docsLink를 열고 get_story_rules로 필요한 고정 규칙을 읽으세요.

3. 반환된 currentData.data 콘텐츠/레이아웃 객체만 수정하세요.

4. 변경하지 않은 Story ID와 currentData.revision으로 save_story_content를 호출하세요. Story에 아직 콘텐츠가 없을 때만 null을 사용하세요.

5. validate_story를 호출한 다음, 반환된 미리보기 URL을 390px와 1280px에서 확인하세요.

다른 클라이언트가 먼저 저장했다면 최신 컨텍스트를 가져와 의도적으로 병합하세요. 최신 콘텐츠를 검토하지 않고 교체된 리비전으로 재시도하지 마세요.

이미지 워크플로

1. Story 콘텐츠에서 유효한 imagePromptPackages[].inputBrief.slotId를 선택하세요.

2. 절대 로컬 이미지 경로로 upload_story_image를 호출하세요.

3. 반환된 imageUrl을 Story 콘텐츠에 사용하고 save_story_content로 저장하세요.

4. update_story_image를 호출하여 메타데이터를 변경하거나 파일을 교체하세요. 교체는 먼저 업로드하고, 업로드가 성공한 후에만 이전 파일을 삭제합니다.

5. 이미지 ID를 확인한 후에만 delete_story_image를 호출하세요. 삭제는 R2 객체를 제거하며 이 MCP로 복구할 수 없습니다.

하나의 반응형 소스를 사용하려면 viewport를 생략하세요. 모바일과 데스크톱 파일을 분리해서 사용하는 경우 목록, 업데이트, 삭제에 정확히 동일한 viewport 객체를 전달하세요.