# 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.

```powershell
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`](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:

```json
{
  "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`](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](https://github.com/ZiYang-xie/WorldGen): panorama 360°, depth, mesh/3DGS.
- [Infinigen](https://github.com/princeton-vl/infinigen): procedural seed, camera và
  ground-truth buffers.
- [HY-World 2.0](https://github.com/Tencent-Hunyuan/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

```powershell
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.