Autocad-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AutoCAD MCP Pro is a FastMCP 3.0 server that exposes ~154 tools, 6 resources, and 5 prompt templates for AutoCAD automation. (The exact tool count is reported dynamically by system_status / system_about — never hardcode it.) It runs with a dual-engine architecture: a live COM backend (Windows/AutoCAD required) and a headless ezdxf backend (works anywhere).

Running the Server

# STDIO mode (default, for MCP clients like Claude Desktop)
python server.py

# HTTP mode
fastmcp run server.py:mcp --transport http --port 8000

# Force a specific backend
AUTOCAD_MCP_BACKEND=ezdxf python server.py   # headless file ops
AUTOCAD_MCP_BACKEND=com python server.py     # live AutoCAD (Windows only)
AUTOCAD_MCP_BACKEND=auto python server.py    # auto-detect (default)

Installation

# Core (ezdxf backend only)
pip install -e .

# With COM backend (Windows + AutoCAD)
pip install -e ".[com]"

# With PDF/screenshot support via matplotlib
pip install -e ".[pdf]"

# Everything
pip install -e ".[full]"

Running Tests

pytest
pytest tests/test_specific.py::test_name   # single test
pytest -x                                   # stop on first failure

Uses pytest-asyncio for async test support.

Architecture

Dual-Backend Pattern

The server uses a strategy pattern with an abstract base:

• backends/contracts/ — the interface, one module per domain (drawing.py, layouts.py, entity_creation.py, …). Split in v1.5.0 out of a single 1854-line ABC; some slices (premium, gdt, settings) also carry shared concrete implementations, so they are mixins rather than pure interfaces.
• backends/capability.py — the refusal vocabulary (UnsupportedCapabilityError) plus @capability(key, reason=...), which marks a contract method optional and gives it a default that raises that refusal. Use it only for genuine engine boundaries, never for an unfinished method; @abstractmethod stays the default. Every key used must be declared in both capability maps — tests/test_capability_contract.py fails otherwise, which is what stops the decorator becoming a way to ship undeclared holes.
• backends/base.py — shared dataclasses (EntityInfo, LayerInfo, BlockInfo, DrawingInfo, CapabilityMap) and the AutoCADBackend composition of every contract. Import surface is unchanged: from backends.base import AutoCADBackend, UnsupportedCapabilityError still works.
• backends/ezdxf_backend.py — EzdxfBackend: file-based DXF operations using the ezdxf library. All sync ezdxf calls are wrapped with asyncio.to_thread via _async(). Transactions are implemented as full DXF snapshots on an _undo_stack.
• backends/com_backend.py — ComBackend: live AutoCAD control via pywin32 COM. All COM calls are routed through a ThreadPoolExecutor with a single thread to satisfy AutoCAD's STA (Single-Threaded Apartment) COM requirement.