I open-sourced a deterministic crochet chart engine — no AI hallucinations, plus an MCP server so agents can use it

leviyi — Mon, 10 Aug 2026 15:43:26 +0000

A crochet chart is a grid. Each cell is one stitch, each color is a yarn, and if row 14 says "7 blue, 3 white" then row 14 has exactly ten stitches — not eleven, never "approximately ten."

That property is exactly why AI image generators are useless at making them. Ask a diffusion model for a "crochet chart of a frog" and you get something that looks like a chart: wavy grid lines, cells that change size mid-row, a legend with nine colors and a frog made of eleven. Pretty. Unworkable. You can't crochet from a vibe.

So the engine behind my crochet site is deterministic image processing, and this week I open-sourced it: crochetpatterngen-engine — Python library, CLI, and MCP server. Same input, same chart, same stitch counts, every time.

What it does

Feed it a photo, get back a stitch-ready chart PNG plus exact per-color stitch counts that sum exactly to the grid size:

from PIL import Image
from crochet_chart_engine import generate_chart, estimate_yarn

png_bytes, meta = generate_chart(
    Image.open("dog.jpg"),
    technique="c2c",   # graph | c2c | tapestry | mosaic | filet
    grid_w=60,         # 20..120
    n_colors=8,        # 2..16
)
# meta: {"grid_w", "grid_h", "colors": [{"hex", "count"}],
#        "total_stitches", "technique", "warning"}

yarn = estimate_yarn(meta, weight="worsted")
# per-color yardage, so you know how much yarn to buy before you start

The pipeline is resize → median-cut color quantization → confetti cleanup (isolated single-stitch specks get absorbed into their neighbors, because nobody wants to change yarn for one stitch). Pillow + numpy, no heavy deps.

The fun bug: C2C blankets come out squashed

The most interesting problem wasn't color — it was geometry. Corner-to-corner (C2C) crochet blocks are physically wider than tall, roughly a 0.7:1 height-to-width ratio. A square grid of C2C blocks does not produce a square piece of fabric.

Every naive photo-to-chart converter gets this wrong: your dog photo comes out vertically stretched on the actual blanket, like a funhouse mirror. The engine corrects grid dimensions by the block aspect ratio, so the worked piece keeps the photo's proportions instead of the chart's.

It's a one-line insight and a week of testing. That's most of applied software, honestly.

Why an MCP server

The same engine also ships as an MCP server, so AI agents (Claude Desktop, Cursor, whatever comes next) can call it as a tool:

{
  "mcpServers": {
    "crochet": {
      "command": "uvx",
      "args": ["--from", "crochetpatterngen-engine[mcp]", "crochetpatterngen-mcp"]
    }
  }
}

Three tools: photo_to_chart, render_ascii_design, estimate_yarn_tool. The pitch: an agent that can say "here's your chart, 60×44, 8 colors, you'll need about 210 yards of the green" is doing something generative AI structurally can't — because the answer is computed, not sampled.

I think "deterministic tools behind an agent frontend" is an underrated pattern right now. Everyone is wrapping LLMs around fuzzy tasks; there's a lot of value in wrapping them around precise ones.

The ASCII design format is my favorite part

Charts can also come from text files — one character per stitch:

palette: G=#58A05C, W=#FFFFFF, .=#FAFAF7
title: Frog Face
technique: graph
---
..GGGG..........GGGG....
.GGWWGG........GGWWGG...

I hand-draw designs in a text editor and git-diff my frogs. There's something deeply satisfying about version-controllable pixel art that becomes a physical object.

Links

GitHub: dengyu123456/crochet-engine — MIT, pytest tests/ passes, PRs welcome
PyPI: pip install crochetpatterngen-engine ([mcp] and [rembg] extras)
The hosted version with a free pattern library: crochetpatterngen.com