solidworks-mcp-server 3.0.9 → 3.1.3

package/README.md

@@ -1,444 +1,195 @@
-# SolidWorks MCP Server
-
-<div align="center">
-
-[![CI](https://github.com/vespo92/SolidworksMCP-TS/actions/workflows/ci.yml/badge.svg)](https://github.com/vespo92/SolidworksMCP-TS/actions/workflows/ci.yml)
-[![npm version](https://badge.fury.io/js/solidworks-mcp-server.svg)](https://www.npmjs.com/package/solidworks-mcp-server)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue?logo=typescript)](https://www.typescriptlang.org/)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green?logo=anthropic)](https://modelcontextprotocol.com)
-[![Node.js](https://img.shields.io/badge/Node.js-20+-green?logo=node.js)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/vespo92/SolidworksMCP-TS/pulls)
-[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/vespo92/SolidworksMCP-TS/graphs/commit-activity)
-
-</div>
-
-A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with SolidWorks CAD software, providing automated design capabilities, macro recording, design tables with SQL integration, VBA generation, and PDM configuration management.
-
-## 🎯 Quick Start
-
-### ⚠️ Windows Users: Local Installation Required
-
-Due to the `winax` native module dependency, this package **cannot be installed via npm global install**. You must build it locally on your Windows machine.
-
-### Installation Steps:
-```bash
-# 1. Clone the repository to your Windows machine
-git clone https://github.com/vespo92/SolidworksMCP-TS
-cd SolidworksMCP-TS
-
-# 2. Install dependencies (this compiles winax for your system)
-npm install
-
-# 3. Build the TypeScript files
-npm run build
-```
-
-### Configure Claude Desktop
-After installation, add the local path to your Claude Desktop config (see detailed instructions below).
-
-Then in Claude Desktop:
-```
-"Generate VBA to batch export all parts in my folder to STEP format"
-"Create a parametric design table for a configurable bracket"
-"Check for interferences in my assembly"
-```
-
-## 🚀 Key Features
-
-### Core Capabilities
-- **Full SolidWorks Control** - Open, create, modify, and analyze CAD models
-- **Macro Recording & Playback** - Record operations and generate reusable macros
-- **Design Tables with SQL** - Create parametric designs driven by database data
-- **PDM Integration** - Configure and manage SolidWorks PDM vaults
-- **VBA Script Generation** - Generate VBA scripts from templates with AI assistance
-- **State Management** - Persistent resource states with auto-save
-- **Resource-Based Architecture** - Modular, extensible design pattern
-
-### New in v2.1.0 - Comprehensive VBA Generation Suite
-⚠️ **IMPORTANT: VBA script generation features are NOT WORKING in the current iteration and require additional testing**
-- 🔧 **Part Modeling VBA** - Advanced features, patterns, sheet metal, surfaces
-- 🏗️ **Assembly Automation** - Mates, components, interference analysis
-- 📐 **Drawing Generation** - Views, dimensions, annotations, tables
-- 📁 **File & PDM Operations** - Batch processing, custom properties, vault management
-- ⚙️ **Advanced Features** - Configurations, equations, simulation setup
-- 🎯 **100+ VBA Tools** - Generate production-ready VBA without coding knowledge
-
-### Enterprise Features (v2.0)
-- 🎯 **Macro Recording System** - Record actions and export to VBA
-- 📊 **SQL-Driven Design Tables** - Connect to databases for parametric designs
-- 🗄️ **PDM Configuration** - Manage vault operations, workflows, and automation
-- 💾 **State Persistence** - Track and restore resource states
-- 🏗️ **Resource Registry** - Dynamic resource type management
-- 📝 **Enhanced Logging** - Comprehensive operation tracking
-
-## 📋 Prerequisites
-
-- Windows 10/11
-- SolidWorks 2021-2025 (licensed installation)
-- Node.js 20 or higher
-- Claude Desktop
-- Optional: SQL Server or PostgreSQL for design tables
-- Optional: SolidWorks PDM for vault operations
-
-## 🛠️ Installation
-
-### 1. Install the MCP Server
-
-#### Local Installation (Required for Windows):
-```bash
-# Clone to your Windows machine
-git clone https://github.com/vespo92/SolidworksMCP-TS
-cd SolidworksMCP-TS
-
-# Install and build
-npm install  # Compiles winax native module for your system
-npm run build  # Compiles TypeScript to JavaScript
-```
-
-**Note:** The `npm install` step will compile the `winax` native module specifically for your Windows system. This is why global npm installation doesn't work - each Windows machine needs its own compiled version.
-
-### 2. Configure Claude Desktop
-
-#### ⚠️ IMPORTANT: Windows Installation Issue
-
-Due to the nature of the `winax` native module (which provides COM/ActiveX support for Windows), the npm global installation method **will not work**. The `winax` module must be compiled locally for your specific Windows system.
-
-#### Required: Local Installation Method
-
-1. **Download or clone this repository to your Windows machine**
-2. **Install dependencies locally:**
-```bash
-cd C:\path\to\SolidworksMCP-Final
-npm install  # This will compile winax for your system
-npm run build  # Build the TypeScript files
-```
-
-3. **Configure Claude Desktop to use the local installation:**
-```json
-{
-  "mcpServers": {
-    "solidworks": {
-      "command": "node",
-      "args": ["C:\\path\\to\\SolidworksMCP-Final\\dist\\index.js"]
-    }
-  }
-}
-```
-
-#### Why This Is Necessary
-
-- `winax` is a C++ native module that interfaces with Windows COM/ActiveX
-- Native modules cannot be pre-compiled for all Windows configurations
-- Each system needs its own compiled version matching its Node.js version and architecture
-- This is a limitation of native modules, not the MCP server itself
-
-#### Future Solutions (In Development)
-
-We're exploring options to simplify installation:
-- Pre-built binaries for common Windows configurations
-- Automatic winax installation script
-- Docker container with pre-configured environment
-- Electron-based standalone application
-
-### 3. Environment Configuration
-
-Create a `.env` file for advanced configuration:
-
-```env
-# SolidWorks Configuration
-SOLIDWORKS_PATH=C:/Program Files/SOLIDWORKS Corp/SOLIDWORKS
-SOLIDWORKS_VERSION=2024
-
-# Feature Flags
-ENABLE_MACRO_RECORDING=true
-ENABLE_PDM=true
-
-# Database Configuration (for Design Tables)
-SQL_CONNECTION=mssql://localhost:1433/solidworks_db
-
-# PDM Configuration
-PDM_VAULT=Engineering
-
-# State Management
-STATE_FILE=.solidworks-state.json
-
-# Logging
-LOG_LEVEL=info
-```
-
-## 🚀 Usage Examples
-
-### Macro Recording
-
-```
-"Start recording a macro called 'CreateBracket'"
-"Create a sketch on the front plane"
-"Add a rectangle 100mm x 50mm"
-"Extrude 25mm"
-"Stop recording and export to VBA"
-```
-
-### Design Tables with SQL
-
-```
-"Create a design table for parametric box configurations from SQL database"
-"Use query: SELECT * FROM box_configurations"
-"Map columns: length, width, height to dimensions"
-"Generate all configurations"
-```
-
-### PDM Operations
-
-```
-"Configure PDM vault 'Engineering' for automatic check-in/check-out"
-"Set up workflow transition from 'Work in Progress' to 'Released'"
-"Create folder structure with permissions for project team"
-```
-
-### Advanced VBA Generation (v2.1.0)
-
-#### Part Modeling
-```
-"Generate VBA to create a parametric bracket with:
-- Reference planes offset by 50mm
-- Sweep feature along a 3D curve
-- Linear pattern with 5 instances
-- Sheet metal conversion with 2mm thickness"
-```
-
-#### Assembly Automation
-```
-"Generate VBA for assembly that:
-- Inserts components from a folder
-- Creates coincident and distance mates
-- Checks for interferences
-- Exports mass properties to Excel"
-```
-
-#### Batch Operations
-```
-"Generate VBA to process all files in C:\Parts that:
-- Opens each SLDPRT file
-- Updates custom properties (Part Number, Revision)
-- Exports to STEP format
-- Checks into PDM vault with comment"
-```
-
-#### Drawing Automation
-```
-"Generate VBA to create drawings that:
-- Creates standard 3-view layout
-- Adds section view A-A
-- Dimensions all features
-- Inserts BOM table
-- Exports to PDF"
-```
-
-## 🔧 Available Tools
-
-### Macro Tools
-- `macro_start_recording` - Begin recording operations
-- `macro_stop_recording` - End recording and save
-- `macro_export_vba` - Export macro to VBA code ⚠️ **NOT WORKING - Requires additional testing**
-- `macro_execute` - Run recorded macro
-
-### Design Table Tools
-- `design_table_create` - Create parametric design table
-- `design_table_refresh` - Update from SQL source
-- `design_table_add_config` - Add configuration
-- `design_table_export` - Export configurations
-
-### PDM Tools
-- `pdm_configure` - Set up vault configuration
-- `pdm_checkin` - Check in files with comments
-- `pdm_checkout` - Check out for editing
-- `pdm_workflow` - Execute workflow transitions
-- `pdm_create_structure` - Set up folder hierarchy
-
-### Resource Management
-- `resource_create` - Create new resource
-- `resource_list` - List all resources
-- `resource_get` - Get resource details
-- `resource_update` - Update resource properties
-- `resource_delete` - Remove resource
-
-### Existing Tools
-All original tools remain available:
-- Modeling tools (create, modify, analyze)
-- Drawing tools (views, dimensions, annotations)
-- Export tools (STEP, IGES, STL, PDF, etc.)
-- VBA tools ⚠️ **NOTE: VBA script generation is NOT WORKING in the current iteration and requires additional testing**
-- Analysis tools (mass properties, interference)
-
-## 📚 API Reference
-
-### Resource Types
-
-#### Design Table Resource
-```typescript
-{
-  type: 'design-table',
-  tableName: string,
-  parameters: Array<{
-    name: string,
-    type: 'dimension' | 'feature' | 'configuration',
-    dataType: 'number' | 'string' | 'boolean',
-    sqlColumn?: string,
-    formula?: string
-  }>,
-  dataSource?: {
-    type: 'sql' | 'file' | 'api',
-    connectionString?: string,
-    query?: string
-  }
-}
-```
-
-#### PDM Configuration Resource
-```typescript
-{
-  type: 'pdm-configuration',
-  vaultName: string,
-  operations: {
-    checkIn?: { enabled: boolean, comment?: string },
-    checkOut?: { enabled: boolean, getLatestVersion?: boolean },
-    workflow?: { 
-      enabled: boolean,
-      transitions: Array<{
-        name: string,
-        fromState: string,
-        toState: string
-      }>
-    }
-  }
-}
-```
-
-## 🧪 Development
-
-### Building from Source
-
-```bash
-git clone https://github.com/vespo92/SolidworksMCP-TS
-cd solidworks-mcp-server
-npm install
-npm run build
-```
-
-### Running Tests
-
-```bash
-npm test                  # Run all tests
-npm run test:unit        # Unit tests only
-npm run test:integration # Integration tests
-```
-
-### Adding Custom Resources
-
-Create a new resource type:
-
-```typescript
-import { SolidWorksResource } from './resources/base';
-
-export class CustomResource extends SolidWorksResource {
-  readonly type = 'custom-type';
-  
-  async execute(api: SolidWorksAPI) {
-    // Implementation
-  }
-  
-  toVBACode(): string {
-    // Generate VBA
-  }
-}
-```
-
-Register the resource:
-
-```typescript
-resourceRegistry.register({
-  type: 'custom-type',
-  name: 'Custom Resource',
-  schema: CustomSchema,
-  factory: (id, name, props) => new CustomResource(id, name, props)
-});
-```
-
-## 🐛 Troubleshooting
-
-### Macro Recording Issues
-- Ensure macro recording is enabled in environment
-- Check that actions are supported for recording
-- Verify VBA export permissions
-
-### SQL Connection Problems
-- Verify connection string format
-- Check database permissions
-- Ensure SQL drivers are installed
-
-### PDM Integration
-- Confirm PDM client is installed
-- Verify vault access permissions
-- Check network connectivity to PDM server
-
-### State Management
-- Check write permissions for state file
-- Clear corrupted state with `resource_clear`
-- Verify auto-save is enabled
-
-## 📊 Performance Considerations
-
-- **Batch Operations**: Use macro recording for repetitive tasks
-- **SQL Queries**: Optimize queries for large datasets
-- **State Storage**: Periodically clean old states
-- **PDM Operations**: Use batch check-in/check-out
-
-## 🔒 Security
-
-- SQL connections use secure authentication
-- PDM credentials are not stored in state
-- Macro execution requires explicit permission
-- State files can be encrypted (configure in .env)
-
-## 📄 License
-
-MIT License - see LICENSE file
-
-## 🤝 Contributing
-
-We welcome contributions! Please see CONTRIBUTING.md for guidelines.
-
-### Areas for Contribution
-- Additional resource types
-- Enhanced SQL integrations
-- More VBA templates
-- PDM workflow automation
-- Testing improvements
-
-## 📞 Support
-
-- Issues: [GitHub Issues](https://github.com/vespo92/SolidworksMCP-TS/issues)
-- Discussions: [GitHub Discussions](https://github.com/vespo92/SolidworksMCP-TS/discussions)
-
-## 🚀 Roadmap
-
-### v2.1 (Q2 2024)
-- [ ] Real-time collaboration features
-- [ ] Cloud storage integration
-- [ ] Advanced simulation tools
-- [ ] Custom property management
-
-### v2.2 (Q3 2024)
-- [ ] AI-powered design suggestions
-- [ ] Automated testing framework
-- [ ] Performance optimization tools
-- [ ] Extended PDM capabilities
-
-## 📖 Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for version history.
-
----
-
-Built with ❤️ for the SolidWorks community
+# SolidWorks MCP Server
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green?logo=anthropic)](https://modelcontextprotocol.io)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-green?logo=node.js)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Windows](https://img.shields.io/badge/Windows-10%2F11-blue?logo=windows)](https://www.microsoft.com/windows)
+
+A Node.js MCP server for automating SolidWorks via COM interop. Connects AI assistants (Claude Desktop, etc.) to SolidWorks for CAD automation tasks.
+
+> **Project Status: Alpha / Experimental**
+>
+> This project is under active development. While the architecture is in place and basic operations (sketch planes, simple extrusions) have been demonstrated, **most tools have not been validated against a live SolidWorks instance**. Expect rough edges, COM quirks, and incomplete functionality. Contributions and testing reports are very welcome.
+
+## How It Works
+
+The server exposes SolidWorks operations as MCP tools over stdio. An intelligent routing layer handles a key limitation of Node.js COM bridges: methods with 13+ parameters often fail via direct COM calls.
+
+- **Simple operations (12 params or fewer)** - Direct COM call via `winax`
+- **Complex operations (13+ params)** - Auto-generated VBA macro executed by SolidWorks
+- **Failed operations** - Automatic fallback with error context
+
+## Prerequisites
+
+- **Windows 10/11** (required - COM interop is Windows-only)
+- **SolidWorks 2021-2025** (licensed, installed)
+- **Node.js 20+**
+- An MCP-compatible client (Claude Desktop, etc.)
+
+## Installation
+
+```bash
+git clone https://github.com/vespo92/SolidworksMCP-TS.git
+cd SolidworksMCP-TS
+
+# Install dependencies (compiles winax native module for your system)
+npm install
+
+# Build TypeScript
+npm run build
+```
+
+> **Note:** The `winax` native module must be compiled locally on each Windows machine. Global npm installation does not work.
+
+## Configure Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "solidworks": {
+      "command": "node",
+      "args": ["C:/path/to/SolidworksMCP-TS/dist/index.js"],
+      "env": {
+        "SOLIDWORKS_PATH": "C:\\Program Files\\SOLIDWORKS Corp\\SOLIDWORKS",
+        "ADAPTER_TYPE": "winax-enhanced"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+The server registers tools across these categories:
+
+| Category | Tools | Status |
+|----------|-------|--------|
+| **Modeling** | create_part, create_extrusion, create_revolve, create_sweep, create_loft, create_fillet, create_chamfer, etc. | Partially tested |
+| **Sketch** | create_sketch, add_line, add_circle, add_rectangle, add_arc, add_constraints, dimension_sketch | Basic ops verified |
+| **Drawing** | create_drawing_from_model, add_drawing_view, add_section_view, add_dimensions, etc. | Untested |
+| **Export** | export_file (STEP, IGES, STL, PDF, DWG, DXF), batch_export | Untested |
+| **Analysis** | get_mass_properties, check_interference, measure_distance, check_geometry | Untested |
+| **VBA Generation** | generate_vba_script, vba_sheet_metal, vba_configurations, vba_equations, etc. | Code generation works; execution untested |
+| **Macro** | macro_start_recording, macro_stop_recording, macro_export_vba | Untested |
+
+**"Partially tested"** means the tool has been run against SolidWorks at least once but not comprehensively. **"Untested"** means only mock/unit tests exist (if any).
+
+## Architecture
+
+```
+MCP Protocol (stdio)
+    |
+Tool Registry (index.ts)
+    |
+Feature Complexity Analyzer --- routes by param count
+    |                    |
+Direct COM (winax)    VBA Macro Generator
+    |                    |
+    +--------------------+
+    |
+SolidWorks COM API
+```
+
+### Key Design Decisions
+
+- **COM parameter limit workaround**: SolidWorks API methods like `FeatureExtrusion3` take 20+ parameters. Node.js COM bridges choke on these. The complexity analyzer detects this and generates a VBA macro instead.
+- **Never pass `null` to COM**: Use `undefined` for optional parameters. COM interprets `null` as `VT_NULL`, causing type mismatch errors (this was the root cause of SelectByID2 failures).
+- **Feature tree traversal over SelectByID2**: `FeatureByPositionReverse()` + `GetTypeName2()` is more reliable for finding sketches than `SelectByID2`.
+- **Winston logger only**: Never use `console.*` - it corrupts the JSON-RPC stdio transport.
+
+## Development
+
+```bash
+npm run build        # TypeScript compile
+npm run dev          # Hot-reload dev server (tsx watch)
+npm run check        # TypeScript + Biome lint in one command
+npm run lint         # Biome lint check
+npm run lint:fix     # Biome auto-fix
+npm run format       # Biome format
+npm run typecheck    # Type check without emit
+```
+
+## Testing
+
+See [TESTING.md](TESTING.md) for the full testing guide.
+
+```bash
+# Unit tests (mock adapter, no SolidWorks needed)
+USE_MOCK_SOLIDWORKS=true npm test
+
+# Watch mode
+npm run test:watch
+```
+
+**Current test status**: Unit tests exist for config and environment utilities. Most tool modules lack test coverage. Integration tests require a Windows machine with SolidWorks and have not been run in CI.
+
+## Known Issues & Limitations
+
+- **No CI integration testing** - Tests only run against mocks. Real SolidWorks integration tests require a self-hosted Windows runner that doesn't exist yet.
+- **winax compilation** - Must be compiled locally on each machine. No pre-built binaries.
+- **Edge.js adapter** - Defined in architecture but not implemented.
+- **PowerShell bridge** - Defined in architecture but not implemented.
+- **Connection pooling / circuit breaker** - Referenced in code but not battle-tested.
+- **Performance metrics are unverified** - No real benchmarking has been done.
+
+## What Has Worked
+
+Based on development testing:
+
+- Connecting to a running SolidWorks instance via COM
+- Creating sketch planes and basic sketch geometry
+- Simple extrusions with limited parameters
+- Feature tree traversal for sketch selection
+- VBA macro code generation (execution path needs more testing)
+
+## Roadmap
+
+- [ ] Comprehensive integration test suite on real SolidWorks
+- [ ] CI with self-hosted Windows runner
+- [ ] Validate all modeling tools end-to-end
+- [ ] Validate drawing and export tools
+- [ ] Edge.js adapter for .NET runtime path
+- [ ] PowerShell bridge as alternative COM path
+- [ ] Performance benchmarking with real metrics
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Key areas where help is needed:
+
+- **Testing against real SolidWorks** - The biggest gap. If you have SolidWorks, running tools and reporting results is extremely valuable.
+- **COM interop edge cases** - Different SolidWorks versions behave differently.
+- **Additional tool implementations** - Many SolidWorks API methods aren't exposed yet.
+
+## Troubleshooting
+
+### COM Registration Issues
+```powershell
+regsvr32 "C:\Program Files\SOLIDWORKS Corp\SOLIDWORKS\sldworks.tlb"
+```
+
+### Build Issues
+```bash
+rm -rf node_modules dist
+npm install
+npm run build
+```
+
+### Debug Logging
+```bash
+ENABLE_LOGGING=true LOG_LEVEL=debug node dist/index.js
+```
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+
+## Acknowledgments
+
+- [winax](https://github.com/nicedreams/node-activex) - COM bridge for Node.js
+- [Anthropic MCP](https://modelcontextprotocol.io) - Model Context Protocol
+- SolidWorks API documentation