# FabTally MCP Server

The **first [MCP](https://modelcontextprotocol.io) server for real FDM 3D-printing
slicing, quoting, and DFM / printability analysis.** Every other 3D-printing MCP just
drives a printer (OctoPrint, Bambu). None of them *slice*, *quote*, or run
*design-for-manufacturability* checks — FabTally does.

It fronts the **FabTally agent API** (https://fabtally.com), which runs a **production
slicing engine** against **12 calibrated FDM printer profiles** and **12 filament
materials**, and exposes it as MCP tools so any MCP-capable agent (Claude Desktop,
Cursor, custom agents) can discover and call it.

- **Free for people; per-call for agents.** A human at a keyboard (Claude Desktop, ChatGPT
  Desktop — no crypto wallet) gets **real answers with zero payment** from *every useful tool*:
  slice metrics (print time, filament, layers, cost), full DFM, orientation optimisation, and
  the printer/material/settings advisors — subject to generous **fair-use daily limits** so the
  free compute can't be farmed. Only the downloadable **G-code file** (and the preview PNG) — the
  commercial deliverable — is paid, via [x402](https://www.x402.org) (USDC on Base) or prepaid
  credits, for **agents, production and high volume**. Hit the daily limit and you get a friendly
  pointer to prepaid credits (`https://fabtally.com/buy`) or the x402 agent lane.
- This server holds **no private key** and **persists no models**. It relays calls to
  `https://fabtally.com/...`; uploaded models are streamed to the slicer, never stored.

## Tools

All tools are **FREE for personal & interactive use** (fair-use daily limits). Only
`slice_model` with `include_gcode`/`include_preview` is paid.

| Tool | Price | What it does |
|---|---|---|
| `list_printers` | free | Live printer fleet (id, bed, nozzle), 12 materials, pricing model. **Call this first.** |
| `get_print_quote` | free | Slicer-accurate price quote: print time, filament grams, priced quote with volume discounts + bring-your-own pricing. |
| `slice_model` | free metrics / **paid file** | Slice metrics (time, filament, layers, geometry, cost) are free. `include_gcode`/`include_preview` returns the downloadable G-code / PNG — **paid** (x402 or prepaid credit `api_key`). |
| `check_printability` | free | DFM/printability. `full=false` fast geometry read; `full=true` full report with **exact** slice-derived support & material deltas. |
| `analyze_model` | free | Geometry preview: bbox (mm), volume (cm³), triangles, watertight, fits-on-bed, printable-so-far verdict. |
| `optimize_orientation` | free | Slices up to 4 orientations, recommends the one using the **least support material**, with savings vs as-is + est price. |
| `compare_printers` | free | Slice across several of your printers → table of time/filament/cost/fits-on-bed + cheapest & fastest picks. |
| `recommend_material` | free | Best filament(s) for a use case (functional/decorative/outdoor/flexible/high-temp/food-contact-note) with reasons + a quote per candidate. |
| `recommend_settings` | free | Layer height / infill / walls for a goal (strength/speed/surface/cost), sliced so you see the tradeoff. |
| `whatif_infill` | free | Table of time/filament/cost across several infill %s. |
| `scale_advisor` | free | New dimensions/time/filament/cost after scaling (`fit-bed` / `percent:<n>` / `dim:<axis>:<mm>`). |
| `validate_model` | free | One-shot go/no-go: watertight, wall-thickness, size vs bed, verdict + one-liner. |
| `cost_breakdown` | free | Material vs machine-time vs setup vs margin, in your currency (bring your own pricing). |
| `analyze_3d_model` | free | General 3D-model analysis (bbox, volume, triangles, watertight, solidity) — useful beyond printing (game/AR-VR asset QC, marketplace validation, engineering checks). |

## The 13 printers

Default: `elegoo-centauri-carbon`.

| id | printer | bed X×Y×Z (mm) | nozzle |
|---|---|---|---|
| `elegoo-centauri-carbon` | Elegoo Centauri Carbon | 256×256×257 | 0.4 |
| `elegoo-neptune4-max` | Elegoo Neptune 4 Max | 420×420×480 | 0.4 |
| `bambu-a1` | Bambu Lab A1 | 256×256×256 | 0.4 |
| `bambu-a1-mini` | Bambu Lab A1 mini | 180×180×180 | 0.4 |
| `bambu-p1s` | Bambu Lab P1S | 256×256×250 | 0.4 |
| `bambu-x1c` | Bambu Lab X1 Carbon | 256×256×250 | 0.4 |
| `prusa-mk4` | Prusa MK4 | 250×210×220 | 0.4 |
| `prusa-mini` | Prusa MINI | 180×180×180 | 0.4 |
| `ender3-v3` | Creality Ender-3 V3 | 220×220×250 | 0.4 |
| `creality-k1` | Creality K1 | 220×220×250 | 0.4 |
| `creality-k1-max` | Creality K1 Max | 300×300×300 | 0.4 |
| `voron-24-350` | Voron 2.4 350 | 350×350×325 | 0.4 |
| `anycubic-kobra2` | Anycubic Kobra 2 | 220×220×250 | 0.4 |

**Materials:** `pla`, `pla-cf`, `petg`, `petg-cf`, `abs`, `abs-cf`, `asa`, `asa-cf`,
`nylon`, `pc`, `pet`, `tpu` (PLA/PETG/ABS/ASA + carbon-fiber variants, Nylon, PC, PET, TPU).
`list_printers` always returns the authoritative live list.

## Supplying a model file

MCP tools can't take raw file uploads, so every model-consuming tool accepts the model **two
ways** — pick one:

- **`model_url`** (PREFERRED) — **just paste a link.** The server fetches and, if needed, unpacks it:
  - a **direct** `https` URL to an `STL` / `3MF` / `OBJ` / `PLY` / `STEP` file;
  - a **Thingiverse**, **Printables** or **MakerWorld** model page is tried, but these sites
    usually block downloads from servers (HTTP 403). You'll get a clear message to download
    the file yourself and upload it;
  - a **GitHub** blob URL (auto-rewritten to raw);
  - a **Google Drive** or **Dropbox** share link (auto-rewritten to the direct-download form);
  - a **`.zip`** archive — the first printable model inside (STL/3MF/OBJ/PLY/STEP) is extracted
    and used, and the response reports which file it picked.

  **Local file?** Drop it once at **https://fabtally.com/upload** (no account, drag-and-drop) to
  get a short-lived URL (auto-deletes in ~2h, nothing kept), then paste that URL as `model_url`.
  Max 64 MB.
- **`model_base64`** + **`filename`** — raw file bytes, base64, plus a filename. **Small-file
  fallback only (roughly <50KB).** MCP clients truncate large inline arguments, so a real STL sent
  this way can silently arrive corrupted. For anything bigger, use `model_url` via the upload bridge.

## Example tool calls

```jsonc
// 1) Discover printers/materials/pricing (free)
{ "name": "list_printers", "arguments": {} }

// 2) Free printability check on a hosted model
{ "name": "check_printability",
  "arguments": { "model_url": "https://fabtally.com/sample-cube-20mm.stl" } }

// 3) Full DFM report (free for interactive use) — paste a GitHub link
{ "name": "check_printability",
  "arguments": { "model_url": "https://github.com/user/repo/blob/main/bracket.stl",
                 "full": true, "printer": "bambu-p1s", "material": "petg" } }

// 4) Slice metrics (free) — no wallet, real print time / filament / cost
{ "name": "slice_model",
  "arguments": { "model_url": "https://raw.githubusercontent.com/CreativeTools/3DBenchy/master/Single-part/3DBenchy.stl",
                 "printer": "prusa-mk4", "material": "pla" } }

// 5) Compare your printers (free)
{ "name": "compare_printers",
  "arguments": { "model_url": "https://.../part.zip",
                 "printers": "bambu-a1,prusa-mk4,ender3-v3", "material": "petg" } }

// 6) The G-code FILE (PAID) — returns an x402 402 challenge unless x_payment/api_key is supplied
{ "name": "slice_model",
  "arguments": { "model_url": "https://example.com/gear.stl",
                 "printer": "voron-24-350", "material": "abs", "include_gcode": true } }
```

## Install

```bash
cd fabtally-mcp-server
npm install
```

## Run (stdio — primary)

```bash
node index.js
# or, after `npm install -g .`:  fabtally-mcp
```

The server speaks MCP over stdio. Point your MCP client at it.

### Claude Desktop / MCP client config

```json
{
  "mcpServers": {
    "fabtally": {
      "command": "node",
      "args": ["/absolute/path/to/fabtally-mcp-server/index.js"]
    }
  }
}
```

## Run (Streamable HTTP — optional)

```bash
MCP_HTTP_PORT=8103 node http.js
# POST MCP JSON-RPC messages to http://127.0.0.1:8103/mcp   (stateless)
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `FABTALLY_BASE` | `https://fabtally.com` | Base origin for the paid `/agent` (x402) lane + discovery. |
| `FABTALLY_FREE_BASE` | = `FABTALLY_BASE` | Base for the FREE lane. The hosted server points this at the localhost quote service. |
| `FABTALLY_FREE_PREFIX` | `/api/quote` | Path prefix for the free lane (empty when `FABTALLY_FREE_BASE` is the quote service directly). |
| `FABTALLY_INTERNAL_SECRET` | _(unset)_ | Hosted server only: authenticates forwarding each desktop user's IP as the fair-use cap identity. |
| `MCP_HTTP_PORT` | `8103` | Port for the optional HTTP transport (`http.js`). |
| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address for the HTTP transport. |

## How paid calls work (x402)

1. Call a paid tool (or `check_printability` with `full: true`) **without** `x_payment`.
   You get `{ "payment_required": true, "http_status": 402, "challenge": { ... } }` containing
   the x402 `accepts` entry (scheme `exact`, network `eip155:8453` = Base, asset USDC, atomic
   `amount`, `payTo`).
2. Build an x402 payment authorization (EIP-3009 `transferWithAuthorization` to `payTo`) for
   that entry using your x402 client / wallet.
3. Call the tool again with the resulting token in the **`x_payment`** argument. The server
   forwards it as the `X-PAYMENT` header and returns the actual result.

Free discovery is always at `GET https://fabtally.com/agent/overview`; the OpenAPI contract at
`https://fabtally.com/openapi.json`; x402 discovery at `https://fabtally.com/.well-known/x402`.

## Test

```bash
node smoke-test.mjs   # lists tools, calls list_printers + check_printability, checks paid 402s
```

## License

MIT · Sunstone Soft · https://fabtally.com