plain-sight

バージョン: 1.0.0

AIが見たものを語る。 生成型画像ディスクライバー — Florence-2 (MIT) をラップする MCP サーバー + CLI。散文による説明、OCR、LoRA データセット用キャプションサイドカーを提供する。ローカルで動作し、デフォルトで決定論的。

ai-eyes-mcp の兄弟ツールです:

誠実性の契約

説明は生成的です。流暢で、通常は正確で、詳細を捏造し得ます。plain-sight は出力を再現可能にします（決定論的デコード——同じ画像は同じキャプションを生成する）が、真実であることを保証するものではありません。画像に関する特定の主張を検証するには、ai-eyes-mcp の image_verify を使ってください。これは測定するものであり、語るものではありません。この2つのツールは設計上異なるモデルファミリーなので、互いに検証し合うことができます。

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 の SaveText ノード（_00001 を追加する）とは異なります。

• そのままの連結: サイドカーには prefix + caption + suffix が 区切り文字を挿入されずに含まれます。"mcpt_style, <caption>" にしたい場合は、 カンマ+スペースをプレフィックスに入れてください。

• 冪等な再実行: 既存のサイドカーはスキップされます（コストもかかりません）。 --overwrite / overwrite=true を指定した場合のみ上書きされます。

• 決定論的: do_sample=false + ビームサーチ——変更されていない画像を 再キャプションすると同じテキストが再現されるため、差分に意味があります。

詳細度の段階

Florence-2 のネイティブなタスクラダー:

high は段落であって、エッセイではありません——Florence-2 はコンパクトな (0.77B) モデルです。 その強みはスループットとライセンスであり、美術評論の深さではありません。キャプションが 途中で切れているように見える場合は、max_new_tokens（デフォルト 1024、最大 4096）を上げてください。

設定

ログ: stderr のみ（stdout は MCP プロトコルチャネル）、ロガー名は plain_sight。

初回呼び出し: モデルは遅延ロードされます——最初の describe/OCR 呼び出しで Florence-2 をロードします（GPU で約10〜20秒; 初回の呼び出しでは約1.5 GBをダウンロード）。 以降の呼び出しは、最新の GPU で high 詳細度の場合、画像1枚あたり約1〜2秒です。

ライセンスの姿勢

• このツール: MIT。

• モデル: florence-community/Florence-2-large に固定——Microsoft の Florence-2 リリースの 公式ネイティブ transformers 変換版です。MIT（ハブのライセンスタグは 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 は決して渡されないため、ハブから取得した Python が実行されることはありません。これには transformers >= 4.51 が必要です。

セキュリティと信頼

このツールはローカルのみで動作します。

• 触れるデータ: ローカル画像ファイル（読み取り専用）; HuggingFace モデルキャッシュ （初回ダウンロード時に一度だけ書き込み）; .txt キャプションサイドカー——書き込むのは これだけであり、呼び出し元が指定した場所（out_dir または画像の隣）にのみ書き込み、 既存のサイドカーは明示的な --overwrite でのみ置き換えられます。

• 実行時のネットワーク送信なし——モデルは初回使用時に一度だけダウンロードされ、 以降の推論はすべてローカルです。

• リモートコード実行なし——ネイティブ transformers クラスのみ; trust_remote_code は決して渡されないため、ハブから取得した Python が実行されることはありません。

• シークレット処理なし、テレメトリなし——どこからも読み取らず、どこにも送信しません。

• 構造化エラーのみ——生のスタックトレースが MCP クライアントや CLI ユーザーに 届くことはありません。CLI 終了コード: 0 正常 · 1 ユーザーエラー · 2 ランタイムエラー · 3 部分成功。

完全なポリシー: SECURITY.md。積極的にメンテナンスされており、 サポート対象バージョンはそこに記載されています。

要件

• Python >= 3.10

• transformers >= 4.51（ネイティブ Florence-2）

• CUDA GPU 推奨（FP16 で約2GB VRAM）; CPU フォールバックも動作します（遅い）

• 初回使用時にモデルを約1.5GBダウンロード

開発

# 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 から借用しています——同じ エンジン/サーバー分割、同じエラー整形、同じセルフテストパターン。同じ契約のクラウド版は Comfy Cloud で caption-florence2-v1 ワークフローとして動作しています（ジョブごとに 1枚の画像というメタデータライダー; このツールはバルクレーンです）。

ライセンス

MIT

MCP Tool Shop によって構築されました。