Initial commit: CNC Part Designer

fluidnumericsJoe · claude · fluidnumericsJoe · commit ee06a9f515d3 · 2026-03-14T09:14:53.000-04:00
Flask app with Claude CLI integration for natural language to SVG generation.
Includes MCP file management server, zoom/pan/rotate preview, and Docker support.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Verify MCP server loads
+        run: uv run python -c "from cnctools.mcp_server import mcp; print('OK')"
+
+      - name: Start server and verify it responds
+        run: |
+          uv run cnctools &
+          for i in $(seq 1 10); do
+            if curl -sf -o /dev/null http://127.0.0.1:5000/; then
+              echo "Server responded with 200"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Server did not respond in time"
+          exit 1
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.cache/
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# Install Node.js (required by claude CLI)
+RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install claude CLI
+RUN npm install -g @anthropic-ai/claude-code
+
+WORKDIR /app
+
+# Install dependencies first for layer caching
+COPY pyproject.toml ./
+RUN uv venv /app/.venv && uv pip install --python /app/.venv/bin/python -e .
+
+# Copy application code
+COPY src/ ./src/
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV CNCTOOLS_WORKSPACE=/workspace
+RUN mkdir -p /workspace
+
+EXPOSE 5000
+
+CMD ["cnctools"]
diff --git a/README.md b/README.md
@@ -0,0 +1,31 @@
+# CNC Part Designer
+
+Describe CNC parts in natural language and get SVG files optimized for VCarve Pro.
+
+## Features
+
+- **Natural language to SVG** — Chat with Claude to design CNC parts
+- **SVG preview** — Zoom, pan, and rotate generated SVGs in the browser
+- **MCP file management** — Save, list, copy, move, and delete SVG files via natural language
+- **Session persistence** — Continue conversations across messages
+
+## Quick Start
+
+```bash
+uv sync
+uv run cnctools
+```
+
+Open http://localhost:5000 in your browser.
+
+## Docker
+
+```bash
+docker compose up --build
+```
+
+## Requirements
+
+- Python 3.11+
+- [Claude CLI](https://github.com/anthropics/claude-code) installed and authenticated
+- [uv](https://docs.astral.sh/uv/) package manager
diff --git a/compose.yaml b/compose.yaml
@@ -0,0 +1,17 @@
+services:
+  cnctools:
+    build: .
+    ports:
+      - "5000:5000"
+    volumes:
+      # Persist claude CLI session data between restarts
+      - claude-data:/root/.claude
+      # Persist workspace files
+      - workspace:/workspace
+    environment:
+      - CNCTOOLS_WORKSPACE=/workspace
+    restart: unless-stopped
+
+volumes:
+  claude-data:
+  workspace:
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,19 @@
+[project]
+name = "cnctools"
+version = "0.1.0"
+description = "CNC Part Designer – describe parts in natural language, get SVG for VCarve Pro"
+requires-python = ">=3.11"
+dependencies = [
+    "flask>=3.0",
+    "mcp>=1.0",
+]
+
+[project.scripts]
+cnctools = "cnctools.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cnctools"]
diff --git a/src/cnctools/__init__.py b/src/cnctools/__init__.py
diff --git a/src/cnctools/app.py b/src/cnctools/app.py
@@ -0,0 +1,34 @@
+import os
+import signal
+import sys
+
+from flask import Flask
+
+from .routes import register_routes
+
+
+def create_app():
+    app = Flask(__name__)
+    register_routes(app)
+
+    @app.before_request
+    def log_request():
+        from flask import request
+        print(f"[cnctools] {request.method} {request.path}", file=sys.stderr, flush=True)
+
+    print("[cnctools] app created, threaded=True", file=sys.stderr, flush=True)
+    return app
+
+
+def main():
+    def handle_sigint(*_):
+        print("\n[cnctools] shutting down...", file=sys.stderr, flush=True)
+        os._exit(0)
+
+    signal.signal(signal.SIGINT, handle_sigint)
+    signal.signal(signal.SIGTERM, handle_sigint)
+    create_app().run(host="0.0.0.0", port=5000, threaded=True, use_reloader=False)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/cnctools/claude_cli.py b/src/cnctools/claude_cli.py
@@ -0,0 +1,77 @@
+import json
+import logging
+import subprocess
+import shlex
+
+from .mcp_config import get_mcp_config_path
+from .prompts import SYSTEM_PROMPT
+
+CLI_TIMEOUT = 300
+log = logging.getLogger(__name__)
+
+
+def invoke_claude(message, session_id, system_prompt=None, mcp_config_path=None, timeout=CLI_TIMEOUT):
+    """Invoke the Claude CLI and return parsed output.
+
+    Returns dict with keys: result, session_id, error
+    """
+    if system_prompt is None:
+        system_prompt = SYSTEM_PROMPT
+    if mcp_config_path is None:
+        mcp_config_path = get_mcp_config_path()
+
+    cmd = [
+        "claude",
+        "-p",
+        message,
+        "--output-format",
+        "json",
+        "--model",
+        "sonnet",
+        "--mcp-config",
+        mcp_config_path,
+    ]
+
+    if session_id:
+        cmd.extend(["--resume", session_id])
+    else:
+        cmd.extend(["--system-prompt", system_prompt])
+
+    print(f"[cnctools] Running: {' '.join(shlex.quote(c) for c in cmd)}", flush=True)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired as e:
+        # Capture any partial output
+        partial_out = (e.stdout or "")[:500] if e.stdout else ""
+        partial_err = (e.stderr or "")[:500] if e.stderr else ""
+        log.error("CLI timed out after %ds. partial stdout=%r partial stderr=%r", timeout, partial_out, partial_err)
+        return {"result": "", "session_id": session_id, "error": f"Claude CLI timed out after {timeout}s"}
+
+    log.info("CLI exited with code %d", result.returncode)
+    if result.stderr:
+        log.info("stderr: %s", result.stderr[:500])
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() if result.stderr else "Unknown error"
+        return {"result": "", "session_id": session_id, "error": f"Claude CLI error: {stderr}"}
+
+    try:
+        output = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        log.error("JSON parse failed. stdout[:500]=%r", result.stdout[:500])
+        return {"result": "", "session_id": session_id, "error": "Failed to parse Claude CLI output"}
+
+    log.info("Success. session_id=%s result_length=%d", output.get("session_id"), len(output.get("result", "")))
+
+    return {
+        "result": output.get("result", ""),
+        "session_id": output.get("session_id", session_id),
+        "error": None,
+    }
diff --git a/src/cnctools/mcp_config.py b/src/cnctools/mcp_config.py
@@ -0,0 +1,44 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+_cached_path = None
+
+
+def get_mcp_config_path(workspace_dir=None):
+    """Generate and cache the MCP config JSON file for the claude CLI.
+
+    Returns the path to the config file.
+    """
+    global _cached_path
+    if _cached_path is not None:
+        return _cached_path
+
+    if workspace_dir is None:
+        workspace_dir = os.environ.get(
+            "CNCTOOLS_WORKSPACE",
+            str(Path.home() / "cnctools-workspace"),
+        )
+
+    # Ensure workspace exists
+    Path(workspace_dir).mkdir(parents=True, exist_ok=True)
+
+    config_dir = Path.home() / ".cache" / "cnctools"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path = config_dir / "mcp-config.json"
+
+    config = {
+        "mcpServers": {
+            "file-manager": {
+                "type": "stdio",
+                "command": sys.executable,
+                "args": ["-m", "cnctools.mcp_server"],
+                "env": {"CNCTOOLS_WORKSPACE": workspace_dir},
+            }
+        }
+    }
+
+    config_path.write_text(json.dumps(config, indent=2))
+    _cached_path = str(config_path)
+    return _cached_path
diff --git a/src/cnctools/mcp_server.py b/src/cnctools/mcp_server.py
@@ -0,0 +1,73 @@
+import os
+import shutil
+from glob import glob
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+WORKSPACE = Path(os.environ.get("CNCTOOLS_WORKSPACE", Path.home() / "cnctools-workspace"))
+
+mcp = FastMCP("file-manager")
+
+
+def _safe_path(filename):
+    """Resolve a filename within the workspace, preventing directory traversal."""
+    resolved = (WORKSPACE / filename).resolve()
+    if not str(resolved).startswith(str(WORKSPACE.resolve())):
+        raise ValueError(f"Path {filename!r} escapes the workspace directory")
+    return resolved
+
+
+@mcp.tool()
+def list_files(pattern: str = "*.svg") -> list[str]:
+    """List files in the workspace matching a glob pattern."""
+    WORKSPACE.mkdir(parents=True, exist_ok=True)
+    matches = glob(str(WORKSPACE / pattern))
+    return [os.path.basename(m) for m in sorted(matches)]
+
+
+@mcp.tool()
+def move_file(source: str, destination: str) -> str:
+    """Move or rename a file within the workspace."""
+    src = _safe_path(source)
+    dst = _safe_path(destination)
+    if not src.exists():
+        return f"Error: {source!r} not found"
+    shutil.move(str(src), str(dst))
+    return f"Moved {source} -> {destination}"
+
+
+@mcp.tool()
+def copy_file(source: str, destination: str) -> str:
+    """Copy a file within the workspace."""
+    src = _safe_path(source)
+    dst = _safe_path(destination)
+    if not src.exists():
+        return f"Error: {source!r} not found"
+    shutil.copy2(str(src), str(dst))
+    return f"Copied {source} -> {destination}"
+
+
+@mcp.tool()
+def delete_file(filename: str) -> str:
+    """Delete a file from the workspace."""
+    path = _safe_path(filename)
+    if not path.exists():
+        return f"Error: {filename!r} not found"
+    path.unlink()
+    return f"Deleted {filename}"
+
+
+@mcp.tool()
+def save_svg(filename: str, content: str) -> str:
+    """Save SVG content to a file in the workspace."""
+    if not filename.endswith(".svg"):
+        filename += ".svg"
+    path = _safe_path(filename)
+    WORKSPACE.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return f"Saved {filename} ({len(content)} bytes)"
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")
diff --git a/src/cnctools/prompts.py b/src/cnctools/prompts.py
@@ -0,0 +1,15 @@
+SYSTEM_PROMPT = """You are a CNC part designer. You generate SVG files optimized for import into VCarve Pro.
+
+SVG Rules:
+- Use real-world units: inches. Map to viewBox using 96 DPI (1 inch = 96 px).
+- Use stroke-only paths with no fill (fill="none", stroke="black", stroke-width="0.5").
+- VCarve interprets strokes as cut paths.
+- Only use CNC-compatible SVG elements: path, line, circle, rect, polygon, ellipse.
+- Prefer arc commands (A) over cubic beziers (C) for curves — arcs produce cleaner G-code.
+- Use exact dimensions and clean coordinates (no unnecessary decimals).
+- Group related features with <g> elements using descriptive id attributes.
+- Always include xmlns="http://www.w3.org/2000/svg" on the root <svg> element.
+- Set width and height attributes in inches (e.g., width="4in" height="6in").
+- Place the SVG inside a markdown code fence tagged as ```svg.
+- After the SVG, briefly describe what you generated and the key dimensions.
+- If the user asks for modifications, output the complete updated SVG (not a partial diff)."""
diff --git a/src/cnctools/routes.py b/src/cnctools/routes.py
diff --git a/src/cnctools/svg.py b/src/cnctools/svg.py
diff --git a/src/cnctools/templates/index.html b/src/cnctools/templates/index.html
diff --git a/uv.lock b/uv.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +__pycache__/
 +*.pyc
 +.venv/
 +*.egg-info/
 +dist/
 +build/
 +.cache/