zwcad-standard-mcp

# ZWCAD Standard MCP Local MCP Server for **ZWCAD Standard**. It is not designed to mechanically expose all COM methods to large models, but to provide a set of medium-grained, batchable, previewable, and verifiable tools around common pain points for CAD users. The underlying uses ZWCAD's publicly available ActiveX/COM API, connected to the locally running ZWCAD via `pywin32`; the MCP layer uses the official Python SDK. > This project does not include proprietary capabilities such as frame, mechanical title block, BOM, ball marker, mechanical standard environment, etc. specific to ZWCAD Mechanical. ## User Problems Solved | User Pain Points | Corresponding Capabilities | |---|---| | AI cannot connect to CAD, version and current drawing are unclear | `diagnose_cad`, `get_cad_app_info`, `get_current_document` | | Receiving unfamiliar DWG, unclear about layers, objects, and blocks | `audit_drawing`, `list_layers`, `query_entities`, `list_block_references` | | External imported drawings are all on layer 0, color and line type do not follow layer | `normalize_selected_entities`, `ensure_layers`, `update_entity_properties` | | Need to batch read, modify, or transform a group of objects | `get_selected_entities`, `get_entity_details`, `transform_entities` | | Repeatedly drawing simple geometry, text, and common annotations | `create_entities_batch` | | Multiple layouts switch one by one and output PDF, or preview print range and device capabilities | `list_layouts`, `plot_layouts`, `preview_plot_scope`, `get_plot_capabilities`, `create_batch_job`, `scan_cad_folder` | | Standard version title block is an attribute block, needs batch checking and filling | `list_block_references`, `get_block_attributes`, `update_block_attributes` | | High operation risk, worry about accidental modification or deletion | Write tools default `dry_run=true`, each call authorization (`confirm`), delete/save secondary confirmation, Undo Mark | ## Tool List (37) ### System Diagnosis - `diagnose_cad` - `get_cad_app_info` - `audit_drawing` ### Document - `get_current_document` - `list_documents` - `activate_document` - `save_document` ### Layer - `list_layers` - `ensure_layers` ### Object Reading and Modification - `get_selected_entities` - `query_entities` - `get_entity_details` - `update_entity_properties` - `normalize_selected_entities` - `transform_entities` - `delete_entities` > `get_selected_entities` returns selected handle list, merged bounding box, space (model/paper), and whether it is an empty selection. ### Basic Drawing - `create_entities_batch` Supports: line, circle, arc, lightweight polyline, single-line text, multi-line text, block, aligned/rotated/radius/diameter annotation. ### Layout, Plotting, and Scope - `list_layouts` - `activate_layout` - `get_layout_plot_settings` - `get_plot_capabilities` - `preview_plot_scope` - `get_current_view` - `get_drawing_extents` - `plot_layouts` - `export_drawing` - `verify_export_files` Supports: reading print device/paper/style, previewing print area, plotting by display/graphical extent/window/layout, and verifying output integrity and scope rationality. ### Block - `list_block_definitions` - `list_block_references` - `get_block_attributes` - `update_block_attributes` - `insert_blocks_batch` ### File Management - `scan_cad_folder` - `open_document` - `close_document` - `create_batch_job` - `get_batch_job_status` > Folder-level batch plotting: first use `scan_cad_folder` to list all CAD files in the target directory, then `create_batch_job(operation="plot_pdf", files=[...], output_dir=..., config={"plot_configuration": "DWG to PDF.pc5", "extension": "pdf"})` to plot in the background thread; `get_batch_job_status` to poll the progress. Batch tasks run in an independent COM adapter instance, not competing with interactive sessions for the main thread. ## Safety Defaults 1. **Default Preview, Call Authorization**: This version has removed the global write switch during startup ( `ZWCAD_MCP_ALLOW_WRITE` no longer takes effect). All write tools default to `dry_run=true` for preview; actual execution requires passing `confirm=true` (and `second_confirm=true` for deletion, `file_path` for saving) on each call. No need to restart the service to switch between read-only and writable. 2. **Write Tools Default Preview**: All batch modification, drawing, plotting, and export tools default to `dry_run=true`. 3. **Secondary Confirmation for Deletion**: Deletion requires both `dry_run=false` and `confirm=true`. 4. **Secondary Confirmation for Saving**: Saving requires `confirm=true`. 5. **Batch Limitation**: Default maximum 200 objects for writing, 500 objects for query return. 6. **Undo Grouping**: Batch CAD modifications are put into one Undo Mark for easy user undo. ## Environment Requirements - Windows 10/11 - ZWCAD Standard installed, with ActiveX/COM automation interface enabled - ZWCAD running and at least one DWG open - Python 3.10+ Default COM ProgID: ```text ZWCAD.Application ``` Some versions or installation environments may use different ProgIDs, which can be modified via `ZWCAD_MCP_PROG_ID`. ## Installation ### One-Click Installation Double-click: ```text install.bat ``` After installation, start ZWCAD, open a DWG, and run: ```text start.bat ``` ### Command-Line Installation ```powershell py -3.11 -m venv .venv .venv\Scripts\activate pip install -e . python -m zwcad_standard_mcp.server ``` ## MCP Client Configuration Copy `mcp-config.example.json` and modify the local absolute path: ```json { "mcpServers": { "zwcad-standard": { "command": "D:\\path\\to\\zwcad-standard-mcp\\.venv\\Scripts\\python.exe", "args": ["-m", "zwcad_standard_mcp.server"], "env": { "ZWCAD_MCP_PROG_ID": "ZWCAD.Application", "ZWCAD_MCP_TRANSPORT": "stdio" } } } } ``` This version uses a "call authorization" model, no need to preset a write switch in the configuration, nor restart the service to switch read/write: - Read-only operations ( `diagnose_cad` / read / query / layer list) are available anytime. - Write operations first preview with `dry_run=true`; after confirmation, add `dry_run=false, confirm=true` to execute. - Deletion requires `confirm=true` and `second_confirm=true`; saving requires `confirm=true` and providing `file_path`. ## Recommended Verification Sequence ### Phase 1: Read-Only Connection 1. `diagnose_cad` 2. `get_current_document` 3. `audit_drawing` 4. `list_layers` 5. `get_selected_entities` ### Phase 2: Low-Risk Modification 1. Duplicate a test drawing in ZWCAD. 2. Select a few objects. 3. Call `normalize_selected_entities(dry_run=true)`. 4. Check the preview. 5. Enable writing and call with `dry_run=false`. 6. Test Undo in ZWCAD. ### Phase 3: Standard Version Title Block 1. `list_block_references(has_attributes=true)` to find the title block. 2. `get_block_attributes` to read attribute tags. 3. `update_block_attributes(dry_run=true)` to preview. 4. Execute with `dry_run=false` after user confirmation. 5. Read attributes again to verify. ### Phase 4: Folder-Level Batch Plotting 1. `scan_cad_folder(path="target directory")` to list all DWG/DXF/DWT. 2. `create_batch_job(operation="plot_pdf", files=[...], output_dir=".../Publish", config={"plot_configuration": "DWG to PDF.pc5", "extension": "pdf"}, confirm=true)` to create and execute batch tasks. 3. `get_batch_job_status(job_id=...)` to poll progress. 4. `verify_export_files(file_paths=[...])` to verify output. ## Examples ### Normalize Current Selected Objects ```json { "target_layer": "OUTLINE", "set_color_bylayer": true, "set_linetype_bylayer": true, "dry_run": true } ``` ### Batch Draw Rectangle and Hole ```json { "entities": [ { "entity_type": "lwpolyline", "layer": "OUTLINE", "params": { "vertices": [[0, 0], [300, 0], [300, 200], [0, 200]], "closed": true } }, { "entity_type": "circle", "layer": "HOLE", "params": {"center": [25, 25, 0], "radius": 5} } ], "dry_run": true } ``` ### Update Standard Version Title Block Attributes ```json { "updates": [ { "handle": "3AF", "attributes": { "DESIGNER": "John Doe", "DATE": "2026-07-21" } } ], "dry_run": true } ``` ## Configuration Items | Environment Variable | Default Value | Description | |---|---:|---| | `ZWCAD_MCP_PROG_ID` | `ZWCAD.Application` | COM ProgID | | `ZWCAD_MCP_AUTO_START` | `false` | Whether to automatically start ZWCAD if not running | | `ZWCAD_MCP_MAX_QUERY_RESULTS` | `500` | Maximum return quantity for single query | | `ZWCAD_MCP_MAX_BATCH_SIZE` | `200` | Maximum quantity for single batch write | | `ZWCAD_MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` | | `ZWCAD_MCP_ADAPTER` | `com` | `com`; can be set to `fake` for testing | | `ZWCAD_MCP_LOG_LEVEL` | `INFO` | Log level | ## Testing The code repository includes a Fake Adapter that does not depend on Windows/ZWCAD: ```powershell pip install -e ".[dev]" pytest ``` For local viewing of MCP tool schema: ```powershell set ZWCAD_MCP_ADAPTER=fake python -m zwcad_standard_mcp.server ``` ## Known Boundaries - Not connected to a real Windows ZWCAD in the current build environment, so COM methods need to be verified on the target ZWCAD version. - Does not include mechanical version-specific objects. - Dynamic blocks, nested blocks, external reference attributes, field objects, and complex proxy objects may require subsequent special adaptation. - `plot_layouts` relies on existing printable configurations in the current layout; different enterprise PC3, PMP, and paper configurations need to be verified on a real machine. - Folder-level batch tasks (passing `files` to `create_batch_job`) open drawings and plot in background threads; if ZWCAD pops up modal dialogs due to missing fonts, proxy objects, or print configurations, it will block the background thread and require closing all pop-ups in ZWCAD before retrying. - Current queries mainly use COM collection traversal; large drawings need to add indexing, selection set filtering, and pagination. - Undo Mark facilitates user undo but is not a database-level automatic transaction rollback. ## Project Structure ```text zwcad-standard-mcp/ ├── README.md ├── pyproject.toml ├── install.bat ├── start.bat ├── mcp-config.example.json ├── docs/ ├── examples/ ├── src/zwcad_standard_mcp/ │ ├── adapters/ │ ├── services/ │ ├── tools/ │ ├── config.py │ ├── models.py │ └── server.py └── tests/ ``` ## References - ZWCAD Application Development Support: https://www.zwsoft.com/support/zwcad-devdoc - Official MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk - ZWCAD Mechanical MCP reference implementation: https://github.com/john0909/ZWCAD-Mechanical-MCP