버전: 1.0.0
AI가 보는 것을 말합니다. 생성형 이미지 설명 도구 — 산문 설명, OCR 및 LoRA 데이터셋 캡션 사이드카를 위해 Florence-2(MIT)를 래핑하는 MCP 서버 + CLI. 로컬에서 실행되며, 기본적으로 결정적(deterministic)입니다.
ai-eyes-mcp의 자매 프로젝트입니다:
ai-eyes-mcp | plain-sight | |
역할 | 이미지를 판정합니다 | 이미지를 설명합니다 |
모델 | SigLIP2 (판별형) | Florence-2 (생성형) |
출력 | 보정된 점수 | 산문 / OCR / 캡션 파일 |
실패 모드 | 서술할 수 없음 | 디테일을 환각할 수 있음 |
사용하기 좋은 때 | "이 이미지에 X가 포함되어 있나요?" | "이 이미지에 무엇이 있나요?" |
설명은 생성형입니다. 유창하고 대체로 정확하지만, 세부 내용을 지어낼 수 있습니다.
plain-sight는 출력을 재현 가능하게 만듭니다(결정론적 디코딩 — 동일한 이미지는 동일한 캡션을 생성). 사실 보장은 아닙니다.
이미지에 대한 특정 주장을 검증하려면 ai-eyes-mcp의 image_verify를 사용하세요 — 측정하는 도구이지 서술하는 도구가 아닙니다.
두 도구는 설계상 서로 다른 모델 계열이므로, 하나가 다른 하나를 검증할 수 있습니다.
Related MCP server: fm-mcp-comfyui-bridge
도구 | 담당 |
| 이미지 하나 → 산문 설명 (세부 수준 3단계) |
| N개 이미지 → |
| OCR — 이미지에서 보이는 텍스트 추출 |
| 상태 점검: 모델, 장치, 로드 상태 |
| 번들된 참조 이미지 설명 및 결과의 온전성 검사 |
pip install -e .
plain-sight-mcp # starts the STDIO MCP server또는 모듈로 실행: python -m plain_sight
# 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{
"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 계층 구조:
수준 | Task 토큰 | 출력 |
|
| 짧은 문장 하나 |
|
| 몇 문장 |
|
| 전체 단락 |
high는 에세이가 아니라 하나의 단락입니다 — Florence-2는 작고(0.77B) 가벼운 모델입니다.
그 특징은 처리량과 라이선스에 있고, 평론가 수준의 깊이는 아닙니다. 캡션이 잘려 보이면 max_new_tokens(기본값 1024, 최대 4096)를 늘리세요.
환경 변수 | 기본값 | 용도 |
|
| HuggingFace 모델 |
| HF 기본 캐시 | 모델 캐시 디렉터리 |
|
| torch 장치 |
| CUDA에서는 |
|
|
| 기본 생성 최대 토큰 수 |
|
| 빔 너비 (결정론적 디코딩) |
|
|
|
| unset | 설정되면(truthy) 서버 시작 시 모델 로드 |
로깅: 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.shengine.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
Blocks until every image completes -- roughly 1-2 s per image plus ~10-20 s if the model is not yet loaded. Chunk large sets. Existing sidecars are skipped unless overwrite=true, so a retry is cheap.
Caption a batch of images, writing .txt sidecars -- the dataset lane. The training-data contract: EXACT basename pairing (img_0042.png -> img_0042.txt, no counter suffix) and BARE prefix+caption+suffix concatenation (no delimiter injected).
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Detail tier: 'low' | 'medium' | 'high' (default) | high |
| prefix | No | Text prepended to every caption, bare concatenation — include your own separator (e.g. 'mcpt_style, ') | |
| suffix | No | Text appended to every caption, bare concatenation | |
| out_dir | No | Directory for sidecar files (created if missing). Default: next to each image | |
| overwrite | No | Re-caption images whose sidecar already exists (default false: skip them, so re-runs are idempotent and cheap) | |
| image_paths | Yes | List of absolute image file paths (max 100) | |
| manifest_path | No | Optional explicit JSON provenance path. Default none — no manifest is written. Refused if it collides with a sidecar. | |
| max_new_tokens | No | Generation length cap (default 1024, max 4096) | |
| write_sidecars | No | Write each caption to <image-stem>.txt (exact basename pairing). When false, captions are returned in the response instead |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so well: it discloses blocking behavior, per-image latency (~1-2 s plus ~10-20 s model load), idempotency via sidecar skipping, and the exact sidecar/manifest naming contract. These are behavioral traits an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight paragraphs, no filler, every clause earns its place. The purpose sentence is slightly buried behind the latency note, so the front-loading is not ideal, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, and the description still covers latency, idempotency, and the sidecar contract for a 9-parameter tool. The main omission is routing guidance versus describe_image and any failure/error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters (prefix/suffix bare concatenation, overwrite skip semantics, manifest collision refusal) are already fully documented in the schema. Baseline 3 applies because the description largely restates those semantics rather than adding new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Caption a batch of images, writing .txt sidecars') and the 'dataset lane' scope, which separates it from the singular describe_image sibling. It never names describe_image explicitly, so the differentiation rests on the word 'batch' rather than a direct contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives operational guidance ('Chunk large sets', retries are cheap because existing sidecars are skipped), which implies when this tool is appropriate. It does not, however, state when to prefer describe_image or describe_batch, nor any preconditions beyond chunking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe an image in prose — an AI says what it sees.
Uses Florence-2 (MIT-licensed, runs locally) with deterministic decoding: the same image at the same tier reproduces the same description.
Descriptions are generative and can hallucinate detail — for verifying a specific claim about the image, prefer ai-eyes-mcp's image_verify.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Detail tier: 'low' (one sentence), 'medium' (a few sentences), 'high' (full paragraph — default) | high |
| image_path | Yes | Absolute path to the image file | |
| max_new_tokens | No | Generation length cap (default 1024, max 4096) — raise if a high-detail caption looks truncated |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses local execution, licensing, deterministic decoding with reproducibility guarantees, and the hallucination risk inherent to generative captioning. It also explains the max_new_tokens escape hatch for truncated output — behavioral context no structured field provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then behavior, then the routing caveat in three tight paragraphs. The opening clause 'an AI says what it sees' is mildly redundant with the name but the rest earns its place with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need no explanation, and the tool is a single-shot read. The description covers execution model, reproducibility, failure mode, and the alternative tool — nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents detail tiers, image_path, and max_new_tokens semantics. The description only echoes the tier concept ('same image at the same tier') without adding syntax or format detail. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Describe an image in prose') and names the underlying mechanism (Florence-2, local, deterministic). It implicitly contrasts with read_text (OCR) and explicitly with image_verify, so an agent can distinguish it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names when NOT to use it ('for verifying a specific claim about the image, prefer ai-eyes-mcp's image_verify') and explains the tier behavior that selects output depth. This is the when/when-not/alternative pattern at full strength.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract visible text from an image (Florence-2 task).
Returns the text the model reads off the pixels — signage, UI labels, documents. Like all generative output it can misread; treat low-stakes.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Absolute path to the image file | |
| max_new_tokens | No | Generation length cap (default 1024, max 4096) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does real work: it discloses that output is generative, may misread, and is low-stakes. This is genuine behavioral context about reliability. It stops short of covering determinism, retry behavior, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short lines with the core action front-loaded. The model-task parenthetical and misread caveat are compact. Slightly fragmentary but nothing wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return shape need not be explained, and annotations are absent. The description covers purpose, examples, and the key reliability caveat for a 2-param generative tool. Adequate without being exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (image_path, max_new_tokens) are already documented with defaults and limits. The description adds no parameter detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (extract) and resource (visible text from an image), and names the underlying model task (Florence-2 <OCR>). An agent can distinguish this from describe_image's broader captioning role by the scoped 'visible text' target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage through examples (signage, UI labels, documents) but never explicitly states when to choose this over describe_image or describe_batch. No exclusions or routing guidance are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Self-test: describe the bundled reference images and confirm the outputs are sane (non-trivial, on-subject, tier ordering holds) — proves the install loaded correctly. Loads the model if it isn't already.
Returns {passed, checks: [{name, expected, measured, ok}], model_id, device, torch_version, transformers_version}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden well: it discloses the side effect ('Loads the model if it isn't already') and enumerates the returned check structure. It does not mention cost, duration, or failure modes when checks fail, keeping it short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and the rationale, and every sentence adds information about scope, side effects, or output. The trailing return-value sentence slightly duplicates the existing output schema, which is the only waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic with an output schema, the description covers what it does, why it exists, and the model-loading side effect. It could be more complete by stating what a failed test implies or recommending a follow-up action, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — run a self-test that describes bundled reference images and validates the outputs — and clarifies the goal ('proves the install loaded correctly'). It is clearly distinguishable from describe_image/describe_batch, though it never names those siblings directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'proves the install loaded correctly', which suggests running it as a post-install verification, and it notes the side effect of loading the model. However, it does not tell the agent when to prefer this over the sibling sight_status or when not to run it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check plain-sight server status.
Returns model info, device, and whether the model is currently loaded. The model loads lazily on first tool call — this tool does NOT trigger loading.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a genuinely useful behavior: the model loads lazily and this call deliberately avoids triggering that load. That is a real side-effect disclosure an agent needs. It stops short of stating whether the call has any other cost or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose and followed by return contents and the key caveat. No filler, every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't restate return values, and the one non-obvious behavior (lazy loading, no load triggered) is covered. It could have pointed to sight_selftest as the follow-up, but nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document; baseline for a no-parameter tool is 4. The description correctly adds no parameter noise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Check plain-sight server status') and enumerates what comes back (model info, device, load state). It distinguishes itself from the describe/read siblings by being a diagnostic call, though it doesn't explicitly contrast with sight_selftest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The note that the tool does NOT trigger loading implicitly tells the agent when to prefer it (a non-invasive status check), but there is no explicit when-to-use statement nor a routing hint toward sight_selftest for deeper diagnostics. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0describe_batchdescribe_imageread_textsight_selftestsight_statusScored across 5 tools
Tools have distinct purposes: single image description, batch captioning with sidecars, OCR, status check, and self-test. The only mild overlap is between describe_image and describe_batch, but the sidecar/dataset contract and blocking behavior make them clearly separable.
Three tools follow verb_noun (describe_image, describe_batch, read_text) while two follow noun_noun with a sight_ prefix (sight_status, sight_selftest). The split is readable but not a single consistent pattern.
Five tools is well within the ideal range for a focused image description/OCR server; each tool has a clear role and none feels redundant.
Core workflows are covered: single and batch description, OCR, status, and self-test. Minor gaps exist, such as no explicit tier selection tool or a way to get batch captions without writing sidecars, but these are workable.
MCP server for Qwen Image 3 AI image generation
MCP server for Flux AI image generation
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for Grok Imagine AI video generation