TopoSpatial-CAD MCP

Spatial Topology Engine, Architectural Ontology & Autonomous CAD Intelligence via Model Context Protocol (MCP)

Executive Overview

Standard CAD automation interfaces treat drawings as collections of disconnected, "dumb" coordinate geometry: lines, polylines, arcs, and blocks. When a Large Language Model (LLM) interacts with raw CAD data, it is forced to guess relationships from coordinate soup (Polyline handle 274, Line handle 281, Block at x=5230, y=3120).

TopoSpatial-CAD MCP transforms AutoCAD, ZWCAD, GstarCAD, and BricsCAD into a semantically structured, topology-aware architectural model for autonomous AI agents and assistants (Claude Desktop, Cursor, VS Code).

Instead of an LLM perceiving:

"Four polylines + one block + two lines"

TopoSpatial-CAD MCP constructs a rich spatial knowledge graph:

• Bedroom-01 (20 m² clear interior usable area) contains Door-03 and Window-02.

• Bedroom-01 is topologically adjacent to Corridor-01.

• Door-03 connects Bedroom-01 directly to Corridor-01.

Version 3.0.0 Architecture & Features

• Pillar 1 — Plugin (plugins/autocad): Native AutoCAD and AutoCAD Architecture C# plugin packages for 2024 (.NET 4.8) and 2025 (.NET 8). Includes TOPOSTUDIO dockable palette hosting the visual topology editor via WebView2, non-invasive TOPOSTUDIOEVENTS event coalescing on CAD idle, and STA COM worker serialization with fast-failing circuit breakers.

• Pillar 2 — Graph (/editor & topology_engine): Interactive web-based Visual Topology Studio with dual synchronized views: full-bleed vector CAD underlay canvas and Cytoscape.js topological circulation graph. Supports top:SpatialIntent authoring, real-time circulation pathfinding, architectural space programming, and live WebSocket updates.

• Pillar 3 — Plan (manage_design & design_engine): High-level design orchestration lifecycle (create, modify, validate, preview, apply, cancel, rollback) with local ExecutionPlan generation, host-before-opening dependency ordering, deterministic shared-wall compilation (cad:boundingRooms), revision-keyed topology caching, and atomic rollback.

• Unified MCP Surface: 9 comprehensive tools bridging high-level design orchestration, topology analysis, drawing primitives, and session management.

• Native ACA & Portable Fallback: Runtime style and API discovery for native AecDbWall, AecDbDoor, and AecDbWindow, with portable standard CAD fallbacks for AutoCAD, ZWCAD, GstarCAD, and BricsCAD.

• 333 automated tests passing with 100% test coverage across COM safety, design orchestration, shared-wall networks, and visual topology editor semantics.

┌────────────────────────────────────────────────────────┐
│                   AI ARCHITECTURE AGENT                │
│             (Semantic & Spatial Reasoning)             │
└───────────────────────────┬────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
  ┌───────────────────┐           ┌───────────────────┐
  │  Spatial Topology │           │ Architectural     │
  │  (TopologicPy)    │           │ Ontology (JSON-LD)│
  └─────────┬─────────┘           └─────────┬─────────┘
            └───────────────┬───────────────┘
                            ▼
               ┌─────────────────────────┐
               │ TopoSpatial Engine Core │
               │ (Transaction Validation)│
               └────────────┬────────────┘
                            ▼
               ┌─────────────────────────┐
               │   AutoCAD / ZWCAD COM   │
               │ (DWG + XData Persistence│
               └─────────────────────────┘

Related MCP server: multiCAD-mcp

Core Architectural Innovations

"TopoSpatial-CAD MCP gives AI hands.
 TopologicPy gives it spatial understanding.
 The ontology gives it architectural vocabulary.
 JSON-LD gives it structured memory.
 Preview / Apply gives it safety."

1. Topology vs. Ontology: The Dual-Layer Brain

• Topology answers: How are objects geometrically related? (Containment, adjacency, connectivity, boundary closure, opening host relationships).

• Ontology answers: What are those objects? (semantic_id = ROOM-BED-004, class = Bedroom, label = Guest Bedroom, host = WALL-019).

This distinction enables high-level architectural reasoning:

• "Which bedrooms don't have direct access to a corridor?"

• "Which habitable rooms lack exterior window access?"

• "Enlarge Bedroom 2 by 600 mm without reducing the corridor width below 1200 mm."

• "Find all rooms directly connected to the main entrance lobby."

2. Strict "Do Not Infer Semantic Classes" Rule

To eliminate LLM hallucinations, unannotated enclosed geometric boundaries are treated strictly as candidate rooms (candidate_room_23, area: 13.5m²) until explicitly designated by the architect or an automated design verification workflow.

AutoCAD Drawing               Candidate Detection            Explicit Classification
┌──────────────┐               ┌─────────────────┐             ┌─────────────────────┐
│              │     ───►      │candidate_room_23│    ───►     │ semantic_id: BED-01 │
│              │               │area: 13.5 m²    │             │ class: Bedroom      │
└──────────────┘               └─────────────────┘             └─────────────────────┘

3. Persistent DWG XData Storage (TOPOSPATIAL_TOPOLOGY)

Intelligence does not disappear when an LLM chat session ends. Semantic identities, ontology classes, group assignments, and schema versions are embedded directly into CAD entities as native Extended Entity Data (XData).

When you close AutoCAD, restart your computer, and reopen the project tomorrow, Wall-12 is still Wall-12, Door-04 is still Door-04, and Bedroom-02 is still Bedroom-02.

4. Deterministic Transaction Pipeline

Autonomous agents are never permitted to execute destructive geometry edits directly. All modifications follow a safe, deterministic transaction lifecycle:

Analyze DWG ──► Query/Reason ──► Preview & Diff ──► Apply ──► Export/Verify

Example Transaction Preview:

TRANSACTION: TX-72A91
Action: Move Kitchen East Wall +600 mm
Affected Entities: Kitchen-01, Wall-18, Door-07, LivingRoom-01
Dimensional Impact:
  - Kitchen clear width: 3600 mm → 4200 mm
  - Living Room clear width: 5100 mm → 4500 mm
Warning:
  - Door-07 host wall displaced by 600 mm (requires repositioning)
Status: Awaiting Architect Approval

5. SHA-256 Drawing Fingerprint & Revision Safety

Every analysis creates a SHA-256 geometric drawing fingerprint (revision = AF84C2...). If an architect manually adjusts a wall in AutoCAD while the AI is reasoning, TopoSpatial-CAD MCP detects the revision mismatch and rejects outdated transactions to prevent geometric corruption.

6. Clear Interior Dimension Contract

In architectural practice, room dimensions always refer to clear interior usable space. TopoSpatial-CAD MCP enforces this contract at the core API level: requesting a 5000 × 4000 mm bedroom automatically calculates wall thickness offsets (e.g. outer footprint 5400 × 4400 mm with 200 mm walls).

Room boundaries and physical walls remain separate. Before preview, the wall network compiler expands every proposed room into explicit wall requirements, normalizes reversed/noisy centerlines on a 0.01 mm grid, and creates each compatible shared partition once. A shared wall persists all bounding room IDs in XData schema version 2 and exports top:boundedBy/top:bounds relations. Conflicting thickness, height, style, or representation returns WALL_SPEC_CONFLICT instead of silently merging walls.

7. Native AutoCAD Architecture Authoring

When AutoCAD Architecture is the active product, topology transactions can create native AecDbWall, AecDbDoor, and AecDbWindow objects. Doors and windows are attached with native opening-to-wall anchors, so ACA wall cleanup, styles, schedules, and object editing remain available. The server discovers the installed AEC automation version at runtime; it is not tied to a single ACA year.

Each create or update change accepts a representation policy:

• auto (default): use native AEC objects when ACA is available and the opening has a native wall host; otherwise use standard AutoCAD entities.

• native_aec: require native ACA authoring and fail preview if it is unavailable or the opening host is not a native wall.

• standard: always use portable lines, arcs, and polylines.

The selected representation is frozen into the preview transaction and persisted in XData, preventing preview/apply drift. Inspect support and installed styles with manage_session action capabilities before preparing a transaction.

8. DWG & JSON-LD as Source of Truth

TopologicPy operates strictly as an on-demand computational layer, ensuring that your underlying project data remains portable and vendor-neutral in standard DWG XData and JSON-LD graphs.

{
  "@context": {"top": "http://w3id.org/topologicpy#", "cad": "urn:topospatial:cad#"},
  "@id": "room:bedroom-01",
  "@type": "arch:Bedroom",
  "label": "Master Bedroom",
  "clearWidth": 5000,
  "clearDepth": 4000,
  "containsElement": ["door:01", "window:03"],
  "adjacentTo": ["room:corridor-01"]
}

Core Capabilities & Tools

TopoSpatial-CAD MCP provides 9 unified tools covering dozens of CAD and topology operations:

Installation & Setup

Method 1: 1-Click MCP Bundle (.mcpb) for Claude Desktop (Recommended)

The easiest way to install TopoSpatial CAD into Claude Desktop without manual terminal configuration:

Requirements

• Windows 10 / 11 (64-bit)

• AutoCAD 2024–2027 (or ZWCAD / GstarCAD / BricsCAD)

• Claude Desktop for Windows

1-Click Steps

1. Download TopoSpatial-CAD-MCP-v3.0.0.mcpb from GitHub Releases.

2. Double-click the .mcpb file (or drag & drop into Claude Desktop).

3. In Claude Desktop, click Install.

4. Start AutoCAD and open your architectural drawing (.dwg).

5. In Claude Desktop, enable TopoSpatial CAD and begin designing!

Pre-flight CAD Health Doctor

To verify AutoCAD COM communication and python dependencies at any time:

python -m server.main --doctor

(Or double-click autodesk/check_cad_health.bat)

Method 2: Official MCP Registry

TopoSpatial-CAD is registered in the Official MCP Registry:

# Discover or install via MCP Registry namespace
io.github.Nihalmannath/topospatial-cad-mcp

Publishers and maintainers can validate and sync metadata using mcp-publisher:

mcp-publisher validate
mcp-publisher publish

Method 3: Developer / Source Installation

For developers customizing tools or writing custom plugins:

# Clone repository
git clone https://github.com/Nihalmannath/TopoSpatial-CAD-MCP.git
cd TopoSpatial-CAD-MCP

# Sync dependencies
uv sync --extra dev
uv run python -m pip install --upgrade pywin32

To enable the optional, pinned TopologicPy spatial topology engine:

uv sync --extra dev --extra topology

Manual Claude Desktop Config

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "topospatial": {
      "command": "C:\\path\\to\\TopoSpatial-CAD-MCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\TopoSpatial-CAD-MCP\\src\\server.py"]
    }
  }
}

3. First connection and native ACA check

In an MCP client, call manage_session with these operations:

[
  {"action": "status"},
  {"action": "capabilities", "include_styles": true}
]

For AutoCAD Architecture, confirm that the result contains "native_aec": true and the expected wall, door, and window styles. Before a topology mutation, set the active drawing's INSUNITS to millimetres (4).

4. Recommended agent workflow

1. Run manage_session status and capabilities.

2. Run manage_design with action="inspect" and keep its SHA-256 revision.

3. For a modification, request only the affected neighborhood with action="get_context".

4. Submit all approved dependent changes in one create or modify preview.

5. Review the compact plan, warnings, problem classes, and affected IDs.

6. Stop for approval when required, then apply the returned transaction ID; repeated apply is safe and returns the stored result.

7. Capture one meaningful final checkpoint, save the DWG, and export as needed.

For modification requests, never create a new drawing unless the user asks for one. Work in the active drawing through preview/apply. Before low-level drawing, identify semantic entities, get their bounded neighborhood, build one plan, batch mutations, validate locally, and return a compact result. Do not call the model between deterministic geometry operations or rerun topology for a cached revision. Repository agents inherit these rules from AGENTS.md.

Use manage_design for the architectural lifecycle. manage_topology remains available for direct graph/export work and backward compatibility; draw_entities remains appropriate for optimized decorative geometry batches.

See Native ACA and topology workflow for a complete 5000 × 4000 mm room example with one door and two windows.

5. Safe cleanup of generated drawings

manage_files can now delete exact .dwg/.dxf outputs inside the configured export root by moving them to the Windows Recycle Bin:

delete|old_plan.dwg|true|false

The last flag controls matching topology sidecars. The action requires confirm=true, refuses wildcards/directories, and refuses any drawing that is still open in CAD. First use list, then explicitly switch and close the target drawing. To clean several outputs, send one exact delete line per file; there is intentionally no delete all or glob operation.

Verification & Testing

# Run the full test suite (286 tests at this revision)
uv run pytest -q

# Check the files changed in your branch
uv run ruff check <changed-files>

# Build the documentation site
uv run --extra docs mkdocs build --strict

The repository contains some pre-existing whole-tree lint debt; use targeted Ruff checks for changed files until that baseline is cleaned up.

Project Structure

TopoSpatial-CAD-MCP/
├── src/
│   ├── server.py              # FastMCP entry point
│   ├── __version__.py         # Version & author metadata
│   ├── config.json            # Runtime configuration
│   ├── core/                  # Interfaces, ConfigManager, Models
│   ├── adapters/              # Mixin-based COM adapter layer
│   ├── mcp_tools/             # Shorthand dispatchers & tool registrations
│   │   └── tools/             # 9 unified MCP tool modules
│   ├── design_engine/         # Plans, cache, context, retries, metrics
│   ├── topology_engine/       # Spatial topology, XData schemas, transactions
│   ├── ui/                    # UI resources and inspector templates
│   └── web/                   # Real-time CAD status dashboard
├── tests/                     # Unit, transaction, adapter, and integration tests
├── docs/                      # Complete architecture & setup documentation
└── mkdocs.yml                 # Documentation site configuration

Documentation

• Installation and MCP client setup

• System architecture

• Native ACA and topology workflow

• Efficient design orchestration

• Round-trip and response benchmarks

• Complete MCP tool reference

• Troubleshooting

• Changelog

Author & License

• Author: Nihal Ahmed Mannath

• License: Apache License 2.0