Skip to content

SolidWorks MCP — Architecture Alignment Report

Updated: April 8, 2026

This report tracks alignment between the documented 5-layer architecture and the actual implementation. It supersedes the initial gap analysis from April 6 and reflects the current state after implementing the missing runtime intelligence layer.

This is a dated planning snapshot, not a source-of-truth spec. Update it when major routing, security, or adapter behavior changes.

Summary

Component Documented Status Notes
Core infrastructure 5 layers ✅ Complete Transport, adapters, circuit breaker, pool
Tool registry 90+ tools ✅ 106 tools Exceeds spec; server-verified count
Circuit breaker State machine ✅ Complete CLOSED/OPEN/HALF_OPEN with auto-recovery
Connection pool Multi-instance ✅ Complete FIFO AsyncIO queue; not load-aware by design
Complexity analyzer Decision tree ✅ Implemented 25+ ops profiled; param-count + history weighted
Intelligent router Runtime routing ✅ Implemented 45+ ops; COM/VBA selection with cache lookup
Response cache Hit/miss cache ✅ Implemented TTL in-memory; 20+ read-heavy ops cached
VBA adapter Registered adapter ✅ Implemented VbaGeneratorAdapter + VbaMacroExecutor
Security enforcement Multi-level ⚠️ Partial API key + rate-limit in tool path; no OAuth2
Load balancing Intelligent dist. 🔮 Planned FIFO pool remains; multi-instance out of scope

Layer-by-Layer Detail

Layer 1: Client

MCP protocol layer handles all documented client types (Claude Desktop, custom apps, direct MCP). Web interface is not yet implemented.

Layer 2: MCP Protocol

Transport: FastMCP handles JSON-RPC serialization, async request dispatch, and tool registration. Fully implemented.

Authentication: API key validation and per-client rate limiting are enforced in the tool invocation path (see security/runtime.py). OAuth2 / JWT transport-level auth is a future item.

CORS: Configurable via security/cors.py. Permissive by default; restrict allowed_origins in config for remote deployments.

Layer 3: Application

Intelligent Router

IntelligentRouter wraps the base adapter and routes 45+ operations. Call path:

  1. Check response cache → return cached result if valid
  2. Score operation with ComplexityAnalyzer
  3. Route to COM path (fast, direct) or VBA path (complex/high-param ops)
  4. Fall back to alternate path on failure
  5. Update performance history

Configuration flags: enable_intelligent_routing, complexity_parameter_threshold (default 12), complexity_score_threshold (default 0.6).

Tool Registry

106 tools across 12 modules, all registered with FastMCP and backed by Pydantic schemas.

analysis.py             5 tools
automation.py           8 tools
drawing.py             12 tools
drawing_analysis.py     8 tools
export.py               7 tools
file_management.py     14 tools
macro_recording.py      7 tools
modeling.py             9 tools
sketching.py           18 tools
template_management.py  6 tools
vba_generation.py      10 tools
docs_discovery.py       2 tools
────────────────────────────────
Total                 106 tools

Response Cache

ResponseCache (cache/response_cache.py) provides:

  • Deterministic key generation from operation name + payload hash
  • Per-operation TTL policies (configurable; default 60 s)
  • LRU eviction bounded by response_cache_max_entries (default 512)
  • Thread-safe via RLock

Cached operations include: get_model_info, list_features, list_configurations, get_mass_properties, get_material_properties, analyze_geometry, all drawing-analysis tools, and discover_solidworks_docs.

Layer 4: Adapter

Complexity Analyzer (adapters/complexity_analyzer.py)

Scores each operation:

score = (param_ratio × 0.45) + (profile_complexity × 0.40) + (history_failure_rate × 0.15)

25+ operations have explicit profiles. VBA path is preferred when:

  • Parameter count exceeds threshold (default 12), OR
  • Operation profile flags it as VBA-preferred (sweep, loft, spline, multi-body), OR
  • Composite score ≥ 0.6

Performance history resets on server restart (in-memory only; SQLite backing is a future item).

VBA Adapter (adapters/vba_adapter.py, adapters/vba_macro_executor.py)

VbaGeneratorAdapter wraps the COM adapter and annotates results with VBA metadata. VbaMacroExecutor manages the macro lifecycle: write to temp file → RunMacro2 → track result → cleanup. Registered in the factory under AdapterType.VBA.

Direct COM Adapter (adapters/pywin32_adapter.py)

~2200-line Windows COM adapter covering document management, part modeling, assembly operations, sketching, analysis, drawing, and export. The primary execution path for all production work. Newly reworked with a scalable Mixin type architecture for all the future COM API tool additions.

Circuit Breaker (adapters/circuit_breaker.py)

Full CLOSED/OPEN/HALF_OPEN state machine. Trips after 5 consecutive failures (configurable), waits 60 s, then allows test calls in HALF_OPEN before closing. Enabled by default; wraps the COM adapter in production.

Connection Pool (adapters/connection_pool.py)

FIFO AsyncIO queue with configurable pool size (default 3). Provides basic parallel access to the same adapter type. Not a load-aware scheduler — that is by design for single-machine deployments.

Layer 5: SolidWorks

All adapter methods map directly to the SolidWorks COM API via pywin32. No gaps at this layer.

Remaining Gaps

Gap Impact Path forward
OAuth2 / JWT auth Remote deployments rely on API key or IP allowlisting Medium priority; implement transport middleware hook
Security level → tool gating security_level config field exists but is not checked; all tools always accessible Medium; add per-tool level check in tools/__init__.py
Persistent performance history Complexity analyzer resets on restart; cold-start routing is less precise Low; add SQLite backing to ComplexityAnalyzer
Multi-instance load balancing Multiple SW processes not distributed intelligently; pool is FIFO Low; single-machine is the standard deployment

References