Skip to content

Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.

feat: Implement comprehensive build, package, and install scripts with CI workflow and updated documentation.

A. Sam Mohammad3eb7cdcf1302
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
new file mode 100644
index 0000000..61b98a0
--- /dev/null
+++ b/.github/workflows/build.yml
@@ -0,0 +1,152 @@
+name: Build and Test
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+ release:
+ types: [created]
+
+jobs:
+ test-python:
+ name: Test Python MCP Server
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+
+ - name: Install dependencies
+ run: |
+ cd packages/mcp-server-revit
+ pip install -e .[dev]
+
+ - name: Lint with ruff
+ run: |
+ ruff check packages/mcp-server-revit
+ ruff format --check packages/mcp-server-revit
+
+ - name: Type check with mypy
+ run: mypy packages/mcp-server-revit/src
+
+ - name: Test with pytest
+ run: pytest packages/mcp-server-revit/tests -v --cov --cov-report=xml
+
+ - name: Upload coverage
+ uses: codecov/codecov-action@v3
+ if: github.event_name == 'push'
+ with:
+ files: ./coverage.xml
+ flags: python
+
+ build-dotnet:
+ name: Build C# Bridge Add-in
+ runs-on: windows-latest
+ strategy:
+ matrix:
+ revit-version: ['2024', '2025']
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup .NET
+ uses: actions/setup-dotnet@v4
+ with:
+ dotnet-version: '8.0.x'
+
+ - name: Restore dependencies
+ run: dotnet restore packages/revit-bridge-addin/RevitBridge.csproj
+
+ - name: Build
+ run: |
+ dotnet build packages/revit-bridge-addin/RevitBridge.csproj `
+ -c Release `
+ -p:RevitVersion=${{ matrix.revit-version }} `
+ --no-restore
+
+ - name: Upload artifacts
+ uses: actions/upload-artifact@v4
+ with:
+ name: revit-bridge-${{ matrix.revit-version }}
+ path: packages/revit-bridge-addin/bin/Release/${{ matrix.revit-version }}/
+ retention-days: 7
+
+ package:
+ name: Create Release Package
+ needs: [test-python, build-dotnet]
+ runs-on: windows-latest
+ if: github.event_name == 'release'
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+
+ - name: Download C# artifacts
+ uses: actions/download-artifact@v4
+ with:
+ path: artifacts
+
+ - name: Install Python packaging tools
+ run: |
+ pip install build pyinstaller
+
+ - name: Create distribution
+ run: |
+ # Create dist structure
+ New-Item -ItemType Directory -Path dist/RevitMCP/bin/2024 -Force
+ New-Item -ItemType Directory -Path dist/RevitMCP/bin/2025 -Force
+ New-Item -ItemType Directory -Path dist/RevitMCP/server -Force
+ New-Item -ItemType Directory -Path dist/RevitMCP/addin -Force
+
+ # Copy C# binaries
+ Copy-Item artifacts/revit-bridge-2024/* dist/RevitMCP/bin/2024/ -Recurse
+ Copy-Item artifacts/revit-bridge-2025/* dist/RevitMCP/bin/2025/ -Recurse
+
+ # Build Python standalone exe
+ cd packages/mcp-server-revit
+ pyinstaller --onefile --name revit_mcp_server src/revit_mcp_server/__main__.py
+ Copy-Item dist/revit_mcp_server.exe ../../dist/RevitMCP/server/
+ cd ../..
+
+ # Copy manifests
+ Copy-Item packages/revit-bridge-addin/RevitBridge.addin dist/RevitMCP/addin/
+
+ - name: Create ZIP archive
+ run: |
+ $version = "${{ github.event.release.tag_name }}".TrimStart('v')
+ Compress-Archive -Path dist/RevitMCP/* -DestinationPath "RevitMCP-$version.zip"
+
+ - name: Upload release asset
+ uses: actions/upload-release-asset@v1
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ with:
+ upload_url: ${{ github.event.release.upload_url }}
+ asset_path: ./RevitMCP-${{ github.event.release.tag_name }}.zip
+ asset_name: RevitMCP-${{ github.event.release.tag_name }}.zip
+ asset_content_type: application/zip
+
+ lint-scripts:
+ name: Lint PowerShell Scripts
+ runs-on: windows-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install PSScriptAnalyzer
+ shell: pwsh
+ run: Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
+
+ - name: Lint scripts
+ shell: pwsh
+ run: |
+ $scripts = Get-ChildItem -Path scripts -Filter *.ps1 -Recurse
+ foreach ($script in $scripts) {
+ Write-Host "Analyzing $($script.Name)..."
+ Invoke-ScriptAnalyzer -Path $script.FullName -Severity Warning
+ }
diff --git a/README.md b/README.md
index 6733dfb..9e362ed 100644
--- a/README.md
+++ b/README.md
@@ -2,332 +2,324 @@
<img src="https://raw.githubusercontent.com/modelcontextprotocol/docs/main/logo/light.svg" alt="MCP Logo" width="120"/>
-# Revit MCP Server
+# RevitMCP: Model Context Protocol for Autodesk Revit
-**Model Context Protocol server for Autodesk Revit automation**
-
-Control Revit from AI agents, Python scripts, or any MCP-compatible client through a standardized interface.
+**Production-grade MCP server enabling AI agents and automation tools to control Autodesk Revit**
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![.NET Framework 4.8](https://img.shields.io/badge/.NET-4.8-512BD4?style=flat-square&logo=dotnet)](https://dotnet.microsoft.com/)
-[![Revit 2020-2024](https://img.shields.io/badge/Revit-2020--2024-0696D7?style=flat-square)](https://www.autodesk.com/products/revit)
+[![Revit 2024-2025](https://img.shields.io/badge/Revit-2024--2025-0696D7?style=flat-square)](https://www.autodesk.com/products/revit)
-[Installation](#installation) • [Features](#features) • [Architecture](#architecture) • [Documentation](#documentation)
+[Quick Start](#quick-start) • [Features](#features) • [Architecture](#architecture) • [Copilot Integration](#microsoft-copilot-studio-integration) • [Docs](#documentation)
</div>
---
-## Overview
-
-This project provides a bridge between the Model Context Protocol (MCP) and Autodesk Revit, enabling programmatic control of Revit through a standardized API. It exposes 25 Revit operations for quality assurance, data extraction, and automation workflows.
+## What is RevitMCP?
-**Key Components:**
+RevitMCP bridges the [Model Context Protocol](https://modelcontextprotocol.io) with Autodesk Revit, enabling:
-- **MCP Server** (Python): Protocol handler with request validation, workspace sandboxing, and audit logging
-- **Bridge Add-in** (C# .NET): Native Revit add-in that executes API calls via ExternalEvent
-- **Mock Mode**: Standalone testing mode with deterministic responses (no Revit required)
+- **Microsoft Copilot Studio** integration for conversational Revit control
+- **AI-powered** model analysis, quality assurance, and reporting
+- **Batch automation** for exports, audits, and data extraction
+- **Secure-by-default** localhost-only bridge with enterprise HTTPS/OAuth options
-**Use Cases:**
+### Key Features
-- Automated quality assurance in CI/CD pipelines
-- AI-powered model analysis and reporting
-- Batch data extraction and exports
-- Integration with custom tooling and workflows
+✅ **25 Revit Tools** - Document management, export (PDF/IFC/DWG/CSV), QA audits, batch operations
+✅ **Enterprise Ready** - MSI installer, OAuth2, audit logging, workspace sandboxing
+✅ **Copilot Studio** - Pre-built integration guide for Microsoft 365
+✅ **Dual Mode** - Mock mode for CI/testing, bridge mode for live Revit
+✅ **Production Threading** - ExternalEvent queue with proper Revit main thread execution
+✅ **Security First** - Localhost-only by default, path validation, structured audit logs
---
-## Installation
+## Quick Start
-### Prerequisites
+### Installation (Windows)
-**For Mock Mode (Testing/Development):**
-- Python 3.11 or higher
-- Git
+**Download the installer:**
-**For Bridge Mode (Production with Revit):**
-- Windows 10/11
-- Autodesk Revit 2020-2024
-- .NET Framework 4.8
-- Visual Studio Build Tools or MSBuild
+1. Go to [Releases](https://github.com/Sam-AEC/Autodesk-Revit-MCP-Server/releases)
+2. Download `RevitMCP-1.0.0.zip`
+3. Extract and run:
-### Quick Start
+```powershell
+.\install.ps1 -RevitVersion 2024
+```
-#### 1. Clone and Install
+**Or install from source:**
-```bash
-git clone https://github.com/Sam-AEC/mcp.git
-cd mcp
-python -m venv venv
+```powershell
+git clone https://github.com/Sam-AEC/Autodesk-Revit-MCP-Server.git
+cd Autodesk-Revit-MCP-Server
+.\scripts\build-addin.ps1 -RevitVersion 2024
+.\scripts\install.ps1 -RevitVersion 2024
```
-**Windows:**
+### Verify Installation
+
+1. **Start Revit 2024**
+2. **Check bridge health:**
+ ```powershell
+ curl http://localhost:3000/health
+ ```
+ Expected response:
+ ```json
+ {
+ "status": "healthy",
+ "revit_version": "2024",
+ "active_document": "YourProject.rvt"
+ }
+ ```
+
+3. **Run MCP server:**
+ ```powershell
+ # Install Python package
+ pip install -e packages/mcp-server-revit
+
+ # Start server
+ python -m revit_mcp_server
+ ```
+
+### Test a Tool
+
```powershell
-.\venv\Scripts\activate
+# List all views in active document
+curl -X POST http://localhost:3000/execute `
+ -H "Content-Type: application/json" `
+ -d '{"tool":"revit.list_views","payload":{},"request_id":"test1"}'
```
-**macOS/Linux:**
-```bash
-source venv/bin/activate
-```
+---
-Install the MCP server:
-```bash
-pip install -e packages/mcp-server-revit[dev]
-```
+## Architecture
-#### 2. Run in Mock Mode
+```
+┌─────────────────────────────────────────────────────────┐
+│ CLIENT LAYER │
+│ • Microsoft Copilot Studio │
+│ • Python scripts │
+│ • Custom MCP clients │
+└────────────────────┬────────────────────────────────────┘
+ │ HTTPS/JSON
+ ┌──────────▼──────────┐
+ │ MCP Server (Python) │
+ │ - Request routing │
+ │ - Security/audit │
+ │ - Workspace guard │
+ └──────────┬──────────┘
+ │ HTTP localhost:3000
+ ┌──────────▼──────────┐
+ │ Bridge Add-in (C#) │
+ │ - HTTP server │
+ │ - CommandQueue │
+ │ - ExternalEvent │
+ └──────────┬──────────┘
+ │ Revit API
+ ┌──────────▼──────────┐
+ │ Revit 2024/2025 │
+ │ - Active document │
+ │ - Views/elements │
+ │ - Export engines │
+ └─────────────────────┘
+```
-```bash
-# Set environment variables
-export MCP_REVIT_MODE=mock
-export WORKSPACE_DIR="$(pwd)/workspace"
-mkdir -p workspace
+**Threading Model:**
+1. HTTP request arrives → Background thread (BridgeServer)
+2. Request queued → CommandQueue (thread-safe)
+3. ExternalEvent raised → Revit main thread
+4. Command executed → Revit API calls
+5. Response returned → TaskCompletionSource correlation
+6. HTTP response → Client receives result
-# Run tests
-pytest packages/mcp-server-revit/tests -v
+---
-# Start server (terminal 1)
-python -m revit_mcp_server
+## Available Tools
+
+### Core Operations
+- `revit.health` - Check Revit session status
+- `revit.open_document` - Open Revit file
+- `revit.list_views` - Enumerate views with metadata
+
+### Exports
+- `revit.export_schedules` - Export schedules to CSV
+- `revit.export_pdf_by_sheet_set` - Generate PDF from sheets
+- `revit.export_dwg_by_sheet_set` - Export DWG drawings
+- `revit.export_ifc_named_setup` - Export IFC using predefined setup
+
+### Quality Assurance (15 Audit Tools)
+- `revit.model_health_summary` - Overall model health report
+- `revit.warning_triage_report` - Categorize Revit warnings
+- `revit.naming_standards_audit` - Validate naming conventions
+- `revit.parameter_compliance_audit` - Check parameter completeness
+- `revit.view_template_compliance_check` - Ensure template usage
+- `revit.tag_coverage_audit` - Verify tag placement
+- `revit.link_monitor_report` - Monitor linked files
+- ...and 8 more (see [API Reference](docs/api.md))
+
+### Batch Operations
+- `revit.batch_create_sheets_from_csv` - Create sheets from CSV
+- `revit.titleblock_fill_from_csv` - Populate titleblock data
+- `revit.batch_place_views_on_sheets` - Auto-place views
-# Run demo client (terminal 2)
-python packages/client-demo/demo.py
-```
+---
-#### 3. Run in Bridge Mode (Windows + Revit)
+## Microsoft Copilot Studio Integration
-```powershell
-# Build and install add-in
-$env:REVIT_SDK = "C:\Program Files\Autodesk\Revit 2024\SDK"
-.\scripts\build-addin.ps1
-.\scripts\install-addin.ps1 -RevitYear 2024
-
-# Start Revit, then configure and run server
-$env:MCP_REVIT_MODE = "bridge"
-$env:WORKSPACE_DIR = "C:\revit-workspace"
-python -m revit_mcp_server
-```
+RevitMCP integrates with Microsoft Copilot Studio to enable conversational Revit control.
-For detailed installation instructions, see [docs/install.md](docs/install.md).
+### Architecture
----
+Since Revit is a desktop app, we use an **on-prem worker** model:
-## Features
+```
+[User in Teams] → [Copilot Studio] → [MCP Server (Azure)]
+ ↓
+ [Azure Queue]
+ ↓
+ [On-prem Worker] → [Revit + Bridge]
+```
-### Available Tools (25)
+### Quick Setup
-| Category | Tools | Description |
-|----------|-------|-------------|
-| **Health Check** | `revit.health` | Server status and connectivity |
-| **Document Management** | `open_document`, `list_views` | File operations and view enumeration |
-| **Quality Assurance** | `model_health_summary`, `warning_triage`, `naming_standards`, `parameter_compliance`, `shared_params`, `view_templates`, `tag_coverage`, `room_completeness`, `link_monitor`, `coordinate_check` | Automated model validation and auditing |
-| **Data Export** | `export_schedules`, `export_quantities`, `export_pdf`, `export_dwg`, `export_ifc` | Multi-format data extraction |
-| **Sheet Management** | `batch_create_sheets`, `place_views_on_sheets`, `fill_titleblocks` | Sheet creation and configuration |
-| **Baseline Tracking** | `export_baseline`, `diff_baseline` | Model comparison and change detection |
+1. **Deploy MCP Server to Azure:**
+ ```bash
+ az containerapp create --name revit-mcp-server \
+ --image ghcr.io/sam-aec/revit-mcp-server:latest \
+ --ingress external --target-port 8000
+ ```
-Full tool documentation: [docs/tools.md](docs/tools.md)
+2. **Configure Entra ID** (OAuth2 tokens)
-### Security Features
+3. **Deploy on-prem worker** (polls Azure queue, executes in Revit)
-- **Workspace Sandboxing**: All file operations restricted to allowed directories
-- **Schema Validation**: Pydantic-based request/response validation
-- **Audit Logging**: JSONL logs with timestamps for all operations
-- **Local-Only**: Bridge runs on localhost (no external network exposure)
-- **Mock Mode**: Complete testing without Revit installation
+4. **Add to Copilot Studio:**
+ - Create agent: "Revit Assistant"
+ - Add MCP server URL with OAuth
+ - Select tools: `revit.health`, `revit.list_views`, `revit.export_schedules`
+ - Publish to Teams
-Security model: [docs/security.md](docs/security.md)
+**Full guide:** [docs/copilot-integration.md](docs/copilot-integration.md)
---
-## Architecture
+## Security
-```
-┌─────────────────────┐
-│ AI Agent/Client │
-│ (Claude, ChatGPT) │
-└──────────┬──────────┘
- │ MCP Protocol (stdio/SSE)
- ▼
-┌─────────────────────┐
-│ Python MCP Server │
-│ - Validation │
-│ - Sandboxing │
-│ - Logging │
-└──────────┬──────────┘
- │ HTTP (localhost:3000)
- ▼
-┌─────────────────────┐
-│ C# Bridge Add-in │
-│ - ExternalEvent │
-│ - API Execution │
-└──────────┬──────────┘
- │ Revit API
- ▼
-┌─────────────────────┐
-│ Autodesk Revit │
-└─────────────────────┘
-```
+### Default: Localhost Only
-**Why this architecture?**
+Out of the box:
+- Bridge binds to `127.0.0.1:3000` (loopback only)
+- **Zero network exposure**
+- All file paths validated against workspace allowlist
-The Revit API requires:
-- .NET Framework (C# code)
-- Windows operating system
-- UI thread execution via ExternalEvent
+### Enterprise Mode (Opt-in)
-This bridge architecture handles the complexity while exposing a simple, cross-platform JSON interface via MCP.
+For Copilot or remote access:
+- ✅ HTTPS via IIS/nginx reverse proxy
+- ✅ OAuth2 JWT validation (Entra ID)
+- ✅ Tenant allowlist
+- ✅ Rate limiting (100 req/min)
+- ✅ JSONL audit logs with caller identity
-Detailed architecture: [docs/architecture.md](docs/architecture.md)
+**Threat model:** [docs/security.md](docs/security.md)
---
-## Usage Example
-
-### Python Client
-
-```python
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-# Connect to MCP server
-server_params = StdioServerParameters(
- command="python",
- args=["-m", "revit_mcp_server"],
- env={"MCP_REVIT_MODE": "bridge"}
-)
-
-async with stdio_client(server_params) as (read, write):
- async with ClientSession(read, write) as session:
- # Initialize
- await session.initialize()
-
- # Open document
- result = await session.call_tool(
- "revit.open_document",
- arguments={"file_path": "/workspace/project.rvt"}
- )
-
- # Run QA audit
- warnings = await session.call_tool(
- "revit.warning_triage_report",
- arguments={}
- )
-
- # Export data
- schedules = await session.call_tool(
- "revit.export_schedules",
- arguments={"output_dir": "/workspace/exports"}
- )
-```
+## Development
-### AI Agent Integration
-
-Configure in your MCP client (Claude Desktop, Continue, etc.):
-
-```json
-{
- "mcpServers": {
- "revit": {
- "command": "python",
- "args": ["-m", "revit_mcp_server"],
- "env": {
- "MCP_REVIT_MODE": "bridge",
- "WORKSPACE_DIR": "C:\\revit-workspace"
- }
- }
- }
-}
-```
+### Build from Source
-The agent can then use natural language to control Revit:
+```powershell
+# Build C# add-in
+.\scripts\build-addin.ps1 -RevitVersion 2024
-```
-User: "Check the hospital.rvt model for warnings and naming violations"
+# Run Python tests
+cd packages/mcp-server-revit
+pytest tests/ -v --cov
-Agent: [calls revit.open_document with hospital.rvt]
- [calls revit.warning_triage_report]
- [calls revit.naming_standards_audit]
- [generates report with findings and recommendations]
+# Package distribution
+.\scripts\package.ps1 -Version 1.0.0
```
----
-
-## Development
-
### Project Structure
```
mcp/
├── packages/
-│ ├── mcp-server-revit/ # Python MCP server
-│ ├── revit-bridge-addin/ # C# Revit add-in
-│ └── client-demo/ # Example client
-├── scripts/ # Build and deployment scripts
-├── docs/ # Documentation
-└── examples/ # Configuration examples
+│ ├── mcp-server-revit/ # Python MCP server
+│ │ ├── src/revit_mcp_server/
+│ │ │ ├── server.py # Main server
+│ │ │ ├── bridge/client.py # HTTP bridge client
+│ │ │ ├── security/ # Workspace + audit
+│ │ │ └── tools/handlers.py# 25 tool handlers
+│ │ └── tests/ # Pytest suite
+│ │
+│ └── revit-bridge-addin/ # C# Revit add-in
+│ ├── src/Bridge/
+│ │ ├── App.cs # IExternalApplication
+│ │ ├── BridgeServer.cs # HTTP server
+│ │ ├── CommandQueue.cs # Request queue
+│ │ └── BridgeCommandFactory.cs # Tool executor
+│ └── RevitBridge.csproj
+│
+├── scripts/
+│ ├── build-addin.ps1 # Build C# DLL
+│ ├── package.ps1 # Create dist/
+│ └── install.ps1 # Install to Revit
+│
+├── docs/
+│ ├── copilot-integration.md # Copilot Studio guide
+│ ├── security.md # Security model
+│ └── api.md # Tool reference
+│
+└── .github/workflows/build.yml # CI/CD
```
-### Running Tests
-
-```bash
-# Python tests
-pytest packages/mcp-server-revit/tests -v
-
-# C# tests (requires Visual Studio)
-dotnet test packages/revit-bridge-addin/RevitBridge.Tests
-```
-
-### Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
-
---
## Documentation
-- **[Installation Guide](docs/install.md)**: Detailed setup for mock and bridge modes
-- **[Tool Reference](docs/tools.md)**: Complete API documentation for all 25 tools
-- **[Architecture](docs/architecture.md)**: System design and component interaction
-- **[Security Model](docs/security.md)**: Trust boundaries and threat mitigation
+- **[Admin Guide](docs/admin-guide.md)** - Enterprise deployment, silent install, troubleshooting
+- **[Copilot Integration](docs/copilot-integration.md)** - Step-by-step Copilot Studio setup
+- **[Security Model](docs/security.md)** - Threat analysis, hardening, enterprise controls
+- **[API Reference](docs/api.md)** - All 25 tools with schemas
+- **[Architecture](docs/architecture.md)** - Threading model, request flow
---
-## Roadmap
-
-**Version 0.2**
-- Complete Revit API implementation (replace stubs)
-- Async HTTP client with connection pooling
-- Enhanced error handling and recovery
-- Performance benchmarks
+## Contributing
-**Future**
-- Additional QA tools (clash detection, BIM validation)
-- Dynamo script integration
-- Navisworks export support
-- BIM 360/ACC integration
-- Multi-document operations
+Contributions welcome! Please:
+1. Fork the repo
+2. Create a feature branch
+3. Add tests for new tools
+4. Run `pytest` and `ruff check`
+5. Submit a pull request
---
## License
-This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see [LICENSE](LICENSE)
---
## Support
-- **Issues**: [GitHub Issues](https://github.com/Sam-AEC/mcp/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/Sam-AEC/mcp/discussions)
-- **Documentation**: [docs/](docs/)
+- **Issues:** [GitHub Issues](https://github.com/Sam-AEC/Autodesk-Revit-MCP-Server/issues)
+- **Security:** See [SECURITY.md](SECURITY.md) for responsible disclosure
+- **Discussions:** [GitHub Discussions](https://github.com/Sam-AEC/Autodesk-Revit-MCP-Server/discussions)
---
<div align="center">
-Built with the [Model Context Protocol](https://modelcontextprotocol.io)
+**Built with ❤️ for the AEC community**
-**[⭐ Star this repo](https://github.com/Sam-AEC/mcp)** if you find it useful
+[⬆ Back to Top](#revitmcp-model-context-protocol-for-autodesk-revit)
</div>
diff --git a/SECURITY.md b/SECURITY.md
index 5c92761..e49c9cc 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,48 +2,81 @@
## Supported Versions
+We actively support and provide security updates for the following versions:
+
| Version | Supported |
| ------- | ------------------ |
-| 0.1.x | :white_check_mark: |
+| 1.x | ✅ Active support |
+| < 1.0 | ❌ Not supported |
## Reporting a Vulnerability
-We take security seriously. If you discover a security vulnerability in MCP Revit Bridge, please report it responsibly.
+**DO NOT** open public GitHub issues for security vulnerabilities.
+
+### Where to Report
+
+Use GitHub's private security advisory feature:
+
+1. Navigate to the repository's **Security** tab
+2. Click **"Report a vulnerability"**
+3. Provide detailed information
+
+### What to Include
+
+- **Description**: Clear description of the vulnerability
+- **Steps to Reproduce**: Detailed steps to demonstrate the issue
+- **Impact Assessment**: What an attacker could achieve
+- **Affected Versions**: Which versions are vulnerable
+- **Suggested Fix** (optional): Your recommendations
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial Triage**: Within 7 days
+- **Fix Development**:
+ - **Critical**: Within 7 days
+ - **High**: Within 30 days
+ - **Medium**: Within 90 days
+
+### Disclosure Policy
+
+We follow **coordinated disclosure**:
+1. Private report received
+2. Fix developed and tested
+3. Patched version released
+4. Public disclosure after 30 days
-### How to Report
+## Security Best Practices
-**Do not open a public issue.** Instead, email security details to the maintainers or use GitHub's private security advisory feature:
+### For Users
-1. Navigate to the repository's Security tab
-2. Click "Report a vulnerability"
-3. Provide detailed information about the vulnerability
+✅ **Keep localhost-only** - Never bind to `0.0.0.0` without enterprise hardening
+✅ **Update regularly** - Apply security patches within 30 days
+✅ **Enable audit logs** - Monitor `%APPDATA%\RevitMCP\Logs\bridge.jsonl`
+✅ **Workspace sandboxing** - Only allow trusted project directories
+✅ **Enterprise mode** - Follow [docs/security.md](docs/security.md) for HTTPS/OAuth
-Include in your report:
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Suggested fix (if any)
+### For Developers
-### What to Expect
+✅ **Input validation** - All inputs validated against schemas
+✅ **No secrets in code** - Use environment variables
+✅ **Least privilege** - No privilege elevation
+✅ **Exception handling** - Sanitize before returning to client
-- Acknowledgment within 48 hours
-- Assessment and triage within 7 days
-- Regular updates on remediation progress
-- Credit in release notes (unless you prefer to remain anonymous)
+## Security Hardening Checklist
-### Security Best Practices
+Before production deployment:
-When using MCP Revit Bridge:
+- [ ] Bridge binds to `127.0.0.1` only
+- [ ] Workspace directories limited
+- [ ] Audit logging enabled
+- [ ] HTTPS configured (if remote access)
+- [ ] OAuth2 enabled (if external clients)
+- [ ] Rate limiting configured
+- [ ] Security reviews scheduled
-1. **Workspace Isolation**: Always configure `WORKSPACE_DIR` and `MCP_REVIT_ALLOWED_DIRECTORIES` to restrict file access
-2. **Network Boundaries**: The bridge runs on localhost only (127.0.0.1:3000) - do not expose to external networks
-3. **Input Validation**: All tool inputs are validated against JSON schemas, but review custom configurations carefully
-4. **Audit Logs**: Enable and monitor audit logs for unexpected tool usage
-5. **Mock Mode Testing**: Use mock mode in CI/CD pipelines to avoid exposing production Revit environments
-6. **Least Privilege**: Run the bridge with minimal Windows permissions required for Revit operations
+Full guide: [docs/security.md](docs/security.md)
-### Known Limitations
+---
-- The bridge HTTP listener does not implement authentication (localhost-only by design)
-- File operations are restricted to allowed directories but rely on OS permissions
-- Revit API operations inherit Revit's security model and limitations
+**Last Updated**: 2026-01-07
diff --git a/scripts/install.ps1 b/scripts/install.ps1
new file mode 100644
index 0000000..914c0c0
--- /dev/null
+++ b/scripts/install.ps1
@@ -0,0 +1,81 @@
+param(
+ [string]$RevitVersion = "2024",
+ [switch]$AllUsers,
+ [string]$DistPath = "$PSScriptRoot\..\dist\RevitMCP"
+)
+
+$ErrorActionPreference = "Stop"
+
+Write-Host "RevitMCP Installer" -ForegroundColor Cyan
+Write-Host "==================`n" -ForegroundColor Cyan
+
+# Verify dist package exists
+if (-not (Test-Path $DistPath)) {
+ Write-Error "Distribution package not found at: $DistPath`nRun .\scripts\package.ps1 first"
+ exit 1
+}
+
+# Install binaries to ProgramData
+Write-Host "Installing binaries..." -ForegroundColor Yellow
+$targetBin = "C:\ProgramData\RevitMCP\bin"
+New-Item -ItemType Directory -Path $targetBin -Force | Out-Null
+
+$sourceBin = "$DistPath\bin\$RevitVersion"
+if (-not (Test-Path $sourceBin)) {
+ Write-Error "Binaries for Revit $RevitVersion not found in distribution package.`nAvailable versions: $((Get-ChildItem "$DistPath\bin" -Directory).Name -join ', ')"
+ exit 1
+}
+
+Copy-Item "$sourceBin\*" $targetBin -Recurse -Force
+Write-Host " Installed to: $targetBin" -ForegroundColor Green
+
+# Install add-in manifest
+Write-Host "`nInstalling add-in manifest..." -ForegroundColor Yellow
+$addinDir = if ($AllUsers) {
+ "C:\ProgramData\Autodesk\Revit\Addins\$RevitVersion"
+} else {
+ "$env:APPDATA\Autodesk\Revit\Addins\$RevitVersion"
+}
+
+New-Item -ItemType Directory -Path $addinDir -Force | Out-Null
+Copy-Item "$DistPath\addin\RevitBridge.addin" $addinDir -Force
+Write-Host " Installed to: $addinDir" -ForegroundColor Green
+
+# Copy config (optional)
+Write-Host "`nCopying default configuration..." -ForegroundColor Yellow
+$configTarget = "C:\ProgramData\RevitMCP\config"
+New-Item -ItemType Directory -Path $configTarget -Force | Out-Null
+Copy-Item "$DistPath\config\default.json" $configTarget -Force
+Write-Host " Installed to: $configTarget\default.json" -ForegroundColor Green
+
+# Installation summary
+Write-Host "`n========================================" -ForegroundColor Cyan
+Write-Host "Installation Complete!" -ForegroundColor Green
+Write-Host "========================================" -ForegroundColor Cyan
+
+Write-Host "`nInstalled components:" -ForegroundColor Yellow
+Write-Host " Bridge DLL: $targetBin\RevitBridge.dll"
+Write-Host " Add-in: $addinDir\RevitBridge.addin"
+Write-Host " Config: $configTarget\default.json"
+
+Write-Host "`nNext steps:" -ForegroundColor Yellow
+Write-Host " 1. Restart Revit $RevitVersion" -ForegroundColor White
+Write-Host " 2. Open a project in Revit" -ForegroundColor White
+Write-Host " 3. Verify bridge: curl http://localhost:3000/health" -ForegroundColor White
+Write-Host " 4. Expected response: {`"status`":`"healthy`",`"revit_version`":`"$RevitVersion`",...}" -ForegroundColor Gray
+
+Write-Host "`nTo install MCP server:" -ForegroundColor Yellow
+if (Test-Path "$DistPath\server\revit_mcp_server.exe") {
+ Write-Host " Run: $DistPath\server\revit_mcp_server.exe" -ForegroundColor White
+} else {
+ $wheel = Get-ChildItem "$DistPath\server\*.whl" -ErrorAction SilentlyContinue | Select-Object -First 1
+ if ($wheel) {
+ Write-Host " pip install $($wheel.FullName)" -ForegroundColor White
+ Write-Host " python -m revit_mcp_server" -ForegroundColor White
+ }
+}
+
+Write-Host "`nTroubleshooting:" -ForegroundColor Yellow
+Write-Host " - Check Revit journal: %LOCALAPPDATA%\Autodesk\Revit\Autodesk Revit $RevitVersion\Journals\" -ForegroundColor Gray
+Write-Host " - Check bridge logs: %APPDATA%\RevitMCP\Logs\bridge.jsonl" -ForegroundColor Gray
+Write-Host " - Uninstall: Remove files from paths above" -ForegroundColor Gray
diff --git a/scripts/package.ps1 b/scripts/package.ps1
new file mode 100644
index 0000000..932b739
--- /dev/null
+++ b/scripts/package.ps1
@@ -0,0 +1,149 @@
+param(
+ [string]$Version = "1.0.0"
+)
+
+$ErrorActionPreference = "Stop"
+
+$distDir = "$PSScriptRoot\..\dist\RevitMCP"
+Write-Host "Creating distribution package: $distDir" -ForegroundColor Cyan
+
+# Clean and create dist directory
+Remove-Item $distDir -Recurse -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Path $distDir | Out-Null
+
+# Build C# for both 2024 and 2025
+Write-Host "`nBuilding C# add-in for Revit 2024 and 2025..." -ForegroundColor Yellow
+foreach ($year in @("2024", "2025")) {
+ & "$PSScriptRoot\build-addin.ps1" -RevitVersion $year -Configuration Release
+
+ if ($LASTEXITCODE -ne 0) {
+ Write-Error "Build failed for Revit $year"
+ exit $LASTEXITCODE
+ }
+
+ $binDir = "$distDir\bin\$year"
+ New-Item -ItemType Directory -Path $binDir -Force | Out-Null
+
+ $sourcePath = "$PSScriptRoot\..\packages\revit-bridge-addin\bin\Release\$year"
+ if (Test-Path $sourcePath) {
+ Copy-Item "$sourcePath\*" $binDir -Recurse -Force
+ Write-Host " Copied binaries for Revit $year" -ForegroundColor Green
+ } else {
+ Write-Warning "Build output not found at $sourcePath"
+ }
+}
+
+# Build Python package with PyInstaller (if available)
+Write-Host "`nPackaging Python MCP server..." -ForegroundColor Yellow
+$serverDir = "$distDir\server"
+New-Item -ItemType Directory -Path $serverDir -Force | Out-Null
+
+Push-Location "$PSScriptRoot\..\packages\mcp-server-revit"
+try {
+ # Try PyInstaller first
+ $pyInstallerAvailable = (Get-Command pyinstaller -ErrorAction SilentlyContinue) -ne $null
+
+ if ($pyInstallerAvailable) {
+ Write-Host " Building standalone executable with PyInstaller..." -ForegroundColor Cyan
+ pyinstaller --onefile --name revit_mcp_server --distpath $serverDir src/revit_mcp_server/__main__.py
+ if ($LASTEXITCODE -eq 0) {
+ Write-Host " Created revit_mcp_server.exe" -ForegroundColor Green
+ } else {
+ Write-Warning "PyInstaller build failed, falling back to wheel"
+ }
+ }
+
+ # Always create wheel as fallback
+ Write-Host " Building Python wheel..." -ForegroundColor Cyan
+ python -m build --wheel --outdir $serverDir
+ if ($LASTEXITCODE -eq 0) {
+ Write-Host " Created Python wheel" -ForegroundColor Green
+ }
+} finally {
+ Pop-Location
+}
+
+# Copy add-in manifests
+Write-Host "`nCopying add-in manifests..." -ForegroundColor Yellow
+$addinDir = "$distDir\addin"
+New-Item -ItemType Directory -Path $addinDir -Force | Out-Null
+Copy-Item "$PSScriptRoot\..\packages\revit-bridge-addin\RevitBridge.addin" $addinDir -Force
+Write-Host " Copied RevitBridge.addin" -ForegroundColor Green
+
+# Create default config
+Write-Host "`nCreating default configuration..." -ForegroundColor Yellow
+$configDir = "$distDir\config"
+New-Item -ItemType Directory -Path $configDir -Force | Out-Null
+
+$defaultConfig = @{
+ version = $Version
+ bridge = @{
+ host = "127.0.0.1"
+ port = 3000
+ use_https = $false
+ }
+ server = @{
+ mode = "bridge"
+ workspace = @("C:\RevitProjects", "$env:USERPROFILE\Documents")
+ }
+}
+
+$defaultConfig | ConvertTo-Json -Depth 10 | Set-Content "$configDir\default.json"
+Write-Host " Created default.json" -ForegroundColor Green
+
+# Create README for distribution
+$distReadme = @"
+# RevitMCP Distribution Package v$Version
+
+This package contains the RevitMCP Bridge add-in and MCP server.
+
+## Installation
+
+### Quick Install (Revit 2024)
+``````powershell
+.\install.ps1 -RevitVersion 2024
+``````
+
+### Manual Install
+1. Copy bin\{year}\* to C:\ProgramData\RevitMCP\bin\
+2. Copy addin\RevitBridge.addin to C:\ProgramData\Autodesk\Revit\Addins\{year}\
+3. Restart Revit
+
+## Verify Installation
+1. Start Revit
+2. In PowerShell: ``curl http://localhost:3000/health``
+3. Should return: ``{"status":"healthy","revit_version":"2024",...}``
+
+## Run MCP Server
+``````powershell
+# If using standalone exe:
+.\server\revit_mcp_server.exe
+
+# If using Python wheel:
+pip install server\revit_mcp_server-*.whl
+python -m revit_mcp_server
+``````
+
+## Documentation
+- README: ../README.md
+- Security: ../docs/security.md
+- Copilot Integration: ../docs/copilot-integration.md
+
+## Support
+https://github.com/Sam-AEC/Autodesk-Revit-MCP-Server/issues
+"@
+
+$distReadme | Set-Content "$distDir\README.txt"
+
+Write-Host "`nPackage created successfully!" -ForegroundColor Green
+Write-Host "Location: $distDir" -ForegroundColor Cyan
+Write-Host "`nContents:" -ForegroundColor Yellow
+Get-ChildItem $distDir -Recurse -File | ForEach-Object {
+ $relativePath = $_.FullName.Replace($distDir, "").TrimStart("\")
+ Write-Host " $relativePath" -ForegroundColor Gray
+}
+
+Write-Host "`nNext steps:" -ForegroundColor Yellow
+Write-Host " 1. Test installation: .\scripts\install.ps1 -RevitVersion 2024" -ForegroundColor White
+Write-Host " 2. Create MSI: Build WiX installer from dist\ folder" -ForegroundColor White
+Write-Host " 3. Create release: Compress to RevitMCP-$Version.zip" -ForegroundColor White