# Mermaid MCP Server

Model Context Protocol server that bundles the official Mermaid syntax docs and a syntax validator so agents can search, quote, and check diagrams before sending them to users.

## What It Does
- Serves Mermaid syntax Markdown as MCP resources (flowchart, sequence, class, C4, etc.) plus a `guide` prompt for quick routing.
- `search_mermaid_docs` finds sections in the bundled docs (`mermaid/docs/syntax`) with optional diagram filtering and snippet/full modes. Results come from a startup cache for speed.
- `validate_mermaid` runs `mermaid.parse` to flag syntax issues; DOM-related errors are treated as pass-through so headless environments still work.

## Architecture
```mermaid
flowchart TD
    Client[MCP client] -->|stdio| StdioTransport
    Client -->|HTTP /mcp| HttpTransport
    StdioTransport --> Server
    HttpTransport --> Server
    Server[Mermaid MCP server] -->|registers| Resources[Docs resources + guide prompt]
    Server -->|tools| Tools
    Tools --> Search[search_mermaid_docs -> cached syntax md]
    Tools --> Validate[validate_mermaid -> mermaid.parse]
    Search --> DocsCache[Docs cache: mermaid/docs/syntax]
    Validate --> MermaidLib[Mermaid parser]
```

## Install & Run
- Clone (includes Mermaid submodule):
  - `git clone --recurse-submodules <repo-url>`
  - or, if already cloned: `git submodule update --init --recursive`
- Prereq: Node 18+
- Install: `npm install`
- Build: `npm run build`
- Start (STDIO for MCP clients): `npm run start:stdio`
- Start (HTTP for testing): `npm run start:http` (health at `/health`, MCP endpoint at `/mcp`)

## MCP Client Wiring (STDIO)
```json
{
  "mcpServers": {
    "mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-mermaid/dist/server.js"]
    }
  }
}
```

## Agent Usage Tips
- Always search first: `search_mermaid_docs` with a single-term query (e.g., `flowchart`, `subgraph`, `arrow`); use `diagram_type` to narrow by file; `mode: "full"` returns entire docs.
- Always validate after editing: `validate_mermaid` on the final diagram string.
- Use the `guide` prompt for quick diagram-type routing and common pitfalls.

## Tests
- Run unit tests: `npm test`

## Project Layout
- `src/server.ts` – MCP server, resources, tools, docs cache
- `src/httpServer.ts` – Express HTTP wrapper for `/mcp`
- `guides/` – `guide.md` prompt and config
- `mermaid/docs/syntax/` – Bundled official Mermaid syntax Markdown
- `dist/` – Built JS output

## Request Flow (User → Answer)
```mermaid
sequenceDiagram
    participant U as User
    participant A as MCP Client/Agent
    participant S as Mermaid MCP Server
    participant Docs as Docs Cache (mermaid/docs/syntax)
    participant V as validate_mermaid (mermaid.parse)

    U->>A: Ask for Mermaid help
    A->>S: search_mermaid_docs {query}
    S-->>Docs: Read cached syntax
    Docs-->>S: Return snippets/full sections
    S-->>A: Matched reference sections
    A->>S: validate_mermaid {code}
    S->>V: Parse diagram
    V-->>S: Valid / warnings / error
    S-->>A: Validation result
    A-->>U: Deliver answer + validated diagram
```