# 📊 Plotting MCP Server

A MCP (Model Context Protocol) server that transforms CSV data into beautiful visualizations. Built with Python and optimized for seamless integration with AI assistants and chat applications.

## ✨ Features

- **📈 Multiple Plot Types**: Create line charts, bar graphs, pie charts, and world maps
- **🌍 Geographic Visualization**: Built-in support for plotting coordinate data on world maps using Cartopy
- **🔧 Flexible Parameters**: Fine-tune your plots with JSON-based configuration options
- **📱 Chat-Ready Output**: Returns base64-encoded PNG images perfect for AI chat interfaces
- **⚡ Fast Processing**: Efficient CSV parsing and plot generation with pandas and matplotlib

## Installation

### Using Makefile

```bash
make install
```

### Using uv

```bash
uv sync
```

## Usage

### Running the Server

```bash
uv run plotting-mcp
```

The server runs on port 9090 by default.

### Tools

#### `generate_plot`
Transform your CSV data into stunning visualizations.

**Parameters:**
- `csv_data` (str): CSV data as a string
- `plot_type` (str): Plot type - `line`, `bar`, `pie`, or `worldmap`
- `json_kwargs` (str): JSON string with plotting parameters for customization

**Plotting Options:**
- **Line/Bar Charts**: Use Seaborn parameters (`x`, `y`, `hue` for data mapping)
- **World Maps**: Automatic coordinate detection (`lat`/`latitude`/`y` and `lon`/`longitude`/`x`)
  - Customize with `s` (size), `c` (color), `alpha` (transparency), `marker` (style)
- **Pie Charts**: Supports single column (value counts) or two columns (labels + values)

**Returns:** Base64-encoded PNG image ready for display

## 🤖 AI Assistant Integration

Perfect for enhancing AI conversations with data visualization capabilities. The server returns plots as base64-encoded PNG images that display seamlessly in:

- **LibreChat**: Direct integration for chat-based data analysis
- **Claude Desktop**: Through `mcp-remote` command to transform from HTTP transport to stdio
```json
{
  "mcpServers": {
    "plotting": {
      "command": "uvx",
      "args": [
        "--from", "/path/to/plotting-mcp",
        "plotting-mcp", "--transport=stdio"
      ]
    }
  }
}
```
- **Custom AI Applications**: Easy integration via MCP protocol
- **Development Tools**: Compatible with any MCP-enabled environment

**Image Format**: High-quality PNG with configurable DPI and sizing

## 🚀 ToolHive Deployment

Deploy and manage your plotting server effortlessly with ToolHive - a platform that provides containerized, secure environments for MCP servers across UI, CLI, and Kubernetes modes.

**Benefits:**
- 🔒 **Secure Containerization**: Isolated environments with comprehensive security controls
- ⚙️ **Multiple Deployment Options**: UI, CLI, and Kubernetes support
- 🔧 **Developer-Friendly**: Seamless integration with popular development tools

📚 **Resources:**
- [ToolHive Documentation](https://docs.stacklok.com/toolhive/)
- [CLI Quickstart Guide](https://docs.stacklok.com/toolhive/tutorials/quickstart-cli)

### Build the Docker image

```bash
docker build -t plotting-mcp .
```

### Run with ToolHive

#### Run locally

```bash
thv run --name plotting-mcp --transport streamable-http plotting-mcp:latest
```

#### Run with ToolHive in K8s with ToolHive operator

1. Create a PVC for the MCP server. This is needed since the plotting libraries Matplotlib and Cartopy require a writable filesystem to cache data:
```bash
kubectl apply -f toolhive-pvc.yaml
```

2. Deploy the MCP server in K8s. In the `toolhive-deployment.yaml`, you can customize the `image` field to point to your image registry.
```bash
kubectl apply -f toolhive-deployment.yaml
```

3. Once the MCP server is deployed, do port-forwarding
```bash
kubectl port-forward svc/mcp-plotting-mcp-proxy 9090:9090
```

## 🛠️ Development

Built with modern Python tooling for a great developer experience.

**Tech Stack:**
- 🐍 **Python 3.13+**: Latest Python features
- 📊 **Seaborn & Matplotlib**: Professional-grade plotting
- 🌍 **Cartopy**: Advanced geospatial visualization
- ⚡ **FastMCP**: High-performance MCP server framework
- 🔧 **UV**: Fast Python package management

### Code Quality

```bash
# Format code and fix linting issues
make format

# Type checking
make typecheck

# Or use uv directly
uv run ruff format .
uv run ruff check --fix .
uv run ty check
```