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.

docs: track consolidated roadmap and update gitignore

A. Sam Mohammad88218e645dff
diff --git a/.gitignore b/.gitignore
index 6d43fd4..800ca2c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -229,9 +229,4 @@ update_dll.ps1
INSTALL_NEW_DLL.txt
temp.json
-# Local proposed architecture / report MD files
-docs/0001-multi-provider-architecture.md
-docs/proposed-multi-workflow-architecture.md
-docs/agent-handover-prompt.md
-docs/roadmap-and-plans.md
diff --git a/docs/0001-multi-provider-architecture.md b/docs/0001-multi-provider-architecture.md
new file mode 100644
index 0000000..43915e2
--- /dev/null
+++ b/docs/0001-multi-provider-architecture.md
@@ -0,0 +1,92 @@
+# ADR 0001: Multi-Provider AEC Automation Architecture
+
+## Status
+Proposed
+
+## Context
+The AEC Model Bridge is being expanded from a Revit-only MCP bridge to a multi-platform AEC automation platform. To accommodate diverse software systems (e.g., Rhino, Tekla, Archicad, IfcOpenShell, Autodesk Forma, Speckle) while maintaining existing Revit tools and compatibility, we need a unified provider architecture.
+
+## Decisions
+
+### 1. Provider Discovery and Registry
+- **Headless & In-Process Providers**: Registered directly in a Python `ProviderRegistry` class.
+- **Local Desktop Adapters**: Discoverable dynamically via local loopback ports. Desktop adapters will bind to dynamic loopback ports and register their active endpoint, process ID, and a security bearer token with a local registry.
+- **Cloud Providers**: Discovered and loaded dynamically based on environment configuration or user credentials.
+
+### 2. Transport Types
+- **Headless/Local Files**: In-process Python imports (e.g., `IfcOpenShell`) for zero overhead and deterministic executions.
+- **Desktop SDKs**: Isolated process HTTP/JSON-RPC boundaries over loopback (e.g., Revit bridge). This isolates non-redistributable SDKs and prevents C# crashes from bringing down the MCP server.
+- **Cloud Integrations**: Secure HTTPS REST/GraphQL protocols.
+- **Batch/Compute Engines**: Asynchronous HTTP/WebSocket queues with job status polling.
+
+### 3. Capability Manifests
+Each provider publishes a runtime capability manifest:
+```json
+{
+ "provider_id": "ifc",
+ "tools": [
+ {
+ "name": "ifc_get_metadata",
+ "description": "Read file headers and schemas...",
+ "input_schema": { ... },
+ "output_schema": { ... },
+ "is_mutating": false,
+ "confirmation_required": false,
+ "execution_mode": "sync"
+ }
+ ]
+}
+```
+The MCP server aggregates these manifests dynamically rather than hardcoding tool names.
+
+### 4. Object References
+Instead of designing a universal BIM object model, we use a flexible reference envelope that preserves native identities:
+```json
+{
+ "provider": "ifc",
+ "project_id": null,
+ "model_id": "structure.ifc",
+ "object_id": "12345",
+ "stable_id": null,
+ "ifc_guid": "2XQ$n5SLP5MBLyL6JQj8Z0",
+ "version": "v1"
+}
+```
+Different platforms map object identities via standard fields like `ifc_guid` or external mapping tables.
+
+### 5. Authentication and Security
+- **Desktop/Local**: Every local desktop bridge generates a random per-session bearer token (nonce) during startup. The client must supply this token in authorization headers. Loops back only to `127.0.0.1`.
+- **Cloud (OAuth)**: Credentials must never appear in tool parameters, results, or logs. Use OS-level secure credential stores or environment variables loaded into the server environment. OAuth code flow with PKCE is used for user-delegated access.
+
+### 6. Mutation Controls
+- Mutating tools support a `dry_run` parameter where applicable.
+- Confirmations are requested before high-risk mutations.
+- Transacted operations are wrapped in host transaction APIs (e.g., Revit transactions) to support undo.
+- Idempotency keys are included for cloud operations.
+
+### 7. Asynchronous Jobs
+Long-running or batch operations yield a job reference:
+```json
+{
+ "job_id": "job_9876",
+ "status": "running",
+ "progress_percent": 45,
+ "artifacts": []
+}
+```
+Clients poll or receive webhooks, with support for cancellation.
+
+### 8. Licensing Boundaries
+- Host SDK binaries (e.g., Autodesk Revit assemblies, RhinoCommon, Tekla Open API) must remain separate from the core repository.
+- Code dependencies utilize standard interfaces. Connectors are packaged separately.
+- Clear licensing boundaries apply (GPL/LGPL linking exemptions where required).
+
+### 9. Compatibility and Legacy Support
+- Existing `revit_*` tool names, routes, and `MCP_REVIT_` configuration are preserved.
+- A Revit Compatibility Adapter maps legacy MCP calls directly to the new `RevitProvider`.
+- Legacy configuration is mapped to provider configuration automatically.
+
+## Consequences
+- **Extensibility**: Adding a new AEC integration only requires writing a class that conforms to the `AECProvider` interface.
+- **Robustness**: In-process libraries like `IfcOpenShell` do not require desktop software to run or test.
+- **Isolation**: Prohibits licensing leakage and maintains strict desktop SDK process isolation.
diff --git a/docs/roadmap-and-plans.md b/docs/roadmap-and-plans.md
new file mode 100644
index 0000000..af168a7
--- /dev/null
+++ b/docs/roadmap-and-plans.md
@@ -0,0 +1,82 @@
+# AEC Model Bridge - Strategic Roadmap & Architecture Thesis
+
+This document outlines the core engineering thesis, historical progress, and future roadmap of the **AEC Model Bridge** platform developed on the `development` branch.
+
+---
+
+## 💡 The Core Thesis
+
+### The Problem in AEC Today
+The Architecture, Engineering, and Construction (AEC) industry is historically fragmented. Structural design occurs in **Rhino/Grasshopper**, detail modeling in **Autodesk Revit**, data analysis in **IFC/Power BI**, and coordination in cloud Common Data Environments (CDEs) like **Speckle** or **Autodesk Construction Cloud (ACC)**.
+AI agents trying to interact with building models are typically blocked by:
+1. Application-specific APIs requiring desktop application lifetimes.
+2. The absence of a unified protocol to query and coordinate models across formats.
+3. Severe security concerns around local paths and cloud access credentials leaking in AI contexts.
+
+### The Solution: A Unified, Secure AEC MCP Runtime
+The **AEC Model Bridge** solves this by wrapping all application contexts into a single, standardized Model Context Protocol (MCP) server. By routing tool queries through a dynamic provider registry, we enable AI and programmatic scripts to edit, audit, and orchestrate BIM data across boundaries.
+
+---
+
+## 🛠️ What Has Been Done (Historical Progress)
+
+Since branching onto `development`, we have built the platform end-to-end:
+
+### Phase 1 & 2: Modular Architecture Foundation
+- **Unified Provider Registry (`base.py`, `registry.py`)**: Extracted the Revit-only bridge into a generic registry where multiple independent providers (IFC, Rhino, Revit, cloud CDEs) can register and expose capabilities.
+- **Legacy Revit Adaptation (`revit.py`)**: Migrated all 100+ native Revit tools into the registry while maintaining 100% backwards compatibility (supporting dot/underscore notations).
+- **IfcOpenShell Provider (`ifc.py`)**: Integrated a headless, read-only Python IFC parser for spatial hierarchy, unit summaries, and geometric bounding box querying.
+- **Identity & Path Mapper (`identity_mapper.py`)**: Implemented deterministic GUID to buildingSMART IfcGUID compression/decompression, custom relational mapping links, and workspace-relative path resolution.
+
+### Phase 3, 4, & 5: Advanced Engineering Workflows (COMPLETED)
+- **Rhino/Compute & Proxy Connector (`rhino.py`, `proxy.py`)**: Built an async provider for `Rhino.Compute` web server, AND a dynamic `McpProxyProvider` over SSE that proxies an active Rhino MCP server (e.g. `localhost:9876`) directly into the unified AEC Model Bridge.
+- **Topological Semantic Graph (`graph.py`)**: Implemented an in-memory `networkx` directed multi-graph mapping model elements as nodes and typing structural and adjacency relationships. Includes structural load path audits and AABB clash checks.
+- **Navisworks Manage Bridge (`NavisworksBridge.dll`)**: Shipped a C# Add-in for Navisworks Manage (2024-2027) hosting its own local HTTP loop (`port 3002`) to allow MCP agents to query coordination/clash data dynamically.
+- **OAuth-PKCE Cloud Sync & Speckle V3 (`cloud.py`, `speckle.py`)**: Integrated `specklepy` 3.x native support (`SpeckleProvider`) and `AutodeskDataProvider`. They handle secure authorization, branch/model querying, and pushing data directly to Power BI via Speckle Manager credentials, keeping tokens redacted.
+
+### Orchestration, Redaction, & Loop Alignment (The Integration Phase)
+- **Async Job Pipeline (`jobs.py`, `job_provider.py`)**: Built an async background queue manager. Calling any MCP tool with `run_async=True` returns a `JobReference` immediately and executes the tool in the background. Exposes `job_status` and `job_cancel` MCP tools.
+- **Persistent Event-Loop Thread**: Structured the legacy synchronous `MCPServer` (`server.py`) to run a background daemon event-loop thread. Background jobs survive after individual synchronous tool-calls return.
+- **Centralized Redaction (`audit.py`)**: Integrated a recursive data parser that redacts Windows/POSIX file paths and sensitive authentication credentials from all tool responses and audit logs.
+
+---
+
+## 🌅 The Strategic Horizon (Future Roadmap)
+
+To maximize business value and align with standard corporate AEC workflows, the remaining platform evolution is structured into the following strategic phases:
+
+### Phase C: Omni-Bridge Orchestrator & Flagship Recipes
+- **Declarative Recipe Engine**: Support defining cross-tool workflows (e.g., Rhino massing → Revit instantiation → Navisworks clash) in YAML.
+- **Run Records & Identity**: Emit versioned records of every orchestration run, linked through a unified identity map (IFC/Revit/Rhino GUIDs).
+- **Flagship Workflows**: Prove end-to-end Concept-to-BIM, Coordination loops, and zero-switch Model Health audits.
+
+### Phase D: Data Plane & Dashboards
+- **Parquet/DuckDB Exporter**: Expose a tool to dump flattened parameters and graph relationships to local Parquet tables for secure, zero-licensing Power BI analysis.
+- **Power BI Templates**: Ship `.pbit` templates over the lakehouse for Model Health and Coordination trends.
+- **buildingSMART IDS**: Implement Information Delivery Specification (IDS) XML rule checking via the IfcOpenShell provider.
+- **Automation Webhooks**: Support Slack/Teams webhooks on job completions.
+- **Graph Exporters**: Export the semantic topological graph to `.graphml` for Neo4j visualization.
+
+### Phase E: Wave 2 Switches
+- **Excel**: Headless table read/write, dry-run diffing, and cloud variants via Microsoft Graph.
+- **ACC/Forma**: AEC Data Model reads, issue publishing, and model-updated webhooks.
+- **Solibri**: Integration for ruleset execution and BCF result extraction.
+
+### Phase F: Platform, Distribution & Docs
+- **Distribution**: End-to-end MkDocs site, zero-switch 10-minute tutorials, and automated release packaging for all switch variants.
+- **SDK Templates**: Provide C# cookiecutter templates for authoring new desktop switches.
+
+### Phase G: Wave 3 Adapter Specifications
+- Prepare specifications for native integration into **Archicad, Tekla Structures, SketchUp, Bentley iTwin, Trimble Connect, and Procore**.
+
+### Phase H: Any-AI Access Layer (Chapter 2)
+- Provide access doors for non-developer BIM professionals, including:
+ 1. **Remote MCP (Streamable HTTP)** to plug directly into ChatGPT, Claude, and Copilot.
+ 2. **REST/OpenAPI Facade** for automation via Power Automate, Zapier, n8n.
+ 3. **BYO-LLM Console** with offline Ollama support.
+
+### Phase I: Popularity Pack
+- **BCF Provider**: Standalone BCF 2.1/3.0 read/write.
+- **IFC-to-glTF**: Create self-contained HTML 3D viewers from IFC files.
+- **LLM-Ready Digest**: Generate compressed markdown summaries of model state.
+- **Automation Watchers**: Execute recipes automatically via drop-folder events.