Animal Map Vision MCP

MCP local cho Google Antigravity và Gemini 3.6 Flash kiểm tra map Anima Engine bằng hai lớp bằng chứng:

• Gemini nhận ảnh viewport thật qua MCP image content để nhìn lỗi hình ảnh.
• Validator xác định kiểm tra geometry, navigation, panorama/alignment và độ hợp lý loài–biome–khí hậu–môi trường.

Server chỉ đọc file bên trong ANIMAL_MAP_ROOT, chặn traversal/symlink thoát root và không có tool sửa hoặc xóa file.

Tool

Tool	Chức năng
discover_map_artifacts	Tìm screenshot, manifest, panorama, depth/normal, camera, navmesh và mesh/3DGS
inspect_map_views	Gửi tối đa 8 ảnh PNG/JPEG/WebP trực tiếp cho Gemini
validate_map_manifest	Chạy quality gate geometry, navigation, pipeline và ecology
prepare_team_review	Tạo brief chuyên trách cho /teamwork-preview

Cài vào Antigravity

Yêu cầu Node.js 20 trở lên.

git clone https://github.com/DuongNAD/mcp-vision.git
cd mcp-vision
npm ci
npm run setup:antigravity -- --project "D:\Projects\Anima-Engine"
npm run doctor -- --project "D:\Projects\Anima-Engine"

Không copy cấu hình từ máy khác. setup:antigravity tự tạo đường dẫn tuyệt đối đúng cho máy hiện tại, merge .agents/mcp_config.json, cài skill và thêm workflow bắt buộc vào AGENTS.md. Có thể chạy lại lệnh sau khi di chuyển repository.

Khi doctor trả "ready": true:

1. Tạo/mở Antigravity Project chứa cả Anima-Engine và repo MCP.
2. Gõ /mcp, reload và kiểm tra animal-map-vision connected.
3. Chọn Gemini 3.6 Flash.
4. Gõ: Use animal-map-review and prepare a map team review.

Hướng dẫn đầy đủ cho Git, máy mới và kiểm tra agent nằm tại docs/ANTIGRAVITY_SETUP.md.

Vì sao Antigravity biết dùng?

Installer tạo ba lớp:

1. .agents/mcp_config.json để Antigravity khởi động MCP.
2. .agents/skills/animal-map-review/SKILL.md để model tự kích hoạt workflow cho nhiệm vụ map, biome, ecology, terrain, water, navigation và lighting.
3. AGENTS.md bắt buộc agent gọi MCP trước khi xác nhận map hoàn tất.

Ngoài ra MCP tự công bố server instructions, mô tả tool và prompt animal-map-team-review. Lệnh doctor bắt tay thật qua stdio và kiểm tra đủ tool/prompt.

Chuẩn bị map

Copy examples/anima-engine.manifest.json thành Anima-Engine/animal-map.manifest.json, rồi nối nó với exporter thật.

Entity sinh học cần:

{
  "species": "emperor_penguin",
  "biomeId": "polar-coast",
  "environment": {
    "medium": "saltwater",
    "submerged": true
  }
}

Loài riêng của dự án khai báo thêm ecology.allowedBiomes, allowedMedia và khoảng temperatureC. Schema đầy đủ ở schemas/animal-map-manifest.schema.json.

Nên xuất các camera cố định:

• overview.png
• navigation.png
• collision.png
• lighting.png
• spawn.png
• water.png
• biome-transition.png
• ecosystem.png

Giữ seed, camera pose, prompt và export settings giống nhau giữa các iteration.

Teamwork Preview

Chọn Gemini 3.6 Flash, gõ /teamwork-preview, rồi dùng docs/TEAMWORK_PROMPT.md. Các workstream:

• Geometry & Collision
• Navigation & Gameplay
• Ecology & World Coherence
• Visual & Lighting
• Integrator

Teamwork Preview dùng quota lớn; review theo từng biome/chunk thay vì giao toàn bộ lục địa trong một lượt.

Cơ sở thiết kế

• WorldGen: panorama 360°, depth, mesh/3DGS.
• Infinigen: procedural seed, camera và ground-truth buffers.
• HY-World 2.0: panorama, obstacle-aware trajectory, world expansion và reconstruction alignment.

MCP không sao chép hoặc chạy các model nặng này; nó áp dụng quality gate phù hợp cho Three.js/React Three Fiber và Rust ECS của Anima Engine.

Phát triển

npm run check
npm run ci
npm run inspect

• check: build và chạy toàn bộ test.
• ci: build, test và audit production dependencies.
• inspect: mở MCP Inspector.

Giới hạn

• MCP nhìn ảnh đã capture; chưa tự điều khiển camera trong ứng dụng.
• Manifest cần exporter cập nhật để phản ánh scene thật.
• Navigation topology không thay thế kiểm tra slope/clearance bằng dữ liệu hoặc ảnh debug.
• Server hiện dùng stdio local. Remote deployment cần Streamable HTTP và authentication.