cyclecad 0.2.2 → 0.2.3

package/docs/MCP-SERVER.md

@@ -0,0 +1,403 @@
+# cycleCAD MCP Server
+
+Model Context Protocol (MCP) server for cycleCAD. Exposes the complete Agent API (55+ commands) as MCP tools that can be used by LLMs like Claude, GPT, and Gemini.
+
+## Quick Start
+
+```bash
+# Start the server
+npx cyclecad-mcp
+
+# Or with custom WebSocket URL
+npx cyclecad-mcp --ws-url ws://10.0.0.1:3000/api/ws
+
+# Or with debug logging
+npx cyclecad-mcp --debug
+
+# Show help
+npx cyclecad-mcp --help
+```
+
+The server reads JSON-RPC requests from stdin and writes responses to stdout (MCP protocol).
+
+## Features
+
+- **55+ Tools**: All Agent API commands exposed as MCP tools
+- **10 Namespaces**: sketch, ops, transform, view, export, validate, render, query, assembly, ai, meta, scene
+- **Dual Transport**: WebSocket (preferred) + HTTP fallback
+- **Non-blocking**: Commands queued if connection unavailable
+- **Zero Dependencies**: No npm packages required (uses Node.js built-ins)
+- **JSON Schema**: Full input validation schemas for all tools
+
+## Tool Categories
+
+### SKETCH (8 tools)
+- `sketch_start` — Start sketch mode on XY/XZ/YZ plane
+- `sketch_end` — End sketch, return all entities
+- `sketch_line` — Draw a line segment
+- `sketch_rect` — Draw a rectangle
+- `sketch_circle` — Draw a circle
+- `sketch_arc` — Draw an arc
+- `sketch_clear` — Clear all sketch entities
+- `sketch_entities` — List current sketch entities
+
+### OPS (20 tools)
+- `ops_extrude` — Extrude sketch into 3D solid
+- `ops_revolve` — Revolve sketch around axis
+- `ops_primitive` — Create primitive shape (box, sphere, cylinder, cone, torus, capsule)
+- `ops_fillet` — Apply fillet to edges
+- `ops_chamfer` — Apply chamfer to edges
+- `ops_boolean` — Boolean operations (union, cut, intersect)
+- `ops_shell` — Create hollow shell
+- `ops_pattern` — Create array pattern
+- `ops_material` — Change material
+- `ops_sweep` — Sweep profile along path
+- `ops_loft` — Loft between profiles
+- `ops_spring` — Generate helical spring
+- `ops_thread` — Generate screw thread
+- `ops_bend` — Sheet metal bend
+
+### TRANSFORM (3 tools)
+- `transform_move` — Translate feature by X/Y/Z offset
+- `transform_rotate` — Rotate feature around axes
+- `transform_scale` — Scale feature along axes
+
+### VIEW (4 tools)
+- `view_set` — Set camera view (front, back, left, right, top, bottom, isometric)
+- `view_fit` — Fit view to feature(s)
+- `view_wireframe` — Toggle wireframe rendering
+- `view_grid` — Toggle grid visibility
+
+### EXPORT (4 tools)
+- `export_stl` — Export STL (binary or ASCII)
+- `export_obj` — Export OBJ
+- `export_gltf` — Export glTF 2.0
+- `export_json` — Export cycleCAD JSON
+
+### VALIDATE (8 tools)
+- `validate_dimensions` — Get bounding box dimensions
+- `validate_wallThickness` — Check minimum wall thickness
+- `validate_printability` — Check FDM/SLA/CNC printability
+- `validate_cost` — Estimate manufacturing cost
+- `validate_mass` — Estimate part mass/weight
+- `validate_surfaceArea` — Calculate surface area
+- `validate_centerOfMass` — Get geometric centroid
+- `validate_designReview` — Auto-analyze (A/B/C/F score)
+
+### RENDER (5 tools)
+- `render_snapshot` — Render viewport as PNG
+- `render_multiview` — Render 6 standard views as PNGs
+- `render_highlight` — Highlight component with color
+- `render_hide` — Hide/show component
+- `render_section` — Enable section cutting (cross-section)
+
+### QUERY (5 tools)
+- `query_features` — List all features
+- `query_bbox` — Get bounding box of feature
+- `query_materials` — List available materials
+- `query_session` — Session info
+- `query_log` — Recent command log
+
+### ASSEMBLY (4 tools)
+- `assembly_addComponent` — Add component to assembly
+- `assembly_removeComponent` — Remove component
+- `assembly_mate` — Define mate constraint
+- `assembly_explode` — Explode component
+
+### SCENE (2 tools)
+- `scene_clear` — Clear all features
+- `scene_snapshot` — Capture viewport as PNG (legacy)
+
+### AI (3 tools)
+- `ai_identifyPart` — Identify part using Gemini Vision
+- `ai_suggestImprovements` — Get design improvement suggestions
+- `ai_estimateCostAI` — AI-powered cost estimation
+
+### META (5 tools)
+- `meta_ping` — Health check + uptime
+- `meta_version` — Version info + feature flags
+- `meta_schema` — Full API schema
+- `meta_modules` — Check available modules
+- `meta_history` — Undo/redo history stack
+
+## Connection
+
+The MCP server connects to cycleCAD via:
+
+1. **WebSocket** (preferred): `ws://localhost:3000/api/ws`
+   - Non-blocking, real-time bidirectional communication
+   - Used for long-running operations
+
+2. **HTTP** (fallback): `http://localhost:3000/api/execute`
+   - Used if WebSocket unavailable
+   - Commands queued until WebSocket connects
+
+The server is non-blocking: if cycleCAD is not running, the MCP server starts anyway and queues commands. Commands are executed as soon as the WebSocket connects.
+
+## Usage Examples
+
+### Via Claude API
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    tools=[
+        {
+            "type": "model_context_protocol",
+            "name": "cyclecad-mcp",
+            "uri": "stdio:///path/to/cyclecad/bin/cyclecad-mcp"
+        }
+    ],
+    messages=[
+        {
+            "role": "user",
+            "content": "Design a simple bracket: rectangle 80x40mm, extrude 5mm, add a cylinder for a bolt hole"
+        }
+    ]
+)
+
+print(response.content)
+```
+
+### Direct Tool Usage
+```python
+# After Claude calls tools, tools are automatically executed by the MCP server
+# and results are returned to Claude for further processing
+```
+
+### Standalone Testing
+```bash
+# Terminal 1: Start cycleCAD
+npx serve . -p 3000
+
+# Terminal 2: Start MCP server
+npx cyclecad-mcp --debug
+
+# Terminal 3: Send JSON-RPC requests
+echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 9000
+echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "sketch_rect", "arguments": {"width": 50, "height": 30}}}' | nc localhost 9000
+```
+
+## Configuration
+
+### Environment Variables
+- `CYCLECAD_WS_URL` — WebSocket URL (default: `ws://localhost:3000/api/ws`)
+- `CYCLECAD_HTTP_URL` — HTTP URL (default: `http://localhost:3000/api/execute`)
+- `DEBUG_MCP` — Enable debug logging (set to `1`)
+
+### Command Line Arguments
+```
+--ws-url URL        Override WebSocket URL
+--http-url URL      Override HTTP URL
+--debug             Enable debug logging
+--help              Show help message
+--version           Show version
+```
+
+## Implementation Details
+
+### JSON-RPC Protocol
+The MCP server implements JSON-RPC 2.0 over stdio:
+
+**Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "sketch_rect",
+    "arguments": {
+      "width": 50,
+      "height": 30
+    }
+  }
+}
+```
+
+**Response (success):**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"id\":\"rect_1\",\"type\":\"rect\",\"origin\":[0,0],\"width\":50,\"height\":30,\"area\":1500,\"edges\":4}"
+      }
+    ]
+  }
+}
+```
+
+**Response (error):**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"ok\":false,\"error\":\"Required parameter \\\"width\\\" is missing\",\"method\":\"sketch.rect\",\"args\":{}}"
+      }
+    ],
+    "isError": true
+  }
+}
+```
+
+### Tool Naming Convention
+- Agent API method: `sketch.start`
+- MCP tool name: `sketch_start` (underscores instead of dots)
+- Conversion: `name.replace(/_/g, '.')`
+
+### JSON Schema
+Each tool has a full JSON Schema for input validation:
+
+```json
+{
+  "name": "sketch_rect",
+  "description": "Draw a rectangle in the sketch",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "x": { "type": "number", "description": "Origin X" },
+      "y": { "type": "number", "description": "Origin Y" },
+      "width": { "type": "number", "description": "Rectangle width" },
+      "height": { "type": "number", "description": "Rectangle height" }
+    },
+    "required": ["width", "height"]
+  }
+}
+```
+
+## Debugging
+
+### Enable Debug Logging
+```bash
+npx cyclecad-mcp --debug
+```
+
+Debug output goes to stderr and includes:
+- Request/response method names
+- Connection status
+- WebSocket events
+- Error messages
+
+### Example Debug Output
+```
+[MCP] Server ready, waiting for requests...
+[MCP] ← tools/list
+[MCP] → OK
+[MCP] ← tools/call
+[MCP] → OK
+[MCP] WebSocket connected
+[MCP] ← tools/call (via WS)
+[MCP] → OK
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Claude / GPT / Gemini / etc (via Claude API)          │
+└────────────────────┬────────────────────────────────────┘
+                     │
+              MCP Protocol (stdio)
+                     │
+┌────────────────────▼────────────────────────────────────┐
+│  cyclecad-mcp Server (Node.js)                          │
+│  ├─ JSON-RPC dispatch                                   │
+│  ├─ Tool definitions (55+ tools)                        │
+│  ├─ WebSocket connection (preferred)                    │
+│  └─ HTTP fallback                                       │
+└────────────┬──────────────────────┬─────────────────────┘
+             │                      │
+     WebSocket (WS)        HTTP (POST)
+             │                      │
+┌────────────▼─────────────────────▼─────────────────────┐
+│  cycleCAD (Browser or Node.js)                         │
+│  ├─ Agent API (app/js/agent-api.js)                    │
+│  ├─ Modules: sketch, ops, viewport, assembly, etc      │
+│  └─ Three.js scene graph                               │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Testing
+
+### Manual Tool Testing
+```bash
+# Start MCP server
+npx cyclecad-mcp --debug &
+
+# Test sketch_rect tool
+node -e "
+const data = JSON.stringify({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'tools/call',
+  params: {
+    name: 'sketch_rect',
+    arguments: { width: 50, height: 30 }
+  }
+});
+process.stdin.write(data + '\n');
+" | npx cyclecad-mcp --debug
+```
+
+### Full Design Workflow
+```javascript
+const commands = [
+  { method: 'sketch.start', params: { plane: 'XY' } },
+  { method: 'sketch.rect', params: { width: 80, height: 40 } },
+  { method: 'ops.extrude', params: { height: 5, material: 'aluminum' } },
+  { method: 'sketch.start', params: { plane: 'XY' } },
+  { method: 'sketch.circle', params: { cx: 40, cy: 20, radius: 3 } },
+  { method: 'ops.extrude', params: { height: 30, material: 'steel' } },
+  { method: 'validate.designReview', params: { target: 'extrude_1' } },
+  { method: 'export.stl', params: { filename: 'bracket.stl' } }
+];
+
+// Send each command via MCP tools/call
+```
+
+## Performance
+
+- **Startup time**: ~100ms
+- **Tool invocation**: <50ms (JSON-RPC + WebSocket)
+- **Command execution**: Variable (depends on cycleCAD operation)
+- **Memory**: ~50MB baseline
+- **Timeout**: 30 seconds per command (configurable)
+
+## Limitations
+
+1. **Browser-based cycleCAD only**: Server communicates with HTTP/WebSocket endpoints on cycleCAD
+2. **Single session**: One MCP server instance = one cycleCAD session
+3. **No persistence**: Commands are in-memory only (use `export.*` to save)
+4. **No real B-rep**: Boolean operations and fillets use mesh approximations
+5. **Timeout**: 30 second hard timeout per command
+
+## Roadmap
+
+- [ ] Real B-rep boolean operations (OpenCascade.js integration)
+- [ ] Session persistence (save/load projects)
+- [ ] Multi-user collaborative mode
+- [ ] GPU-accelerated rendering
+- [ ] Plugin API for custom tools
+- [ ] Cloud deployment (AWS Lambda, Google Cloud Run)
+
+## License
+
+MIT — See LICENSE in cycleCAD repo
+
+## Contact
+
+- GitHub: https://github.com/vvlars-cmd/cyclecad
+- Email: vvlars@googlemail.com
+- Web: https://cyclecad.com