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 선택)이며, 아래 클라이언트 모두 연동 가능. 키 해석 순서: 환경 변수 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. 키 구성: 환경 변수 DEEPSEEK_API_KEY 설정, 또는 .env.example을 <repo>/.env로 복사하여 입력 (.env는 .gitignore에 제외되어 버전 관리에 포함되지 않음; adatile_status로 키 준비 여부 확인 가능).

2. MCP 서버 등록(위 표) 후 클라이언트 세션 재시작.

3. 먼저 adatile_status 호출(API 호출 0회, 비용 0)로 키 구성과 로컬 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 호출 0회)로 키 구성과 로컬 기능을 확인한 뒤, 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 단일 직접 전송

• Files API 사용 불가 → 주요 방안에 자동 다운그레이드 없음(Phase 3에서 전체 인라인 다운그레이드 체인 구현)