# echart-mcp-view

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/echart-mcp-view.svg)](https://www.npmjs.com/package/echart-mcp-view)
[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json)
[![MCP Apps](https://img.shields.io/badge/MCP-Apps-635bff.svg)](https://github.com/modelcontextprotocol/ext-apps)
[![ECharts 6](https://img.shields.io/badge/ECharts-6-5470c6.svg)](https://echarts.apache.org/)

Agent-ready ECharts visualization for MCP Apps.

`echart-mcp-view` is an MCP server that turns structured tool arguments into polished, interactive chart views. It exposes one model-visible opener tool per chart type, serves each chart UI as an independent MCP App HTML resource, and lets the embedded app rebuild ECharts options from validated data without asking the model to hand-write chart configuration.

## Highlights

- **16 focused chart apps** for tables, Cartesian charts, relationships, hierarchy, flow, KPI, finance, and distribution views.
- **MCP Apps first**: every opener tool maps to a `ui://` HTML resource rendered by a compliant host.
- **Structured chart input**: callers provide data, encodings, axes, presentation, and interaction controls instead of raw ECharts options.
- **Host-aware UI**: app chrome follows Host theme, locale, and `inline` / `fullscreen` display mode when available.
- **Single-file app bundles**: every chart surface is built into a self-contained HTML resource under `dist/client/`.
- **Safe customization**: `advanced.optionPatch` accepts controlled style/layout keys while blocking series, datasets, axes, formatter functions, HTML rendering, timelines, and render modes.
- **Debuggable by design**: optional debug mode reveals input JSON and generated chart options for local inspection.

## How It Works

1. The model calls a chart opener tool such as `echart_mcp_view_open_line`.
2. The tool validates the input and returns structured content plus MCP App metadata.
3. The Host fetches the matching `ui://echart-mcp-view/*.html` resource and renders it in a sandboxed iframe.
4. The embedded React app receives tool input/result notifications, builds an ECharts option through the app-only helper tool, and renders the chart.

This keeps the model-facing tool surface compact while keeping chart rendering, theme handling, and interactive UI behavior inside the app.

## Chart Catalog

Model-visible opener tools:

| Chart | Tool | Best for |
| --- | --- | --- |
| Table | `echart_mcp_view_open_table` | Row and column inspection |
| Line | `echart_mcp_view_open_line` | Trends, time series, multi-metric comparison |
| Bar | `echart_mcp_view_open_bar` | Category comparison, grouped bars, stacked bars |
| Pie | `echart_mcp_view_open_pie` | Share-of-total, donut, rose charts |
| Scatter | `echart_mcp_view_open_scatter` | Correlation, bubble size, visual maps |
| Radar | `echart_mcp_view_open_radar` | Multi-dimensional profile comparison |
| Heatmap | `echart_mcp_view_open_heatmap` | Matrix intensity and two-dimensional density |
| Funnel | `echart_mcp_view_open_funnel` | Conversion stages and ordered drop-off |
| Gauge | `echart_mcp_view_open_gauge` | Single KPI, progress, threshold state |
| Tree | `echart_mcp_view_open_tree` | Parent-child hierarchy |
| Treemap | `echart_mcp_view_open_treemap` | Hierarchical size comparison |
| Graph | `echart_mcp_view_open_graph` | Node-link relationship networks |
| Sankey | `echart_mcp_view_open_sankey` | Weighted source-target flows |
| Candlestick | `echart_mcp_view_open_candlestick` | OHLC market or range data |
| Boxplot | `echart_mcp_view_open_boxplot` | Distribution summaries and outliers |
| Mixed | `echart_mcp_view_open_mixed` | Combined bar and line series |

App-only helper tools:

| Tool | Purpose |
| --- | --- |
| `echart_mcp_view_app_build_option` | Validate chart input and return a table view model or ECharts option for the current app payload |
| `echart_mcp_view_app_examples` | Return reusable sample inputs for one chart type or all chart types |

## Quick Start

Requirements:

- Node.js 20+
- npm

Run the published package over Streamable HTTP:

```bash
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```

Default HTTP endpoints:

```text
http://127.0.0.1:3338/mcp
http://127.0.0.1:3338/healthz
```

Run over stdio when an MCP host launches this server as a local command:

```bash
npx -y echart-mcp-view@latest --stdio
```

For a source checkout, install and build first:

```bash
npm install
npm run build
npm run start
```

## MCP Host Configuration

Recommended stdio configuration with `npx`:

```json
{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "npx",
      "args": ["-y", "echart-mcp-view@latest", "--stdio"]
    }
  }
}
```

Pin the version for reproducible host setups:

```json
{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "npx",
      "args": ["-y", "echart-mcp-view@0.1.1", "--stdio"]
    }
  }
}
```

Source checkout stdio configuration:

```json
{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "node",
      "args": ["/absolute/path/to/echart-mcp-view/dist/index.js", "--stdio"]
    }
  }
}
```

Streamable HTTP with `npx`:

```bash
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```

Use the `/mcp` endpoint in hosts that support Streamable HTTP MCP connections.

## NPM Package

The package exposes a single executable:

```bash
echart-mcp-view --stdio
echart-mcp-view --http --host 127.0.0.1 --port 3338
```

Local global install is optional:

```bash
npm install -g echart-mcp-view
echart-mcp-view --stdio
```

Use `npx` for one-off runs or Host-managed launches:

```bash
npx -y echart-mcp-view@latest --stdio
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```

## Runtime Modes

### Transports

- `--stdio`: stdio transport for local MCP host process management.
- `--http`: Streamable HTTP transport, served at `/mcp`.
- `--host` and `--port`: override HTTP bind host and port.

### Environment

```bash
ECHART_MCP_VIEW_HTTP_HOST=127.0.0.1
ECHART_MCP_VIEW_HTTP_PORT=3338
ECHART_MCP_VIEW_ALLOWED_ORIGINS=http://localhost:3000
ECHART_MCP_VIEW_ALLOWED_HOSTS=localhost,127.0.0.1
ECHART_MCP_VIEW_HTTP_AUTH_TOKEN=optional-bearer-token
ECHART_MCP_VIEW_DEBUG=0
```

Remote HTTP mode requires explicit allowed hosts, allowed origins, and an auth token.

### Debug Mode

The JSON input and generated-option panel is hidden by default. Enable it when inspecting payloads or chart output:

```bash
ECHART_MCP_VIEW_DEBUG=1 node dist/index.js --http --host 127.0.0.1 --port 3338
ECHART_MCP_VIEW_DEBUG=1 node dist/index.js --stdio
```

For direct local app-page inspection, append `?debug=1` or `?debug=true` to the built app URL.

## MCP Apps Behavior

- **Theme**: explicit `presentation.theme` wins; otherwise the app follows `hostContext.theme`; without Host context it falls back to `prefers-color-scheme`.
- **Display mode**: app capabilities advertise `inline` and `fullscreen`; the app requests mode changes through the MCP Apps bridge and trusts the Host result.
- **Locale**: app chrome uses `hostContext.locale` when present, then `navigator.language`, then `en-US`.
- **Host styles**: supported Host CSS variables and fonts are applied through the MCP Apps SDK helpers.
- **App-only tools**: helper tools are marked app-visible so the embedded UI can rebuild options without expanding the model-visible tool set.

## Input Contract

Chart opener tools accept chart-specific subsets of the common input model:

| Field | Purpose |
| --- | --- |
| `title` | Top-level chart title |
| `subtitle` | Top-level chart subtitle |
| `data.source` | Tabular rows as object records or a matrix |
| `data.dimensions` | Optional ordered field names |
| `data.columns` | Table column metadata |
| `data.tree` | Hierarchical tree or treemap nodes |
| `data.nodes` / `data.links` | Graph or Sankey relation data |
| `encoding` | Mapping from data fields to visual channels |
| `series` | Optional per-series overrides |
| `presentation` | Theme, palette, labels, legend, stacking, smoothing, orientation |
| `axes` | Cartesian or mixed chart axis settings |
| `interaction` | Tooltip, legend, zoom, toolbox, visual map |
| `advanced` | Renderer and restricted ECharts option patch |

Use `data.source` for tabular charts, `data.tree` for hierarchy charts, and `data.nodes` / `data.links` for graph or Sankey charts. Prefer top-level `title` and `subtitle`; presentation fallback titles are accepted by app-side option building.

Radar charts accept both wide rows (`encoding.name` plus metric fields in `encoding.y`) and long rows (`encoding.category` for indicators, with either value columns in `encoding.y` or grouped `encoding.series` plus `encoding.value`).

### Line Chart Example

```json
{
  "title": "Revenue by Month",
  "subtitle": "Actuals and profit trend",
  "data": {
    "source": [
      { "month": "Jan", "revenue": 82, "profit": 21 },
      { "month": "Feb", "revenue": 91, "profit": 24 },
      { "month": "Mar", "revenue": 104, "profit": 31 }
    ]
  },
  "encoding": {
    "x": "month",
    "y": ["revenue", "profit"]
  },
  "presentation": {
    "smooth": true,
    "showLegend": true
  },
  "interaction": {
    "tooltip": true,
    "dataZoom": "both"
  }
}
```

### Sankey Example

```json
{
  "title": "Budget Flow",
  "data": {
    "nodes": [
      { "name": "Budget" },
      { "name": "Product" },
      { "name": "Marketing" }
    ],
    "links": [
      { "source": "Budget", "target": "Product", "value": 62 },
      { "source": "Budget", "target": "Marketing", "value": 38 }
    ]
  },
  "interaction": {
    "tooltip": true
  }
}
```

## Architecture

| Layer | Files | Responsibility |
| --- | --- | --- |
| MCP server | `src/mcp/createServer.ts` | Register chart opener tools, app-only helpers, and resources |
| Resource registry | `src/mcp/resources/registerResources.ts` | Serve `ui://` MCP App HTML resources and JSON metadata resources |
| Chart service | `src/services/ChartService.ts` | Validate opener payloads and produce structured tool results |
| Option builder | `src/domain/optionBuilder.ts` | Convert normalized chart input into table view models or ECharts options |
| App runtime | `src/app/AppRoot.tsx` | Connect to the Host, apply theme/locale/display context, render chart UI |
| App bundles | `src/app/pages/*.tsx` | One entry point per chart HTML resource |
| Test harness | `tests/mcp-harness/src/run.ts` | Exercise stdio and HTTP MCP server behavior |

Build output:

| Path | Contents |
| --- | --- |
| `dist/index.js` | Compiled MCP server entry |
| `dist/client/mcp-app-*.html` | Single-file MCP App HTML resources |
| `dist/**/*.d.ts` | Type declarations for compiled modules |

## Security Notes

- App HTML resources use the MCP Apps resource MIME type and a restrictive empty CSP domain list by default.
- Remote HTTP mode requires host allow-list, origin allow-list, and bearer-token authentication.
- External links are handled by the Host; chart apps do not need broad network access for normal rendering.
- `advanced.optionPatch` is limited to safe visual/layout keys: `aria`, `backgroundColor`, `color`, `dataZoom`, `grid`, `legend`, `textStyle`, `title`, `toolbox`, `tooltip`, and `visualMap`.
- `optionPatch` rejects nested overrides for generated data structures and executable/rendering fields such as `series`, `dataset`, axes, `formatter`, `html`, `rich`, `timeline`, `media`, and render mode.

## Development

Common scripts:

| Script | Description |
| --- | --- |
| `npm run build` | Compile the server and build all app HTML bundles |
| `npm run build:app` | Build only the single-file MCP App HTML resources |
| `npm run start` | Start HTTP transport from `dist/index.js` |
| `npm run start:stdio` | Start stdio transport from `dist/index.js` |
| `npm run typecheck` | Run TypeScript checks for source and tests |
| `npm test` | Run unit tests |
| `npm run test:ui-layout` | Build app HTML and verify UI layout snapshots/checks |
| `npm run test:e2e` | Run stdio and HTTP MCP harness tests |
| `npm run check` | Run typecheck, unit tests, UI layout tests, and MCP harness tests |

## Verification

Run fast local checks:

```bash
npm run typecheck
npm test
```

Run full verification:

```bash
npm run check
```