cura-mcp 0.1.0__tar.gz

cura_mcp-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# --- Project-specific ---
+# Internal build specs: local reference for the implementation agent, never shipped.
+specs/
+docs/
+# Local agent/dev context (implementation guide for the coding agent), never shipped.
+CLAUDE.md
+# Local dogfooding instrumentation (Layer-1 logger + local bridge entrypoint): kept
+# on disk for local use, never published. The public cura_mcp package has no
+# reference to it (see cura_dogfood/bridge.py).
+cura_dogfood/
+# Local auth token written by the Cura plugin at runtime (see SECURITY).
+*.cura-mcp-token
+.cura-mcp/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# --- Editors / OS ---
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# --- Logs / local artifacts ---
+logs/
+*.log
+*.gcode
+*.stl
+*.3mf
+!examples/**/*.stl
+!examples/**/*.3mf

cura_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: cura-mcp
+Version: 0.1.0
+Summary: Local MCP server that drives the UltiMaker Cura slicer. No hub, no telemetry.
+Author-email: padymies <padymies@gmail.com>
+License: MIT
+Keywords: 3d-printing,cura,mcp,model-context-protocol,slicer
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cura-mcp (bridge)
+
+The MCP server. Speaks MCP to your AI client and forwards each tool call to the
+Cura plugin over loopback HTTP. Knows nothing about Cura internals — it is pure
+transport, schemas, and error mapping.
+
+## Run (users)
+
+Users don't install this directly — their MCP client launches it via
+[`uv`](https://docs.astral.sh/uv/): `uvx cura-mcp` (see the top-level
+[`README`](../README.md#install)). `uv` brings its own Python, so no separate
+Python install is required.
+
+## Install (dev)
+
+```bash
+cd mcp-server
+pip install -e ".[dev]"
+python -m cura_mcp.server
+```
+
+Requires Cura running with the `cura-plugin` installed (the bridge fails fast
+with a clear error otherwise). Configuration via env vars — see `config.py`:
+
+- `CURA_MCP_HOST` (default `127.0.0.1`)
+- `CURA_MCP_PORT` (default `8765`)
+- `CURA_MCP_TOKEN_FILE` (default: platform user dir `~/.cura-mcp/token`)
+- `CURA_MCP_TIMEOUT` (default `30` seconds; slice waits use a longer timeout)
+
+## Layout
+
+```
+src/cura_mcp/
+  server.py     MCP entrypoint; registers tools
+  client.py     HTTP client to the plugin (token-authenticated)
+  models.py     pydantic schemas (tool I/O + plugin contract)
+  config.py     settings
+  errors.py     typed error hierarchy
+  tools/        one module per tool
+```

cura_mcp-0.1.0/README.md

@@ -0,0 +1,40 @@
+# cura-mcp (bridge)
+
+The MCP server. Speaks MCP to your AI client and forwards each tool call to the
+Cura plugin over loopback HTTP. Knows nothing about Cura internals — it is pure
+transport, schemas, and error mapping.
+
+## Run (users)
+
+Users don't install this directly — their MCP client launches it via
+[`uv`](https://docs.astral.sh/uv/): `uvx cura-mcp` (see the top-level
+[`README`](../README.md#install)). `uv` brings its own Python, so no separate
+Python install is required.
+
+## Install (dev)
+
+```bash
+cd mcp-server
+pip install -e ".[dev]"
+python -m cura_mcp.server
+```
+
+Requires Cura running with the `cura-plugin` installed (the bridge fails fast
+with a clear error otherwise). Configuration via env vars — see `config.py`:
+
+- `CURA_MCP_HOST` (default `127.0.0.1`)
+- `CURA_MCP_PORT` (default `8765`)
+- `CURA_MCP_TOKEN_FILE` (default: platform user dir `~/.cura-mcp/token`)
+- `CURA_MCP_TIMEOUT` (default `30` seconds; slice waits use a longer timeout)
+
+## Layout
+
+```
+src/cura_mcp/
+  server.py     MCP entrypoint; registers tools
+  client.py     HTTP client to the plugin (token-authenticated)
+  models.py     pydantic schemas (tool I/O + plugin contract)
+  config.py     settings
+  errors.py     typed error hierarchy
+  tools/        one module per tool
+```

cura_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cura-mcp"
+version = "0.1.0"
+description = "Local MCP server that drives the UltiMaker Cura slicer. No hub, no telemetry."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "padymies", email = "padymies@gmail.com" }]
+keywords = ["mcp", "cura", "3d-printing", "slicer", "model-context-protocol"]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+cura-mcp = "cura_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cura_mcp"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

cura_mcp-0.1.0/src/cura_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""cura-mcp: a local MCP server that drives the UltiMaker Cura slicer."""
+
+__version__ = "0.1.0"

cura_mcp-0.1.0/src/cura_mcp/client.py

@@ -0,0 +1,59 @@
+"""HTTP client to the Cura plugin's local server.
+
+Reads the per-session token written by the plugin, injects it on every request,
+and maps the plugin's structured error envelope back to typed exceptions. This is
+the only place the bridge talks to the plugin.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Settings
+from .errors import CuraNotRunning, from_plugin_code
+from .models import PluginResponse
+
+
+class PluginClient:
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._client = httpx.AsyncClient(base_url=settings.base_url, timeout=settings.timeout)
+
+    def _read_token(self) -> str:
+        try:
+            return self._settings.token_file.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise CuraNotRunning(
+                "No Cura plugin token found. Is Cura running with the cura-mcp plugin?"
+            ) from exc
+
+    async def call(
+        self,
+        method: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Call a plugin method; return ``data`` on success, raise a typed error otherwise."""
+        token = self._read_token()
+        try:
+            resp = await self._client.post(
+                "/rpc",
+                json={"method": method, "params": payload or {}},
+                headers={"X-Cura-Mcp-Token": token, "Host": self._settings.host},
+                timeout=timeout or self._settings.timeout,
+            )
+        except httpx.ConnectError as exc:
+            raise CuraNotRunning(
+                "Could not reach the Cura plugin server. Is Cura open?"
+            ) from exc
+
+        body = PluginResponse.model_validate(resp.json())
+        if body.ok:
+            return body.data or {}
+        assert body.error is not None
+        raise from_plugin_code(body.error.code, body.error.message)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

cura_mcp-0.1.0/src/cura_mcp/config.py

@@ -0,0 +1,42 @@
+"""Bridge configuration. All values overridable via environment variables.
+
+The token-file path is the shared contract with the plugin: the plugin writes
+the per-session token there, the bridge reads it. Keep both sides in sync.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _default_token_file() -> Path:
+    # Mirrors the plugin's token location (see cura-plugin/server/auth.py).
+    return Path.home() / ".cura-mcp" / "token"
+
+
+@dataclass(frozen=True)
+class Settings:
+    host: str = os.environ.get("CURA_MCP_HOST", "127.0.0.1")
+    port: int = int(os.environ.get("CURA_MCP_PORT", "8765"))
+    token_file: Path = Path(os.environ.get("CURA_MCP_TOKEN_FILE", "")) or _default_token_file()
+    # General request timeout (seconds). Slicing uses slice_timeout instead.
+    timeout: float = float(os.environ.get("CURA_MCP_TIMEOUT", "30"))
+    slice_timeout: float = float(os.environ.get("CURA_MCP_SLICE_TIMEOUT", "300"))
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+
+def load_settings() -> Settings:
+    # Resolve token_file explicitly (dataclass default expr runs at import time).
+    env_token = os.environ.get("CURA_MCP_TOKEN_FILE")
+    token_file = Path(env_token) if env_token else _default_token_file()
+    return Settings(
+        host=os.environ.get("CURA_MCP_HOST", "127.0.0.1"),
+        port=int(os.environ.get("CURA_MCP_PORT", "8765")),
+        token_file=token_file,
+        timeout=float(os.environ.get("CURA_MCP_TIMEOUT", "30")),
+        slice_timeout=float(os.environ.get("CURA_MCP_SLICE_TIMEOUT", "300")),
+    )

cura_mcp-0.1.0/src/cura_mcp/errors.py

@@ -0,0 +1,117 @@
+"""Typed error hierarchy for the bridge.
+
+Tool functions catch these and return structured errors to the LLM rather than
+leaking stack traces. The plugin returns an error ``code`` in its JSON response;
+``from_plugin_code`` maps it back to the right class.
+"""
+from __future__ import annotations
+
+
+class CuraMcpError(Exception):
+    """Base class for all bridge-surfaced errors."""
+
+    code = "cura_mcp_error"
+
+
+class CuraNotRunning(CuraMcpError):
+    """The plugin's local server could not be reached (Cura not open?)."""
+
+    code = "cura_not_running"
+
+
+class AuthError(CuraMcpError):
+    """Token missing/invalid, or request rejected by the plugin's auth layer."""
+
+    code = "auth_error"
+
+
+class InvalidPath(CuraMcpError):
+    """load_model path failed the plugin's sandbox (allow-list / traversal / ext)."""
+
+    code = "invalid_path"
+
+
+class NodeNotFound(CuraMcpError):
+    """No model on the plate matches the given node_id."""
+
+    code = "node_not_found"
+
+
+class ExportFailed(CuraMcpError):
+    """Writing the mesh to disk failed (no writer for the format, or I/O error)."""
+
+    code = "export_failed"
+
+
+class UnknownSetting(CuraMcpError):
+    """The setting key does not exist in the active machine definition."""
+
+    code = "unknown_setting"
+
+
+class InvalidSettingValue(CuraMcpError):
+    """The value is the wrong type or outside the setting's allowed range/options."""
+
+    code = "invalid_setting_value"
+
+
+class PerExtruderUnsupported(CuraMcpError):
+    """The setting is per-extruder; v1 of the settings API handles global only."""
+
+    code = "per_extruder_unsupported"
+
+
+class UnknownProfile(CuraMcpError):
+    """No machine/material/quality profile matches the given name."""
+
+    code = "unknown_profile"
+
+
+class LoadFailed(CuraMcpError):
+    """The model load did not complete (e.g. timed out or the reader failed)."""
+
+    code = "load_failed"
+
+
+class SliceFailed(CuraMcpError):
+    """The slice ended in an error state or the model was unsliceable."""
+
+    code = "slice_failed"
+
+
+class SliceTimeout(CuraMcpError):
+    """The slice did not settle within the timeout."""
+
+    code = "slice_timeout"
+
+
+class NoActiveProfile(CuraMcpError):
+    """No machine/material profile is active; estimates would be meaningless."""
+
+    code = "no_active_profile"
+
+
+_BY_CODE = {
+    cls.code: cls
+    for cls in (
+        CuraMcpError,
+        CuraNotRunning,
+        AuthError,
+        InvalidPath,
+        NodeNotFound,
+        ExportFailed,
+        UnknownSetting,
+        InvalidSettingValue,
+        PerExtruderUnsupported,
+        UnknownProfile,
+        LoadFailed,
+        SliceFailed,
+        SliceTimeout,
+        NoActiveProfile,
+    )
+}
+
+
+def from_plugin_code(code: str, message: str) -> CuraMcpError:
+    """Build the right error subtype from a plugin error code."""
+    return _BY_CODE.get(code, CuraMcpError)(message)