bottle-cap-mcp

NitroStack MCP server exposing three tools for the bottle-cap-cad workflow. Vision/dimension extraction from the source photo happens client-side (in Claude, the MCP client) — 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	CadQuery (Python — local subprocess, or remote via CAD_API_URL)	none / HTTPS
fill	hole/cavity geometry JSON (circle/rectangle/polygon, uniform or tapered)	CadQuery (Python — local subprocess, or remote via CAD_API_URL)	none / HTTPS
repair_mesh	mesh URL or base64	PyMeshLab (Python — local subprocess, or remote via CAD_API_URL)	none / HTTPS
generate_visual_mesh	raw image (base64)	Meshy API	HTTPS

Setup

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.

Deploying to NitroCloud (or any Node-only host)

NitroCloud's managed hosting runs this server in a Node-only container — there's no python3 there for getPythonCommand() to find, so fill/generate_precise_cap/repair_mesh fail with "Could not find a working Python interpreter" if deployed as-is.

The fix: run api/server.py (a small FastAPI wrapper around the same three CAD scripts) somewhere that does have Python — your own machine, a VPS, Render, Railway, Fly.io, etc. — and point the NitroCloud deployment at it.

1. Run the API somewhere with Python:

# locally, for testing (tunnel with ngrok/cloudflared if NitroCloud needs to reach it)
pip install -r requirements.txt --break-system-packages
export CAD_API_KEY=<pick-a-secret>
uvicorn api.server:app --host 0.0.0.0 --port 8787

# or as a container, anywhere that runs Docker:
docker build -f api/Dockerfile -t bottle-cap-cad-api .
docker run -d -p 8787:8787 -e CAD_API_KEY=<pick-a-secret> bottle-cap-cad-api

pymeshlab's mesh I/O plugins are Qt-based and need libgl1/libglu1-mesa present on the host even for fully headless use — the Dockerfile already includes them, but a bare VPS/Render/Railway box may need them installed separately (apt-get install libgl1 libglu1-mesa), or /repair calls will fail with Unknown format for load: stl.

2. Point the NitroCloud deployment at it — set these in NitroCloud's environment variables dashboard (not just your local .env, since that doesn't travel with the deploy):

CAD_API_URL=https://<wherever-you-ran-the-api-above>
CAD_API_KEY=<same secret as above>

That's it — fill.tools.ts/cap.tools.ts/repair.tools.ts check for CAD_API_URL at call time and switch to HTTP automatically. Leave it unset for local NitroStudio dev and they fall back to the original local-subprocess behavior, unchanged.

Structure

bottle-cap-mcp/
├── src/
│   ├── app.module.ts        # registers the tool providers
│   ├── main.ts               # bootstrap / entrypoint
│   └── tools/
│       ├── shapes.ts          # shared circle/rectangle/polygon 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 api/server.py (CAD_API_URL)
├── cad/
│   ├── precise_cap.py         # CadQuery threaded-cap builder
│   ├── fill.py                # CadQuery plug builder
│   └── repair_mesh.py         # PyMeshLab repair pipeline
├── api/
│   ├── server.py              # FastAPI wrapper exposing /fill /cap /repair over HTTP
│   └── Dockerfile              # standalone image for hosting api/server.py
├── package.json
├── tsconfig.json
└── requirements.txt

Known gaps (carried over from the design discussion)

• Real threads — resolved: precise_cap.py now builds a solid, closed top and cuts a blind bore (not a through-hole), and unions one or more real helical thread ridges onto the skirt's inner wall via a triangular/trapezoidal profile swept along a cq.Wire.makeHelix() path (see make_thread_solid). threadStarts (1-4), threadDepth, and topThickness are new optional fields on generate_precise_cap — threadPitch still 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; swap in cq_warehouse's generators if you need an exact standard spec (e.g. a certified PCO 1881 mating thread).
• Polygon flush caps: fill's capStyle: "flush" is implemented for circle/rectangle top shapes only. A polygon top with flush is downgraded to none by fill.tools.ts (with a warning returned to the caller) rather than silently failing.
• Loft corner fillets: for tapered holes, rectangle corner radii are applied at the wire level before lofting (an approximation), since filleting a lofted solid's edges directly is more involved than filleting a simple extrusion's vertical edges.
• NitroCloud deployment target — resolved: NitroCloud's managed hosting is Node-only (no Python interpreter available for the execFile calls). CadQuery/PyMeshLab now run behind a separate api/server.py microservice, called over HTTP when CAD_API_URL is set — see "Deploying to NitroCloud" above. Local NitroStudio dev is unaffected (falls back to the original subprocess path when CAD_API_URL is unset).
• main.ts bootstrap call: NitroFactory.createMcpServer(...).listen() follows NitroStack's documented NestJS-style pattern, but the exact factory method wasn't pinned down in the source discussion — confirm against your installed NitroStack version.
• Meshy polling: mesh.tools.ts polls for task completion; swap for Meshy's webhook callback in production to avoid long-held connections.