monosketch-mcp

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