# vvk-charts-mcp

<p>
  <a href="https://github.com/valderan/vvk-charts-mcp/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0ea5e9" /></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-2563eb" />
  <img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-10b981" />
  <img alt="Plotly" src="https://img.shields.io/badge/Plotly-modern%20charts-7c3aed" />
</p>

Documentation language:

- English: `README.md`
- Russian: [`README_ru.md`](README_ru.md)

Modern Python MCP server for rendering charts and diagrams (`line`, `bar`, `pie`, `scatter`, `area`, and `combined dashboard`) with customizable themes and export to PNG/SVG/base64.

<p align="center">
  <img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate combined dashboard example" width="560" />
  <br />
  <em>Example output: dark corporate combined dashboard generated by the MCP tool.</em>
</p>

## Table of contents

- [Features](#features)
- [Quick start](#quick-start)
- [MCP tools](#mcp-tools)
- [Combined dashboard payload example](#combined-dashboard-payload-example)
- [Terminal chart payload example](#terminal-chart-payload-example)
- [Demo gallery](#demo-gallery)
- [AI presets (skill and agent)](#ai-presets-skill-and-agent)
- [OpenCode setup (detailed)](#opencode-setup-detailed)
- [Codex setup (detailed)](#codex-setup-detailed)
- [Local development](#local-development)

## Features

- MCP tools for single charts and mixed dashboards.
- Terminal chart tools with ANSI rendering and monochrome fallback.
- Modern Plotly styling with full theme customization.
- Works with multi-series and larger datasets.
- Export formats: `png`, `svg`, `base64`.
- Interactive CLI test client with predefined templates.

## Quick start

Install from GitHub with `uvx`:

```bash
uvx install git+https://github.com/valderan/vvk-charts-mcp.git
```

Run MCP server:

```bash
uvx run vvk-charts-mcp
```

Run interactive test client:

```bash
uvx run vvk-charts-cli
```

The CLI asks what to draw, where to save, output format, and image size.

Tip: set output mode to `terminal` in `vvk-charts-cli` to preview console dashboards.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `list_theme_presets` | Lists available image/terminal themes |
| `create_line_chart` | Trends over time |
| `create_bar_chart` | Category comparison |
| `create_pie_chart` | Part-to-whole split |
| `create_scatter_chart` | Correlation and bubble plots |
| `create_area_chart` | Stacked/cumulative composition |
| `create_combined_dashboard` | Multiple chart types in one image |
| `create_terminal_chart` | ANSI/mono chart output for terminal clients |
| `create_terminal_dashboard` | Multi-panel terminal dashboard as plain text |

Common options supported by all tools:

- `theme_preset`, `theme`, `title`, `width`, `height`
- `format` (`png`, `svg`, `base64`)
- `filename`, `save_to_disk`

Image tools always return chat preview (`ImageContent`).
To save files, set `save_to_disk: true` and configure `OUTPUT_DIR` in MCP `env`.

## Theme presets

Use `list_theme_presets` to get all available theme names at runtime.

Image theme presets:
- `clean_light` (default)
- `dark_corporate`
- `pastel_startup`
- `medical_monitor`

Terminal theme presets:
- `dark_corporate_cli` (default)
- `pastel_startup_cli`

Example request:

```json
{
  "tool": "list_theme_presets",
  "arguments": {}
}
```

## Combined dashboard payload example

```json
{
  "title": "Marketing Dashboard",
  "rows": 1,
  "cols": 2,
  "theme_preset": "dark_corporate",
  "format": "png",
  "save_to_disk": true,
  "filename": "combined_dashboard",
  "panels": [
    {
      "type": "line",
      "row": 1,
      "col": 1,
      "title": "Revenue Trend",
      "x_label": "Month",
      "y_label": "k USD",
      "data": [
        {
          "name": "Revenue",
          "x": ["Jan", "Feb", "Mar", "Apr"],
          "y": [120, 132, 148, 160]
        }
      ],
      "options": {
        "line_shape": "spline"
      }
    },
    {
      "type": "pie",
      "row": 1,
      "col": 2,
      "title": "Budget Split",
      "data": [
        {
          "labels": ["Search", "Social", "Email"],
          "values": [45, 35, 20]
        }
      ],
      "options": {
        "hole": 0.45
      }
    }
  ]
}
```

## Terminal chart payload example

```json
{
  "tool": "create_terminal_chart",
  "arguments": {
    "type": "line",
    "title": "Revenue Trend (CLI)",
    "x_label": "Month",
    "y_label": "k USD",
    "theme": "dark_corporate_cli",
    "use_color": true,
    "force_mono": false,
    "raw_output": true,
    "data": [
      {
        "name": "Revenue",
        "x": ["Jan", "Feb", "Mar", "Apr", "May"],
        "y": [120, 132, 148, 160, 178]
      }
    ]
  }
}
```

`raw_output: true` is recommended for terminal clients: tool returns only chart text (no JSON wrapper).

## Image save behavior (`OUTPUT_DIR`)

- `save_to_disk: false` (default): no file is written, preview is returned to chat.
- `save_to_disk: true` and `OUTPUT_DIR` is set: file is saved only into `OUTPUT_DIR`.
- `save_to_disk: true` and `OUTPUT_DIR` is not set: no error, preview only (`saved=false` in metadata).
- `output_path` is not supported.

Example MCP config fragment:

```json
{
  "mcp": {
    "vvkcharts": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "git+https://github.com/valderan/vvk-charts-mcp.git", "vvk-charts-mcp"],
      "env": {
        "OUTPUT_DIR": "./output"
      }
    }
  }
}
```

## Demo gallery

<p>
  <img src="demo/demo_combined_showcase.png" alt="Combined dashboard showcase" width="420" />
  <img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate dashboard" width="420" />
  <img src="demo/demo_combined_pastel_startup.png" alt="Pastel startup dashboard" width="420" />
</p>

<p>
  <img src="demo/demo_line_chart.png" alt="Line chart demo" width="270" />
  <img src="demo/demo_bar_chart.png" alt="Bar chart demo" width="270" />
  <img src="demo/demo_pie_chart.png" alt="Pie chart demo" width="270" />
  <img src="demo/demo_scatter_chart.png" alt="Scatter chart demo" width="270" />
  <img src="demo/demo_area_chart.png" alt="Area chart demo" width="270" />
</p>

## AI presets (skill and agent)

Repository includes reusable AI presets in `ai/`:

- `ai/vvk-charts-skill.md` - skill instructions for chart payload building.
- `ai/vvk-charts-agent.md` - chart-specialized subagent profile.

Use whichever workflow is more convenient.

## OpenCode setup (detailed)

### 1) Add this MCP server

Create or edit `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vvkcharts": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/valderan/vvk-charts-mcp.git",
        "vvk-charts-mcp"
      ]
    }
  }
}
```

### 2) Install as an OpenCode skill

```bash
mkdir -p .opencode/skills/vvk-charts-mcp
cp ai/vvk-charts-skill.md .opencode/skills/vvk-charts-mcp/SKILL.md
```

### 3) Install as an OpenCode agent

```bash
mkdir -p .opencode/agents
cp ai/vvk-charts-agent.md .opencode/agents/vvk-charts.md
```

### 4) Verify

- Start `opencode` in this repository.
- Ensure `vvkcharts_*` tools are visible.
- Test prompt: `Build a monthly revenue line chart and save as png in ./output using vvkcharts`.

References:

- https://opencode.ai/docs/mcp-servers/
- https://opencode.ai/docs/skills/
- https://opencode.ai/docs/agents/

## Codex setup (detailed)

Codex-compatible clients may vary, but this flow works in MCP-enabled environments.

### 1) Register MCP server

```bash
uvx --from git+https://github.com/valderan/vvk-charts-mcp.git vvk-charts-mcp
```

Typical JSON shape used by many clients:

```json
{
  "mcpServers": {
    "vvkcharts": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/valderan/vvk-charts-mcp.git",
        "vvk-charts-mcp"
      ]
    }
  }
}
```

### 2) Reuse skill and agent presets

- Use `ai/vvk-charts-skill.md` as a reusable prompt template.
- Use `ai/vvk-charts-agent.md` as a dedicated chart profile/system prompt.

### 3) Verify

Run a request like:

`Use vvkcharts tools to generate a bar chart and save it to ./output/sales-q1.png`.

## Local development

```bash
uv sync
uv run ruff check .
uv run mypy src
```

## Repository

- https://github.com/valderan/vvk-charts-mcp

---

Русская версия документации: [`README_ru.md`](README_ru.md)