# kenshape-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants such as Claude create low-poly 3D art for
[Kenney Shape](https://tools.kenney.nl/kenney-shape/). The assistant draws on Kenney Shape's tile canvas, looks at
rendered previews of the extruded model, and saves `.kenshape` projects or exports GLB, OBJ, SVG and PNG files.

![A rocket built through kenshape-mcp: flat drawing, 3D view, side view and top view](docs/images/rocket.png)

*A rocket built with a single `draw` call. The preview shows the flat drawing, a 3D view, a side view and a top view.*

> **Not affiliated with Kenney.** This is an unofficial companion tool. It needs **your own purchased copy of
> Kenney Shape**: the tile shapes are read from your install when the server starts, and nothing from the program
> is included in this repository.

## Features

- **Draws like a person would.** Rectangles, lines, ellipses, flood fill, mirroring, and an ASCII `grid` op that
  places detailed pixel art in one call.
- **Covers every tile property.** All 22 tile shapes and 4 rotations, per-tile depth (thickness), back-face color
  and back depth.
- **Shows its work.** It renders a PNG preview sheet (drawing, 3D, side and top views) so the assistant can check
  the model and fix it.
- **Exports models.** GLB (glTF 2.0) and OBJ+MTL with one material per palette color, plus SVG like Kenney Shape's
  vector export.
- **Produces real Kenney Shape projects.** It saves `.kenshape` files the program opens, and can launch Kenney Shape
  with a project for its other exporters (FBX, Collada, VOX, Minecraft, GIF).
- **Builds models the way Kenney Shape does.** Each tile is 1×1 unit and is extruded `depth` units around the center
  plane, scaled by the project's depth multiplier.

## Requirements

- [Node.js](https://nodejs.org) 18 or newer
- Kenney Shape (Windows build tested), bought from [kenney.nl](https://tools.kenney.nl/kenney-shape/)
- An MCP client: Claude Code, Claude Desktop, or any other client that supports stdio servers

## Installation

```bash
git clone https://github.com/CuteTechGuy/kenshape-mcp.git
```

```bash
cd kenshape-mcp
```

```bash
npm install
```

Then point the server at your copy of the program with `KENSHAPE_EXE`. If you clone this repository into the
Kenney Shape folder, next to `Kenney Shape.exe`, the server finds the program without it.

| Variable | Default | Meaning |
|---|---|---|
| `KENSHAPE_EXE` | `../../Kenney Shape.exe` relative to `src/` | Path to `Kenney Shape.exe`. Its `Kenney Shape_Data` folder must sit next to it. |
| `KENSHAPE_DIR` | `~/Documents/Kenney Shape` | Default folder for saved projects and exports |

### Claude Code

Add a `.mcp.json` to your project, or put the same block in your user settings:

```json
{
  "mcpServers": {
    "kenshape": {
      "command": "node",
      "args": ["C:/path/to/kenshape-mcp/src/index.js"],
      "env": {
        "KENSHAPE_EXE": "C:/path/to/Kenney Shape/Kenney Shape.exe",
        "KENSHAPE_DIR": "C:/path/to/output"
      }
    }
  }
}
```

### Claude Desktop

Add the same `kenshape` entry under `mcpServers` in `claude_desktop_config.json`, then restart the app.

## Usage

Ask your assistant for a model, for example:

> Make a 16×16 treasure chest in Kenney Shape: dark wood, gold trim, a thick lid. Show me a preview, then export a GLB.

A typical session:

1. `new_project`: start a 16, 24, 32 or 64 tile canvas.
2. `list_shapes`: optional; learn the tile shapes and their rotations.
3. `draw`: lay out the art, usually with one `grid` op, then `round_corners` or `mirror`.
4. `render_preview`: look at the result and fix anything wrong.
5. `export_model` or `save_project`: write `.glb`, `.obj`, `.svg`, `.png` or `.kenshape`.

## Tools

| Tool | Description |
|---|---|
| `list_shapes` | The tile shapes, with ASCII pictures of each rotation |
| `new_project` | Create an empty project with an optional custom palette (up to 32 colors) |
| `open_project` | Load an existing `.kenshape` file |
| `draw` | Run drawing operations (see below) |
| `view_project` | ASCII view of colors, depths or shapes |
| `set_project_properties` | Title, depth multiplier, palette |
| `render_preview` | PNG preview: a 2×2 sheet, or one view at any yaw and pitch |
| `save_project` | Save as `.kenshape` |
| `export_model` | Export `glb`, `obj`, `svg` or `png` |
| `open_in_kenney_shape` | Save the project and open it in Kenney Shape |
| `list_projects` | Projects currently held in memory |

### Drawing operations

Coordinates are tile positions: x points right, y points down, and `(0, 0)` is the top-left tile.

| Op | Fields | Effect |
|---|---|---|
| `set` | `x, y` or `points: [[x, y], ...]` | Paint single tiles |
| `rect` | `x, y, w, h, filled?` | Rectangle (filled by default) |
| `line` | `x1, y1, x2, y2` | Line between two tiles |
| `ellipse` | `x, y, w, h, filled?` | Ellipse inside a bounding box |
| `fill` | `x, y` | Flood-fill the connected area of the same color |
| `grid` | `x?, y?, rows, legend` | ASCII art: each character maps to a brush; `.` and spaces are skipped |
| `mirror` | `axis: x\|y, from` | Copy one half onto the other, with shapes mirrored correctly |
| `round_corners` | `shape?, x?, y?, w?, h?, color?` | Turn outer corners of filled areas into corner shapes |
| `shift` | `dx, dy` | Move the whole canvas, wrapping at the edges |
| `replace_color` | `from, to` | Swap one palette color for another |
| `clear` | none | Empty the canvas |

Each op can also take brush fields: `color` (a palette index or `#RRGGBB`; `-1` erases), `shape` (a name or index),
`angle` (0–3), `depth` (0–8), `colorBack`, `depthBack` and `erase`. A brush without `color` only changes tiles that
are already filled, which is how you paint depth or shapes onto existing art.

```json
{
  "op": "grid",
  "rows": [
    "..RR..",
    ".RWWR.",
    ".RWWR."
  ],
  "legend": {
    "R": { "color": 9, "depth": 4 },
    "W": { "color": 15, "depth": 5, "shape": "cornerRounded", "angle": 0 }
  }
}
```

The [tool reference](docs/tools.md) covers every option, and the [file format notes](docs/kenshape-format.md)
describe `.kenshape` files. [examples/rocket.mjs](examples/rocket.mjs) builds the rocket shown above.

## How it works

- `src/assets.js` reads the shape definitions (names, mirror partners and outline paths) from your Kenney Shape
  install's Unity asset files when the server starts.
- `src/geometry.js` turns each tile's outline into a polygon, triangulates it and extrudes it into a flat-shaded mesh.
  It skips walls hidden between neighboring tiles.
- `src/render.js` is a small software rasterizer that writes PNGs with no native dependencies.
- `src/export.js` writes GLB, OBJ+MTL and SVG files.

Exported models are centered on the origin, with +Y up and the front facing +Z, and one unit per tile.

## Development

```bash
npm test
```

The smoke test starts the server over stdio, draws a model, exports every format and reloads the saved project.
It needs a Kenney Shape install. See [CHANGELOG.md](CHANGELOG.md) for release notes.

## License

[MIT](LICENSE) © İbrahim Alkan. Kenney Shape is © Kenney and has its own license; this project does not include or
redistribute any part of it.