OpenRouter GenImage Kote for Claude Code

openrouter-genimage-kote는 OpenRouter를 통해 래스터 이미지를 생성하고 편집하는 네이티브 Claude Code 플러그인입니다. 이미지-투-이미지가 기본 워크플로입니다. 이 플러그인은 포즈, 복장, 배경, 조명 또는 스타일을 바꾸면서도 캐릭터나 객체를 보존할 수 있으며, 순서가 있는 참조 이미지를 최대 16개까지 사용할 수 있습니다. 시각적 참조가 필요 없는 새 에셋에는 텍스트-투-이미지를 사용할 수 있습니다.

이 플러그인은 고정된 OpenRouter API 오리진에 직접 연결됩니다. 프록시 모드, KoteGateway, 설정 가능한 API 오리진, 경로 선택, 외부 이미지 브로커에 대한 의존성이 없습니다.

Claude Code
    -> bundled local stdio MCP server
    -> direct HTTPS
    -> https://openrouter.ai/api/v1/
    -> generated file inside the primary project root

요구 사항

• Claude Code 2.1.216 이상. 2.1.216은 지원되는 최소 버전입니다. 이 플러그인은 수정된 플러그인-스킬 네임스페이스 동작과 안전한 userConfig 처리를 사용하기 때문입니다. 개발 검증은 Claude Code 2.1.241에 고정되어 있습니다.

• node로 사용할 수 있는 Node.js 20 이상.

• 개인 OpenRouter API 키.

• 요청한 작업과 매개변수를 지원하는 정확한 OpenRouter 이미지 모델 ID.

• 선택 사항: 전체 계정 크레딧 정보를 위한 OpenRouter 관리 키.

MCP 루트 새로고침 동작 자체는 Claude Code 2.1.203+가 필요하지만, 이 플러그인은 위와 같은 이유로 의도적으로 더 높은 최소 버전 2.1.216을 설정합니다.

Related MCP server: openrouter-imgen-mcp

마켓플레이스에서 설치

Claude Code에서 GitHub 마켓플레이스를 추가하세요:

/plugin marketplace add koteyye/openrouter-genimage-kote-claude-code

플러그인을 설치하세요:

/plugin install openrouter-genimage-kote@kote-plugins

이미지 생성은 비용이 발생할 수 있으므로 플러그인은 기본적으로 비활성화되어 있습니다. /plugin을 열고 아래 설명된 네 가지 옵션을 구성한 다음 플러그인을 명시적으로 활성화하세요. 비밀 값은 대화형 플러그인 UI에서 입력하세요. 실제 API 키를 셸 명령에 넣지 마세요. 셸 히스토리에 남을 수 있습니다.

구성 후 플러그인 구성 요소를 다시 로드하세요:

/reload-plugins

그런 다음 MCP 상태를 확인하세요:

/mcp

openrouter-images 서버가 연결되어 세 가지 도구를 노출해야 합니다.

구성

플러그인이 활성화되면 Claude Code가 다음 userConfig 값을 요청합니다:

민감한 값은 마스킹되어 Claude Code 보안 저장소에 보관됩니다. 플러그인은 로컬 MCP 프로세스의 환경 변수로만 전달받습니다. 빈 관리 키는 없는 것으로 취급합니다.

의도적으로 baseUrl, 엔드포인트, 라우팅, 공급자 또는 프록시 라우팅 설정은 없습니다. 모델이 네트워크 경로를 선택하거나 다른 이미지 모델을 조용히 선택할 수 없습니다.

도구

Claude Code 도구 이름은 런타임에 네임스페이스가 지정됩니다. 잔액 스킬은 mcp__plugin_openrouter-genimage-kote_openrouter-images__openrouter_balance라는 예상 이름으로 범위가 지정되며, 스킬 및 정적 검사는 Claude Code 2.1.241에 고정되어 있습니다. 실제 도구 목록에 나타나는지 여부는 인터렉티브 릴리스 승인 확인으로 남습니다.

두 유료 도구는 _meta["anthropic/requiresUserInteraction"] = true를 게시하므로 Claude Code는 모든 생성 편집에 대해 명시적 승인을 요청해야 합니다. 그에 MCP 서버는 자체 프롬프트를 구현하지 않으며, MCP 전송 외부의 stdin를 읽지 않습니다.

이미지-투-이미지(image-to-image): 기본 워크플로

Claude에게 워크스페이스 안 경로의 이미지를 편집하라고 요청하세요:

Make the background transparent in assets/character.png and save the result as
assets/character-transparent.png. Preserve the character, clothing, proportions,
and illustration style.

Claude는 project_file 참조와 함께 openrouter_edit_image를 호출해야 합니다. 로컬 PNG, JPEG 또는 WebP 파일은 실제 경로와 크기, 매직 바이트로 확인한 다음 메모리 안에서 base64 데이터 URL로 전송됩니다. 원본 파일은 수정되지 않습니다.

반복 편집은 이전 도구 호출이 반환한 경로를 참조하세요:

Create another variation of assets/generated/character-in-tavern.png with
evening lighting. Keep everything else as close as possible.

공개 HTTPS 참조

Use https://example.com/reference.webp as the visual reference and create a
matching inventory icon with a transparent background.

자격 정보가 없는 public https:// URL만 허용됩니다. 로컬호스트, 루프백(loopback), 링크-로컬(link-local), 메타데이터 주소, http:, file:, data:, blob:, javascript: 입력은 지원되지 않습니다. 명시된 HTTPS 참조는 그대로 OpenRouter로 전달됩니다. 플러그인은 해당 URL에 OpenRouter 인증을 추가하지 않습니다.

순서가 있는 참조 여러 장

Use assets/references/girl.png for identity and face,
assets/references/outfit.png for clothing only, and
https://example.com/style.webp for palette and lighting. Preserve that order.

Claude는 프롬프트에서 각 참조 이미지의 역할을 설명하고 동일한 순서로 전달합니다. 플러그인은 정렬, 병합, 제거 또는 재해석하지 않습니다.

채팅에 붙여넣은 이미지

공용 MCP 인터페이스는 접근 가능한 워크스페이스 경로만 받습니다. 공개 HTTPS URL도 사용할 수 있습니다. 이미지가 Claude Code에 붙여넣어졌지만 모델에 경로가 노출되지 않으면, Claude가 경로를 임의로 찾거나 문서화되지 않은 Claude Code 캐시를 검색해서는 안 됩니다. 첨부 이미지를 프로젝트 안에 저장하세요. 예를 들면 assets/references/source.png로 저장한 다음 해당 경로를 제공하거나, 공개 HTTPS URL을 제공하세요.

지원된 Claude Code 버전이 구체적인 경로를 제공한다면, MCP 루트 검증을 거친 후에만 일반 project_file으로 처리합니다.

텍스트-투-이미지

기존의 시각적 참조가 결과에 영향을 미치면 안 되는 경우에만 사용하세요:

Create a 1:1 inventory icon of one healing potion, centered with generous
padding, readable at small size, no text, transparent background, PNG.

기본적으로 요청당 하나의 결과가 생성됩니다. 대안 여러 개를 원하면 명시적으로 요청하세요. n은 1~10까지 지정할 수 있고 이미지가 많아지면 비용이 커질 수 있습니다. 형식, 배경, 해상도, 품질, 시드(seed) 등은 요청하고 모델이 지원하면 툴 기능 매개변수로 전달됩니다. (원문 문장 정리 단계에서 앞 아래문이 발생.)

과금 요청 전에 서버는 모델 기능을 확인합니다. 지원하지 않는 이미지 입력·출력 또는 매개변수는 로컬에서 거부되며 다른 모델로 대체되지 않습니다. 과금이 발생한 POST 요청이 실패해도 잔액 상태가 불명확할 수 있으므로 자동 재시도하지 않습니다.

(원문의 phrase가 한국어 번역만 제공됨)

출력

결과는 소스가 추가 MCP 루트에서 온 경우에도 CLAUDE_PROJECT_DIR 안에만 기록됩니다. 경로는 모두 프로젝트 기준입니다. 존재하는 파일은 절대 덮어쓰지 않으며 충돌 시 숫자 접미사를 붙입니다. 기록은 완전히 동기화된 임시 파일로 만든 뒤 같은 디렉토리에 원자적으로 게시하고 기존 대상은 대체하지 않습니다.

MCP 결과는 간결한 텍스트와 구조화된 내용을 포함합니다: 작업, 모델, 요청/반환 개수, 참조 개수, 선택적 비용, 저장 경로, MIME 유형, 바이트 크기, 경고. 원본 이미지 바이트, base64, 프롬프트, 인증 정보를 절대로 반환하지 않습니다. 반환 항목 중 일부가 유효하지 않으면 나머지 유효한 이미지는 저장하고 결과에 부분 성공을 보고합니다. OpenRouter가 usage.cost을 생략할 때는 비용 “제공 안 됨”으로 표시하고 0으로 표시하지 않습니다.

생성 후에는 정확한 저장 경로를 보고하고, 이미지를 설명하기 전에 파일을 확인해야 합니다. 저장된 경로는 다음 이미지-투-이미지 참조로 사용할 수 있습니다.

워크스페이스 루트

상대 입력 경로는 CLAUDE_PROJECT_DIR을 기준으로 합니다. 절대 입력 경로는 실제 경로가 현재 MCP 루트 내의 일반 파일일 때만 허용됩니다. 루트는 프로젝트 루트에 --add-dir, /add-dir, 또는 Claude Code의 추가 디렉터리 설정으로 추가된 디렉터리가 포함됩니다. 서버는 notifications/roots/list_changed 이후 메모리의 루트를 갱신합니다.

추가 루트는 플러그인 관점에서 읽기 전용입니다. 모든 생성 결과물은 프로젝트 내부에 남습니다. 경로 탐색과 심볼릭 링크 탈출은 입력과 출력 모두에서 거부합니다.

잔액 및 크레딧 원노트

네임스페이스가 있는 네이티브 스킬로 실행하세요:

/openrouter-genimage-kote:openrouter-balance

라고 말할 수도 있습니다: "Check my OpenRouter balance." — 스킬은 openrouter_balance를 정확히 한 번만 호출하며 생성하지 않습니다.

GET /key는 현재 API 키의 사용량과 키 한도를 알려줍니다. limit_remaining 값은 전체 OpenRouter 계정 잔액이 아니라 API 키 한도에서 남은 금액입니다. 관리 키가 구성되었거나 현재 키가 관리자 키임을 명시하면 플러그인은 GET /credits도 호출하여 총 크레딧, 계정 총 사용량 그리고 그 차이를 보고합니다. 크레딧 실패는 사용 불가능으로 보고하되 키 사용량은 계속 표시됩니다. 응답은 캐시하지 않습니다.

보안 및 네트워크 동작

• 모든 인증 프로덕션 요청은 https://openrouter.ai/api/v1/으로 HTTPS를 통해 직접 전송됩니다.

• 리디렉션은 거부됩니다. 인증 정보가 리디렉션 대상으로 유출되지 않습니다.

• 프록시 환경 변수를 자동으로 읽지 않습니다. 전역 fetch 인터셉트, 프록시 디스패처, 게이트웨이 부트스트랩, 경로 마커는 없습니다.

• API 키는 명령줄 인자나 플러그인 파일이 아닌 환경 대입으로 로컬 프로세스에 전달됩니다.

• 로그는 stderr에 비식별 JSON 라인으로 기록됩니다. 전체 프롬프트, 키, 인증 헤더, base64, 이진 이미지, 원문 응답 본문은 포함하지 않습니다.

• 로컬 참조 이미지는 파일당 20MiB, 합계 50MiB, 16개로 제한됩니다. 응답 및 디코딩 이미지 합계는 기본 128MiB로 제한됩니다.

• 공개 HTTPS 참조는 유료 요청의 일부로 OpenRouter에 전달됩니다. 당 서비스와 공유하기 승인된 URL만 사용하세요.

보안 취약점 보고와 전체 위협 모델은 SECURITY.md를 참조하세요.

버전 0.1.0 제한 사항

버전 0.1.0은 마스크, 대화형 인페인팅, 픽셀 완벽 편집, 내부 첨부 식별자, 문서화되지 않은 Claude 이미지 캐시, SVG 출력, PDF/GIF/HEIC/TIFF/BMP/ICO 입력, 비디오, LoRA 파인튜닝, 스트리밍 이미지 생성, 플러그인 UI, 객체 스토리지, 외부 이미지 브로커, 자동 입력 크기 조정, 자동 크레딧 충전을 지원하지 않습니다. 공급자별 passthrough와 설정 보안 자동 모델 교체는 의도적으로 구현하지 않았습니다.

이미지 모델은 생성형이므로 보존과 시드가 픽셀 동일함이나 완전한 재현을 보장하지 않습니다.

문제 해결

MCP 서버 연결 끊김

1. node --version이 20 이상인지 확인합니다.

2. Claude Code가 2.1.216 이상인지 확인합니다.

3. /plugin을 열어 플러그인이 활성화되고 필수 옵션이 비어있지 않는지 확인합니다.

4. /reload-plugins 실행 후 /mcp를 실행합니다.

5. Claude Code 디버그 출력을 살펴보고 MCP stderr를 확인합니다. 지워지지 않은 키를 이슈에 붙여넣지 마세요.

구성 오류

/plugin을 열고 API 키와 정확히 일치하는 이미지 모델 ID, 상대 출력 폴더를 확인하세요. 서버는 시작 환경이 잘못됐더라도 모든 도구를 등록합니다. 호출은 GENIMAGE_CONFIG_INVALID를 반환할 뿐 MCP 쓰레드를 종료하지 못합니다.

참조 이미지가 거부되었음

PNG, JPEG, WebP를 사용하세요. 파일이 커런트 MCP 루트 안에 있고 20MiB 미만인지 확인하세요. 루트 밖 절대 경로를 복사하지 않고 Claude Code에서 다른 디렉터리를 추가하세요. 붙여 넣은 이미지는 먼저 프로젝트에 저장하세요.

지원되지 않는 모델이나 매개변수

이미지 출력을 명시한 정확한 OpenRouter 모델을 고르세요. 이미지-투-이미지에는 이미지 입력과 input_references도 필요합니다. 지원되지 않는 선택 매개변수를 제거하거나 스스로 적절한 모델을 구성하세요. 플러그인은 대체 모델을 선택하지 않습니다.

이미 생성된 출력

프로젝트 상대 새 경로를 정하세요. 기존 파일을 덮어쓰지 않는 것은 의도된 동작입니다.

갱신과 제거

마켓플레이스를 새로 고치고 플러그인을 업데이트하세요:

/plugin marketplace update
/plugin update openrouter-genimage-kote@kote-plugins
/reload-plugins

제거 방법은 다음과 같습니다:

/plugin uninstall openrouter-genimage-kote@kote-plugins

플러그인은 API 키를 자체적으로 저장하지 않습니다. 생성된 프로젝트 파일은 플러그인을 제거한 뒤에도 남아 있으므로, 더 이상 필요하지 않으면 사용자가 직접 삭제해야 합니다.

개발 및 검증

npm ci
npm run ci

빌드는 로컬 esbuild만 사용하며 네트워크 요청을 수행하지 않습니다. 소스 맵이 없는 단일 Node 20 ESM 파일을 plugins/openrouter-genimage-kote/dist/mcp-server.mjs에 생성하며, 플러그인 런타임에는 인접한 node_modules 디렉터리가 필요하지 않습니다.

현재 고정된 Claude 검증기를 명시적으로 실행하세요:

npx --yes @anthropic-ai/claude-code@2.1.241 plugin validate ./plugins/openrouter-genimage-kote --strict
npx --yes @anthropic-ai/claude-code@2.1.241 plugin validate . --strict

npm run validate:plugin은 매니페스트, 스킬, 금지 라우팅, 비밀값에 대해 항상 정적 검사를 수행합니다. 또한 해당 패키지가 이미 npm 캐시에 있으면 고정된 CLI를 실행하며, 이 자동 경로는 오프라인입니다. CI는 고정된 검증기를 명시적으로 호출합니다.

npm run smoke:marketplace는 마켓플레이스와 플러그인을 임시 캐시 레이아웃에 복사하고 실제 Claude 구성을 건드리지 않습니다. RUN_CLAUDE_MARKETPLACE_SMOKE=1을 설정하면 격리된 임시 설정(config) 및 플러그인 디렉터리에서 Claude Code 2.1.241을 사용해 로컬 마켓플레이스를 추가/설치, 목록 확인, 제거할 수 있습니다.

실제 OpenRouter 테스트는 유료이며 기본적으로 비활성화되어 있습니다:

RUN_OPENROUTER_E2E=1 \
OPENROUTER_API_KEY="<enter through a secure CI secret or local environment>" \
OPENROUTER_IMAGE_MODEL="provider/model-id" \
npm run test:e2e

선택적 관리 키(management-key) 크레딧 테스트는 추가로 OPENROUTER_MANAGEMENT_API_KEY를 읽습니다. 실제 자격 증명을 커밋된 파일이나 명령 기록에 넣지 마세요.

CI는 Ubuntu, macOS, Windows에서 실행되도록 구성되어 있습니다. 자동 검사는 소스, 프로토콜, 통합, 번들, 매니페스트, 격리된 마켓플레이스 동작을 다룹니다. 대화형 /mcp, slash-skill 검색, 호출별 확인 대화상자, 유료 이미지 품질은 릴리스 게이트(release-gate) 검사로 남아 있으므로, 소스 빌드가 성공했다는 것만으로 해당 검사가 수행되었다고 판단하지 마세요.

라이선스 및 출처

MIT 라이선스로 배포됩니다. 플랫폼 독립적인 부분은 openrouter-genimage-kote-opencode의 커밋 fd1e29d4a740d1765ce69b80ace722cec0a9258b(이 역시 MIT 라이선스)에서 소스 수준으로 적용되었습니다. 의존성 및 재사용 고지 사항은 THIRD_PARTY_NOTICES.md를 참조하세요.