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

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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 — Floorplan generation
• mcp-interior — Interior rendering
• WorkspaceAgent — Orchestrator

License

Proprietary — Virtus Agents