fabtally-mcp

# 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.

- **Two-angle design.** A human at a keyboard (Claude Desktop, ChatGPT Desktop — no crypto
  wallet) gets **real answers with zero payment** from the everyday tools: `list_printers`,
  `check_printability`, `analyze_model`, `get_print_quote`. These call FabTally's free,
  rate-limited public endpoints. An autonomous agent with a wallet gets the heavier/exact
  tools — `optimize_orientation`, `slice_model`, and the full (`full=true`) DFM report —
  metered over [x402](https://www.x402.org) (USDC on Base). With no payment supplied, those
  return the x402 *challenge* (price, network, asset, `payTo`) so the calling agent knows the
  cost and can pay and retry.
- This server holds **no private key** and **persists no models**. It only relays calls to
  `https://fabtally.com/...`; uploaded models are streamed to the slicer, never stored.

## Tools

| Tool | Price | What it does |
|---|---|---|
| `list_printers` | **free** | Live 12-printer fleet (id, bed, nozzle), 12 materials, and x402 pricing tiers. **Call this first.** |
| `check_printability` | **free** / premium $0.01 | DFM/printability report. Free geometry preview: printable verdict, watertight, wall-thickness estimate, overhang/support heuristic, fits-on-bed. `full=true` → premium, x402-metered full report with **exact** slice-derived support & material deltas. |
| `analyze_model` | **free** | Geometry preview, no payment: bounding box (mm), volume (cm³), triangle count, watertight, fits-on-bed, plus a printable-so-far verdict as a bonus. |
| `get_print_quote` | **free** (rate-limited) | Slicer-accurate FDM price quote: print time, filament grams, priced quote with volume discounts. Supports optional bring-your-own pricing (`currency`, `machine_rate_per_hour`, `margin`, `setup_fee`, `minimum_price`, `material_cost_per_kg`, `markup_percent`) — omit for FabTally's hobbyist defaults. |
| `optimize_orientation` | premium, x402-metered $0.02 | Slices up to 4 orientations and recommends the one using the **least support material** (exact), with savings vs as-is. For autonomous agents with a wallet — unlimited, machine-speed. |
| `slice_model` | premium, x402-metered $0.005–$0.02 | Full slice on any printer: time, filament, layers, geometry. Optional preview PNG (+$0.005) and/or G-code (+$0.01). For autonomous agents with a wallet. |

The free tools are rate-limited public endpoints — fine for a human exploring a design, not for
high-volume or production integrations. For unlimited, machine-speed access, an autonomous
agent with a wallet can pay per call via x402: the premium tools above, or `check_printability`
with `full=true` for the exact (slice-derived) DFM report.

## The 12 printers

| id | printer | bed X×Y×Z (mm) | nozzle |
|---|---|---|---|
| `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 for local files) — a public `https` URL to an `STL` / `3MF` /
  `OBJ` / `PLY` / `STEP` file. The server fetches it. (Try
  `https://fabtally.com/sample-cube-20mm.stl`.) Got a file on your machine — Claude Desktop,
  ChatGPT Desktop? Drop it at **https://fabtally.com/upload** (no account, drag-and-drop) to get
  a short-lived URL back (auto-deletes in ~2 hours, nothing kept), then pass that URL as
  `model_url`. That page also has a "Get quote now" button for an instant human-readable quote
  with zero MCP involved.
- **`model_base64`** + **`filename`** — the raw file bytes, base64-encoded, plus a filename
  (e.g. `"cube.stl"`) so the file type is known. **Only reliable for small files (roughly
  <50KB).** MCP clients truncate large inline tool-call arguments, so a real STL sent this way
  can silently arrive as a corrupted fragment and produce garbage results (wrong dimensions,
  bogus quotes) with no error. For anything bigger, use `model_url` via the upload bridge above.

## 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 (premium, x402-metered; returns x402 challenge unless x_payment is supplied)
{ "name": "check_printability",
  "arguments": { "model_url": "https://example.com/bracket.stl",
                 "full": true, "printer": "bambu-p1s", "material": "petg" } }

// 4) Price quote, base64 model, 10 parts (free, real result, no payment)
{ "name": "get_print_quote",
  "arguments": { "model_base64": "<...>", "filename": "part.stl",
                 "material": "pla", "quantity": 10 } }

// 5) Least-support orientation (premium, x402-metered, $0.02)
{ "name": "optimize_orientation",
  "arguments": { "model_url": "https://example.com/handle.stl", "printer": "prusa-mk4" } }

// 6) Slice with a preview PNG (premium, x402-metered tier, $0.01)
{ "name": "slice_model",
  "arguments": { "model_url": "https://example.com/gear.stl",
                 "printer": "voron-24-350", "material": "abs",
                 "quality": "standard", "include_preview": 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 of the FabTally API. |
| `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