# mcp-monodraw

An MCP (Model Context Protocol) server for [Monodraw](https://monodraw.helftone.com/), the powerful ASCII art editor for macOS.

## Features

- **Export diagrams** - Convert `.monopic` and `.monojson` files to plain text or JSON
- **List diagrams** - Find all Monodraw files in a directory
- **Open in Monodraw** - Launch files directly in the Monodraw app
- **Create ASCII art** - Generate boxes, flowcharts, tables, trees, and sequence diagrams
- **Diagram prompts** - Pre-built templates for common diagram types

## Requirements

- Node.js 18+
- macOS
- Monodraw (Direct version from [helftone.com](https://monodraw.helftone.com/), not App Store)

> **Note:** The Monodraw CLI is only available in the Direct version. The Mac App Store version does not include CLI support due to sandbox restrictions.

## Installation

```bash
npm install -g mcp-monodraw
```

Or use directly with npx:

```bash
npx mcp-monodraw
```

## Configuration

### Claude Code

Add the MCP server to your project or global config:

```bash
claude mcp add monodraw -- npx mcp-monodraw
```

Or manually add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "monodraw": {
      "command": "npx",
      "args": ["mcp-monodraw"]
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "monodraw": {
      "command": "npx",
      "args": ["mcp-monodraw"]
    }
  }
}
```

## Tools

### export_diagram

Export a Monodraw diagram to plain ASCII text.

```
filePath: string (required) - Path to the .monopic or .monojson file
unicode: boolean - Use Unicode characters in output (default: false)
trimWhitespace: boolean - Trim trailing whitespace (default: true)
```

### export_diagram_json

Export a diagram with full metadata as structured JSON.

```
filePath: string (required) - Path to the diagram file
```

### list_diagrams

Find all Monodraw files in a directory.

```
directory: string - Directory to search (default: ".")
recursive: boolean - Search subdirectories (default: true)
```

### open_in_monodraw

Open a file in the Monodraw application.

```
filePath: string (required) - Path to the file to open
```

### get_diagram_preview

Get a text preview of a diagram file.

```
filePath: string (required) - Path to the diagram file
maxLines: number - Maximum lines to return (default: 20)
```

### create_ascii_art

Generate ASCII art programmatically.

```
type: "box" | "flowchart" | "sequence" | "architecture" | "table" | "tree"
content: string (required) - Content or description
style: "single" | "double" | "rounded" | "heavy" | "ascii" (default: "single")
width: number - Maximum width
```

## Prompts

Pre-built templates for generating diagrams:

- `flowchart` - Create flowchart diagrams
- `box-diagram` - Create box/container diagrams
- `sequence-diagram` - Create sequence diagrams
- `architecture` - Create architecture diagrams
- `table` - Create ASCII tables
- `tree` - Create tree structures

## Examples

### Export a diagram

```
Use the export_diagram tool with filePath: "/path/to/diagram.monopic"
```

### Create a flowchart

```
Use the create_ascii_art tool with:
  type: "flowchart"
  content: "Start, Process Data, Validate, Save, End"
  style: "rounded"
```

Output:
```
╭─────────────────╮
│      Start      │
╰─────────────────╯
        │
        v
╭─────────────────╮
│  Process Data   │
╰─────────────────╯
        │
        v
╭─────────────────╮
│    Validate     │
╰─────────────────╯
        │
        v
╭─────────────────╮
│      Save       │
╰─────────────────╯
        │
        v
╭─────────────────╮
│       End       │
╰─────────────────╯
```

## Development

```bash
# Install dependencies
yarn install

# Build
yarn build

# Run in development
yarn dev
```

## License

MIT