plain-sight

버전: 1.0.0

AI가 보는 것을 말합니다. 생성형 이미지 설명 도구 — 산문 설명, OCR 및 LoRA 데이터셋 캡션 사이드카를 위해 Florence-2(MIT)를 래핑하는 MCP 서버 + CLI. 로컬에서 실행되며, 기본적으로 결정적(deterministic)입니다.

ai-eyes-mcp의 자매 프로젝트입니다:

정직성 계약

설명은 생성형입니다. 유창하고 대체로 정확하지만, 세부 내용을 지어낼 수 있습니다. plain-sight는 출력을 재현 가능하게 만듭니다(결정론적 디코딩 — 동일한 이미지는 동일한 캡션을 생성). 사실 보장은 아닙니다. 이미지에 대한 특정 주장을 검증하려면 ai-eyes-mcp의 image_verify를 사용하세요 — 측정하는 도구이지 서술하는 도구가 아닙니다. 두 도구는 설계상 서로 다른 모델 계열이므로, 하나가 다른 하나를 검증할 수 있습니다.

Related MCP server: fm-mcp-comfyui-bridge

도구 (MCP)

빠른 시작

pip install -e .
plain-sight-mcp   # starts the STDIO MCP server

또는 모듈로 실행: python -m plain_sight

CLI

# One image, full paragraph
plain-sight describe hero.png

# One short sentence
plain-sight describe hero.png --detail low

# OCR
plain-sight ocr screenshot.png

# The dataset lane: caption a directory into .txt sidecars with a trigger token
plain-sight batch ./dataset --prefix "mcpt_style, " --detail high

# Re-runs are idempotent — existing sidecars are skipped unless you --overwrite
plain-sight batch ./dataset --prefix "mcpt_style, " --overwrite

Claude Code 설정

{
  "mcpServers": {
    "plain-sight": {
      "command": "plain-sight-mcp",
      "env": {
        "PLAIN_SIGHT_MODEL_DIR": "/path/to/model/cache"
      }
    }
  }
}

캡션 계약 (데이터셋 경로)

LoRA 학습 집합(style-dataset-lab 등)을 위해 만들어졌습니다:

• 정확한 기본 파일명 짝짓기: img_0042.png → img_0042.txt. 카운터 접미사가 없습니다 — ComfyUI가 _00001을 추가하는 SaveText 노드와는 다릅니다.

• 구분자 없는 연결: 사이드카는 prefix + caption + suffix를 구분자를 주입하지 않고 그대로 담습니다. "mcpt_style, <caption>"을 원하세요? 쉼표와 공백을 접두사의 공백에 넣으세요.

• 멱등 재실행: --overwrite / overwrite=true가 없으면 이미 있는 사이드카에 대체하지 않습니다(비용도 없음).

• 결정적: do_sample=false + beam search — 변경되지 않은 이미지를 다시 캡션하면 같은 텍스트가 생성되므로 diff가 의미를 갖습니다.

세부 수준

Florence-2의 기본 task 계층 구조:

high는 에세이가 아니라 하나의 단락입니다 — Florence-2는 작고(0.77B) 가벼운 모델입니다. 그 특징은 처리량과 라이선스에 있고, 평론가 수준의 깊이는 아닙니다. 캡션이 잘려 보이면 max_new_tokens(기본값 1024, 최대 4096)를 늘리세요.

구성

로깅: stderr에만 출력(stdout은 MCP 프로토콜 채널), 로거 이름 plain_sight.

첫 호출: 모델은 lazy하게 로드됩니다 — 첫 describe/OCR 호출이 Florence-2를 로드합니다(GPU에서 약 10–20초; 최초 호출은 약 1.5 GB 다운로드로드). 이후에는 최신 GPU에서 high 수준 기준 이미지당 약 1–2초면 됩니다.

라이선스 정책

• 이 도구: MIT.

• 모델: florence-community/Florence-2-large로 고정 — Microsoft Florence-2 배포의 공식 native-transformers 변환입니다. MIT (허브 라이선스 태그 확인 2026-08-19). 상용 이용 문제없음.

• 왜 transformers / microsoft/Florence-2-large가 아니라? 가중치와 MIT 라이선스는 같지만, 원본 리포지토리는 trust_remote_code로만 로드되는 pre-native 설정이 포함되어 있습니다 — 이 도구는 원칙적으로 이를 거부합니다. 반면 커뮤니티 변환은 transformers 내장 Florence-2 클래스로 로드됩니다.

• 일부로 제공하지 않는 것: Florence-2 fine-tune 모음 (MiaoshouAI PromptGen, CogFlorence, SD3/Flux captioner, Castollux). 이 라이선스는 검증되지 않았고, 확인될 때까지 제외됩니다. PLAIN_SIGHT_MODEL_ID를 통해서 이들을 덮어 쓰는 것은 가능하지만 그 라이선스 책임은 사용자에게 있습니다.

• 원격 코드 없음: 엔진은 transformers의 네이티브 Florence-2 지원만 사용합니다 — trust_remote_code를 전혀 사용하지 않으므로 허브에서 가져온 Python은 절대 실행되지 않습니다. 이를 위해 transformers >= 4.51이 필요합니다.

보안 및 신뢰

이 도구는 로컬 환경에서만 동작합니다.

• 다루는 데이터: 로컬 이미지 파일(읽기 전용); HuggingFace 모델 캐시(첫 다운로드 시 한 번만 쓰기); .txt 캡션 사이드카 — 이 도구가 제가 쓰는 유일한 파일이며, 호출자가 요청한 위치(out_dir 또는 이미지 옆)에만 씁니다. 기존 사이드카는 명시적 --overwrite가 있어야만 대체합니다.

• 명시적으로 outbound가 없음 ] — 모델은 첫 사용 시 한 번만 다운로드하고, 그 이후에는 모든 추론이 로컬에서 실행됩니다.

• 원격 코드 실행 없음 — native transformers 클래스만 사용하므로 trust_remote_code는 절대 전달되지 않고 허브에서 끌어온 Python이 실행되지 않습니다.

• 비밀값 처리·원격 전송 없음 — 아무것도 읽지도 보내지도 않습니다.

• 구조화된 오류만 — MCP 클라이언트나 CLI 사용자에게 surow 스택 추적이 도달하지 않습니다. CLI 새로 종료 코드: 0 정상, 1 사용자 오류, 2런타임 오류, 3 부분 성공.

전체 정책: SECURITY.md. 계속 관리되고 있으며, 지원하는 버전이 여기에 나와 있습니다.

요구사항

• Python >= 3.10

• transformers >= 4.51 (네이티브 Florence-2)

• CUDA GPU 권장 (FP16 기준 VRAM ~2 GB); CPU 폴백 작동 (느리지만)

• 모델 첫 사용 시 ~1.5 GB 다운로드 필요

개발

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# CI-safe tests (no model, no GPU)
pytest tests/test_edge_cases.py -v

# Dogfood tests (real model + GPU)
pytest tests/test_dogfood.py -v

# Full verify: imports, edge tests, build
bash verify.sh

아키텍처

engine.py    Standalone Florence-2 wrapper — no MCP dependency.
             Lazy-loads the model; validation runs BEFORE the load.
             Importable directly: from plain_sight.engine import Florence2Engine

sidecars.py  The training-data contract, pure stdlib: basename pairing,
             bare concatenation, directory expansion. Testable without torch.

server.py    FastMCP wrapper exposing engine methods as MCP tools.
             Thin layer: validation, error shaping, tool metadata.

cli.py       argparse CLI over the same engine (describe / ocr / batch /
             status / selftest). Structured errors, meaningful exit codes.

아키텍처는 ai-eyes-mcp에서 의도적으로 가져온 것입니다 — 같은 엔진/서버 분리, 같은 오류 형태, 같은 selftest 패턴을 사용합니다. 같은 계약의 클라우드 형제는 Comfy Cloud에서 caption-floret1-v1 워크플로우로 실행됩니다(작업당 이미지 하나라는 메타데이터 특성이 되고, 이 도구가 대량 처리 경로입니다).

라이선스

MIT

MCP Tool Shop제작.