monosketch-mcp

An MCP server that gives AI agents the ability to create beautiful ASCII diagrams using Unicode box-drawing characters. Built on the rendering engine from MonoSketch.

┌──────────────────┐       ┌──────────────────┐
│                  │       │                  │
│     Frontend     │──────▶│      API         │
│                  │       │                  │
└──────────────────┘       └────────┬─────────┘
                                    │
                                    │
                           ┌────────▼─────────┐
                           │                  │
                           │    Database      │
                           │                  │
                           └──────────────────┘

Setup

Requires Bun runtime.

git clone https://github.com/supersterling/monosketch-mcp.git
cd monosketch-mcp
bun install

Add to Claude Code

claude mcp add monosketch -- bun run /path/to/monosketch-mcp/index.ts

Add to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "monosketch": {
      "command": "bun",
      "args": ["run", "/path/to/monosketch-mcp/index.ts"]
    }
  }
}

Tools

render_scene

Stateless one-shot rendering. Pass an array of shapes, get back ASCII art.

{
  "shapes": [
    {
      "type": "rectangle",
      "x": 0, "y": 0, "width": 20, "height": 5,
      "border": { "enabled": true }
    },
    {
      "type": "text",
      "x": 0, "y": 0, "width": 20, "height": 5,
      "content": "Hello World",
      "horizontalAlign": "center",
      "verticalAlign": "middle",
      "border": { "enabled": true }
    }
  ]
}

Output:

┌──────────────────┐
│                  │
│   Hello World    │
│                  │
└──────────────────┘

Canvas Tools (Stateful)

Build diagrams incrementally across multiple tool calls:

Tool	Description
create_canvas	Create a named canvas session
add_shape	Add a shape to a canvas
modify_shape	Update shape properties
remove_shape	Remove a shape
render_canvas	Render current state to ASCII
list_canvases	List active sessions
clear_canvas	Remove all shapes

Utilities

Tool	Description
list_styles	List all available border, fill, and anchor styles
measure_text	Compute bounding box for word-wrapped text

Shape Types

Rectangle

{ "type": "rectangle", "x": 0, "y": 0, "width": 10, "height": 4,
  "border": { "enabled": true, "style": "S1", "corner": "rounded" },
  "fill": { "enabled": true, "style": "F1" } }

Text

{ "type": "text", "x": 0, "y": 0, "width": 20, "height": 3,
  "content": "Centered text", "horizontalAlign": "center", "verticalAlign": "middle",
  "border": { "enabled": true } }

Line

{ "type": "line",
  "points": [{"x": 0, "y": 2}, {"x": 10, "y": 2}, {"x": 10, "y": 5}],
  "stroke": { "enabled": true },
  "endAnchor": "A1" }

Group

{ "type": "group", "children": [
  { "type": "rectangle", "x": 0, "y": 0, "width": 10, "height": 3, "border": { "enabled": true } },
  { "type": "rectangle", "x": 15, "y": 0, "width": 10, "height": 3, "border": { "enabled": true } }
]}

Style Reference

Border / Stroke Styles

ID	Name	Characters
S1	Thin (default)	─ │ ┌ ┐ └ ┘
S2	Bold	━ ┃ ┏ ┓ ┗ ┛
S3	Double	═ ║ ╔ ╗ ╚ ╝
S4	Rounded	─ │ ╭ ╮ ╰ ╯

Fill Styles

ID	Name	Character
F1	Space	(opaque blank)
F2	Solid	█
F3	Medium shade	▒
F4	Light shade	░
F5	Diagonal	▚

Anchor Styles (Line Endpoints)

ID	Name	L R U D
A1	Filled arrow	◀ ▶ ▲ ▼
A12	Hollow arrow	◁ ▷ △ ▽
A2	Filled square	■ ■ ■ ■
A21	Hollow square	□ □ □ □
A220	Filled diamond	◆ ◆ ◆ ◆
A221	Hollow diamond	◇ ◇ ◇ ◇
A3	Hollow circle	○ ○ ○ ○
A5	Filled circle	● ● ● ●

Dash Patterns

Add "dash": { "dash": 3, "gap": 1 } to any shape for dashed borders/strokes.

Line Crossing

When lines cross, junction characters are automatically resolved:

    │
────┼────
    │

The engine handles all combinations of single, bold, and double line styles with correct Unicode junction characters (T-junctions, crosses, corners).

Tests

bun test

208 tests covering geometry primitives, bitmap rendering, board compositing, crossing resolution, shape hierarchy, renderer pipeline, canvas management, and end-to-end integration scenarios.

Architecture

The rendering engine was extracted from MonoSketch, an open-source ASCII diagram editor.

Shape Description (JSON)
  → BitmapFactory (per shape type)
    → MonoBitmap (sparse character matrix)
      → MonoBoard (tiled canvas with crossing resolution)
        → ASCII string output

Engine modules:

• engine/geo/ — Point, Rect, Size geometry primitives
• engine/shape/ — Shape hierarchy (Rectangle, Text, Line, Group)
• engine/style/ — Stroke, fill, anchor, and alignment styles
• engine/bitmap/ — Sparse bitmap matrix and per-shape rendering factories
• engine/board/ — Tiled canvas compositing with Unicode line crossing resolution

License

MIT