# Celi Miro MCP

Model Context Protocol (MCP) server for converting live Miro architecture diagrams into semantic, AI-ready graph context for coding assistants.

![Celi Miro MCP Hero Banner](assets/miro_mcp_hero.jpg)

---

## Executive Overview

**Celi Miro MCP** enables modern AI coding agents—including **Antigravity**, **Claude Code**, and **Cursor**—to deeply inspect, traverse, and understand architectural diagrams created on Miro whiteboards.

Instead of manually exporting diagrams, screenshotting boards, or manually describing system architectures, you can paste any Miro board URL directly into your AI chat:

```text
"Inspect the architecture in this board and implement the missing authentication service:
 https://miro.com/app/board/uXjVHCjkewI=/"
```

Your AI assistant automatically queries the Celi Miro MCP server, fetches board items and connectors, parses semantic groupings and relationships, compresses the topology into an optimal context graph, and applies the architecture directly to your codebase.

---

## Key Capabilities

| Feature | Description |
|---|---|
| **Zero Manual Exports** | Point your AI assistant to any Miro board URL; extraction and traversal occur in real time. |
| **Semantic Graph Reduction** | Translates raw Miro shapes, sticky notes, cards, and text boxes into structured nodes and edges. |
| **Short-ID Context Compression** | Assigns compact IDs (`n1`, `n2`, `n3`) to minimize token consumption in LLM context windows. |
| **In-Memory TTL Caching** | Prevents redundant Miro API requests during multi-turn developer chat conversations. |
| **Dual Transport Support** | Operates over standard input/output (`stdio`) for local development or `streamable-http` for remote container deployments. |
| **Multi-Editor Ready** | Native configurations for Google Antigravity, Cursor, and Anthropic Claude Code. |

---

## System Architecture & Data Flow

![Miro MCP Technical Pipeline](assets/mcp_pipeline.jpg)

The pipeline transforms raw whiteboard visual primitives into topological system architectures through four discrete phases:

```
[ Miro Board URL ] 
       │
       ▼
 1. URL Parser & Guard ─────── Validates board URL syntax & token presence
       │
       ▼
 2. Miro REST Client   ─────── Paginates /v2/boards/{board_id}/items & /connectors
       │
       ▼
 3. Graph Engine       ─────── Filters shapes, cleans HTML, resolves labels & groups
       │
       ▼
 4. Semantic Reducer   ─────── Builds adjacency graph, generates short-ID map (n1, n2...)
       │
       ▼
[ FastMCP Server ]     ─────── Delivers context to Antigravity, Claude Code, or Cursor
```

### Request Lifecycle Sequence

```mermaid
sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Agent as AI Coding Agent (Antigravity / Cursor)
    participant MCP as Celi Miro MCP Server
    participant Miro as Miro REST API v2

    Dev->>Agent: "Analyze architecture: https://miro.com/app/board/uXjV.../"
    Agent->>MCP: get_miro_architecture(board_url)
    MCP->>MCP: Parse board ID & verify auth header
    MCP->>Miro: GET /v2/boards/{board_id}/items (paginated)
    Miro-->>MCP: Raw items (shapes, cards, text)
    MCP->>Miro: GET /v2/boards/{board_id}/connectors (paginated)
    Miro-->>MCP: Raw connectors & captions
    MCP->>MCP: Strip HTML, resolve node labels & group hierarchy
    MCP->>MCP: Build adjacency list & compress to compact graph
    MCP-->>Agent: JSON semantic architecture graph + token map
    Agent->>Dev: Delivers precise architectural insights & code scaffolding
```

---

## MCP Tools Reference

![Miro MCP Tools Overview](assets/mcp_tools.jpg)

The server exposes four focused MCP tools designed for agentic reasoning:

### 1. `get_miro_architecture`
Extracts the complete semantic architecture graph for a given Miro board.

- **Parameters**:
  - `board_url` (*string*, required): Full Miro board URL (e.g., `https://miro.com/app/board/uXjVHCjkewI=/`).
  - `force_refresh` (*boolean*, optional, default: `false`): Bypass TTL cache and re-fetch directly from Miro.
- **Example Agent Query**:
  > *"What are all the services and databases defined on this architecture board?"*
- **Response Format**:
  ```json
  {
    "success": true,
    "board_id": "uXjVHCjkewI=",
    "nodes": [
      { "id": "n1", "label": "API Gateway", "type": "shape", "fill": "#2d9cdb" },
      { "id": "n2", "label": "Authentication Service", "type": "shape", "fill": "#27ae60" },
      { "id": "n3", "label": "User Database", "type": "shape", "fill": "#f2994a" }
    ],
    "edges": [
      { "source": "n1", "target": "n2", "directed": true, "label": "POST /auth/login" },
      { "source": "n2", "target": "n3", "directed": true, "label": "SQL Query" }
    ],
    "id_map": {
      "3458764512345678901": "n1",
      "3458764512345678902": "n2",
      "3458764512345678903": "n3"
    }
  }
  ```

---

### 2. `get_miro_board_info`
Lightweight pre-flight probe to verify token permissions and board accessibility without downloading the complete canvas.

- **Parameters**:
  - `board_url` (*string*, required): Full Miro board URL.
- **Example Agent Query**:
  > *"Can I access this Miro board with my current credentials?"*
- **Response Format**:
  ```json
  {
    "success": true,
    "board_id": "uXjVHCjkewI=",
    "accessible": true
  }
  ```

---

### 3. `get_miro_node`
Retrieves a specific component by its compressed node ID along with all immediate upstream and downstream connections.

- **Parameters**:
  - `board_url` (*string*, required): Full Miro board URL.
  - `node_id` (*string*, required): Compressed node ID (e.g., `"n2"`).
  - `force_refresh` (*boolean*, optional, default: `false`): Force cache invalidation.
- **Example Agent Query**:
  > *"Inspect node n2: what services depend on it and what does it connect to?"*
- **Response Format**:
  ```json
  {
    "success": true,
    "node": {
      "id": "n2",
      "label": "Authentication Service",
      "type": "shape"
    },
    "connections": [
      {
        "id": "n1",
        "label": "API Gateway",
        "direction": "incoming",
        "edge_label": "POST /auth/login"
      },
      {
        "id": "n3",
        "label": "User Database",
        "direction": "outgoing",
        "edge_label": "SQL Query"
      }
    ]
  }
  ```

---

### 4. `search_miro_architecture`
Performs a case-insensitive search across all node labels on the board to locate specific components.

- **Parameters**:
  - `board_url` (*string*, required): Full Miro board URL.
  - `query` (*string*, required): Search term (e.g., `"database"`, `"redis"`, `"payment"`).
  - `force_refresh` (*boolean*, optional, default: `false`): Force cache invalidation.
- **Example Agent Query**:
  > *"Search the board for any components related to 'payment' or 'checkout'."*
- **Response Format**:
  ```json
  {
    "success": true,
    "query": "payment",
    "matches": [
      { "id": "n7", "label": "Payment Processing Service", "type": "card" },
      { "id": "n8", "label": "Stripe Webhook Handler", "type": "shape" }
    ]
  }
  ```

---

## Installation & Setup

### Prerequisites
- Python 3.10 or later
- A Miro account with a Personal Access Token ([Generate Miro Token](https://miro.com/app/settings/user-profile/api-access))

### 1. Clone & Install Dependencies

```bash
# Clone the repository
git clone <repo-url>
cd "miro MCP/project"

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install required dependencies
pip install -r requirements.txt
```

---

### 2. Automated 1-Click Client Setup (Windows)

Use the built-in interactive setup script to configure your AI editors in seconds:

```powershell
# Run the PowerShell setup script
cd install
.\setup_mcp.ps1
```

Or double-click `setup_mcp.bat`. The installer will prompt for your Miro Access Token and automatically configure:
- Google Antigravity (`~/.gemini/config/mcp_config.json`)
- Cursor IDE (`~/.cursor/mcp.json`)
- Claude Code CLI (`claude mcp add`)

---

### 3. Manual Editor Configuration

#### A. Google Antigravity
Add the server entry to your global or workspace `mcp_config.json`:

```json
{
  "mcpServers": {
    "celi-miro": {
      "command": "python",
      "args": ["-m", "mcp_data.server"],
      "cwd": "C:/Users/USER/Desktop/miro MCP/project",
      "env": {
        "MIRO_ACCESS_TOKEN": "your_miro_access_token_here",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

*For HTTP transport mode:*
```json
{
  "mcpServers": {
    "celi-miro": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer your_miro_access_token_here"
      }
    }
  }
}
```

#### B. Cursor IDE
Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "celi-miro": {
      "command": "python",
      "args": ["-m", "mcp_data.server"],
      "cwd": "C:/Users/USER/Desktop/miro MCP/project",
      "env": {
        "MIRO_ACCESS_TOKEN": "your_miro_access_token_here"
      }
    }
  }
}
```

#### C. Claude Code
Run the registration command in your terminal:

```bash
# stdio mode
claude mcp add --scope user celi-miro python -m mcp_data.server

# HTTP mode
claude mcp add --transport http --header "Authorization: Bearer YOUR_MIRO_TOKEN" --scope user celi-miro http://127.0.0.1:8000/mcp
```

---

## Standalone Pipeline Execution (`main.py`)

You can also run the extraction pipeline as a standalone CLI tool without launching an MCP server:

```bash
# Set environment variables in .env
MIRO_ACCESS_TOKEN=your_token_here
MIRO_BOARD_ID=your_board_id_here
MIRO_OUTPUT_DIR=miro_data

# Execute the pipeline
python main.py
```

### Generated Artifacts (`miro_data/`)

| File | Purpose |
|---|---|
| `items.json` | Complete raw JSON array of all items on the board. |
| `connectors.json` | Complete raw JSON array of all board connectors and captions. |
| `architecture_graph.json` | Compressed semantic graph featuring shortened IDs (`n1`, `n2`...). |
| `architecture.md` | Ultra-compact Markdown representation tailored for LLM prompt context. |
| `id_map.json` | Bi-directional mapping between raw Miro IDs and compressed short IDs. |
| `relationships.json` | Human-readable component relationship inventory. |
| `board.json` | Consolidated snapshot containing all items, connectors, and relations. |

### Sample Markdown Output (`architecture.md`)

```markdown
# Architecture Graph (uXjVHCjkewI=)

## Items
- n1: API Gateway (shape)
- n2: Authentication Service (shape)
- n3: User Database (shape)
- n4: Redis Session Store (shape)

## Relations
- n1 (API Gateway) -[POST /auth/login]-> n2 (Authentication Service)
- n2 (Authentication Service) -[SQL Query]-> n3 (User Database)
- n2 (Authentication Service) -[Cache Lookup]-> n4 (Redis Session Store)
```

---

## Docker & Remote Hosting

A production-ready `Dockerfile` is included for hosting Celi Miro MCP on container platforms (e.g., AWS ECS, Google Cloud Run, Railway):

```bash
# Build the Docker container
docker build -t celi-miro-mcp .

# Run with HTTP transport on port 8000
docker run -d \
  -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e PORT=8000 \
  -e MIRO_ACCESS_TOKEN=your_token \
  celi-miro-mcp
```

Test the live endpoint:
```bash
curl http://localhost:8000/mcp
```

---

## Environment Variables Reference

| Variable | Required | Default | Description |
|---|---|---|---|
| `MIRO_ACCESS_TOKEN` | Yes (or `MIRO_API_KEY`) | — | Miro API Personal Access Token. |
| `MIRO_BOARD_ID` | Only for `main.py` | — | Target Miro board identifier for standalone runs. |
| `MCP_TRANSPORT` | No | `stdio` | Transport protocol: `stdio` (local) or `http` (remote). |
| `PORT` | No | `8000` | HTTP listen port when `MCP_TRANSPORT=http`. |
| `MIRO_OUTPUT_DIR` | No | `miro_data` | Directory for files generated by `main.py`. |

---

## Project Structure

```
project/
├── assets/                  # AI-generated documentation graphics & diagrams
│   ├── miro_mcp_hero.jpg    # Hero banner illustration
│   ├── mcp_pipeline.jpg     # Technical architecture pipeline schematic
│   └── mcp_tools.jpg        # 4-tool overview and query workflow diagram
├── install/                 # One-click client installer scripts
│   ├── setup_mcp.ps1        # PowerShell automated configuration utility
│   └── setup_mcp.bat        # Windows batch file launcher
├── mcp_data/                # MCP protocol server implementation
│   ├── __init__.py
│   ├── errors.py            # Structured MCP error response builders
│   ├── miro_url.py          # Miro URL validation & board ID extractor
│   ├── pipeline.py          # Cached extraction pipeline with TTL
│   └── server.py            # FastMCP server & tool definitions
├── client.py                # Paginated Miro REST API v2 client
├── config.py                # Environment configuration & constants
├── Dockerfile               # Container build definition (Python 3.12-slim)
├── graph.py                 # Graph construction & short-ID compression
├── LICENSE                  # Non-Commercial Personal & Hobby Use License
├── main.py                  # Standalone local extraction entrypoint
├── parser.py                # HTML tag stripping & node label extraction
├── README.md                # Comprehensive documentation
├── requirements.txt         # Pinned Python package dependencies
└── storage.py               # JSON & Markdown export utilities
```

---

## Error Codes & Troubleshooting

| Error Code | HTTP Status | Meaning | Resolution |
|---|---|---|---|
| `MIRO_AUTH_TOKEN_MISSING` | — | No access token was provided in header or env. | Add `MIRO_ACCESS_TOKEN` to env or `Authorization: Bearer <token>` in header. |
| `MIRO_AUTHENTICATION_FAILED` | `401` | Token is invalid, revoked, or expired. | Generate a new token in Miro Developer settings. |
| `MIRO_BOARD_ACCESS_DENIED` | `403` | Token lacks permission for this specific board. | Confirm board is shared with the Miro account owning the token. |
| `MIRO_BOARD_NOT_FOUND` | `404` | Board URL does not exist or was deleted. | Check board URL spelling and verify board exists. |
| `MIRO_RATE_LIMITED` | `429` | Miro rate limit threshold reached. | Server respects `Retry-After`; wait and retry. |
| `INVALID_MIRO_URL` | — | Provided string is not a valid Miro board link. | Ensure URL begins with `https://miro.com/app/board/`. |
| `NODE_NOT_FOUND` | — | Requested node ID does not exist in graph. | Call `get_miro_architecture` or `search_miro_architecture` to find IDs. |

---

## License

This project is licensed under the **Non-Commercial Personal & Hobby Use License**.

- **Permitted**: Personal, educational, experimentation, testing, and hobbyist projects are free of charge.
- **Strictly Prohibited**: Selling, reselling, sublicensing, leasing, commercial distribution, or incorporating into commercial products/services without explicit prior written authorization from the Copyright Holder.

See [LICENSE](LICENSE) for the complete legal terms.