ChatGPT Image Bridge

ChatGPT Image Bridge는 텍스트 전용 에이전트에 휴대용 이미지 워크플로를 제공합니다:

1. 사용자가 로그인한 Codex 및 ChatGPT 계정으로 래스터 이미지를 생성하거나 편집합니다.

2. 호출자가 project_root를 제공하면 <project>/assets/generated/에 직접 저장합니다.

3. 별도의 OpenAI 비전 턴을 통해 검사, 비교, 전사 또는 비평을 수행합니다.

4. 비전 결과를 모든 기본 모델이 사용할 수 있는 일반 텍스트로 반환합니다.

이 저장소는 Agent Plugins 1.0 패키지입니다. 실제 도구 경계는 표준 MCP이므로 Factory, DeepSeek Harness, Codex, Cursor, VS Code 또는 다른 개별 호스트에 묶여 있지 않습니다.

[!IMPORTANT] 이것은 독립적인 실험용 브리지입니다. 로컬에 설치된 Codex app-server 인터페이스와 내장 imagegen 스킬을 사용하며, 이는 안정적인 공개 제공자 API가 아닙니다. Codex 업데이트로 인해 어댑터 업데이트가 필요할 수 있습니다. 이 프로젝트는 OpenAI와 제휴하거나 보증하지 않습니다.

제공하는 기능

• imagegen_status: 로컬 Codex 로그인, 이미지 권한, 비전 모델을 확인합니다.

• generate_image: 이미지를 생성하고 선택적으로 활성 프로젝트에 저장합니다.

• generate_image_edit: 로컬 또는 데이터 URL 참조 1~4개를 편집합니다.

• get_image_job: 호스트의 일반 MCP 시간 초과를 초과하는 생성을 복구합니다.

• analyze_image: 생성된 작업, 로컬 이미지 경로 또는 데이터 URL을 모델이 읽을 수 있는 시각적 증거로 변환합니다.

성공한 작업은 항상 플러그인 데이터 디렉터리에 정식 사본을 보관합니다. 절대 경로 project_root를 제공하면 assets/generated/에 고유한 이름의 덮어쓰지 않는 사본이 추가로 작성됩니다.

Related MCP server: vision-router-mcp

요구 사항

• macOS, Linux 또는 Windows에서 Python 3.11 이상.

• 휴대용 플러그인 실행기를 위한 PATH의 uv.

• 로컬에 설치된 Codex 실행 파일. macOS ChatGPT 번들은 자동으로 감지됩니다. 그 외의 경우 codex를 PATH에 추가하거나 CODEX_BIN을 설정하세요.

• 이미지 생성 및 이미지 입력을 지원하는 모델과 함께 Codex에 로그인된 ChatGPT 계정.

브리지는 의도적으로 Codex 자식 프로세스에서 API 키 환경 변수를 제거합니다. 사용자의 로컬 ChatGPT/Codex 로그인을 사용하도록 설계되었으며, API 키를 조용히 소비하지 않습니다.

각 설치본은 수신자의 자체 로컬 Codex 로그인 및 계정 권한을 사용합니다. 플러그인은 게시자의 로그인, 구독, 쿠키 또는 토큰을 번들하거나 전송하지 않습니다.

로컬 실행

uv sync
uv run chatgpt-image-bridge-mcp --stdio

MCP Inspector의 경우:

uv run mcp dev src/chatgpt_image_bridge_mcp/server.py

localhost 전용 Streamable HTTP 엔드포인트의 경우:

uv run chatgpt-image-bridge-mcp --http --port 8788

엔드포인트는 http://127.0.0.1:8788/mcp입니다. HTTP 모드는 이 알파 릴리스에서 휴대용 인증이 없으며 루프백 바인딩만 허용합니다. 일반 설치에서는 stdio를 사용하세요. 향후 인증된 네트워크 배포는 별도의 명시적 검토 기능이어야 합니다.

Agent Plugin으로 설치

휴대용 패키지 진입점은 다음과 같습니다:

• plugin.json

• mcp.json

• skills/chatgpt-image-workflow/SKILL.md

Agent Plugins 1.0 클라이언트에서 저장소 디렉터리를 로드합니다. 클라이언트는 PLUGIN_ROOT와 쓰기 가능한 PLUGIN_DATA를 제공합니다. mcp.json은 stdio를 통해 uv로 서버를 시작합니다.

Agent Plugins는 패키지를 표준화하며, 보편적인 설치 명령을 제공하지 않습니다. 클라이언트가 배포 UX에 수렴할 때까지 Git이 가장 신뢰할 수 있는 소스입니다.

별도의 내장 이미지 도구를 노출하는 호스트는 MCP를 참조하기 전에 해당 도구를 이름으로 선택할 수 있습니다. 내장 도구가 구독으로 제한된 경우 이 플러그인의 generate_image 도구 또는 해당 서버 네임스페이스를 명시적으로 선택하세요. 클라이언트 노트를 참조하세요.

OpenAI/Codex 호환 패키지 빌드

OpenAI의 현재 플러그인 디렉터리는 별도의 .codex-plugin/plugin.json 패키지 형태를 사용합니다. 두 번째 서버 구현을 유지하는 대신 동일한 소스에서 자체 포함 호환 아티팩트를 생성하세요:

python3 scripts/build_openai_plugin.py

결과는 dist/openai/chatgpt-image-bridge-mcp/입니다. 동일한 서버와 워크플로 스킬, 그리고 OpenAI의 .codex-plugin/plugin.json 및 .mcp.json 매니페스트가 포함됩니다. 이를 생성된 출력으로 유지하면 공급업체 간 패키지와 OpenAI 전용 설치 아티팩트 간의 동작 차이를 방지할 수 있습니다.

빌더는 명시적 릴리스 허용 목록만 복사하며 심볼릭 링크, Python 바이트코드 또는 로컬 체크아웃 경로를 거부합니다. 이를 통해 호환 아티팩트를 깨끗한 Git 체크아웃에서 재현할 수 있고 무시된 개발자 파일이 릴리스에 유출되는 것을 방지합니다.

일반 MCP로 구성

MCP를 지원하지만 Agent Plugins를 지원하지 않는 클라이언트는 동일한 서버를 직접 시작할 수 있습니다. 외부 구성 형태를 호스트에 맞게 조정하세요:

{
  "command": "uv",
  "args": [
    "run",
    "--project",
    "/absolute/path/to/chatgpt-image-bridge-mcp",
    "--locked",
    "--no-dev",
    "chatgpt-image-bridge-mcp",
    "--stdio"
  ],
  "env": {
    "CHATGPT_IMAGE_BRIDGE_MCP_DATA_DIR": "/absolute/writable/path/chatgpt-image-bridge-mcp",
    "UV_PROJECT_ENVIRONMENT": "/absolute/writable/path/chatgpt-image-bridge-mcp/venv"
  }
}

의도된 모델 워크플로

생성의 경우:

1. imagegen_status를 한 번 호출합니다.

2. 시각적 프롬프트와 활성 프로젝트의 절대 루트로 generate_image를 호출합니다.

3. 반환된 relative_saved_path를 웹사이트 또는 애플리케이션에서 사용합니다.

4. 작업에 시각적 판단이 필요한 경우 반환된 job_id로 analyze_image를 호출합니다.

5. 작성된 분석을 시각적 증거로 계속 사용합니다. 기본 모델이 텍스트 전용이라는 이유만으로 래스터를 SVG 또는 CSS로 대체하지 마세요.

기존 이미지의 경우 analyze_image를 정확히 하나의 소스(job_id, image_paths 또는 image_data_urls)로 호출하세요.

구성

기본적으로 로컬 경로 액세스는 MCP의 신뢰된 stdio 모델을 따릅니다. 호출자는 계정 소유자가 읽을 수 있는 모든 경로를 지정할 수 있으며, 생성된 프로젝트 사본은 assets/generated/로 제한됩니다. 공유되거나 신뢰도가 낮은 하네스의 경우 CHATGPT_IMAGE_BRIDGE_MCP_ALLOWED_ROOTS를 승인된 프로젝트 디렉터리 하나 이상으로 설정하세요.

Codex 자식 프로세스는 호스트 프로세스 환경을 상속하는 대신 최소 운영 환경을 받습니다. CHATGPT_IMAGE_BRIDGE_MCP_CODEX_ENV_ALLOWLIST에 비밀을 추가하지 마세요.

개발

uv sync
uv run ruff check src tests scripts
uv run pytest
uv build
python3 scripts/build_openai_plugin.py

테스트는 가짜 계정 런타임을 사용하며 제공자 호출이나 유료 이미지 요청을 하지 않습니다. 특정 Codex 빌드 및 계정 권한을 입증하려면 별도의 라이브 스모크 테스트가 필요합니다.

릴리스를 게시하기 전에 깨끗한 체크아웃에서 위 명령을 실행하고, 패키지된 플러그인을 사용하여 하나의 실제 생성과 하나의 analyze_image 후속 작업을 최소 하나의 MCP 호스트에서 검증하세요. Codex app-server 브리지는 실험적이므로 런타임 호환성은 이 저장소와 독립적으로 변경될 수 있습니다.

라이선스

MIT. LICENSE를 참조하세요.