# EraCore Revit MCP

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Architecture](https://img.shields.io/badge/architecture-hexagonal-512BD4.svg)](docs/architecture/README.md)
[![MCP](https://img.shields.io/badge/protocol-MCP-000000.svg)](https://modelcontextprotocol.io/)

**EraCore Revit MCP** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects LLM assistants (Cursor, Claude Desktop, and others) to **Autodesk Revit** BIM models. It exposes typed tools for reading model metadata, listing elements, creating geometry, batch-updating parameters, and exporting schedules.

Built with **Hexagonal Architecture**, **Domain-Driven Design**, and a **Walking Skeleton** delivery approach.

| | |
|---|---|
| **Version** | 1.0.0 |
| **Revit** | 2024–2027 (pyRevit bridge tested on 2027) |
| **Python** | 3.12+ |
| **Platform** | Windows (Revit integration); fake mode runs anywhere |

---

## Features

| Capability | Fake mode | pyRevit mode |
|------------|:---------:|:------------:|
| MCP tools (7) — ping, model info, list/get elements | ✅ | ✅ |
| Create walls with Revit transactions | ✅ | ✅ |
| Batch parameter updates (≤100 per batch) | ✅ | ✅ |
| Export ViewSchedule to CSV | ✅ | ✅ |
| Real Revit document read/write via HTTP bridge | — | ✅ |
| Unit tests without Revit installed | ✅ | — |

---

## Quick Start

### Prerequisites

- **Python 3.12+**
- **Windows 10/11** (required for live Revit integration)
- **Autodesk Revit 2024+** and **[pyRevit](https://github.com/pyrevitlabs/pyRevit)** (optional; fake mode needs neither)

### Install

```powershell
git clone <repository-url> eracore
cd eracore

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Copy-Item .env.example .env
```

### Run the Walking Skeleton (fake mode — no Revit)

```powershell
# Default: REVIT_MCP_REVIT_ADAPTER_MODE=fake in .env
python -m revit_mcp demo
```

Expected output ends with:

```text
WALKING SKELETON OK — walls: 2 → 3
Report generated: reports/demo_walls.csv
```

### Run with real Revit (pyRevit)

```powershell
# 1. Install pyRevit extension and dependencies
.\scripts\install_revit_deps.ps1

# 2. Start Revit with the bridge
.\scripts\start_revit_with_bridge.ps1

# 3. Open any .rvt model, then set adapter mode
#    REVIT_MCP_REVIT_ADAPTER_MODE=pyrevit  in .env

python -m revit_mcp demo
python -m revit_mcp mcp
```

See [Revit & pyRevit setup](docs/guides/revit-pyrevit-setup.md) for full instructions.

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `ping()` | Health check — server version and Revit connectivity |
| `get_model_info(include_stats?)` | Project metadata, levels, optional category statistics |
| `list_elements(...)` | Filtered, paginated element list |
| `get_element(element_id)` | Single element with parameters |
| `create_wall(...)` | Create a wall between two XYZ points (mm) |
| `batch_update_parameters(...)` | Bulk parameter updates with per-item error reporting |
| `export_schedule(...)` | Export a ViewSchedule to CSV |

Full contracts: [Software Design Document](docs/specs/SDD_v1.md) · [MCP server source](src/revit_mcp/adapters/primary/mcp/server.py)

---

## CLI Commands

```powershell
python -m revit_mcp mcp      # Start MCP server (stdio transport)
python -m revit_mcp demo     # Run end-to-end Walking Skeleton
python -m revit_mcp config   # Print active configuration
python -m revit_mcp help     # Show help
```

---

## Project Structure

```text
eracore/
├── src/revit_mcp/              # Python MCP server (hexagonal layers)
│   ├── domain/                 # Entities, value objects, ports
│   ├── application/            # Use cases and DTOs
│   ├── adapters/
│   │   ├── primary/mcp/        # MCP inbound adapter
│   │   └── secondary/pyrevit_adapter/  # Revit bridge outbound adapters
│   └── config/                 # Settings and DI container
├── pyrevit_extension/          # EraCoreMCP pyRevit extension (HTTP bridge)
├── scripts/                    # Install and Revit launch scripts
├── tests/unit/                 # Use-case tests (fake adapter)
└── docs/                       # Architecture (C4) and guides
```

---

## Configuration

Environment variables use the `REVIT_MCP_` prefix. Copy [`.env.example`](.env.example) to `.env`.

| Variable | Default | Description |
|----------|---------|-------------|
| `REVIT_MCP_REVIT_ADAPTER_MODE` | `fake` | `fake` or `pyrevit` |
| `REVIT_MCP_REVIT_BRIDGE_HOST` | `127.0.0.1` | HTTP bridge host |
| `REVIT_MCP_REVIT_BRIDGE_PORT` | `47200` | HTTP bridge port |
| `REVIT_MCP_REVIT_API_TIMEOUT_SEC` | `30` | Bridge RPC timeout (increase for slow models) |
| `REVIT_MCP_LOG_LEVEL` | `INFO` | Logging level |

---

## Development

```powershell
# Unit tests (≥70% coverage enforced)
pytest tests/unit -q

# Linting and types
ruff check src tests
ruff format src tests
mypy -p src.revit_mcp

# Architecture boundary checks
lint-imports
```

Docker (fake mode only — Revit cannot run inside Linux containers):

```powershell
docker compose --profile ci run --rm tests
docker compose --profile demo run --rm demo
```

---

## MCP Client Integration

### Cursor

Add to MCP settings:

```json
{
  "mcpServers": {
    "eracore-revit": {
      "command": "python",
      "args": ["-m", "revit_mcp", "mcp"],
      "cwd": "F:\\Teach\\eracore",
      "env": {
        "REVIT_MCP_REVIT_ADAPTER_MODE": "pyrevit"
      }
    }
  }
}
```

More clients: [MCP client configuration guide](docs/guides/mcp-client-configuration.md).

---

## Documentation

| Document | Description |
|----------|-------------|
| [Documentation index](docs/README.md) | Entry point for all docs |
| [C4 Architecture](docs/architecture/README.md) | Context → Container → Component → Code |
| [Getting started](docs/guides/getting-started.md) | Detailed setup walkthrough |
| [Revit integration](docs/guides/revit-pyrevit-setup.md) | pyRevit bridge and extension |
| [SDD v1](docs/specs/SDD_v1.md) | Use cases, MCP contracts, acceptance criteria |
| [PRINCIPLES.md](PRINCIPLES.md) | Engineering and architecture rules |

---

## Architecture at a Glance

```text
 LLM Client (Cursor / Claude)
        │  MCP stdio JSON-RPC
        ▼
 EraCore MCP Server (Python)
        │  Use Cases → Ports
        ▼
 Fake adapter (in-memory)  OR  pyRevit HTTP Bridge (:47200)
                                      │
                                      ▼
                              Autodesk Revit 2027 + .rvt model
```

Full C4 diagrams: [System Context](docs/architecture/01-system-context.md) · [Containers](docs/architecture/02-containers.md) · [Components](docs/architecture/03-components.md)

---

## License

MIT — see [LICENSE](LICENSE).

---

**EraCore Team** · BIM × AI · 2026