<p align="center">
  <img src="./assets/logo.png" width="120" alt="Algo-MCP logo" />
</p>

<h1 align="center">Algo-MCP</h1>

<p align="center">
  Render live algorithmic visualizations directly in your AI chats via MCP.
</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
  <img src="https://img.shields.io/badge/Bun-1.0+-black?logo=bun" alt="Bun version" />
</p>

> **Prompt:** "Explain how the Sliding Window pattern works on the string 'abcabcbb'"
>
> **Agent:** Uses Algo-MCP's `render_tree_svg` tool to draw step-by-step state diagrams, and `render_algorithm_visualization` to summarize the time complexity with LaTeX and Mermaid flowcharts.

## Quick Start

```bash
# Install dependencies
bun install

# Compile the standalone production executable
bun run build

# Start the Hono server on port 3000
bun run start
```

<details>
<summary><strong>Table of contents</strong></summary>

- [What Is Algo-MCP?](#what-is-algo-mcp)
- [What Is Included](#what-is-included)
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Available Prompts](#available-prompts)
- [Run Locally](#run-locally)
- [Deployment (Docker)](#deployment-docker)

</details>

## What Is Algo-MCP?

Algo-MCP is an MCP (Model Context Protocol) server designed to help AI assistants teach and visualize Data Structures and Algorithms (DSA) like a pen-and-paper tutor. 

Instead of printing dense text or ASCII art, the agent can call Algo-MCP to render rich, colourful **SVG diagrams** (for trees, arrays, matrices, graphs, linked lists) and strict **LaTeX math states** for every step of an algorithmic dry run.

The central pattern is:

```mermaid
flowchart LR
    A[Agent Analysis] --> B[LaTeX Dry Run State]
    B --> C[SVG State Rendering]
    C --> D[Mermaid Call Graph Summary]
```

## What Is Included

- **Zero-Dependency SVG Engine**: A pure TypeScript layout engine in `src/svg-renderer.ts` that supports Arrays, Vertical Arrays (Stacks), Matrices (Grids), Linked Lists, Binary Trees, and Graphs.
- **Hono + Bun Server**: High-performance HTTP server wrapping the official MCP SDK.
- **Custom Prompts**: Pre-built instructions (`analyze_problem_statement`) that force the LLM to follow a strict, professional layout without cutting corners.

## Prerequisites

- [Bun](https://bun.sh/) (v1.3+ recommended) to run and build the project.
- An MCP client that supports standard HTTP/SSE connections.

## Configuration

Algo-MCP can be configured via environment variables:

| Variable | Description | Default |
| -------- | ----------- | ------- |
| `PORT`   | The port the Hono server binds to. | `3000` |

## Available Tools

### `render_tree_svg`
Renders visual representations of algorithms as a styled SVG image (dark theme, coloured highlights, comparison arrows). Returns the SVG as a base64 image alongside a markdown caption so it renders natively in the chat UI.
- **Inputs**: `title`, `description`, `trees` (array of tree nodes with `active`, `comparing`, `matched`, `mismatched`, `base` highlights), `comparisonArrows`.

### `render_algorithm_visualization`
Produces the final algorithmic summary.
- **Inputs**: `patternName`, `timeComplexity` (LaTeX), `spaceComplexity` (LaTeX), `stepByStepMath` (array of LaTeX states), `mermaidSyntax` (final composite flowchart).

### `list_directory`
Utility to list contents of a directory on the server.

## Available Prompts

### `analyze_problem_statement`
Upload a problem statement and force the model to solve it step-by-step with LaTeX math blocks and live SVG tree diagrams rendered in-chat. It guarantees a highly structured, rigorous dry-run.

## Run Locally

Install workspace dependencies:

```bash
bun install
```

Run in development (watch) mode:

```bash
bun run dev
```

Expected behavior: the server listens on `http://localhost:3000`. 
- **Healthcheck**: `GET http://localhost:3000/health`
- **MCP Endpoint**: `POST http://localhost:3000/mcp`

To format and lint the code before committing:
```bash
bun run format
bun run lint
```

## Deployment (Docker)

A multi-stage `Dockerfile` is provided for highly optimized production deployments:

```bash
# Build the image
docker build -t algo-mcp .

# Run the container
docker run -p 3000:3000 algo-mcp
```

The Docker image uses `oven/bun:1-slim` and runs as a secure, non-root `bun` user.