# chart-mcp

An MCP App server that renders an interactive [Chart.js](https://www.chartjs.org/) chart inside an MCP host (e.g. Claude Desktop). Users can switch between chart types and regenerate random data without leaving the host UI.

## Features

- Eight chart types: line, bar, pie, doughnut, radar, polar area, bubble, scatter
- Chart type selector dropdown
- "Regenerate Data" button that fetches fresh random data from the server
- Host theme integration via CSS custom properties

## How it works

The server exposes two MCP tools and one resource:

| Name | Type | Description |
|------|------|-------------|
| `render-chart` | UI tool | Opens the chart UI in the host. Accepts an optional `chartType` argument. |
| `generate-data` | Tool | Returns Chart.js-compatible JSON for the given chart type. Called from the UI. |
| `ui://chart/mcp-app.html` | Resource | The bundled React + Chart.js single-file HTML served to the host. |

When the host invokes `render-chart` it reads the `_meta.ui.resourceUri` field and loads the bundled HTML as an interactive panel. The React UI then calls `generate-data` via `app.callServerTool()` whenever data is needed.

## Requirements

- Node.js 18+
- npm

## Getting started

```bash
npm install
npm run build
npm run serve          # HTTP transport on port 3001
# or
npm run serve:stdio    # stdio transport
```

During development, Vite watches source files and the server restarts on changes:

```bash
npm run dev
```

## Connecting to an MCP host

### HTTP transport

Point your MCP host at:

```
http://localhost:3001/mcp
```

### stdio transport

Use the `serve:stdio` script as the command in your host configuration:

```json
{
  "mcpServers": {
    "chart-mcp": {
      "command": "npm",
      "args": ["run", "serve:stdio"],
      "cwd": "/path/to/chart-mcp"
    }
  }
}
```

### Test host

The [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) repo ships a browser-based test host:

```bash
cd /path/to/mcp-ext-apps/examples/basic-host
npm install && npm run start
# open http://localhost:8080
```

Enter `http://localhost:3001/mcp` as the server URL, then invoke `render-chart` to open the chart UI.

## Usage

Once connected, ask the host to call the `render-chart` tool:

```
render-chart                         # defaults to bar chart
render-chart chartType="pie"         # open with pie chart selected
```

Inside the UI:

- Use the **Chart Type** dropdown to switch chart types — new data is fetched automatically.
- Click **Regenerate Data** to get fresh random data for the current chart type.

## Project structure

```
chart-mcp/
├── mcp-app.html       # Vite HTML entry point
├── main.ts            # HTTP + stdio transport entry point
├── server.ts          # MCP server: tools, resource, data generation
├── vite.config.ts     # Vite + singlefile config
├── tsconfig.json
├── package.json
└── src/
    ├── mcp-app.tsx    # React chart UI
    └── global.css     # Host CSS variable fallbacks
```

## Scripts

| Script | Description |
|--------|-------------|
| `npm run build` | Type-check and bundle the UI to `dist/mcp-app.html` |
| `npm run dev` | Vite watch + MCP server with live reload |
| `npm run serve` | Start MCP server (HTTP, port 3001) |
| `npm run serve:stdio` | Start MCP server (stdio) |

## License

Apache 2.0 — see [LICENSE](LICENSE).