AdaTile-MCP v1.0

Adaptive high-resolution image tiling preprocessing layer (MCP), targeting the DeepSeek deepseek-v4-flash-vision-exp model. All Phase 0–5 were completed per the six-week plan in the AdaTile-MCP Project Build Guide (v1.2). Progress and measured data are in STATE.md; the current list of known issues is in KNOWN_ISSUES.md.

Six-Layer Pipeline (pipeline_v1)

L1 fast path (magic bytes/lazy decoding/over-limit downsampling/small-image direct pass) → L2 saliency (spectral residual, CPU default; U²-Netp optional; Watchdog timeout degradation) → L3 adaptive tiling (connected components/budget pre-allocation/contiguous block selection/document fine path) → L4 assembly & upload (tile-level pipelined encode → upload, three-level cache, six compliance hard checks, degradation chain) → L5 streaming invocation (forced json_object output, TTFT dual metrics, retry and global fallback) → L6 rule-based merging (IOU>0.3, merge same-label bboxes).

Related MCP server: image-tiler-mcp-server

Degradation Behavior

Quality and Latency Baselines (measured; see experiments/*.json for details)

• First preprocess p95 1116ms (including real upload) / cache hit 134ms; TTFT 847ms/613ms; 10 concurrent, 100% success

• Phase 5 four-scheme comparison and ablation: experiments/phase5_results.json

Environment Requirements

• Python 3.11+ (the project's .venv uses 3.13)

• Environment variable DEEPSEEK_API_KEY (request it on the DeepSeek platform)

• Activate venv on Windows/Git Bash: source .venv/Scripts/activate

• One-click environment setup on a new machine: setup.bat (Windows) / setup.sh (macOS/Linux), see the next section

Getting Started from Scratch (new machine / any agent)

.venv and keys don't ship with the repo; a new machine only needs 5 steps:

1. Install Python 3.11+ (check "Add to PATH" during Windows installation).

2. Get the code: git clone https://github.com/Mutton-hub/adatile-mcp.git (or copy this directory; no need to include .venv).

3. Set up the environment: run setup.bat (Windows) or ./setup.sh (macOS/Linux) in the project root — it automatically creates .venv and installs all dependencies in requirements.txt.

4. Configure the key: set the environment variable DEEPSEEK_API_KEY, or copy .env.example to .env and fill it in (choose either one; .env is excluded by .gitignore).

5. Register the MCP: per the table below, point your agent config to run.bat (Windows) / run.sh (Unix) under the repo's absolute path on this machine; after restarting the session, call adatile_status first for a self-check.

When connecting multiple agents on the same machine, just repeat step 5 (each client configures it separately); the environment and key are shared.

MCP Registration — Works with Any Local Agent/Harness

The server is standard MCP (stdio by default; http / sse optional). All of the following clients can connect. Key resolution order: environment variable DEEPSEEK_API_KEY → project-root .env file (just copy .env.example to .env and fill it in; suitable for clients where environment variables are hard to inject).

Generic form (for all clients that support stdio MCP). Replace <repo> with the actual absolute path after the repo is cloned/checked out (an absolute path is required if the path contains Chinese characters or spaces):

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

The run.bat launcher automatically locates the venv (use <repo>/run.sh on macOS/Linux). You can also point directly to <repo>/.venv/Scripts/python.exe + server.py.

Where each client places its config:

ZCode project-level configuration example (<repo>/.zcode/config.json; shared with the team along with the repo after cloning):

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

Usage Flow After Connection (any agent/harness)

1. Configure the key: set the environment variable DEEPSEEK_API_KEY, or copy .env.example to <repo>/.env and fill it in (.env is excluded by .gitignore and won't enter version control; adatile_status can confirm whether the key is ready).

2. Register the MCP server (table above) and restart the client session.

3. First call adatile_status (zero API calls, zero cost) to confirm the key configuration and local L1–L6 capabilities.

4. Then call analyze_high_res_image, passing image_path (local absolute path) and task_hint.

5. Prefer the returned merged_answer; the bbox in objects/tile_details can be used for precise localization.

6. For follow-up questions on the same image, just call the same image_path again — the internal three-level cache hits automatically, with no need to manage file_id manually.

HTTP mode example (container/remote harness):

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

After connecting, first call adatile_status (zero API calls) to confirm the key configuration and local capabilities, then call analyze_high_res_image.

Tool: analyze_high_res_image

Returns: merged_answer, objects (best-effort parsing), tile_details (with bbox and file_id), latency_ms, token_usage, upload_stats, route (direct_pass / tile_pipeline).

Common Commands

# 生成测试集 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-Side System Prompt (Template B, Guide 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——必须走本工具，否则细节丢失。

Degradation Behavior (Phase 0)

• L1 corrupted/unsupported format → structured error {stage:"L1", reason:...}, no degradation path

• Small image (≤640,000 pixels) → DirectPass single direct pass

• Files API unavailable → no automatic degradation for the primary scheme yet (Phase 3 implements the all-inline degradation chain)