# Kroki MCP Diagram Generator

A Python project that turns natural-language prompts into rendered diagrams using a LangGraph workflow, an LLM, and the Kroki rendering engine. It can generate diagram source, validate it against Kroki, and save the final SVG output to disk for direct viewing.

## Overview

This project combines three main components:

- A Kroki HTTP client for sending diagram source to Kroki
- A FastMCP server that exposes rendering tools to AI agents
- A LangGraph agent that classifies the request, generates DSL, validates it, and repairs it if needed

The goal is to make diagram generation feel like a tool-backed AI workflow rather than a standalone script.

## Architecture

```mermaid
flowchart LR
    A[User Prompt] --> B[LangGraph Agent]
    B --> C[Intent Classification]
    C --> D[DSL Generation]
    D --> E[Kroki Validation / Render]
    E -->|Failure| F[Self Repair]
    F --> E
    E -->|Success| G[SVG File Output]
```

## Project Structure

```text
kroki_mcp/
├── agent.py             # LangGraph workflow for generating and validating diagrams
├── kroki_client.py     # HTTP client for Kroki rendering requests
├── mcp_server.py       # FastMCP server exposing diagram tools
├── requirements.txt    # Python dependencies
├── .env.example        # Example environment variables
└── output/             # Generated SVG files
```

## Main Components

### 1. Agent Workflow

The agent in [agent.py](agent.py) uses a state machine to:

1. Interpret the user's request
2. Choose the most appropriate diagram engine
3. Generate diagram source in the relevant DSL
4. Send it to Kroki for rendering
5. Retry and self-repair if the syntax is invalid

It uses:

- LangGraph for orchestration
- LangChain message objects for prompts
- OpenAI-compatible LLM endpoints via langchain-openai

### 2. Kroki Client

The client in [kroki_client.py](kroki_client.py) handles:

- payload compression and encoding
- HTTP GET/POST requests to Kroki
- SVG rendering requests

It supports the public Kroki endpoint at https://kroki.io by default.

### 3. MCP Server

The FastMCP server in [mcp_server.py](mcp_server.py) exposes tools such as:

- render_diagram
- validate_diagram
- get_diagram_capabilities

These tools can be used by AI agents or MCP-compatible clients.

## Supported Diagram Types

The workflow can target several diagram engines, including:

- mermaid
- plantuml
- d2
- c4plantuml
- graphviz
- erd
- bpmn

## Dependencies

The project uses:

- fastmcp
- httpx
- langgraph
- langchain-core
- langchain-openai
- pydantic
- python-dotenv

See [requirements.txt](requirements.txt) for the exact versions.

## Environment Setup

Create a local environment file named `.env` in the project root.

Example:

```env
KROKI_HOST=https://kroki.io
API_KEY=your_api_key_here
BASE_URL=your_base_url_here
MODEL_NAME=your_model_name_here
```

> The agent will fall back to local placeholder content if the LLM configuration is not available.

## Installation

Create and activate a virtual environment:

```bash
python -m venv .venv
.venv\Scripts\activate
```

Install dependencies:

```bash
pip install -r requirements.txt
```

## Running the Agent

Run:

```bash
python agent.py
```

If rendering succeeds, the script will write an SVG file to the [output](output) directory.

## Example Flow

```mermaid
sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Kroki

    User->>Agent: Give a diagram request
    Agent->>LLM: Choose diagram type
    LLM-->>Agent: Selected engine
    Agent->>LLM: Generate DSL
    LLM-->>Agent: Diagram source
    Agent->>Kroki: Render SVG
    Kroki-->>Agent: Rendered SVG
    Agent->>User: Save SVG file
```

## Output

The generated file is saved in the output folder as an SVG, for example:

- [output/diagram_mermaid.svg](output/diagram_mermaid.svg)

This file can be opened directly in a browser or any SVG-compatible viewer.

## Notes

- The project is designed for experimentation and integration with AI agents.
- It is not yet a full production deployment system, but it provides the core building blocks for one.
- For real-world use, you may want to add authentication, logging, caching, and persistent storage.

## Future Improvements

Possible enhancements include:

- support for PNG and PDF export
- richer error handling and logging
- database-backed history and diagram storage
- a web UI for uploading prompts and viewing diagrams
- deployment as a service or container