Algo-MCP

<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

# 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 Included
• Prerequisites
• Configuration
• Available Tools
• Available Prompts
• Run Locally
• 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:

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 (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:

bun install

Run in development (watch) mode:

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:

bun run format
bun run lint

Deployment (Docker)

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

# 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.