版本： 1.0.0
一个AI 描述它所看到的内容。 生成式图像描述器 — MCP 服务器 + CLI，封装了 Florence-2 (MIT) 用于散文描述、OCR 和 LoRA 数据集标注旁文件。 本地运行，默认确定性输出。
是 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 的 SaveText 节点（会追加 _00001）。
直接拼接： 旁文件包含 prefix + caption + suffix，
不插入任何分隔符。想要 "mcpt_style, <caption>"？将
逗号空格放在前缀中。
幂等重运行： 现有旁文件会被跳过（且不消耗成本），除非
使用 --overwrite / overwrite=true。
确定性： do_sample=false + 束搜索——对未更改的图像重新标注
会生成相同的文本，因此差异具有意义。
Florence-2 的原生任务阶梯：
层级 | 任务 token | 输出 |
|
| 一个短句 |
|
| 几句话 |
|
| 一个完整段落 |
high 是一个段落，而非一篇短文——Florence-2 是一个紧凑（0.77B）模型。
它的优势在于吞吐量和许可证，而非艺术评论的深度。如果标注看起来
被截断，请提高 max_new_tokens（默认 1024，最大 4096）。
环境变量 | 默认值 | 用途 |
|
| HuggingFace 模型 |
| HF 默认缓存 | 模型缓存目录 |
|
| torch 设备 |
| CUDA 上为 |
|
|
| 默认生成上限 |
|
| 束宽（确定性解码） |
|
|
|
| 未设置 | 如果为真，则在服务器启动时加载模型 |
日志： 仅输出到 stderr（stdout 是 MCP 协议通道），logger 名称
plain_sight。
首次调用： 模型延迟加载——首次 describe/OCR 调用会加载
Florence-2（GPU 上约 10–20 秒；首次调用会下载约 1.5 GB）。后续
调用在现代 GPU 上以 high 细节处理每张图像约需 1–2 秒。
本工具： MIT。
模型： 固定为 florence-community/Florence-2-large——微软 Florence-2 发布的官方原生 transformers 转换版本。
MIT（hub 许可证标签验证于 2026-08-19）。商业使用无问题。
为何不使用 microsoft/Florence-2-large？ 相同的权重，相同的 MIT 许可证，
但原始仓库附带预原生配置，只能通过
trust_remote_code 加载——本工具原则上拒绝使用。社区
转换版本可通过 transformers 的内置 Florence-2 类加载。
刻意不提供： Florence-2 微调模型动物园（MiaoshouAI
PromptGen、CogFlorence、SD3/Flux 标注器、Castollux）。它们的许可证
未经验证；在明确之前不会纳入。将 PLAIN_SIGHT_MODEL_ID 覆盖为
其中一个模型是可能的，但许可证问题将由您自行承担。
无远程代码： 引擎仅使用 transformers 的原生 Florence-2
支持——从不传递 trust_remote_code，因此不会执行任何从 hub 获取的
Python 代码。这要求 transformers >= 4.51。
此工具仅本地运行。
接触的数据： 本地图像文件（只读）；HuggingFace 模型缓存
（首次下载时写入一次）；.txt 标注旁文件——这是它唯一写入的文件，
且仅写入调用者指定的位置（out_dir 或图像旁边），
现有旁文件仅在显式 --overwrite 下才会被替换。
运行时无网络出站流量——模型在首次使用时下载一次， 之后所有推理均在本地进行。
无远程代码执行——仅使用原生 transformers 类；
从不传递 trust_remote_code，因此不会执行任何 hub 获取的代码。
不处理机密信息，无遥测——不读取或发送任何内容。
仅结构化错误——原始堆栈跟踪永远不会到达 MCP 客户端或 CLI 用户。CLI 退出代码：0 成功 · 1 用户错误 · 2 运行时错误 · 3 部分成功。
完整政策：SECURITY.md。积极维护；受支持的 版本列于其中。
Python >= 3.10
transformers >= 4.51（原生 Florence-2）
推荐使用 CUDA GPU（FP16 下约需 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——相同的
引擎/服务器拆分、相同的错误塑造、相同的自检模式。同一契约的云端
姊妹版本在 Comfy Cloud 上作为
caption-florence2-v1 工作流运行（每任务一个图像的元数据附加项；此工具
是批量通道）。
MIT
由 MCP Tool Shop 构建
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