AdaTile-MCP v1.0

Hochauflösende Bild-adaptive Zerteilungs-Vorverarbeitungsschicht (MCP), Zielmodell DeepSeek deepseek-v4-flash-vision-exp. Gemäß dem „AdaTile-MCP-Projektaufbaurichtlinie (v1.2)"-Sechs-Wochen-Plan wurden alle Phasen 0–5 abgeschlossen. Fortschritt und gemessene Daten siehe STATE.md, die aktuell gefundene Problemliste siehe KNOWN_ISSUES.md.

Sechs-Schichten-Pipeline (pipeline_v1)

L1 Schnellkanal (Magic Bytes/träges Dekodieren/Überlimit-Downsampling/Kleinbild-Direktübertragung) → L2 Salienz (Spektralresiduum CPU standardmäßig, U²-Netp optional, Watchdog-Timeout-Degradierung) → L3 Adaptive Zerteilung (Zusammenhangskomponenten/Budget-Vorabzuweisung/Kontinuierliche-Block-Auswahl/Dokument-Fine- Pfad) → L4 Assemblierung und Upload (Tile-Ebene pipelineisiertes Encoding→Upload, dreistufiger Cache, sechs Compliance-Hartprüfungen, Degradierungskette) → L5 Streaming-Aufruf (json_object erzwungene Ausgabe, TTFT-Doppelmessung, Wiederholung und globale Absicherung) → L6 Regelbasierte Zusammenführung (IOU>0,3 gleiche Labels und bbox).

Related MCP server: Vision MCP

Erläuterung des Degradierungsverhaltens

Qualitäts- und Latenz-Baseline (gemessen, Details siehe experiments/*.json)

• Erste Vorverarbeitung p95 1116ms (inkl. echtem Upload) / Cache-Treffer 134ms; TTFT 847ms/613ms; 10 gleichzeitige Anfragen 100% Erfolg

• Phase-5-Vier-Szenarien-Vergleich und Ablation: experiments/phase5_results.json

Umgebungsanforderungen

• Python 3.11+ (.venv im Projekt ist 3.13)

• Umgebungsvariable DEEPSEEK_API_KEY (über DeepSeek-Plattform beantragen)

• venv unter Windows/Git Bash aktivieren: source .venv/Scripts/activate

• Ein-Klick-Umgebungseinrichtung auf neuer Maschine: setup.bat (Windows) / setup.sh (macOS/Linux), siehe nächster Abschnitt

Integration von Grund auf (neue Maschine / beliebiger Agent)

.venv und Schlüssel werden nicht mit dem Repository verteilt, auf einer neuen Maschine sind nur 5 Schritte nötig:

1. Python 3.11+ installieren (bei Windows-Installation „Add to PATH" anhaken).

2. Code abrufen: git clone https://github.com/Mutton-hub/adatile-mcp.git (oder dieses Verzeichnis kopieren, ohne .venv).

3. Umgebung einrichten: Im Projektstamm setup.bat (Windows) oder ./setup.sh (macOS/Linux) ausführen – erstellt automatisch .venv und installiert alle Abhängigkeiten aus requirements.txt.

4. Key konfigurieren: Umgebungsvariable DEEPSEEK_API_KEY setzen oder .env.example als .env kopieren und ausfüllen (eines von beiden; .env ist durch .gitignore ausgeschlossen).

5. MCP registrieren: Gemäß der Tabelle unten die Agent-Konfiguration auf run.bat (Windows) / run.sh (Unix) im absoluten Pfad des lokalen Repositorys verweisen, nach Neustart der Sitzung zuerst adatile_status zur Selbstprüfung aufrufen.

Beim Anbinden mehrerer Agents auf derselben Maschine muss nur Schritt 5 wiederholt werden (jeder Client konfiguriert selbst), Umgebung und Key werden gemeinsam genutzt.

MCP-Registrierung – Anpassung an beliebige lokale Agents/Harnesses

Der Server ist ein Standard-MCP (stdio standardmäßig / http / sse optional), die folgenden Clients können alle angebunden werden. Key-Auflösungsreihenfolge: Umgebungsvariable DEEPSEEK_API_KEY → .env-Datei im Projektstamm (.env.example als .env kopieren und ausfüllen, geeignet für Clients, in die schwer Umgebungsvariablen injiziert werden können).

Allgemeine Form (alle Clients, die stdio-MCP unterstützen). <repo> durch den tatsächlichen absoluten Pfad nach Klonen/Checkout des Repositorys ersetzen (bei Pfaden mit chinesischen Zeichen oder Leerzeichen muss der absolute Pfad verwendet werden):

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

Der run.bat-Launcher lokalisiert das venv automatisch (macOS/Linux: <repo>/run.sh). Alternativ kann direkt auf <repo>/.venv/Scripts/python.exe + server.py verwiesen werden.

Ablageorte der einzelnen Clients:

ZCode-Projektebene-Konfigurationsbeispiel (<repo>/.zcode/config.json, nach dem Klonen mit dem Team geteilt):

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

Nutzungsablauf nach der Integration (beliebiger Agent/Harness)

1. Key konfigurieren: Umgebungsvariable DEEPSEEK_API_KEY setzen oder .env.example als <repo>/.env kopieren und ausfüllen (.env ist durch .gitignore ausgeschlossen und gelangt nicht in die Versionskontrolle; adatile_status kann bestätigen, ob der Key bereit ist).

2. MCP-Server registrieren (siehe Tabelle oben) und Client-Sitzung neu starten.

3. Zuerst adatile_status aufrufen (null API-Aufrufe, null Kosten), um Key-Konfiguration und lokale L1–L6-Fähigkeiten zu bestätigen.

4. Dann analyze_high_res_image aufrufen und image_path (lokaler absoluter Pfad) sowie task_hint übergeben.

5. Bevorzugt die zurückgegebene merged_answer verwenden; die bbox in objects/tile_details können zur präzisen Lokalisierung genutzt werden.

6. Für Nachfragen zum selben Bild einfach denselben image_path erneut aufrufen – der interne dreistufige Cache greift automatisch, keine manuelle Verwaltung von file_id nötig.

HTTP-Modus-Beispiel (Container/Remote-Harness):

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

Nach der Integration zuerst adatile_status aufrufen (null API-Aufrufe), um Key-Konfiguration und lokale Fähigkeiten zu bestätigen, dann analyze_high_res_image aufrufen.

Tool: analyze_high_res_image

Rückgabe: merged_answer, objects (bestmögliche Analyse), tile_details (mit bbox und file_id), latency_ms, token_usage, upload_stats, route (direct_pass / tile_pipeline).

Häufige Befehle

# 生成测试集 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

System-Prompt auf Agent-Seite (Vorlage B, Richtlinie 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——必须走本工具，否则细节丢失。

Degradierungsverhalten (Phase 0)

• L1 beschädigt/nicht unterstütztes Format → strukturierter Fehler {stage:"L1", reason:...}, kein Degradierungspfad

• Kleines Bild (≤640.000 Pixel) → DirectPass einmalige Direktübertragung

• Files-API nicht verfügbar → Hauptschema hat derzeit keine automatische Degradierung (Phase 3 implementiert vollständige Inline-Degradierungskette)