Automate Threadsmith with the API and MCP

Threadsmith’s stitch engine is the same TypeScript code in the browser app and on the server. Three engine tools are available as a JSON API and as MCP tools, so scripts and AI agents can create designs and hand them to a person who opens them in the app.

The API runs on https://threadsmith.usefulweb.site (and on the main site). The project file format is published at /project.schema.json; the MCP endpoint is /mcp.

All coordinates are millimetres, x to the right, y down, and (0, 0) is the hoop centre.

1. Digitize lettering

POST /api/v1/tools/threadsmith-digitize/calculate
Content-Type: application/json

{
  "source": "text",
  "text": "Ada",
  "textSize": 14,
  "stitchType": "satin",
  "satinWidth": 2,
  "color": "navy",
  "includeStitches": true
}

Response (shortened; these are the real values):

{
  "summary": "394 stitches in 1 colour(s), 39.2 × 16.4 mm, 9 trim(s), about 1 min 12 s at 700 stitches/min.",
  "result": {
    "stitches": 394, "jumps": 10, "trims": 9, "colorChanges": 0,
    "widthMm": 39.2, "heightMm": 16.4, "sewingTime": "1 min 12 s",
    "topThreadM": 1.23, "bobbinThreadM": 0.3,
    "hoop": { "id": "130x180", "fits": true, "overflowMm": 0 },
    "density": { "maxLayers": 2.12, "areaOverMm2": 0, "threshold": 2.6 },
    "colors": [{ "name": "Navy", "hex": "#1d2a52", "stitches": 394, "topThreadM": 1.23 }],
    "stitchList": [[-7.28, 7, "jump"], [-7.28, 7, "stitch"], [-7.54, 6.35, "stitch"], [-7.28, 7, "stitch"], "…"],
    "project": { "format": "threadsmith", "version": 1, "objects": ["…"] },
    "openInApp": "https://threadsmith.usefulweb.site/app#project=eyJmb3JtYXQiOi…"
  }
}

• openInApp carries the whole project in the URL fragment (it never reaches a server). Give it to a person and the design opens in their browser as an editable copy.
• stitchList (only with includeStitches: true) is the full machine plan: [x, y, type] with type stitch, jump, trim, color or end. The first entries above are the jump to the first point and the tie-in.
• presentation (not shown) contains a thread-look SVG preview and tables, ready to display.

Other source values: shape (ellipse, rect, star, hexagon, heart with widthMm/heightMm), path (pathD in mm), svg (SVG markup, optional fitWidth) and project.

2. Build a whole project

Send a project as JSON text. This one is a teal tatami badge with outline-font initials and a satin border:

{
  "source": "project",
  "project": "{\"name\":\"Agent badge\",\"hoop\":\"100x100\",\"objects\":[{\"kind\":\"ellipse\",\"cx\":0,\"cy\":0,\"rx\":30,\"ry\":30,\"color\":\"teal\",\"stitch\":{\"type\":\"tatami\",\"angle\":30}},{\"kind\":\"text\",\"text\":\"HI\",\"x\":0,\"y\":8,\"size\":18,\"font\":\"outline\",\"weight\":3,\"color\":\"gold\",\"stitch\":{\"type\":\"satin\"}},{\"kind\":\"ellipse\",\"cx\":0,\"cy\":0,\"rx\":30,\"ry\":30,\"color\":\"navy\",\"stitch\":{\"type\":\"satin\",\"mode\":\"border\",\"width\":3}}]}"
}

Result: "3,495 stitches in 3 colour(s), 63.4 × 63.4 mm, 3 trim(s), about 5 min 54 s at 700 stitches/min." with the sewing order ["o1", "o2", "o3"] and per-colour usage Teal 2,637 / Old gold 228 / Navy 630 stitches.

Object kinds: path (d), rect (x y w h r), ellipse (cx cy rx ry), polygon (cx cy radius sides inner), text (text x y size font weight align spacing slant) and stitches (points). Every object has color (a palette thread id, a built-in thread id such as ruby, or #rrggbb), stitch and optional underlay, start, end. Missing values get sensible defaults; invalid ones produce an error in plain words, e.g. Object 1: unknown kind "blob" (use path, rect, ellipse, polygon, text, stitches).

3. Write a DST file

Pass the stitch list from step 1 (as a JSON string) to the file writer:

{ "format": "dst", "label": "ADA", "stitches": "[[-7.28,7,\"jump\"],[-7.28,7,\"stitch\"],[-7.54,6.35,\"stitch\"], …]" }

Real response:

{
  "summary": "stitches.dst: 1,820 bytes, 394 stitch and 41 jump records, 0 colour change(s); round-trip verified.",
  "result": {
    "format": "dst", "bytes": 1820, "records": 436, "stitchRecords": 394, "jumpRecords": 41,
    "verified": true, "maxErrorMm": 0.07,
    "header": { "LA": "ADA", "ST": "435", "CO": "0", "+X": "197", "-X": "195", "+Y": "82", "-Y": "82",
                "AX": "+  197", "AY": "-   70", "MX": "+    0", "MY": "+    0", "PD": "******" },
    "firstRecords": [
      { "index": 1, "hex": "66 80 9b", "meaning": "jump", "dx": -73, "dy": -70 },
      { "index": 2, "hex": "00 00 03", "meaning": "stitch", "dx": 0, "dy": 0 },
      { "index": 3, "hex": "a1 42 03", "meaning": "stitch", "dx": -2, "dy": 7 }
    ],
    "artifactUrl": "https://threadsmith.usefulweb.site/artifacts/a40945972495e824e538c3e31da1e24e/stitches.dst",
    "base64": "TEE6QURBICAgICAgICAgICAgIA1TVDogICAgNDM1…"
  }
}

The writer decodes its own output again and reports verified and the largest position difference (maxErrorMm, at most half a 0.1 mm machine unit diagonally). Download the file from artifactUrl (kept for about two hours) or decode base64. Jumps include the trims: each trim is written as three zero-sum jumps. You can also send "project": "…" instead of stitches, and "format": "exp" for Melco EXP.

Reading the first record: DST stores y upwards, so the jump to (−7.28, 7) mm is dx −73, dy −70 in 0.1 mm units; 66 80 9b is the balanced-ternary encoding of those values with the jump flag 0x80 set in the third byte.

4. Analyse an existing file

{
  "file": { "filename": "ada.dst", "contentBase64": "TEE6QURBICAgICAg…" },
  "spm": 800,
  "colors": ["#1d2a52"],
  "hoop": "100x100"
}

Response: DST "ADA": 394 stitches, 1 colour(s), 9 trim(s), 39.2 × 16.4 mm, about 1 min 6 s at 800 stitches/min, 1.23 m top thread. — the same numbers as the digitizer, which confirms the file round-trips exactly. The result also lists hotspots where the density limit is exceeded and warnings for stitches longer than 12.1 mm or shorter than 0.3 mm.

5. The same over MCP

Connect your MCP client to https://threadsmith.usefulweb.site/mcp (streamable HTTP). tools/list returns the three tools; call them with the same arguments:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "threadsmith_digitize",
              "arguments": { "source": "shape", "shape": "star", "widthMm": 50, "heightMm": 50, "stitchType": "contour", "color": "citrine" } } }

The response’s structuredContent.summary reads "323 stitches in 1 colour(s), 45.4 × 43.1 mm, 1 trim(s), about 30 s at 700 stitches/min." and structuredContent.result holds the same fields as the API.

A good agent workflow

1. Build a project JSON (see /project.schema.json) from the user’s request.
2. Call threadsmith_digitize with source: "project"; read warnings, hoop.fits and density.
3. Adjust (smaller size, lower density, different stitch type) until there are no warnings.
4. Give the user the openInApp link to review and tweak, and/or call threadsmith_stitch_file for a DST.
5. Remind the user to test-stitch: estimates are planning figures, and DST/EXP files carry no thread colours.