# mcp-archviz

3D architecture visualization MCP server with stub provider.

**Status:** Phase 4 MVP — Stub provider with placeholder URLs (no real 3D rendering)

## Overview

mcp-archviz provides tools for 3D visualization of workspace layouts from mcp-floorplans.

**Current implementation:** STUB provider
- All URLs are placeholder (`stub:///`) indicating no real rendering occurs
- API matches future real providers (Roomify, Unreal Engine 5)
- Fully testable without external 3D rendering service
- Ready for Phase 5+ integration with real providers

## Architecture

```
server.py
  ├─ MCP server with 3 tools
  ├─ generate_3d_model — 3D model from layout
  ├─ render_perspective — Perspective view from angle
  └─ export_model — Export in multiple formats

test_archviz.py
  └─ 15+ unit tests, all deterministic
```

## Quick Start

```bash
# Install dependencies
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run tests
pytest test_archviz.py -v

# Start MCP server (stdio mode for Claude)
python server.py
```

## MCP Tools

### generate_3d_model

Generate 3D model from floorplan layout.

**Input:**
```json
{
  "layout": {
    "variant_id": "balanced-001",
    "zones": [...],
    "metrics": {
      "total_sqm": 200,
      "workstations": 12,
      "meeting_rooms": 1,
      "collaboration_zones_pct": 25
    }
  },
  "style": "contemporary",
  "brand_colors": {
    "primary": "#1a73e8",
    "secondary": "#4285f4"
  }
}
```

**Output:** Model metadata
- `model_id` — Unique model identifier
- `3d_model_url` — STUB URL to 3D model (GLB format)
- `preview_image_url` — STUB URL to preview image
- `dimensions` — Calculated space dimensions
- `zones` — Zone objects with textures and materials
- `brand_integration` — Color accents from brand DNA
- `interactive_features` — Planned features for real implementation
- `formats_available` — Export formats

### render_perspective

Generate perspective view from specific angle.

**Input:**
```json
{
  "model_id": "model-abc123",
  "angle_degrees": 45,
  "height_m": 1.6
}
```

**Output:** Rendered view metadata
- `render_id` — Unique render identifier
- `rendered_image_url` — STUB URL to rendered image
- `camera` — Camera position and angle
- `available_angles` — Standard view angles [0, 45, 90, ...]

### export_model

Export 3D model in requested format.

**Input:**
```json
{
  "model_id": "model-abc123",
  "format": "glb"
}
```

**Supported formats:**
- `glb` — Web-ready 3D (Three.js, Babylon.js)
- `gltf` — Portable 3D format
- `usdz` — Apple ARKit compatible
- `usd` — Unreal Engine 5 compatible
- `stl` — 3D printing format
- `obj` — Blender/Maya compatible

**Output:** Export metadata
- `download_url` — STUB URL to exported file
- `file_size_mb_estimate` — Estimated file size
- `supported_applications` — Applications that can open format
- `compression` — Compression method used

## Integration Pattern

Workflow: mcp-floorplans → mcp-archviz

```
1. Generate layout (mcp-floorplans)
   └─ returns zones, metrics, stub floorplan URLs

2. Generate 3D model (mcp-archviz)
   └─ receives layout
   └─ returns model_id, stub 3D URLs

3. Render perspective (mcp-archviz)
   └─ receives model_id, angle
   └─ returns stub rendered image URL

4. Export (mcp-archviz)
   └─ receives model_id, format
   └─ returns stub export URL
```

## Stub Provider Details

**What "STUB provider" means:**

All URLs returned follow the pattern `stub:///path/to/resource`:

```
stub:///models/{model_id}/model.glb
stub:///renders/{render_id}/perspective-45deg.png
stub:///exports/{export_id}/model.glb
```

**Why stubs?**

1. **No external dependency** — Don't require 3D rendering service API key
2. **Deterministic** — Same input always produces same output
3. **Testable** — Can verify logic without network calls
4. **Honest** — Clear indicator that images/models don't actually exist
5. **Autonomous** — Agent can run without user provisioning real infrastructure

**When real 3D is needed:**

Phase 5+ will integrate:
- Roomify API (commercial 3D rendering)
- Unreal Engine 5 (heavy duty rendering)
- Blender API (open-source alternative)
- Three.js (web-based visualization)

## Phase 4 Status

✅ **COMPLETED:**
- Stub 3D provider implementation
- All 3 tools with full signatures
- Metadata generation for future real implementation
- 15+ unit tests (all passing)
- Integration tests with mcp-floorplans output
- Style support (minimal, contemporary, luxury)
- Brand color integration
- Multi-format export support

⏸️ **DEFERRED (Phase 5+):**
- Real 3D model generation
- Real perspective rendering
- Real texture/material application
- Virtual walkthroughs
- AR/VR export
- Animation rigs

## Example Response

**Model generation response:**

```json
{
  "status": "success",
  "provider": "STUB:archviz",
  "model_id": "model-abc12345",
  "layout_id": "balanced-001",
  "style": "contemporary",
  "3d_model_url": "stub:///models/model-abc12345/model.glb",
  "preview_image_url": "stub:///models/model-abc12345/preview.png",
  "zones": [
    {
      "zone_name": "Open Space",
      "zone_type": "open-space",
      "3d_object_url": "stub:///zones/open-space.glb",
      "texture_url": "stub:///textures/contemporary_open-space.png"
    }
  ],
  "brand_integration": {
    "primary_color_accent": "#1a73e8",
    "signage": "Brand logos and wayfinding (stub)"
  },
  "notes": "STUB provider — real 3D rendering deferred to Phase 5+. All URLs are placeholder (`stub:///`)."
}
```

## Testing

```bash
# Run all tests
pytest test_archviz.py -v

# Test categories:
# - Model generation (all styles, with/without brand colors)
# - Perspective rendering (all angles, custom heights)
# - Model export (all formats)
# - Stub markers (all URLs should contain "stub:///")
# - Integration workflow (floorplan → model → render → export)
# - Error handling (missing parameters)
```

## Architecture Decisions

1. **Stub over mock:** Placeholder URLs clearly indicate test/placeholder state
2. **Full metadata:** Each response includes real metadata (dimensions, materials, etc.)
3. **No 3D libs:** Deliberately not using Three.js, Babylon, or Blender to avoid false impression of real rendering
4. **Type-safe:** All inputs/outputs validated and documented
5. **Async-ready:** All tools are async for scaling in production

## Phase 3 Integration

Works alongside:
- **mcp-interior** — Interior redesign of existing spaces
- **mcp-floorplans** — Space layout calculation (provides input)
- **WorkspaceAgent** — Orchestrates all three services

## References

- [mcp-floorplans](../mcp-floorplans/) — Floorplan generation
- [mcp-interior](../mcp-interior/) — Interior rendering
- [WorkspaceAgent](./.virtus_factory/agents/WorkspaceAgent.md) — Orchestrator

## License

Proprietary — Virtus Agents