cyclecad 0.2.2 → 0.3.0

package/QUICKSTART-CLI.md

@@ -0,0 +1,211 @@
+# cycleCAD CLI Quick Start
+
+Get started with the cycleCAD command-line interface in 5 minutes.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g cyclecad
+
+# Or use locally in the project
+cd ~/cyclecad
+```
+
+## Start the Server
+
+In one terminal:
+```bash
+# Start mock server (for development)
+node bin/server.js
+
+# Output:
+#   cyclecad Agent API mock server running on http://localhost:3000
+```
+
+## Basic Commands
+
+In another terminal, try these commands:
+
+### 1. Create a Shape
+```bash
+node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80
+```
+
+Output:
+```
+[10:37:35] ✓ Command executed: shape.cylinder
+  Entity ID: cylinder_1774521455193
+```
+
+### 2. Create a Box
+```bash
+node bin/cyclecad-cli.js shape.box --width 50 --height 40 --depth 30
+```
+
+### 3. Sketch Operations
+```bash
+# Start sketch
+node bin/cyclecad-cli.js sketch.start --plane XY
+
+# Draw a circle
+node bin/cyclecad-cli.js sketch.circle --cx 0 --cy 0 --radius 15
+
+# End sketch
+node bin/cyclecad-cli.js sketch.end
+```
+
+### 4. Features
+```bash
+# Extrude
+node bin/cyclecad-cli.js feature.extrude --height 10
+
+# Add fillet
+node bin/cyclecad-cli.js feature.fillet --radius 5 --edges all
+```
+
+### 5. Validation
+```bash
+# Check dimensions
+node bin/cyclecad-cli.js validate.dimensions --target extrude_1
+
+# Estimate cost
+node bin/cyclecad-cli.js validate.cost --target extrude_1 --process CNC --material aluminum
+
+# Estimate weight
+node bin/cyclecad-cli.js validate.mass --target extrude_1 --material aluminum
+```
+
+### 6. Export
+```bash
+# Export to STL
+node bin/cyclecad-cli.js export.stl --filename my-part.stl --binary true
+```
+
+## Get Help
+
+### List all commands
+```bash
+node bin/cyclecad-cli.js --list
+```
+
+### Get help for a specific command
+```bash
+node bin/cyclecad-cli.js --describe shape.cylinder
+```
+
+### Show version
+```bash
+node bin/cyclecad-cli.js --version
+```
+
+## Output Modes
+
+### Pretty-printed (default)
+```bash
+node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80
+```
+
+### JSON output (for scripts)
+```bash
+node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80 --json
+```
+
+### Quiet mode (suppress status messages)
+```bash
+node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80 --quiet
+```
+
+## Interactive REPL
+
+Start an interactive session:
+```bash
+node bin/cyclecad-cli.js --interactive
+```
+
+Then type commands directly:
+```
+cyclecad> shape.cylinder --radius 25 --height 80
+✓ Command executed: shape.cylinder
+
+cyclecad> validate.cost --target cylinder_1 --process FDM
+[10:37:35] ✓ Command executed: validate.cost
+
+cyclecad> help
+Available Commands
+...
+
+cyclecad> exit
+Goodbye!
+```
+
+## Batch Mode
+
+Create a script file `my-commands.txt`:
+```
+shape.cylinder --radius 25 --height 80
+feature.fillet --radius 3 --edges all
+validate.dimensions --target cylinder_1
+export.stl --filename output.stl
+```
+
+Execute it:
+```bash
+node bin/cyclecad-cli.js --batch my-commands.txt
+```
+
+## Use from Shell Scripts
+
+```bash
+#!/bin/bash
+
+# Create and export a part
+ENTITY=$(node bin/cyclecad-cli.js shape.cylinder --radius 25 --height 80 --json | jq -r '.entityId')
+echo "Created entity: $ENTITY"
+
+node bin/cyclecad-cli.js feature.fillet --radius 5 --edges all --quiet
+node bin/cyclecad-cli.js export.stl --filename bracket.stl
+```
+
+## Next Steps
+
+- Read the full [CLI documentation](docs/CLI.md)
+- Check out example batch files in `examples/`
+- Integrate with your CAD workflow
+- Build automation scripts
+
+## Troubleshooting
+
+### "Connection failed"
+Make sure the server is running in another terminal:
+```bash
+node bin/server.js
+```
+
+### "Unknown command"
+List available commands:
+```bash
+node bin/cyclecad-cli.js --list
+node bin/cyclecad-cli.js --describe <command>
+```
+
+### JSON parsing errors
+Make sure you're in the right directory and have Node.js 14+ installed:
+```bash
+node --version
+```
+
+## Key Features
+
+✅ **Zero dependencies** — Pure Node.js built-ins
+✅ **Colored output** — Easy to read terminal UI
+✅ **JSON support** — Perfect for scripting
+✅ **Interactive mode** — Great for exploration
+✅ **Batch processing** — Automate workflows
+✅ **Tab completion** — Type less, do more
+✅ **Command history** — Replay previous commands
+✅ **Extensible** — Easy to add new commands
+
+---
+
+For the full API reference, see [docs/CLI.md](docs/CLI.md)

package/QUICKSTART-MCP.md

@@ -0,0 +1,196 @@
+# cycleCAD MCP Server — Quick Start
+
+## 30-Second Setup
+
+```bash
+# Terminal 1: Start cycleCAD web server
+npm start
+
+# Terminal 2: Start MCP server
+npm run mcp
+```
+
+Done! The server is now ready to receive MCP requests from Claude.
+
+## Integration with Claude
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=2048,
+    tools=[{
+        "type": "model_context_protocol",
+        "name": "cyclecad-mcp",
+        "uri": "stdio:///absolute/path/to/cyclecad/bin/cyclecad-mcp"
+    }],
+    messages=[{
+        "role": "user",
+        "content": "Design a bracket: 80x40mm rectangle, extrude 5mm, add a 3mm hole for a bolt"
+    }]
+)
+
+print(response.content[0].text)
+```
+
+Claude will automatically call cycleCAD tools to design the part.
+
+## What You Can Do
+
+### Ask Claude to design parts
+- "Create a cylinder 50mm diameter, 100mm tall"
+- "Design a bracket: 80x40mm, 5mm thick, with a hole"
+- "Make a spring with 10mm radius, 20mm height, 5 turns"
+
+### Ask Claude to analyze designs
+- "Is this part printable with FDM?"
+- "What's the weight if made from aluminum?"
+- "Check the design for manufacturing issues"
+
+### Ask Claude to modify designs
+- "Add a 2mm fillet to all edges"
+- "Chamfer the corners by 1mm"
+- "Create 3 copies of this in a 10mm grid"
+
+### Ask Claude to export
+- "Export as STL for 3D printing"
+- "Save as OBJ for rendering"
+- "Export as glTF for web viewing"
+
+## Debug Mode
+
+```bash
+# See all requests and responses
+DEBUG_MCP=1 npm run mcp
+
+# Or
+npx cyclecad-mcp --debug
+```
+
+## Configuration
+
+```bash
+# Custom cycleCAD server URL
+npx cyclecad-mcp --ws-url ws://10.0.0.1:3000/api/ws
+
+# Custom HTTP fallback URL
+npx cyclecad-mcp --http-url http://10.0.0.1:3000/api/execute
+```
+
+## All Tools (55+)
+
+**Sketch** (8): start, end, line, rect, circle, arc, clear, entities
+
+**Design** (20): extrude, revolve, primitive, fillet, chamfer, boolean, shell, pattern, material, sweep, loft, spring, thread, bend
+
+**Transform** (3): move, rotate, scale
+
+**View** (4): set, fit, wireframe, grid
+
+**Export** (4): stl, obj, gltf, json
+
+**Validate** (8): dimensions, wallThickness, printability, cost, mass, surfaceArea, centerOfMass, designReview
+
+**Render** (5): snapshot, multiview, highlight, hide, section
+
+**Query** (5): features, bbox, materials, session, log
+
+**Assembly** (4): addComponent, removeComponent, mate, explode
+
+**AI** (3): identifyPart, suggestImprovements, estimateCostAI
+
+**Meta** (5): ping, version, schema, modules, history
+
+**Scene** (2): clear, snapshot
+
+## Full Documentation
+
+- **Complete Reference**: `docs/MCP-SERVER.md`
+- **Implementation Details**: `IMPLEMENTATION.md`
+- **Examples & Workflows**: (See examples in this file)
+
+## Troubleshooting
+
+**"Connection refused"**
+- Make sure cycleCAD is running: `npm start`
+- Check it's on localhost:3000: `curl http://localhost:3000`
+
+**"WebSocket not available"**
+- MCP server falls back to HTTP automatically
+- No action needed
+
+**"No response from cycleCAD"**
+- cycleCAD may not be running or Agent API not accessible
+- Commands are queued and will execute when cycleCAD connects
+- Check `DEBUG_MCP=1 npm run mcp` for more info
+
+**"Tool not found"**
+- Tool names use underscores: `sketch_rect` not `sketch.rect`
+- See list of all tools above
+
+## Performance
+
+- **Startup**: ~100ms
+- **Tool invocation**: <50ms
+- **Command execution**: Varies (depends on cycleCAD operation)
+- **Memory**: ~50MB
+
+## Architecture
+
+```
+You (write prompts)
+    ↓
+Claude API
+    ↓
+Claude calls cycleCAD tools via MCP
+    ↓
+MCP Server (cyclecad-mcp)
+    ↓
+cycleCAD (Three.js scene)
+    ↓
+Design output (STL, OBJ, glTF, or rendered)
+```
+
+## Environment Variables
+
+```bash
+CYCLECAD_WS_URL=ws://localhost:3000/api/ws
+CYCLECAD_HTTP_URL=http://localhost:3000/api/execute
+DEBUG_MCP=1  # Enable debug logging
+```
+
+## Next Steps
+
+1. Start cycleCAD: `npm start`
+2. Start MCP server: `npm run mcp`
+3. Use with Claude API (see Integration section above)
+4. Read full docs: `docs/MCP-SERVER.md`
+
+## Example Interaction
+
+**You to Claude:**
+> "Design a simple bracket for mounting a motor. Make it 100x80mm base, 10mm thick, with 4 mounting holes (8mm diameter) spaced 10mm from the edges. Add 2mm fillets to all edges."
+
+**Claude calls tools (automatically):**
+1. `sketch.start` (XY plane)
+2. `sketch.rect` (width: 100, height: 80)
+3. `ops.extrude` (height: 10, material: aluminum)
+4. `sketch.start` (XY plane)
+5. `sketch.circle` (radius: 4, at each corner)
+6. `ops.extrude` (height: 10)
+7. `ops.boolean` (union) [x4 for each hole]
+8. `ops.fillet` (radius: 2, all edges)
+9. `validate.designReview` (check printability)
+10. `export.stl` (filename: bracket.stl)
+
+**Claude to you:**
+> "I've designed a mounting bracket with the specifications you requested. It's 100x80mm with 10mm thickness, has 4 mounting holes at the corners with 2mm fillets on all edges. The design is optimized for 3D printing and the file has been exported as bracket.stl."
+
+## Support
+
+- **Issues**: https://github.com/vvlars-cmd/cyclecad/issues
+- **Email**: vvlars@googlemail.com
+- **Web**: https://cyclecad.com

package/README-MCP.md

@@ -0,0 +1,208 @@
+# cycleCAD MCP Server
+
+**Model Context Protocol (MCP) server** for cycleCAD Agent API.
+
+Exposes all 55+ design commands as MCP tools that can be called by LLMs (Claude, GPT, Gemini, etc).
+
+## ⚡ Quick Start
+
+### 1. Start cycleCAD web server
+```bash
+npm start
+# Runs on http://localhost:3000
+```
+
+### 2. Start MCP server
+```bash
+npx cyclecad-mcp
+# Or: npm run mcp
+```
+
+The MCP server reads JSON-RPC requests from stdin and writes responses to stdout.
+
+### 3. Use with Claude API
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=2048,
+    tools=[
+        {
+            "type": "model_context_protocol",
+            "name": "cyclecad-mcp",
+            "uri": "stdio:///path/to/cyclecad/bin/cyclecad-mcp"
+        }
+    ],
+    messages=[
+        {
+            "role": "user",
+            "content": "Design a bracket: 80x40mm rectangle, 5mm tall, with a 3mm hole for a bolt"
+        }
+    ]
+)
+
+print(response.content[0].text)
+```
+
+Claude will automatically call the MCP tools to design the bracket.
+
+## 📋 Available Tools (55+)
+
+### Sketch Tools (8)
+- `sketch_start`, `sketch_end`
+- `sketch_line`, `sketch_rect`, `sketch_circle`, `sketch_arc`
+- `sketch_clear`, `sketch_entities`
+
+### Design Tools (20)
+- `ops_extrude`, `ops_revolve`, `ops_primitive`
+- `ops_fillet`, `ops_chamfer`, `ops_boolean`
+- `ops_shell`, `ops_pattern`, `ops_material`
+- `ops_sweep`, `ops_loft`, `ops_spring`, `ops_thread`, `ops_bend`
+
+### Transform Tools (3)
+- `transform_move`, `transform_rotate`, `transform_scale`
+
+### View Tools (4)
+- `view_set`, `view_fit`, `view_wireframe`, `view_grid`
+
+### Export Tools (4)
+- `export_stl`, `export_obj`, `export_gltf`, `export_json`
+
+### Validation Tools (8)
+- `validate_dimensions`, `validate_wallThickness`
+- `validate_printability`, `validate_cost`, `validate_mass`
+- `validate_surfaceArea`, `validate_centerOfMass`
+- `validate_designReview` (A/B/C/F scoring)
+
+### Render Tools (5)
+- `render_snapshot`, `render_multiview`
+- `render_highlight`, `render_hide`, `render_section`
+
+### Query Tools (5)
+- `query_features`, `query_bbox`, `query_materials`
+- `query_session`, `query_log`
+
+### Assembly Tools (4)
+- `assembly_addComponent`, `assembly_removeComponent`
+- `assembly_mate`, `assembly_explode`
+
+### AI Tools (3)
+- `ai_identifyPart`, `ai_suggestImprovements`, `ai_estimateCostAI`
+
+### Meta Tools (5)
+- `meta_ping`, `meta_version`, `meta_schema`, `meta_modules`, `meta_history`
+
+### Scene Tools (2)
+- `scene_clear`, `scene_snapshot`
+
+## 🔧 Configuration
+
+```bash
+# Custom WebSocket URL
+npx cyclecad-mcp --ws-url ws://10.0.0.1:3000/api/ws
+
+# Custom HTTP URL (fallback)
+npx cyclecad-mcp --http-url http://10.0.0.1:3000/api/execute
+
+# Debug mode
+npx cyclecad-mcp --debug
+
+# Help
+npx cyclecad-mcp --help
+```
+
+Environment variables:
+```bash
+export CYCLECAD_WS_URL=ws://localhost:3000/api/ws
+export CYCLECAD_HTTP_URL=http://localhost:3000/api/execute
+export DEBUG_MCP=1
+```
+
+## 📚 Documentation
+
+- **Full API Reference**: See `docs/MCP-SERVER.md`
+- **Example Workflows**: See `docs/EXAMPLES.md`
+- **Architecture**: See `docs/ARCHITECTURE.md`
+
+## 🧪 Testing
+
+The MCP server can be tested without Claude API:
+
+```bash
+# Test with stdio
+echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | npx cyclecad-mcp
+
+# Get available tools
+echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | npx cyclecad-mcp
+echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' | npx cyclecad-mcp
+
+# Call a tool
+echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | npx cyclecad-mcp
+echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sketch_rect", "arguments": {"width": 50, "height": 30}}}' | npx cyclecad-mcp
+```
+
+## 🏗️ Architecture
+
+```
+Claude API
+    ↓
+MCP Protocol (stdio)
+    ↓
+cyclecad-mcp Server
+    ├─ JSON-RPC dispatch
+    ├─ Tool definitions (55+)
+    └─ Connection management
+         ├─ WebSocket (preferred)
+         └─ HTTP (fallback)
+    ↓
+cycleCAD (Browser or Server)
+    ├─ Agent API
+    ├─ Sketch module
+    ├─ Operations module
+    ├─ Viewport (Three.js)
+    └─ Assembly
+```
+
+## 🚀 Features
+
+- ✅ **55+ Tools** — All Agent API commands as MCP tools
+- ✅ **JSON Schema** — Full input validation
+- ✅ **Error Handling** — Descriptive error messages
+- ✅ **Non-blocking** — Works even if cycleCAD not running (queues commands)
+- ✅ **Dual Transport** — WebSocket + HTTP fallback
+- ✅ **Debug Mode** — Full request/response logging
+- ✅ **Zero Dependencies** — Uses only Node.js built-ins
+
+## 📦 Package Scripts
+
+```bash
+npm start          # Start cycleCAD web server
+npm run mcp        # Start MCP server
+npm run dev        # Dev mode
+npm run cli        # CLI mode
+npm run server     # API server
+```
+
+## 🔗 Related Docs
+
+- [Full MCP Server Documentation](docs/MCP-SERVER.md)
+- [Agent API Reference](docs/AGENT-API.md)
+- [Examples & Workflows](docs/EXAMPLES.md)
+
+## 📝 License
+
+MIT — See LICENSE in root
+
+## 🤝 Contributing
+
+Issues & PRs welcome at https://github.com/vvlars-cmd/cyclecad
+
+## 📧 Contact
+
+- Email: vvlars@googlemail.com
+- Web: https://cyclecad.com
+- GitHub: https://github.com/vvlars-cmd/cyclecad