AdaTile-MCP v1.0

Capa de preprocesamiento de adaptación y división de imágenes de alta resolución (MCP), modelo objetivo DeepSeek deepseek-v4-flash-vision-exp. Según el plan de seis semanas de la Guía de construcción del proyecto AdaTile-MCP (v1.2), se completaron todas las fases 0–5. El progreso y los datos medidos se encuentran en STATE.md; la lista actual de problemas detectados está en KNOWN_ISSUES.md.

Pipeline de seis capas (pipeline_v1)

L1 Canal rápido (magic bytes/decodificación perezosa/redimensionado por exceso de límite/paso directo de imágenes pequeñas) → L2 Saliencia (residuo espectral por CPU por defecto, U²-Netp opcional, degradación por timeout del Watchdog) → L3 División adaptativa (dominios conexos/preasignación de presupuesto/selección de bloques contiguos/ruta fina para documentos) → L4 Ensamblado y subida (codificación→subida en pipeline a nivel de tile, caché de tres niveles, seis verificaciones duras de cumplimiento, cadena de degradación) → L5 Invocación en streaming (salida forzada de json_object, TTFT con doble métrica, reintentos y garantía global mínima) → L6 Fusión reglada (IOU>0.3 misma etiqueta y fusión de bbox).

Related MCP server: image-tiler-mcp-server

Descripción del comportamiento de degradación

Línea base de calidad y latencia (medida, ver experiments/*.json)

• p95 del primer preprocesamiento 1116ms (incluye subida real) / 134ms con acierto de caché; TTFT 847ms/613ms; 10 concurrencias 100% de éxito

• Comparación de cuatro esquemas y ablación de la Fase 5: experiments/phase5_results.json

Requisitos del entorno

• Python 3.11+ (el .venv del proyecto es 3.13)

• Variable de entorno DEEPSEEK_API_KEY (solicitar en la plataforma DeepSeek)

• Activar venv en Windows/Git Bash: source .venv/Scripts/activate

• Instalación del entorno en una máquina nueva con un solo comando: setup.bat (Windows) / setup.sh (macOS/Linux), ver sección siguiente

Integración desde cero (máquina nueva / cualquier agente)

El .venv y las claves no viajan con el repositorio; en una máquina nueva solo se necesitan 5 pasos:

1. Instalar Python 3.11+ (en Windows, marcar "Add to PATH" durante la instalación).

2. Obtener el código: git clone https://github.com/Mutton-hub/adatile-mcp.git (o copiar este directorio, sin necesidad de incluir .venv).

3. Instalar el entorno: ejecutar setup.bat (Windows) o ./setup.sh (macOS/Linux) en la raíz del proyecto — crea automáticamente .venv e instala todas las dependencias de requirements.txt.

4. Configurar la clave: establecer la variable de entorno DEEPSEEK_API_KEY, o copiar .env.example como .env y rellenarla (elegir una de las dos opciones; .env ya está excluido por .gitignore).

5. Registrar MCP: según la tabla siguiente, apunta la configuración de tu agente a run.bat (Windows) / run.sh (Unix) en la ruta absoluta del repositorio local; tras reiniciar la sesión, llama primero a adatile_status para la autocomprobación.

Al conectar varios agentes en la misma máquina, solo hay que repetir el paso 5 (cada cliente se configura por separado); el entorno y la clave se comparten.

Registro MCP — adaptable a cualquier agente/harness local

El servidor es un MCP estándar (stdio por defecto / http / sse opcional); los siguientes clientes pueden conectarse. Orden de resolución de la clave: variable de entorno DEEPSEEK_API_KEY → archivo .env en la raíz del proyecto (basta con copiar .env.example como .env y rellenarlo; adecuado para clientes donde es difícil inyectar variables de entorno).

Forma general (todos los clientes compatibles con stdio MCP). Reemplaza <repo> por la ruta absoluta real tras clonar/extraer el repositorio (si la ruta contiene caracteres chinos o espacios, es obligatorio usar ruta absoluta):

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

El lanzador run.bat localiza automáticamente el venv (en macOS/Linux usar <repo>/run.sh). También se puede apuntar directamente a <repo>/.venv/Scripts/python.exe + server.py.

Ubicación de configuración por cliente:

Ejemplo de configuración a nivel de proyecto en ZCode (<repo>/.zcode/config.json, se comparte con el equipo tras clonar):

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

Flujo de uso tras la integración (cualquier agente/harness)

1. Configurar la clave: establecer la variable de entorno DEEPSEEK_API_KEY, o copiar .env.example como <repo>/.env y rellenarla (.env ya está excluido por .gitignore y no entrará en el control de versiones; adatile_status permite confirmar si la clave está lista).

2. Registrar el servidor MCP (tabla anterior) y reiniciar la sesión del cliente.

3. Llamar primero a adatile_status (cero llamadas a la API, cero coste) para confirmar la configuración de la clave y las capacidades locales de L1–L6.

4. Luego llamar a analyze_high_res_image, pasando image_path (ruta absoluta local) y task_hint.

5. Usar preferentemente el merged_answer devuelto; los bbox en objects/tile_details sirven para localización precisa.

6. Para preguntas de seguimiento sobre la misma imagen, basta con volver a llamar con el mismo image_path — la caché interna de tres niveles se activa automáticamente, sin necesidad de gestionar file_id manualmente.

Ejemplo en modo HTTP (contenedor/harness remoto):

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

Tras la integración, llamar primero a adatile_status (cero llamadas a la API) para confirmar la configuración de la clave y las capacidades locales, y luego llamar a analyze_high_res_image.

Herramienta: analyze_high_res_image

Devuelve: merged_answer, objects (parseo con mejor esfuerzo), tile_details (incluye bbox y file_id), latency_ms, token_usage, upload_stats, route (direct_pass / tile_pipeline).

Comandos habituales

# 生成测试集 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 del lado del agente (plantilla B, guía 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——必须走本工具，否则细节丢失。

Comportamiento de degradación (Fase 0)

• L1 archivo dañado/formato no soportado → error estructurado {stage:"L1", reason:...}, sin ruta de degradación

• Imagen pequeña (≤640 000 píxeles) → DirectPass con subida única directa

• Files API no disponible → el esquema principal no tiene degradación automática por ahora (la Fase 3 implementa la cadena de degradación totalmente en línea)