AdaTile-MCP v1.0

高解像度画像の適応的タイル分割前処理層（MCP）。対象モデルは DeepSeek deepseek-v4-flash-vision-exp。 『AdaTile-MCP プロジェクト構築ガイド（v1.2）』の6週間計画に従い、Phase 0–5 をすべて完了。進捗と実測データは STATE.md、現在判明している問題の一覧は KNOWN_ISSUES.md を参照。

6層パイプライン（pipeline_v1）

L1 高速パス（magic bytes/遅延デコード/上限超過時のダウンサンプリング/小画像の直接送信）→ L2 顕著性（スペクトル残差 CPU デフォルト、 U²-Netp オプション、Watchdog タイムアウト時はダウングレード）→ L3 適応的タイル分割（連結成分/予算の事前割り当て/連続ブロック選択/ドキュメント fine パス）→ L4 アセンブルとアップロード（tile 単位のパイプライン化エンコード→アップロード、3段階キャッシュ、コンプライアンス6項目のハード検証、ダウングレードチェーン）→ L5 ストリーミング呼び出し（json_object 強制出力、TTFT の二重計測、リトライとグローバルフォールバック）→ L6 ルールベースのマージ （IOU>0.3 かつ同一ラベルなら bbox を結合）。

Related MCP server: image-tiler-mcp-server

ダウングレード動作の説明

品質とレイテンシのベースライン（実測、詳細は experiments/*.json）

• 初回前処理 p95 1116ms（実アップロード含む）/ キャッシュヒット 134ms；TTFT 847ms/613ms；10 並行で 100% 成功

• Phase 5 の4方式比較とアブレーション：experiments/phase5_results.json

環境要件

• Python 3.11+（プロジェクト内の .venv は 3.13）

• 環境変数 DEEPSEEK_API_KEY（DeepSeek プラットフォームで申請）

• Windows/Git Bash で venv を有効化：source .venv/Scripts/activate

• 新規マシンで環境をワンクリック構築：setup.bat（Windows）/ setup.sh（macOS/Linux）、詳細は次節

ゼロからの導入（新マシン / 任意の agent）

.venv とキーはリポジトリに含まれないため、新マシンでは以下の5ステップのみ：

1. Python 3.11+ をインストール（Windows ではインストール時に「Add to PATH」にチェック）。

2. コードを取得：git clone https://github.com/Mutton-hub/adatile-mcp.git（または本ディレクトリをコピー。.venv は不要）。

3. 環境を構築：プロジェクトルートで setup.bat（Windows）または ./setup.sh（macOS/Linux）を実行——.venv を自動作成し、requirements.txt の全依存関係をインストール。

4. キーを設定：環境変数 DEEPSEEK_API_KEY を設定するか、.env.example を .env にコピーして記入（どちらか一方；.env は .gitignore で除外済み）。

5. MCP を登録：以下の表に従い、agent の設定を本機のリポジトリ絶対パス配下の run.bat（Windows）/ run.sh（Unix）に指定し、セッション再起動後にまず adatile_status で自己診断。

同一マシンで複数の agent を接続する場合は、手順5を繰り返すだけ（各クライアントが個別に設定）。環境とキーは共用。

MCP 登録 —— 任意のローカル agent/harness に対応

サーバーは標準 MCP（stdio デフォルト / http / sse オプション）で、以下のクライアントすべてで接続可能。 key の解決順序：環境変数 DEEPSEEK_API_KEY → プロジェクトルートの .env ファイル（.env.example を .env にコピーして記入するだけ。環境変数を注入しにくいクライアントに最適）。

汎用形式（stdio MCP をサポートするすべてのクライアント）。<repo> はリポジトリのクローン/チェックアウト後の実際の絶対パスに置き換え（パスに中国語やスペースが含まれる場合は必ず絶対パスを使用）：

{
  "mcpServers": {
    "adatile-mcp": {
      "command": "<repo>\\run.bat",
      "args": []
    }
  }
}

run.bat ランチャーが venv を自動的に特定（macOS/Linux は <repo>/run.sh）。または <repo>/.venv/Scripts/python.exe + server.py を直接指定してもよい。

各クライアントの配置場所：

ZCode プロジェクトレベル設定の例（<repo>/.zcode/config.json。クローン後にリポジトリごとチームへ共有）：

{
  "mcp": {
    "servers": {
      "adatile-mcp": {
        "command": "C:\\path\\to\\cloned-repo\\run.bat",
        "args": []
      }
    }
  }
}

導入後の利用フロー（任意の agent/harness）

1. key を設定：環境変数 DEEPSEEK_API_KEY を設定するか、.env.example を <repo>/.env にコピーして記入 （.env は .gitignore で除外済みのためバージョン管理に入らない；adatile_status で key の準備状態を確認可能）。

2. MCP サーバーを登録（上の表）し、クライアントのセッションを再起動。

3. まず adatile_status を呼び出し（API 呼び出しゼロ、費用ゼロ）、key の設定とローカルの L1–L6 機能を確認。

4. 次に analyze_high_res_image を呼び出し、image_path（ローカルの絶対パス）と task_hint を渡す。

5. 返された merged_answer を優先使用；objects/tile_details 内の bbox で正確な位置を特定可能。

6. 同じ画像への追加質問は、同じ image_path を繰り返し呼び出すだけでよい——内部の3段階キャッシュが自動的にヒットし、 file_id を手動管理する必要はない。

HTTP モードの例（コンテナ/リモート harness）：

./run.sh --transport http --host 0.0.0.0 --port 8765
# MCP endpoint: http://<host>:8765/mcp

導入後はまず adatile_status を呼び出し（API 呼び出しゼロ）、key の設定とローカル機能を確認してから analyze_high_res_image を呼び出す。

ツール：analyze_high_res_image

戻り値：merged_answer、objects（ベストエフォートで解析）、tile_details（bbox と file_id を含む）、latency_ms、token_usage、upload_stats、route（direct_pass / tile_pipeline）。

よく使うコマンド

# 生成测试集 A（50 张 4K 合成图 + ground_truth.json）
.venv/Scripts/python.exe experiments/cases/gen_set_a.py --n 10 --seed 42

# Phase 0 校准实验（先跑一票否决用例！）
.venv/Scripts/python.exe experiments/run_phase0.py --cases TC-0.1.8 TC-0.3.1 TC-0.4.2
.venv/Scripts/python.exe experiments/run_phase0.py --list        # 查看全部用例
.venv/Scripts/python.exe experiments/run_phase0.py --full        # 含重型用例
.venv/Scripts/python.exe experiments/run_phase0.py --rounds 10   # TTFT 轮数控制费用

# 本地自检（无 API 调用）
.venv/Scripts/python.exe -m pytest tests/test_local.py -q

# stdio 端到端冒烟测试（真实子进程 + 官方 MCP SDK，零 API 调用）
.venv/Scripts/python.exe tests/stdio_smoke.py

Agent 側 System Prompt（テンプレート B、ガイド 3.3）

当用户上传高分辨率图像（总像素 > 64 万）时：
1. 调用 analyze_high_res_image 工具，传入 image_path 和 task_hint（上传与切片由工具自动经 Files API 完成）；
2. task_hint：文字识别→"ocr"；全景描述→"describe"；具体元素→"detect"；
3. 优先使用 merged_answer；tile_details 中的 bbox 可精确定位；
4. 同一张图的追问请复用工具（内部缓存自动命中）；
5. 禁止直接将原图 base64 传给 VLM——必须走本工具，否则细节丢失。

ダウングレード動作（Phase 0）

• L1 破損/非対応形式 → 構造化エラー {stage:"L1", reason:...}、ダウングレードパスなし

• 小画像（≤64万画素）→ DirectPass で1回の直接送信

• Files API が利用不可 → 主要方式には現時点で自動ダウングレードなし（Phase 3 で全インラインダウングレードチェーンを実装）