mcp-floorplans

Workspace floorplan generation MCP server with deterministic space layout calculation.

Status: Phase 4 MVP — Deterministic space layout engine (no external APIs)

Features

• Deterministic space layout calculation — No API dependencies, pure Python logic
• 3 layout variants per brief — Balanced, Collaboration-heavy, Focus-intensive
• Detailed metrics — Workstations, meeting rooms, collaboration %, window distances
• Zone adjacency analysis — Functional recommendations for zone placement
• Space brief validation — Feasibility checking with recommendations

Architecture

space_calculator.py
  ├─ SpaceCalculator class — Core calculation engine
  ├─ Zone, LayoutVariant, SpaceMetrics dataclasses
  └─ generate_space_layouts_json() — Main entry point

server.py
  ├─ MCP server with 3 tools
  ├─ generate_space_layouts — Layout generation
  ├─ analyze_zone_adjacencies — Adjacency rules
  └─ validate_space_brief — Feasibility validation

test_space_calculator.py
  └─ 15+ unit tests, 100% deterministic

Quick Start

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

# Run tests
pytest test_space_calculator.py -v

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

MCP Tools

generate_space_layouts

Generate 3 workspace layout variants from brief.

Input:

{
  "surface_sqm": 200,
  "headcount": 20,
  "zone_types": ["open-space", "meeting", "quiet-zone"],
  "collaboration_style": "medium_collab",
  "project_id": "test-proj-1"
}

Output: JSON with 3 layout variants, each containing:

• Zones with dimensions and occupancy
• Metrics (workstations, meeting rooms, collaboration %, window distances)
• Stub floorplan URL (stub:///floorplans/...)
• Design notes

analyze_zone_adjacencies

Get functional adjacency recommendations for zone types.

Input:

{
  "zone_types": ["open-space", "meeting", "quiet-zone"]
}

validate_space_brief

Check feasibility and get recommendations.

Input:

{
  "surface_sqm": 200,
  "headcount": 20,
  "zone_types": ["open-space", "meeting"]
}

Calculation Logic

Space Sizing

Standard guidelines per zone type:

• Open-space: 5–8.5 sqm per workstation (hotdesking to dedicated)
• Quiet-zone: 4 sqm per person
• Meeting: 2.5 sqm per person
• Phone-booth: 2 sqm per booth (1 person)
• Break-room: 1 sqm per person

Collaboration Percentages

• high_collab: 40% meeting + break + phone zones
• medium_collab: 30%
• low_collab: 20%

Circulation

15% of total area reserved for corridors, stairs, etc.

Metrics Provided

For each variant:

• total_sqm — Total workspace area
• workstations — Number of workstations
• meeting_rooms — Number of dedicated meeting rooms
• phone_booths — Number of private call booths
• quiet_zones — Number of focus areas
• break_rooms — Number of break/social areas
• collaboration_zones_pct — % of space for collaborative work
• average_sqm_per_person — Density metric
• window_distance_avg — Average distance to windows (meters)
• natural_light_zones_pct — % of space with potential window access

Example Usage

from space_calculator import generate_space_layouts_json

# Generate layouts for 200 sqm, 20 people
json_output = generate_space_layouts_json(
    surface_sqm=200,
    headcount=20,
    zone_types=["open-space", "meeting", "quiet-zone", "phone-booth", "break-room"],
    project_id="my-project"
)

# Parse output
import json
data = json.loads(json_output)

# Access first variant
variant = data["variants"][0]
print(f"Variant: {variant['layout_name']}")
print(f"Workstations: {variant['metrics']['workstations']}")
print(f"Collaboration: {variant['metrics']['collaboration_zones_pct']}%")

Testing

All calculation logic is deterministic and fully tested:

# Run all tests
pytest test_space_calculator.py -v

# Test categories:
# - Calculator initialization and configuration
# - Usable area calculation
# - Zone distribution across types
# - Metrics calculation accuracy
# - Variant generation (3 variants per brief)
# - JSON output format validation
# - Edge cases (small/large spaces)
# - Determinism (same input → same output)

Phase 3 Integration (mcp-interior)

mcp-floorplans works alongside:

• mcp-interior — Interior redesign of existing spaces (Decor8 API, stub provider)
• mcp-archviz — 3D visualization of layouts (stub provider)
• WorkspaceAgent — Orchestrates all three services

Phase 4 Status

✅ COMPLETED:

• Space calculator implementation (deterministic, no API calls)
• 3 layout variants per brief
• Metrics calculation
• Zone adjacency analysis
• Space brief validation
• 15+ unit tests (all passing)
• Full test coverage of calculation logic

⏸️ DEFERRED (Phase 5+):

• Real floorplan image generation (requires image service)
• 3D model generation (via mcp-archviz)
• CAD export (SVG/DXF format)
• Furniture library integration
• Cost estimation (fit-out budgeting)

Architecture Decisions

1. Deterministic (no APIs): Core calculation is pure Python, testable, reproducible
2. Stub floorplans: stub:///floorplans/... URLs indicate placeholder images
3. Dataclasses: Type-safe zone/layout/metrics models
4. No external services: Calculation doesn't depend on CasaAI, HWFC, Roomify, etc.
5. MCP standard tools: Integrates with Claude agents via MCP protocol

License

Proprietary — Virtus Agents

See Also

• Phase 3: mcp-interior
• Phase 4: mcp-archviz
• Orchestrator: WorkspaceAgent