# 3D CAD BasePlate Generator MCP.

A [NitroStack](https://www.npmjs.com/package/@nitrostack/core) MCP server for
the **bottle-cap-cad** workflow: turn a photo of a broken bottle cap, worn
plug, or cavity into a printable replacement.

Vision/dimension extraction from the source photo happens **client-side**
(in the MCP client, e.g. Claude) — none of these tools re-derive dimensions
from pixels. `generate_visual_mesh` is the one exception, since Meshy infers
geometry directly from the image itself.

## Tools

| Tool | Input | Backend | Network |
|---|---|---|---|
| `generate_precise_cap` | dimensions JSON (outer/inner diameter, height, thread pitch/starts/depth) | CadQuery (Python, local subprocess) | none |
| `fill` | hole/cavity geometry JSON — circle, rectangle, stadium (slot), polygon, or freeform/organic outline, uniform or tapered | CadQuery (Python, local subprocess) | none |
| `repair_mesh` | mesh URL or base64 (STL/OBJ/PLY/GLB/OFF) | PyMeshLab (Python, local subprocess) | none (fetches `url` if given) |
| `generate_visual_mesh` | raw image (base64) | [Meshy](https://www.meshy.ai/) image-to-3D API | HTTPS |

A `fill-geometry-guide` MCP prompt is also registered, walking a caller
through the fields `fill` expects.

**Suggested pipeline:** `generate_visual_mesh` (rough visual reference from
a photo) → `repair_mesh` (make it manifold/watertight) → `generate_precise_cap`
or `fill` for the actual dimensionally-accurate part → `repair_mesh` again if
the CAD output needs cleanup after boolean operations.

## Setup

```bash
npm install
pip install -r requirements.txt --break-system-packages   # or your own venv
cp .env.example .env   # set MESHY_API_KEY
npm run build
npm start
```

For local iteration without a build step: `npm run dev`.

`generate_precise_cap`, `fill`, and `repair_mesh` shell out to a local Python
interpreter (`python-runtime.ts` auto-detects `python3`/`python`/`py`, or
respects a `PYTHON_EXECUTABLE` override in `.env`) — Python 3 with the
packages in `requirements.txt` needs to be installed wherever this server
runs. `generate_visual_mesh` only needs `MESHY_API_KEY`; it makes no Python
calls.

## Structure

```text
3D-CAD-Modeling-using-MCP/
├── src/
│   ├── app.module.ts          # registers the four tool providers + prompt
│   ├── main.ts                 # bootstrap / entrypoint
│   ├── index.ts                # re-exports main.ts
│   ├── modules/bottle-cap-cad/
│   │   └── bottle-cap-cad.prompts.ts   # fill-geometry-guide prompt
│   └── tools/
│       ├── shapes.ts            # shared circle/rectangle/stadium/polygon/freeform zod schema
│       ├── cap.tools.ts         # generate_precise_cap
│       ├── fill.tools.ts        # fill
│       ├── repair.tools.ts      # repair_mesh
│       ├── mesh.tools.ts        # generate_visual_mesh (pure TS, calls Meshy)
│       ├── python-runtime.ts    # local python3/python/py auto-detection
│       └── cad-api-client.ts    # optional HTTP client for a remote CAD API
├── cad/
│   ├── precise_cap.py           # CadQuery threaded-cap builder
│   ├── fill.py                  # CadQuery plug builder
│   └── repair_mesh.py           # PyMeshLab repair pipeline
├── package.json
├── tsconfig.json
└── requirements.txt
```

## Notes on the current code

- **Thread generation**: `precise_cap.py` builds a solid, closed-top cap
  with a blind bore (not a through-hole) and sweeps one or more real helical
  thread ridges onto the skirt's inner wall along a `cq.Wire.makeHelix()`
  path. `threadStarts` (1–4), `threadDepth`, and `topThickness` are optional
  fields on `generate_precise_cap`; `threadPitch` falls back to an
  approximate PCO 1810-style pitch (3.18mm, single start) when omitted. This
  is a parametric approximation tuned for FDM printing, not a certified
  thread-spec generator.
- **`fill` shapes**: `shapes.ts` supports five top/bottom shape types —
  `circle`, `rectangle` (with optional corner radius), `stadium` (true
  rounded slot with semicircular ends), `polygon` (straight-edged, arbitrary
  point count), and `freeform` (a smooth closed spline through 6–300 traced
  boundary points, for organic/irregular openings). `capStyle: "flush"` is
  only implemented for circle/rectangle/stadium/freeform tops — a polygon
  top with `flush` is downgraded to `none` by `fill.tools.ts`, with a
  warning returned to the caller rather than failing silently.
- **Low-confidence inputs**: both `generate_precise_cap` and `fill` accept a
  `confidence` field (`high`/`medium`/`low`, from the caller's own
  vision-based dimension extraction). A `low` value still generates output,
  but the response includes a warning recommending the dimensions be
  confirmed before printing.
- **Remote CAD API**: `cad-api-client.ts` supports routing
  `generate_precise_cap` / `fill` / `repair_mesh` over HTTP to a
  `CAD_API_URL` instead of spawning Python locally, for hosting environments
  without a Python runtime. **This repo does not currently include the
  server-side counterpart** (no `api/` directory) — `CAD_API_URL` /
  `CAD_API_KEY` are recognized but there's nothing to point them at yet.
  Leave both unset for local development; the tools fall back to the
  local-subprocess path automatically.
- **Meshy polling**: `mesh.tools.ts` polls Meshy's `image-to-3d` endpoint
  every 3s for up to 60 attempts rather than using a webhook callback.
  Meshy's free tier output is CC BY 4.0 licensed — check
  [meshy.ai/pricing](https://www.meshy.ai/pricing) for current terms before
  relying on it beyond a demo.
- **`app.module.ts`** registers a harmless placeholder for NitroStack's
  `OAUTH_CONFIG` DI token purely to silence a noisy (but non-fatal) startup
  log from `OAuthModule` — this server has no HTTP/OAuth surface and the
  placeholder has no effect on transport selection.

---

## Team

- Reshvanth Yeddla
- Nirlep Boddapally
- Tarun
- Vijay Reddy