# RevitMCP

Natural language control of Autodesk Revit through an AI-powered MCP (Model Context Protocol) server. Create walls, rooms, floor plans, dimensions, and more using conversational commands.

## Architecture

```
 Revit 2024/2025/2026
       |
 C# Add-in (RevitMCP_core)     <-- Revit API bridge on port 48884
       |
 Python MCP Server (FastAPI)    <-- AI orchestrator on port 8001
       |
 AI Provider (Hugging Face / Claude / Gemini / LM Studio)
         ↑
    Auto-fallback chain:
    1. Hugging Face Inference API (primary)
    2. LM Studio (local fallback)
    3. Claude/Gemini (cloud fallback)
```

**RevitMCP_core** is a Revit add-in that exposes the Revit API over HTTP. The **Python server** receives natural language queries, detects intent via templates and workflow chains, builds execution plans, and sends commands to Revit through the add-in.

The new **Adaptive Orchestrator** supports multiple LLM providers with automatic fallback:
- **Hugging Face** (primary): Fast inference, 500k+ models, native tool calling
- **LM Studio** (fallback): Local models, privacy, offline capable
- **Claude/Gemini** (fallback): Cloud providers, high capability

**RevitMCP_core** is a Revit add-in that exposes the Revit API over HTTP. The **Python server** receives natural language queries, detects intent via templates and workflow chains, builds execution plans, and sends commands to Revit through the add-in.

## Prerequisites

- **Windows 10/11**
- **Autodesk Revit 2024, 2025, or 2026**
- **Python 3.10 - 3.12** (PyTorch compatibility)
- **.NET SDK 8.0+** (to build the C# add-in)
- **One of:** Hugging Face token (recommended), Claude API key, Google Gemini API key, or LM Studio running locally

## Quick Install

### Option A: Automated (Recommended)

Run PowerShell as Administrator:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```

Flags:
- `-SkipEnhancer` — Skip AI rendering setup (core + brain only)
- `-CPUOnly` — No GPU acceleration
- `-AMD` — Use DirectML instead of CUDA

### Option B: Manual

1. **Build the C# add-in:**
   ```
   dotnet build RevitMCP_core\RevitMCP_core.csproj -c Release
   ```

2. **Create the Revit manifest** at `%APPDATA%\Autodesk\Revit\Addins\2026\RevitMCP.addin`:
   ```xml
   <?xml version="1.0" encoding="utf-8"?>
   <RevitAddIns>
     <AddIn Type="Application">
       <Name>RevitMCP</Name>
       <Assembly>C:\RevitMCP\RevitMCP_core.dll</Assembly>
       <FullClassName>RevitMCP_core.App</FullClassName>
       <ClientId>a1b2c3d4-e5f6-7890-abcd-ef1234567890</ClientId>
       <VendorId>RevitMCP</VendorId>
     </AddIn>
   </RevitAddIns>
   ```

3. **Set up Python environment:**
   ```
   cd server
   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements.txt
   ```

4. **Configure your AI provider** — edit `%APPDATA%\RevitMCP\llm_config.json`:
   
   **Option A: Hugging Face (Recommended - fast, reliable, cost-effective)**
   ```json
   {
     "llm_provider": "huggingface",
     "huggingface": {
       "api_key_env": "HF_TOKEN",
       "model": "Qwen/Qwen2.5-72B-Instruct",
       "provider": "nebius"
     }
   }
   ```
   Set the environment variable: `set HF_TOKEN=hf_your_token`
   Get your token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
   
   **Option B: Claude**
   ```json
   {
     "llm_provider": "claude",
     "claude": { "api_key_env": "ANTHROPIC_API_KEY" }
   }
   ```
   Set the environment variable: `set ANTHROPIC_API_KEY=sk-ant-...`
   
   **Option C: LM Studio (Local)**
   ```json
   {
     "llm_provider": "lmstudio"
   }
   ```
   Start LM Studio with a model loaded on port 1234.

5. **Start the server:**
   ```
   cd server
   python server.py
   ```

6. **Open Revit** — the add-in loads automatically. Click "Start Server" in the RevitMCP settings panel.

## Usage

Once running, send natural language commands through the chat UI in Revit:

| Command | What it does |
|---------|-------------|
| `build a 40x30 house` | Creates a building shell with exterior walls |
| `3 bed 2 bath 35x25` | Generates a full room layout with partitions |
| `add foundation` | Creates foundation walls and footings below grade |
| `dimension everything` | Adds professional 3-tier architectural dimensions |
| `design a house` | Starts an interactive QBD (Question-Based Design) session |

See [REFERENCE.md](REFERENCE.md) for the full list of 280+ tools and templates.

## Configuration

All configuration is via environment variables (with sensible defaults):

| Variable | Default | Description |
|----------|---------|-------------|
| `REVITMCP_REVIT_PORT` | `48884` | Port for the Revit C# add-in HTTP server |
| `REVITMCP_SERVER_PORT` | `8001` | Port for the Python FastAPI server |
| `REVITMCP_LM_STUDIO_PORT` | `1234` | Port for LM Studio (if using local models) |
| `REVITMCP_ENHANCER_PORT` | `5000` | Port for the AI rendering server |
| `REVITMCP_HOST` | `localhost` | Host for all services |
| `REVITMCP_AUTH_TOKEN` | *(empty)* | Shared secret for server authentication (recommended) |
| `REVITMCP_CORS_ORIGINS` | *(empty)* | Additional CORS origins (comma-separated) |
| `HF_TOKEN` | — | Hugging Face API token (recommended) |
| `ANTHROPIC_API_KEY` | — | Claude API key |
| `GOOGLE_API_KEY` | — | Google Gemini API key |

## Project Structure

```
RevitMCP/
  RevitMCP_core/          C# Revit add-in
    App.cs                  Plugin entry point
    McpServer.cs            HTTP listener (port 48884)
    RequestHandler.cs       Route dispatcher (150+ routes)
    UI/                     Settings window (XAML)
  server/                 Python MCP server
    server.py               FastAPI entry point (port 8001)
    config.py               Centralized configuration
    client_orchestrator.py  Intent detection and plan execution
    adaptive_orchestrator.py Multi-provider orchestrator (HF/LM/Cloud)
    hf_orchestrator.py      Hugging Face Inference integration
    templates.py            Pre-built workflow templates
    workflow_chains.py      Multi-phase compound workflows
    qbd_session.py          Question-Based Design sessions
    tools/                  280+ Revit API tool implementations
      geometry_tools.py       Walls, floors, roofs
      annotation_tools.py     Dimensions, grids, sheets
      auto_dimensions.py      Professional dimensioning
      physics_tools.py        Structural/thermal analysis
      family_editor_tools.py  Parametric family creation
      ...
    examples/               Usage examples
      hf_example.py           Hugging Face integration demo
    tests/                  Integration test suite
  scripts/                Installation scripts
    install.ps1             Automated installer
    uninstall.ps1           Clean uninstaller
  docs/                   Documentation
```

## Health Check

```
GET http://localhost:8001/health
```

Returns server status and Revit connectivity.

## Troubleshooting

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.

**Quick checks:**
1. Is Revit running with the add-in loaded?
2. Is the server running? (`python server.py`)
3. Can you reach `http://localhost:8001/health`?
4. Is your AI provider configured? Check `%APPDATA%\RevitMCP\llm_config.json`

## License

Proprietary. All rights reserved.