# SmartCut

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/jgmedialtd/smartcut-api  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/smartcut

## Description
Cutlist optimization for sheet, linear and roll stock, with grain, kerf, nesting and saw exports.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "smartcut": {
    "command": "npx",
    "args": ["-y","smartcut"]
  }
}
```

## Documentation & README

# SmartCut API

SmartCut is a hosted cutting-optimisation (cutlist / nesting) API for sheet,
linear and roll stock. This repository holds the OpenAPI specification, runnable
examples and MCP configuration for integrating it into your own software.

[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
[![OpenAPI 3.0](https://img.shields.io/badge/OpenAPI-3.0-green.svg)](openapi/v3.json)
[![Docs](https://img.shields.io/badge/docs-smartcut.dev-informational.svg)](https://smartcut.dev/docs)

## What it does

- **Sheet optimisation** — guillotine (edge-to-edge, saw-cuttable) and efficiency
  modes for plywood, MDF, glass, plastic and sheet metal.
- **Linear (1D) optimisation** for timber, bar, pipe and extrusion.
- **True-shape nesting** for irregular parts from DXF, for laser, plasma,
  waterjet and CNC routing.
- **Grain direction and per-part orientation locks**, so a part can be pinned to
  the length or width of the grain, or left free to rotate.
- **Edge banding, face finishes, blade kerf and stock trim** as first-class
  inputs, not post-processing.
- **Machine-ready exports** — PDF, CSV, DXF, SVG, and native saw formats
  including PTX (Homag), Biesse XML and Mayer `.may`.
- **Printable part labels** generated from the same result.

## Quickstart

Get a key at <https://smartcut.dev/account>, then:

```bash
curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: $SMARTCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d @examples/requests/guillotine.json
```

That returns a job id. Poll until it is ready, then fetch the result:

```bash
curl "https://api.smartcut.dev/v3/result/ready?id=$JOB_ID" -H "Authorization: $SMARTCUT_API_KEY"
curl "https://api.smartcut.dev/v3/result?id=$JOB_ID"       -H "Authorization: $SMARTCUT_API_KEY"
```

The result carries one entry per stock piece, each listing the parts placed on
it with their positions, the cuts needed to produce them, and the offcut left
over. Complete runnable versions in four languages are in
[`examples/`](examples/).

## Authentication

Pass the raw API key in the `Authorization` header:

```
Authorization: YOUR_API_KEY
```

**There is no `Bearer` prefix.** This is the single most common integration
mistake — a `Bearer ` prefix returns 401.

## Endpoints (v3)

<!-- This table is generated from the OpenAPI specification on release.
     Edits between the markers are overwritten. -->
<!-- generated:endpoints -->
| method | path | what it does | sync |
|---|---|---|---|
| POST | `/v3/calculate` | Submit calculation | async |
| POST | `/v3/validate` | Validate inputs without calculating | sync |
| GET | `/v3/result/ready` | Check if calculation is complete | sync |
| GET | `/v3/result` | Retrieve calculation result | sync |
| GET | `/v3/export/pdf` | Export result as PDF | sync |
| GET | `/v3/export/csv` | Export result as CSV | sync |
| GET | `/v3/export/ptx` | Export result as PTX (beam saw format) | sync |
| GET | `/v3/export/dxf` | Export result as DXF | sync |
| GET | `/v3/export/svg` | Export result as SVG | sync |
| GET | `/v3/export/mayer` | Export result as Mayer .may (Beta) | sync |
| GET | `/v3/export/biesse` | Export result as Biesse XML CutList (Beta) | sync |
| GET | `/v3/saws` | List saws + export formats offered | sync |
| GET | `/v3/spec` | Optimisation spec — selectable models + saws + their gating | sync |
| POST | `/v3/labels` | Generate printable part labels | sync |
| POST | `/webhooks/result` | Calculation result delivery | — *your* endpoint |
| GET | `/v3/calls` | Get API usage statistics | sync |
<!-- /generated:endpoints -->

Full reference: <https://smartcut.dev/api-docs/v3>

## How the async model works

Optimisation takes longer than a request should block for, so `/v3/calculate`
returns a job id immediately. You then either poll `/v3/result/ready` until it
reports done, or register a webhook and let SmartCut POST to you when the result
is available. Either way you fetch the payload from `/v3/result`.

Webhook registration, signature verification and retry behaviour are documented
at <https://smartcut.dev/docs/webhooks>.

## MCP server

SmartCut runs a hosted [Model Context Protocol](https://modelcontextprotocol.io)
server, so an agent can run optimisations directly with your existing API key.

```
POST https://api.smartcut.dev/mcp
```

Streamable HTTP transport. Authentication is the same raw key in the
`Authorization` header, **without** a `Bearer` prefix. Configuration for Claude
Desktop and other clients is in [`mcp/`](mcp/).

Tools: `calculate`, `validate`, `status`, `result`, `cancel`, `usage`, `export`,
`labels`, `list_cut_types` — plus `import_parts`, which is different from the
rest: it pushes parts an agent has extracted (from a PDF or a photo of a cutting
plan) into an open [Cutlist Evolution](https://cutlistevo.com) editor for the
user to confirm, rather than calling the optimisation API.

The `calculate` tool waits for the result in-call (about 25 seconds by default,
overridable with `waitMs`) and falls back to returning a job id if the
optimisation is still running, so an agent usually gets a layout in one call.

## Generating a client

**There is no official SDK, and that is deliberate.** The API is a JSON body and
one header, so `fetch` is already the client — and a generated client in your own
idiom will fit your codebase better than a hand-written one would. Point any
generator at the spec:

```bash
npx openapi-typescript openapi/v3.json -o smartcut.d.ts
npx @hey-api/openapi-ts -i openapi/v3.json -o src/smartcut
openapi-generator-cli generate -i openapi/v3.json -g python -o ./smartcut-python
```

## Examples

| language | file |
|---|---|
| curl | [`examples/curl/optimise.sh`](examples/curl/optimise.sh) |
| Node | [`examples/node/optimise.mjs`](examples/node/optimise.mjs) |
| Python | [`examples/python/optimise.py`](examples/python/optimise.py) |
| PHP | [`examples/php/optimise.php`](examples/php/optimise.php) |

Each reads a payload from [`examples/requests/`](examples/requests/), which is
generated from the specification — so the examples cannot drift from the schema.

## What this is, and is not

SmartCut is a **hosted service with a subscription**, not a self-hosted library.
It suits quoting, order processing, e-commerce cut-to-size checkout and CAM
hand-off, where you want optimisation quality and saw-format output without
maintaining a geometry engine. If you want an in-process bin-packer with no
network call and no account, this is the wrong tool and an open-source packing
library is the right one.

## Links

- Documentation — <https://smartcut.dev/docs>
- Interactive API reference — <https://smartcut.dev/api-docs/v3>
- Get an API key — <https://smartcut.dev/account>
- Published benchmarks — <https://smartcut.dev/benchmarks>
- WooCommerce plugin — <https://github.com/jgmedialtd/smartcut-wp-plugin>

## Support

Issues here are for the **specification and the examples** only. For API access,
billing, quota or integration support, use the contact form at
<https://smartcut.dev/contact>. Specification files are generated and cannot be
changed by pull request — see [`openapi/README.md`](openapi/README.md).