threecrate-mcp 0.1.0__py3-none-any.whl

threecrate_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server that gives AI agents threecrate's point cloud and mesh tools."""
+
+__version__ = "0.1.0"

threecrate_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

threecrate_mcp/ops.py

@@ -0,0 +1,563 @@
+"""Point cloud and mesh operations behind the MCP tools.
+
+Each function reads its inputs from files, runs a threecrate operation, writes
+any result to a file, and returns a small summary dict. Point data never goes
+back to the agent: a large scan would flood its context.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional, Sequence
+
+import numpy as np
+import threecrate as tc
+
+from .workspace import MESH_FORMATS, POINT_CLOUD_WRITE_FORMATS, Workspace, WorkspaceError
+
+# Points sampled when estimating spacing; enough for a stable median.
+SPACING_SAMPLE = 2000
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _header_point_count(path: Path) -> Optional[int]:
+    """The point count a PLY or PCD header declares, read without loading the
+    points; None for other formats or an unreadable header."""
+    suffix = path.suffix.lower()
+    if suffix not in {".ply", ".pcd"}:
+        return None
+    try:
+        with open(path, "rb") as fh:
+            for _ in range(200):  # headers are short; give up on anything odd
+                line = fh.readline()
+                if not line:
+                    return None
+                words = line.decode("ascii", errors="replace").split()
+                if suffix == ".ply" and words[:2] == ["element", "vertex"] and len(words) == 3:
+                    return int(words[2])
+                if suffix == ".pcd" and words[:1] == ["POINTS"] and len(words) == 2:
+                    return int(words[1])
+                if words[:1] in (["end_header"], ["DATA"]):
+                    return None
+    except (OSError, ValueError):
+        return None
+    return None
+
+
+def _read_cloud(ws: Workspace, path: str) -> tuple[Path, "tc.PointCloud"]:
+    resolved = ws.input_path(path)
+    # Refuse oversized files before loading them, when the header says how big.
+    declared = _header_point_count(resolved)
+    if declared is not None:
+        ws.check_size(declared, resolved)
+    try:
+        cloud = tc.read_point_cloud(str(resolved))
+    except Exception as exc:  # threecrate raises plain exceptions for bad files
+        raise WorkspaceError(f"could not read {path} as a point cloud: {exc}") from exc
+    ws.check_size(len(cloud), resolved)
+    if len(cloud) == 0:
+        raise WorkspaceError(f"{path} contains no points")
+    return resolved, cloud
+
+
+def _read_mesh(ws: Workspace, path: str) -> tuple[Path, "tc.TriangleMesh"]:
+    resolved = ws.input_path(path)
+    try:
+        mesh = tc.read_mesh(str(resolved))
+    except Exception as exc:
+        raise WorkspaceError(f"could not read {path} as a mesh: {exc}") from exc
+    if mesh.is_empty:
+        raise WorkspaceError(f"{path} contains no triangles")
+    return resolved, mesh
+
+
+def _bounds(points: np.ndarray) -> dict:
+    finite = points[np.isfinite(points).all(axis=1)]
+    if len(finite) == 0:
+        return {"finite_points": 0}
+    lo = finite.min(axis=0)
+    hi = finite.max(axis=0)
+    return {
+        "finite_points": int(len(finite)),
+        "min": [round(float(v), 6) for v in lo],
+        "max": [round(float(v), 6) for v in hi],
+        "extent": [round(float(v), 6) for v in hi - lo],
+        "centroid": [round(float(v), 6) for v in finite.mean(axis=0)],
+    }
+
+
+def _spacing(cloud: "tc.PointCloud") -> Optional[float]:
+    """Median distance from a point to its nearest neighbour, on a sample."""
+    points = cloud.to_numpy()
+    finite = points[np.isfinite(points).all(axis=1)]
+    if len(finite) < 2:
+        return None
+    rng = np.random.default_rng(0)
+    sample = finite[rng.choice(len(finite), size=min(SPACING_SAMPLE, len(finite)), replace=False)]
+    tree = tc.KdTree(cloud)
+    distances = []
+    for query in sample:
+        _, dist = tree.knn(query, 2)
+        # The first neighbour is the point itself (distance 0).
+        others = [d for d in dist if d > 0]
+        if others:
+            distances.append(others[0])
+    return float(np.median(distances)) if distances else None
+
+
+def _cloud_summary(cloud: "tc.PointCloud") -> dict:
+    return {"points": len(cloud), **_bounds(cloud.to_numpy())}
+
+
+def _mesh_summary(mesh: "tc.TriangleMesh") -> dict:
+    return {
+        "vertices": mesh.vertex_count,
+        "faces": mesh.face_count,
+        **{k: v for k, v in _bounds(mesh.vertices()).items() if k != "finite_points"},
+    }
+
+
+def _write_cloud(cloud: "tc.PointCloud", path: Path) -> None:
+    tc.write_point_cloud(cloud, str(path))
+
+
+def _write_ply_with_normals(positions: np.ndarray, normals: np.ndarray, path: Path) -> None:
+    """Binary PLY with x y z nx ny nz (threecrate's writer only stores positions)."""
+    data = np.hstack([positions, normals]).astype("<f4")
+    header = (
+        "ply\nformat binary_little_endian 1.0\n"
+        f"element vertex {len(data)}\n"
+        "property float x\nproperty float y\nproperty float z\n"
+        "property float nx\nproperty float ny\nproperty float nz\n"
+        "end_header\n"
+    )
+    with open(path, "wb") as fh:
+        fh.write(header.encode("ascii"))
+        fh.write(data.tobytes())
+
+
+def _orient(normals: "tc.NormalPointCloud", orientation: str, k: int) -> "tc.NormalPointCloud":
+    """`consistent`: agree all around (outward on closed objects). `viewpoint`:
+    keep estimate_normals' choice, facing a point above the cloud (one-sided scans)."""
+    if orientation == "consistent":
+        return tc.orient_normals(normals, k)
+    if orientation == "viewpoint":
+        return normals
+    raise WorkspaceError(f"unknown normal_orientation {orientation!r}; use 'consistent' or 'viewpoint'")
+
+
+def _matrix(transform: Sequence[Sequence[float]]) -> np.ndarray:
+    matrix = np.asarray(transform, dtype=np.float64)
+    if matrix.shape != (4, 4):
+        raise WorkspaceError("transform must be a 4x4 matrix (a list of 4 rows of 4 numbers)")
+    if not np.allclose(matrix[3], [0, 0, 0, 1]):
+        raise WorkspaceError("the last row of a rigid transform must be [0, 0, 0, 1]")
+    return matrix
+
+
+def _matrix_list(matrix: np.ndarray) -> list[list[float]]:
+    return [[round(float(v), 8) for v in row] for row in np.asarray(matrix)]
+
+
+# ---------------------------------------------------------------------------
+# Inspection and conversion
+# ---------------------------------------------------------------------------
+
+
+def inspect_point_cloud(ws: Workspace, path: str) -> dict:
+    resolved, cloud = _read_cloud(ws, path)
+    spacing = _spacing(cloud)
+    summary = {
+        "path": ws.relative(resolved),
+        "file_bytes": resolved.stat().st_size,
+        **_cloud_summary(cloud),
+        "median_spacing": None if spacing is None else round(spacing, 6),
+    }
+    if spacing:
+        # Rules of thumb the agent can start from; see the skill for details.
+        summary["suggested"] = {
+            "voxel_size_light": round(2 * spacing, 6),
+            "voxel_size_strong": round(5 * spacing, 6),
+            "outlier_radius": round(3 * spacing, 6),
+            "cluster_tolerance": round(3 * spacing, 6),
+        }
+    return summary
+
+
+def inspect_mesh(ws: Workspace, path: str) -> dict:
+    resolved, mesh = _read_mesh(ws, path)
+    return {"path": ws.relative(resolved), "file_bytes": resolved.stat().st_size, **_mesh_summary(mesh)}
+
+
+def convert(
+    ws: Workspace,
+    path: str,
+    output: str,
+    kind: Literal["point_cloud", "mesh"] = "point_cloud",
+    overwrite: bool = False,
+) -> dict:
+    if kind == "mesh":
+        resolved, mesh = _read_mesh(ws, path)
+        out = ws.output_path(output, inputs=[resolved], default_suffix="converted",
+                             allowed=MESH_FORMATS, overwrite=overwrite)
+        tc.write_mesh(mesh, str(out))
+        return {"output": ws.relative(out), **_mesh_summary(mesh)}
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="converted",
+                         allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+    _write_cloud(cloud, out)
+    return {"output": ws.relative(out), "points": len(cloud)}
+
+
+# ---------------------------------------------------------------------------
+# Cleaning
+# ---------------------------------------------------------------------------
+
+
+def downsample(
+    ws: Workspace, path: str, voxel_size: float, output: Optional[str] = None, overwrite: bool = False
+) -> dict:
+    if not voxel_size > 0:
+        raise WorkspaceError("voxel_size must be positive")
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="downsampled",
+                         allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+    result = tc.voxel_downsample(cloud, voxel_size)
+    _write_cloud(result, out)
+    return {
+        "output": ws.relative(out),
+        "points_before": len(cloud),
+        "points_after": len(result),
+        "voxel_size": voxel_size,
+    }
+
+
+def remove_outliers(
+    ws: Workspace,
+    path: str,
+    method: Literal["statistical", "radius"] = "statistical",
+    k_neighbors: int = 20,
+    std_ratio: float = 2.0,
+    radius: Optional[float] = None,
+    min_neighbors: int = 5,
+    output: Optional[str] = None,
+    overwrite: bool = False,
+) -> dict:
+    if method == "radius" and (radius is None or not radius > 0):
+        raise WorkspaceError("method='radius' needs a positive radius (see inspect_point_cloud's suggestion)")
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="clean",
+                         allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+    if method == "statistical":
+        result = tc.remove_statistical_outliers(cloud, k_neighbors, std_ratio)
+        params = {"k_neighbors": k_neighbors, "std_ratio": std_ratio}
+    else:
+        result = tc.remove_radius_outliers(cloud, radius, min_neighbors)
+        params = {"radius": radius, "min_neighbors": min_neighbors}
+    _write_cloud(result, out)
+    return {
+        "output": ws.relative(out),
+        "method": method,
+        **params,
+        "points_before": len(cloud),
+        "points_after": len(result),
+        "removed": len(cloud) - len(result),
+    }
+
+
+def estimate_normals(
+    ws: Workspace,
+    path: str,
+    k_neighbors: int = 10,
+    output: Optional[str] = None,
+    overwrite: bool = False,
+    normal_orientation: Literal["consistent", "viewpoint"] = "consistent",
+) -> dict:
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="normals",
+                         allowed={".ply"}, default_extension=".ply", overwrite=overwrite)
+    normals_cloud = _orient(tc.estimate_normals(cloud, k_neighbors), normal_orientation, k_neighbors)
+    _write_ply_with_normals(normals_cloud.positions(), normals_cloud.normals(), out)
+    return {
+        "output": ws.relative(out),
+        "points": len(normals_cloud),
+        "k_neighbors": k_neighbors,
+        "normal_orientation": normal_orientation,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Registration and transforms
+# ---------------------------------------------------------------------------
+
+
+def register(
+    ws: Workspace,
+    source: str,
+    target: str,
+    method: Literal["icp", "point_to_plane", "gicp", "global"] = "icp",
+    max_iterations: int = 50,
+    max_correspondence_distance: float = 1.0,
+    voxel_size: Optional[float] = None,
+    initial_transform: Optional[Sequence[Sequence[float]]] = None,
+    aligned_output: Optional[str] = None,
+    overwrite: bool = False,
+) -> dict:
+    if voxel_size is not None and not voxel_size > 0:
+        raise WorkspaceError("voxel_size must be positive")
+    if method == "global" and initial_transform is not None:
+        raise WorkspaceError("method='global' finds its own starting pose; drop initial_transform")
+    init = None if initial_transform is None else _matrix(initial_transform)
+    source_path, source_cloud = _read_cloud(ws, source)
+    target_path, target_cloud = _read_cloud(ws, target)
+    out = None
+    if aligned_output is not None:
+        out = ws.output_path(aligned_output, inputs=[source_path, target_path], default_suffix="aligned",
+                             allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+
+    # Optional downsampling for speed; the transform still applies to the full clouds.
+    src, tgt = source_cloud, target_cloud
+    if voxel_size:
+        src = tc.voxel_downsample(source_cloud, voxel_size)
+        tgt = tc.voxel_downsample(target_cloud, voxel_size)
+
+    if method == "icp":
+        result = tc.icp(src, tgt, max_iterations, init)
+        metrics = {"mse": result.mse, "iterations": result.iterations, "converged": result.converged}
+    elif method == "point_to_plane":
+        result = tc.icp_point_to_plane(src, tc.estimate_normals(tgt, 10), max_iterations, init)
+        metrics = {"mse": result.mse, "iterations": result.iterations, "converged": result.converged}
+    elif method == "gicp":
+        result = tc.gicp(src, tgt, max_iterations=max_iterations,
+                         max_correspondence_distance=max_correspondence_distance,
+                         init_transform=init)
+        metrics = {"mse": result.mse, "iterations": result.iterations, "converged": result.converged}
+    elif method == "global":
+        result = tc.global_registration(src, tgt, icp_max_iterations=max_iterations)
+        metrics = {
+            "inlier_count": result.inlier_count,
+            "inlier_ratio": result.inlier_ratio,
+            "mse": result.icp_mse,
+            "converged": result.icp_converged,
+        }
+    else:
+        raise WorkspaceError(f"unknown method {method!r}")
+
+    transform = np.asarray(result.transformation(), dtype=np.float64)
+    if metrics.get("mse") is not None:
+        metrics["rmse"] = round(float(np.sqrt(max(metrics["mse"], 0.0))), 8)
+        metrics["mse"] = round(float(metrics["mse"]), 10)
+
+    summary = {
+        "method": method,
+        "transform": _matrix_list(transform),
+        **metrics,
+        "source_points": len(source_cloud),
+        "target_points": len(target_cloud),
+    }
+    if voxel_size:
+        summary["registered_on"] = {"voxel_size": voxel_size, "source_points": len(src), "target_points": len(tgt)}
+    if out is not None:
+        _write_cloud(tc.transform_point_cloud(source_cloud, transform), out)
+        summary["aligned_output"] = ws.relative(out)
+    return summary
+
+
+def transform(
+    ws: Workspace,
+    path: str,
+    transform: Sequence[Sequence[float]],
+    output: Optional[str] = None,
+    overwrite: bool = False,
+) -> dict:
+    matrix = _matrix(transform)
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="transformed",
+                         allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+    result = tc.transform_point_cloud(cloud, matrix)
+    _write_cloud(result, out)
+    return {"output": ws.relative(out), **_cloud_summary(result)}
+
+
+# ---------------------------------------------------------------------------
+# Segmentation
+# ---------------------------------------------------------------------------
+
+
+def segment_plane(
+    ws: Workspace,
+    path: str,
+    distance_threshold: float = 0.01,
+    max_iterations: int = 1000,
+    inliers_output: Optional[str] = None,
+    outliers_output: Optional[str] = None,
+    overwrite: bool = False,
+) -> dict:
+    resolved, cloud = _read_cloud(ws, path)
+    # Check every output before computing or writing anything, so a bad path
+    # can't leave half the results on disk.
+    outputs = {}
+    for key, wanted, suffix in (("inliers_output", inliers_output, "plane"),
+                                ("outliers_output", outliers_output, "rest")):
+        if wanted is not None:
+            outputs[key] = ws.output_path(wanted, inputs=[resolved], default_suffix=suffix,
+                                          allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+    if len(outputs) == 2 and outputs["inliers_output"] == outputs["outliers_output"]:
+        raise WorkspaceError("inliers_output and outliers_output must be different files")
+    result = tc.segment_plane(cloud, distance_threshold, max_iterations)
+    a, b, c, d = (float(v) for v in result.plane_coefficients())
+    inliers = np.asarray(result.inlier_indices(), dtype=np.int64)
+    summary = {
+        "plane": {"a": round(a, 8), "b": round(b, 8), "c": round(c, 8), "d": round(d, 8)},
+        "equation": "a*x + b*y + c*z + d = 0",
+        "inliers": int(len(inliers)),
+        "inlier_ratio": round(len(inliers) / len(cloud), 6),
+    }
+    points = cloud.to_numpy()
+    mask = np.zeros(len(points), dtype=bool)
+    mask[inliers] = True
+    for key, keep in (("inliers_output", mask), ("outliers_output", ~mask)):
+        if key in outputs:
+            _write_cloud(tc.PointCloud(points[keep]), outputs[key])
+            summary[key] = ws.relative(outputs[key])
+    return summary
+
+
+def extract_clusters(
+    ws: Workspace,
+    path: str,
+    tolerance: float,
+    min_cluster_size: int = 100,
+    max_cluster_size: int = 25000,
+    output_dir: Optional[str] = None,
+    max_files: int = 50,
+    overwrite: bool = False,
+) -> dict:
+    if not tolerance > 0:
+        raise WorkspaceError("tolerance must be positive (see inspect_point_cloud's suggestion)")
+    resolved, cloud = _read_cloud(ws, path)
+    clusters = tc.extract_clusters(cloud, tolerance, min_cluster_size, max_cluster_size)
+    summary = {
+        "clusters": len(clusters),
+        "sizes": [len(c) for c in clusters[:max_files]],
+        "points_in_clusters": int(sum(len(c) for c in clusters)),
+        "points_total": len(cloud),
+    }
+    if output_dir is not None:
+        folder = ws.output_dir(output_dir)
+        # Check every file name first, so an existing file can't stop the
+        # call halfway with only some clusters written.
+        outs = [
+            ws.output_path(str(folder / f"{resolved.stem}.cluster{index:03d}.ply"),
+                           inputs=[resolved], default_suffix="cluster",
+                           allowed=POINT_CLOUD_WRITE_FORMATS, overwrite=overwrite)
+            for index in range(min(len(clusters), max_files))
+        ]
+        for cluster, out in zip(clusters, outs):
+            _write_cloud(cluster, out)
+        summary["files"] = [ws.relative(out) for out in outs]
+        if len(clusters) > max_files:
+            summary["note"] = f"wrote the {max_files} largest clusters; raise max_files for more"
+    return summary
+
+
+# ---------------------------------------------------------------------------
+# Meshes
+# ---------------------------------------------------------------------------
+
+
+def reconstruct(
+    ws: Workspace,
+    path: str,
+    method: Literal["auto", "poisson", "ball_pivoting", "alpha_shape", "delaunay"] = "auto",
+    normals_k: int = 10,
+    radius: Optional[float] = None,
+    alpha: Optional[float] = None,
+    output: Optional[str] = None,
+    overwrite: bool = False,
+    depth: int = 7,
+    trim_distance: Optional[float] = None,
+    normal_orientation: Literal["consistent", "viewpoint"] = "consistent",
+) -> dict:
+    if not 3 <= depth <= 8:
+        raise WorkspaceError("depth must be between 3 and 8 (7 takes about a second, 8 about 10-20 seconds)")
+    resolved, cloud = _read_cloud(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="mesh",
+                         allowed=MESH_FORMATS, default_extension=".ply", overwrite=overwrite)
+    if method == "auto":
+        mesh = tc.reconstruct(cloud)
+    elif method == "poisson":
+        normals = _orient(tc.estimate_normals(cloud, normals_k), normal_orientation, normals_k)
+        mesh = tc.poisson_reconstruct(normals, depth=depth, trim_distance=trim_distance)
+    elif method == "ball_pivoting":
+        if radius is None:
+            spacing = _spacing(cloud)
+            if not spacing:
+                raise WorkspaceError("could not estimate a ball radius; pass radius")
+            radius = 2.0 * spacing
+        mesh = tc.ball_pivoting_reconstruct(cloud, radius)
+    elif method == "alpha_shape":
+        mesh = tc.alpha_shape_reconstruct(cloud, 1.0 if alpha is None else alpha)
+    elif method == "delaunay":
+        mesh = tc.delaunay_triangulate(cloud)
+    else:
+        raise WorkspaceError(f"unknown method {method!r}")
+    if mesh.is_empty:
+        raise WorkspaceError(f"{method} produced an empty mesh; try another method or parameters")
+    tc.write_mesh(mesh, str(out))
+    summary = {"output": ws.relative(out), "method": method, **_mesh_summary(mesh)}
+    if method == "ball_pivoting":
+        summary["radius"] = round(float(radius), 6)
+    if method == "poisson":
+        summary["depth"] = depth
+    return summary
+
+
+def simplify_mesh(
+    ws: Workspace,
+    path: str,
+    reduction_ratio: float = 0.5,
+    output: Optional[str] = None,
+    overwrite: bool = False,
+    preserve_boundary: bool = True,
+) -> dict:
+    if not 0 < reduction_ratio < 1:
+        raise WorkspaceError("reduction_ratio must be between 0 and 1 (0.5 removes about half the faces)")
+    resolved, mesh = _read_mesh(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="simplified",
+                         allowed=MESH_FORMATS, overwrite=overwrite)
+    result = tc.simplify_mesh(mesh, reduction_ratio, preserve_boundary=preserve_boundary)
+    tc.write_mesh(result, str(out))
+    return {
+        "output": ws.relative(out),
+        "faces_before": mesh.face_count,
+        "faces_after": result.face_count,
+        "vertices_after": result.vertex_count,
+    }
+
+
+def smooth_mesh(
+    ws: Workspace,
+    path: str,
+    method: Literal["taubin", "laplacian", "hc"] = "taubin",
+    iterations: int = 10,
+    output: Optional[str] = None,
+    overwrite: bool = False,
+) -> dict:
+    resolved, mesh = _read_mesh(ws, path)
+    out = ws.output_path(output, inputs=[resolved], default_suffix="smooth",
+                         allowed=MESH_FORMATS, overwrite=overwrite)
+    if method == "taubin":
+        result = tc.smooth_mesh_taubin(mesh, iterations)
+    elif method == "laplacian":
+        result = tc.smooth_mesh_laplacian(mesh, iterations)
+    elif method == "hc":
+        result = tc.smooth_mesh_hc(mesh, iterations)
+    else:
+        raise WorkspaceError(f"unknown method {method!r}")
+    tc.write_mesh(result, str(out))
+    return {"output": ws.relative(out), "method": method, "iterations": iterations, **_mesh_summary(result)}

threecrate_mcp/server.py

@@ -0,0 +1,319 @@
+"""MCP server exposing threecrate point cloud and mesh tools.
+
+Run with `threecrate-mcp` (or `uvx threecrate-mcp`). It talks MCP over stdio,
+so any MCP client (Claude Code, Claude Desktop, Codex, OpenCode, Cursor, ...)
+can launch it. Tools read and write files inside one workspace folder (the
+current directory, or `--root` / THREECRATE_MCP_ROOT) and return short
+summaries rather than point data.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import os
+from functools import lru_cache
+from typing import Annotated, Any, Callable, Literal, Optional, TypeVar
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from pydantic import Field
+
+from . import ops
+from .workspace import MAX_POINTS_ENV, ROOT_ENV, Workspace
+
+INSTRUCTIONS = """\
+Tools for 3D point clouds and meshes (PLY, PCD, XYZ, CSV, OBJ, ...), powered by
+threecrate. All paths are relative to the workspace folder. Tools write results
+to new files and return summaries, never raw points.
+
+Typical flow: start with inspect_point_cloud to learn the size, units and point
+spacing (it also suggests voxel sizes and radii), then clean (remove_outliers,
+downsample), then register two scans or reconstruct a mesh. Outputs default to
+a new file next to the input; existing files are only replaced with
+overwrite=true.
+"""
+
+mcp = MCPServer("threecrate", instructions=INSTRUCTIONS)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def tool(fn: F) -> F:
+    """Register `fn` as an MCP tool whose failures reach the agent.
+
+    The SDK only passes `ToolError` messages to the model; any other exception
+    becomes a bare "Error executing tool". Our messages (a path outside the
+    workspace, an output that already exists, a threecrate error on a bad file)
+    are what the agent needs to fix its call, so every error becomes a ToolError.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (ToolError, KeyboardInterrupt, SystemExit):
+            raise
+        # BaseException: a Rust panic arrives as pyo3's PanicException, which
+        # is not an Exception and would otherwise take the server down.
+        except BaseException as exc:  # noqa: BLE001 - surface every failure to the agent
+            raise ToolError(str(exc) or type(exc).__name__) from exc
+
+    mcp.tool()(wrapper)
+    return fn
+
+
+@lru_cache(maxsize=1)
+def _ws() -> Workspace:
+    return Workspace.from_env()
+
+
+Path_ = Annotated[str, Field(description="File path, relative to the workspace folder")]
+Output = Annotated[
+    Optional[str],
+    Field(description="Where to write the result. Default: a new file next to the input"),
+]
+Overwrite = Annotated[bool, Field(description="Replace the output file if it already exists")]
+NormalOrientation = Annotated[
+    Literal["consistent", "viewpoint"],
+    Field(
+        description=(
+            "consistent: normals agree all around, outward on closed objects (default). "
+            "viewpoint: face a point above the cloud; better for one-sided scans of walls or facades"
+        )
+    ),
+]
+
+
+@tool
+def inspect_point_cloud(path: Path_) -> dict:
+    """Summarize a point cloud file: point count, bounds, centroid, median point
+    spacing, and suggested voxel sizes and radii for the other tools. Call this
+    first on any new cloud."""
+    return ops.inspect_point_cloud(_ws(), path)
+
+
+@tool
+def inspect_mesh(path: Path_) -> dict:
+    """Summarize a mesh file: vertex and face counts, bounds and centroid."""
+    return ops.inspect_mesh(_ws(), path)
+
+
+@tool
+def convert(
+    path: Path_,
+    output: Annotated[str, Field(description="Output path; its extension picks the format")],
+    kind: Annotated[Literal["point_cloud", "mesh"], Field(description="What the file holds")] = "point_cloud",
+    overwrite: Overwrite = False,
+) -> dict:
+    """Convert a point cloud (PLY, PCD, XYZ, CSV) or mesh (PLY, OBJ) to another format."""
+    return ops.convert(_ws(), path, output, kind, overwrite)
+
+
+@tool
+def downsample(
+    path: Path_,
+    voxel_size: Annotated[
+        float,
+        Field(gt=0, description="Voxel edge length in the cloud's units; each voxel keeps the centroid of its points"),
+    ],
+    output: Output = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Reduce point density with a voxel grid. Good before registration or
+    reconstruction. 2x the median spacing is a light pass, 5x a strong one."""
+    return ops.downsample(_ws(), path, voxel_size, output, overwrite)
+
+
+@tool
+def remove_outliers(
+    path: Path_,
+    method: Annotated[
+        Literal["statistical", "radius"],
+        Field(description="statistical: far from neighbours on average; radius: too few neighbours nearby"),
+    ] = "statistical",
+    k_neighbors: Annotated[int, Field(ge=2, description="Neighbours checked (statistical)")] = 20,
+    std_ratio: Annotated[float, Field(gt=0, description="Lower removes more (statistical)")] = 2.0,
+    radius: Annotated[Optional[float], Field(gt=0, description="Search radius (radius method, required)")] = None,
+    min_neighbors: Annotated[int, Field(ge=1, description="Minimum neighbours within radius (radius method)")] = 5,
+    output: Output = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Remove stray points (sensor noise, reflections) from a point cloud."""
+    return ops.remove_outliers(_ws(), path, method, k_neighbors, std_ratio, radius, min_neighbors, output, overwrite)
+
+
+@tool
+def estimate_normals(
+    path: Path_,
+    k_neighbors: Annotated[int, Field(ge=3, description="Neighbours used for each normal")] = 10,
+    output: Annotated[Optional[str], Field(description="Output .ply path (stores normals as nx ny nz)")] = None,
+    overwrite: Overwrite = False,
+    normal_orientation: NormalOrientation = "consistent",
+) -> dict:
+    """Estimate a surface normal for every point and save them in a PLY file.
+    Not needed before register or reconstruct; those estimate normals themselves."""
+    return ops.estimate_normals(_ws(), path, k_neighbors, output, overwrite, normal_orientation)
+
+
+@tool
+def register(
+    source: Annotated[str, Field(description="Cloud to move")],
+    target: Annotated[str, Field(description="Cloud to align to")],
+    method: Annotated[
+        Literal["icp", "point_to_plane", "gicp", "global"],
+        Field(
+            description=(
+                "icp: fast, needs a rough initial alignment. point_to_plane: better on smooth "
+                "surfaces. gicp: most robust local method. global: no initial alignment needed "
+                "(feature matching + ICP), slower"
+            )
+        ),
+    ] = "icp",
+    max_iterations: Annotated[int, Field(ge=1)] = 50,
+    max_correspondence_distance: Annotated[
+        float, Field(gt=0, description="Ignore matches farther than this (gicp only)")
+    ] = 1.0,
+    voxel_size: Annotated[
+        Optional[float],
+        Field(gt=0, description="Downsample both clouds first for speed; the result still applies to the full clouds"),
+    ] = None,
+    initial_transform: Annotated[
+        Optional[list[list[float]]], Field(description="Starting 4x4 transform (not for method='global')")
+    ] = None,
+    aligned_output: Annotated[
+        Optional[str], Field(description="Also save the source cloud moved into the target's frame here")
+    ] = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Align a source point cloud to a target. Returns the 4x4 rigid transform
+    (source to target), fit error (mse, rmse) and convergence."""
+    return ops.register(
+        _ws(), source, target, method, max_iterations, max_correspondence_distance,
+        voxel_size, initial_transform, aligned_output, overwrite,
+    )
+
+
+@tool
+def transform(
+    path: Path_,
+    transform: Annotated[list[list[float]], Field(description="4x4 rigid transform, e.g. from register")],
+    output: Output = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Apply a 4x4 rigid transform to every point of a cloud."""
+    return ops.transform(_ws(), path, transform, output, overwrite)
+
+
+@tool
+def segment_plane(
+    path: Path_,
+    distance_threshold: Annotated[float, Field(gt=0, description="Max distance from the plane for a point to count")] = 0.01,
+    max_iterations: Annotated[int, Field(ge=1, description="RANSAC iterations")] = 1000,
+    inliers_output: Annotated[Optional[str], Field(description="Save the plane's points here")] = None,
+    outliers_output: Annotated[Optional[str], Field(description="Save everything else here (e.g. objects on a floor)")] = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Find the dominant plane (floor, wall, table) with RANSAC. Returns its
+    equation and how many points lie on it; can split the cloud in two."""
+    return ops.segment_plane(_ws(), path, distance_threshold, max_iterations, inliers_output, outliers_output, overwrite)
+
+
+@tool
+def extract_clusters(
+    path: Path_,
+    tolerance: Annotated[float, Field(gt=0, description="Max gap between points of one cluster")],
+    min_cluster_size: Annotated[int, Field(ge=1)] = 100,
+    max_cluster_size: Annotated[int, Field(ge=1)] = 25000,
+    output_dir: Annotated[Optional[str], Field(description="Folder to save each cluster as its own PLY")] = None,
+    max_files: Annotated[int, Field(ge=1, description="Save at most this many clusters, largest first")] = 50,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Split a cloud into separate objects by distance (Euclidean clustering).
+    Often run after segment_plane removes the floor."""
+    return ops.extract_clusters(
+        _ws(), path, tolerance, min_cluster_size, max_cluster_size, output_dir, max_files, overwrite
+    )
+
+
+@tool
+def reconstruct(
+    path: Path_,
+    method: Annotated[
+        Literal["auto", "poisson", "ball_pivoting", "alpha_shape", "delaunay"],
+        Field(
+            description=(
+                "auto: picks a method. poisson: smooth watertight surfaces. ball_pivoting: keeps "
+                "detail, may leave holes. alpha_shape: rough hulls. delaunay: near-flat clouds"
+            )
+        ),
+    ] = "auto",
+    normals_k: Annotated[int, Field(ge=3, description="Neighbours for the normals Poisson needs")] = 10,
+    radius: Annotated[Optional[float], Field(gt=0, description="Ball radius (ball_pivoting; default 2x spacing)")] = None,
+    alpha: Annotated[Optional[float], Field(gt=0, description="Alpha (alpha_shape)")] = None,
+    depth: Annotated[
+        int,
+        Field(ge=3, le=8, description="Poisson detail: grid of 2^depth cells per side. 7 takes about 1 s; 8 is finer but 10-20 s"),
+    ] = 7,
+    trim_distance: Annotated[
+        Optional[float],
+        Field(gt=0, description="Poisson: drop surface farther than this from any point. Use on open scans (e.g. 2x spacing)"),
+    ] = None,
+    normal_orientation: NormalOrientation = "consistent",
+    output: Annotated[Optional[str], Field(description="Output mesh path (.ply or .obj)")] = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Build a triangle mesh from a point cloud. Clean and downsample first for
+    better results. Poisson always closes the surface; set trim_distance for
+    scans that only see one side."""
+    return ops.reconstruct(
+        _ws(), path, method, normals_k, radius, alpha, output, overwrite, depth, trim_distance, normal_orientation
+    )
+
+
+@tool
+def simplify_mesh(
+    path: Path_,
+    reduction_ratio: Annotated[float, Field(gt=0, lt=1, description="Share of faces to remove (0.5 removes about half)")] = 0.5,
+    preserve_boundary: Annotated[
+        bool,
+        Field(description="Keep holes and open borders fixed. Set false if the call fails because the mesh is mostly holes"),
+    ] = True,
+    output: Output = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Reduce a mesh's triangle count while keeping its shape (quadric decimation)."""
+    return ops.simplify_mesh(_ws(), path, reduction_ratio, output, overwrite, preserve_boundary)
+
+
+@tool
+def smooth_mesh(
+    path: Path_,
+    method: Annotated[
+        Literal["taubin", "laplacian", "hc"],
+        Field(description="taubin keeps volume best; laplacian is strongest but shrinks the mesh"),
+    ] = "taubin",
+    iterations: Annotated[int, Field(ge=1)] = 10,
+    output: Output = None,
+    overwrite: Overwrite = False,
+) -> dict:
+    """Smooth a noisy or bumpy mesh, for example after reconstruct. Taubin keeps
+    the overall size; Laplacian smooths harder but shrinks the mesh."""
+    return ops.smooth_mesh(_ws(), path, method, iterations, output, overwrite)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="threecrate MCP server (stdio)")
+    parser.add_argument("--root", help=f"Workspace folder (default: current folder, or ${ROOT_ENV})")
+    parser.add_argument("--max-points", type=int, help=f"Refuse larger clouds (default 50M, or ${MAX_POINTS_ENV})")
+    args = parser.parse_args()
+    if args.root:
+        os.environ[ROOT_ENV] = args.root
+    if args.max_points:
+        os.environ[MAX_POINTS_ENV] = str(args.max_points)
+    _ws()  # fail fast on a bad root
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

threecrate_mcp/workspace.py

@@ -0,0 +1,119 @@
+"""Where the server may read and write, and how output paths are chosen.
+
+Every path an agent passes in is resolved against one root folder and must stay
+inside it. Outputs never overwrite an input, and never overwrite an existing
+file unless the caller asks for it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+ROOT_ENV = "THREECRATE_MCP_ROOT"
+MAX_POINTS_ENV = "THREECRATE_MCP_MAX_POINTS"
+DEFAULT_MAX_POINTS = 50_000_000
+
+POINT_CLOUD_WRITE_FORMATS = {".ply", ".pcd", ".xyz", ".csv"}
+MESH_FORMATS = {".ply", ".obj"}
+
+
+class WorkspaceError(ValueError):
+    """A path or size the server refuses to work with. The message is shown to the agent."""
+
+
+@dataclass(frozen=True)
+class Workspace:
+    root: Path
+    max_points: int = DEFAULT_MAX_POINTS
+
+    @classmethod
+    def from_env(cls) -> "Workspace":
+        root = Path(os.environ.get(ROOT_ENV) or Path.cwd()).resolve()
+        if not root.is_dir():
+            raise WorkspaceError(f"workspace root {root} is not a folder")
+        max_points = int(os.environ.get(MAX_POINTS_ENV, DEFAULT_MAX_POINTS))
+        return cls(root=root, max_points=max_points)
+
+    def _resolve(self, path: str) -> Path:
+        candidate = Path(path).expanduser()
+        if not candidate.is_absolute():
+            candidate = self.root / candidate
+        resolved = candidate.resolve()
+        if resolved != self.root and not resolved.is_relative_to(self.root):
+            raise WorkspaceError(
+                f"{path} is outside the workspace {self.root}. "
+                f"Set {ROOT_ENV} to allow another folder."
+            )
+        return resolved
+
+    def input_path(self, path: str) -> Path:
+        """An existing file inside the workspace."""
+        resolved = self._resolve(path)
+        if not resolved.is_file():
+            raise WorkspaceError(f"{path} does not exist or is not a file")
+        return resolved
+
+    def output_dir(self, path: str) -> Path:
+        """A folder inside the workspace, created if needed."""
+        resolved = self._resolve(path)
+        if resolved.exists() and not resolved.is_dir():
+            raise WorkspaceError(f"{path} exists and is not a folder")
+        resolved.mkdir(parents=True, exist_ok=True)
+        return resolved
+
+    def output_path(
+        self,
+        path: Optional[str],
+        *,
+        inputs: list[Path],
+        default_suffix: str,
+        allowed: set[str],
+        default_extension: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> Path:
+        """Where to write a result.
+
+        Without `path`, the result goes next to the first input, named
+        `<input stem>.<default_suffix><extension>`. The extension must be in
+        `allowed`. An input is never overwritten; an existing file only when
+        `overwrite` is set.
+        """
+        if path is None:
+            first = inputs[0]
+            extension = default_extension or first.suffix.lower()
+            if extension not in allowed:
+                # e.g. a LAS input: write the result as PLY, which every writer supports
+                extension = ".ply"
+            resolved = first.with_name(f"{first.stem}.{default_suffix}{extension}")
+        else:
+            resolved = self._resolve(path)
+
+        if resolved.suffix.lower() not in allowed:
+            raise WorkspaceError(
+                f"cannot write {resolved.name}: use one of {', '.join(sorted(allowed))}"
+            )
+        if any(resolved == item for item in inputs):
+            raise WorkspaceError(f"refusing to overwrite the input file {resolved.name}")
+        if resolved.exists() and not overwrite:
+            raise WorkspaceError(
+                f"{self.relative(resolved)} already exists; pass overwrite=true to replace it"
+            )
+        resolved.parent.mkdir(parents=True, exist_ok=True)
+        return resolved
+
+    def check_size(self, count: int, path: Path) -> None:
+        if count > self.max_points:
+            raise WorkspaceError(
+                f"{path.name} has {count:,} points, above the limit of {self.max_points:,}. "
+                f"Downsample it first or raise {MAX_POINTS_ENV}."
+            )
+
+    def relative(self, path: Path) -> str:
+        """`path` relative to the workspace root, for messages and results."""
+        try:
+            return path.relative_to(self.root).as_posix()
+        except ValueError:
+            return str(path)

threecrate_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: threecrate-mcp
+Version: 0.1.0
+Summary: MCP server that gives AI agents threecrate's 3D point cloud and mesh tools
+Project-URL: Repository, https://github.com/rajgandhi1/threecrate
+License: MIT OR Apache-2.0
+Keywords: 3d,agents,lidar,mcp,mesh,point-cloud
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2
+Requires-Dist: numpy>=1.20
+Requires-Dist: threecrate>=0.10.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# threecrate-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI agents work with 3D
+point clouds and meshes using [threecrate](https://github.com/rajgandhi1/threecrate).
+Ask your agent to "clean up scan.ply", "align these two scans" or "turn this cloud
+into a mesh", and it calls these tools.
+
+Works with any MCP client: Claude Code, Claude Desktop, Codex, OpenCode, Cursor,
+Gemini CLI and others.
+
+## Setup
+
+You need [uv](https://docs.astral.sh/uv/) (for `uvx`) or Python 3.10+.
+
+**Claude Code** (from your project folder):
+
+```bash
+claude mcp add threecrate -- uvx threecrate-mcp
+```
+
+**Codex** (from your project folder):
+
+```bash
+codex mcp add threecrate -- uvx threecrate-mcp
+```
+
+**OpenCode** (`opencode.json` in your project):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "threecrate": { "type": "local", "command": ["uvx", "threecrate-mcp"], "enabled": true }
+  }
+}
+```
+
+**Claude Desktop, Cursor and other apps** (their MCP JSON config). These apps
+don't start servers in your project folder, so pass it with `--root`:
+
+```json
+{
+  "mcpServers": {
+    "threecrate": {
+      "command": "uvx",
+      "args": ["threecrate-mcp", "--root", "/path/to/your/scans"]
+    }
+  }
+}
+```
+
+Without `uv`, install with `pip install threecrate-mcp` and use `threecrate-mcp`
+as the command.
+
+## How it behaves
+
+- **One workspace folder.** Tools only read and write inside it: the folder the
+  server starts in, or `--root` (also `THREECRATE_MCP_ROOT`). Paths are relative
+  to it.
+- **New files, never overwrites.** Results go to a new file next to the input
+  (for example `scan.downsampled.ply`) unless you name one. Inputs are never
+  overwritten, and existing files only with `overwrite=true`.
+- **Summaries, not points.** Tools return counts, bounds, transforms and errors.
+  Point data stays in files, so a big scan doesn't flood the agent's context.
+- **Size limit.** Clouds above 50 million points are refused
+  (`--max-points` or `THREECRATE_MCP_MAX_POINTS` to change).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `inspect_point_cloud` | Point count, bounds, spacing, and suggested voxel sizes and radii |
+| `inspect_mesh` | Vertex and face counts, bounds |
+| `convert` | Change format (PLY, PCD, XYZ, CSV; meshes PLY, OBJ) |
+| `downsample` | Voxel grid downsampling |
+| `remove_outliers` | Statistical or radius outlier removal |
+| `estimate_normals` | Save per-point normals to a PLY |
+| `register` | Align two clouds: ICP, point-to-plane, GICP, or global (no starting pose needed) |
+| `transform` | Apply a 4x4 rigid transform |
+| `segment_plane` | Find a floor, wall or table plane; split the cloud |
+| `extract_clusters` | Split a cloud into separate objects |
+| `reconstruct` | Point cloud to mesh: auto, Poisson, ball pivoting, alpha shape, Delaunay |
+| `simplify_mesh` | Reduce triangle count |
+| `smooth_mesh` | Taubin, Laplacian or HC smoothing |
+
+Readable point cloud formats: PLY, PCD, XYZ, CSV (and others threecrate
+supports). Writable: PLY, PCD, XYZ, CSV.
+
+## Agent Skill
+
+If you would rather not run a server, the [threecrate skill](../skills/threecrate/SKILL.md)
+teaches an agent to do the same work with short Python scripts. See
+[INSTALL.md](../INSTALL.md) for Claude Code, Codex, Gemini CLI, OpenCode and
+Cursor.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```

threecrate_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+threecrate_mcp/__init__.py,sha256=0CnpWu6vL_bR2cxWZDoJS7R72P82oI4onD2uyCc4usg,102
+threecrate_mcp/__main__.py,sha256=3dYKHfmWsrdExFlTFlcR5a_icR9fAkn06Yh14TQkEd8,33
+threecrate_mcp/ops.py,sha256=o3P78XKDFhabXop4C5WqNHEqg-zrZo9mgJVcOrMOUpU,22516
+threecrate_mcp/server.py,sha256=bJUR_iZKs15C1jGDVCZmXZVcixczIpqFAqIlCqJzR_k,13147
+threecrate_mcp/workspace.py,sha256=f1qdSOmNmUV8toLb8zjuc-iugWN-8XV_4R2jj5Nvdk0,4455
+threecrate_mcp-0.1.0.dist-info/METADATA,sha256=GAreo0RrynMREIPQ1BGyIBD2C32NLzHl2DevtWK4loQ,4041
+threecrate_mcp-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+threecrate_mcp-0.1.0.dist-info/entry_points.txt,sha256=jwGeDXaCftzpA8aJ4uYy_PpuFDenxGL8I4k0FIxmrBQ,62
+threecrate_mcp-0.1.0.dist-info/RECORD,,

threecrate_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

threecrate_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+threecrate-mcp = threecrate_mcp.server:main