Content
# MCP ECharts Server
This project is an ECharts chart auto-generation service based on the Model Context Protocol (MCP). It supports dynamic chart generation via a unified API, suitable for AI agents or automation systems.
## Features
- **Unified /mcp endpoint** using JSON-RPC 2.0 protocol, supporting session management, tool listing, and tool invocation
- **Dynamic tool loading**: Each JS file in the `tools/` directory is a chart type and is auto-registered
- **Multiple chart types**: bar, line, pie, map, radar, tree, heatmap, and more
- **Map data support**: The `mapdata/` directory contains China and world GeoJSON for map charts
- **Highly extensible**: Add new chart types by simply adding a JS file
- **ECharts CDN**: Frontend rendering uses the official CDN, generated HTML can be opened locally
## Directory Structure
```
.
├── index.js # Main server entry, unified /mcp API
├── package.json # Project dependencies and metadata
├── tools/ # Chart type modules, one JS file per type
├── mapdata/ # Map GeoJSON data
├── test/ # Test and example scripts
│ ├── test.py # Python end-to-end example
│ ├── mcp_echarts_tools.py# Auto-exported tool schemas
│ └── generated_chart.html# Example generated chart HTML
└── README.md # Project documentation
```
## Installation & Startup
1. **Clone the repository**
```sh
git clone <your-repo-url>
cd mcp_echarts
```
2. **Install dependencies**
```sh
npm install
```
3. **Start the server**
```sh
npm start
```
Default port is `1123`. You can override with the `PORT` environment variable.
## Unified API
All operations use `POST /mcp` with JSON-RPC 2.0 request body:
### 1. Initialize Session
```json
{
"jsonrpc": "2.0",
"method": "initialize",
"id": 1
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"status": "ok",
"session_id": "<unique session id>"
}
}
```
### 2. List Tools
```json
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 2
}
```
**Headers:** `Mcp-Session-Id: <session_id>`
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"status": "ok",
"tools": [ ... ],
"session_id": "<session_id>"
}
}
```
### 3. Call Chart Tool
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 3,
"params": {
"name": "bar",
"arguments": { ... }
}
}
```
**Headers:** `Mcp-Session-Id: <session_id>`
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"status": "ok",
"tool": "bar",
"arguments": { ... },
"option": { ... }, // ECharts option config
"mapData": { ... }, // GeoJSON for map tools
"error": null,
"session_id": "<session_id>"
}
}
```
## Tool Development
Each `tools/xxx.js` must export:
- `tool`: Tool metadata (name, description, inputSchema, etc.)
- `handler`: Function that receives arguments and returns `{ option, mapData? }` or `{ html }`
Example:
```js
exports.tool = {
name: 'bar',
description: 'Generate bar chart',
inputSchema: { ... }
};
exports.handler = function(args) {
// Generate option/mapData/html
return { option };
};
```
## Map Data Support
The `mapdata/` directory contains China provinces/cities and world GeoJSON. Map tools can auto-load these.
## Python End-to-End Example
See `test/test.py` for a full workflow. Core steps:
```python
import requests
import json
# 1. Initialize session
mcp_url = "http://localhost:1123/mcp"
init_payload = {"jsonrpc": "2.0", "method": "initialize", "id": 1}
init_resp = requests.post(mcp_url, json=init_payload)
session_id = init_resp.json()["result"]["session_id"]
# 2. List tools
tools_list_payload = {"jsonrpc": "2.0", "method": "tools/list", "id": 2}
tools_list_headers = {"Mcp-Session-Id": session_id, "Content-Type": "application/json"}
tools_list_resp = requests.post(mcp_url, json=tools_list_payload, headers=tools_list_headers)
tools = tools_list_resp.json()["result"]["tools"]
# 3. Call tool to generate chart
call_payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"id": 3,
"params": {
"name": "bar",
"arguments": {
"data": [
{"x": "Mon", "y": 120},
{"x": "Tue", "y": 200},
{"x": "Wed", "y": 150}
],
"title": "Weekly Sales",
"orientation": "vertical"
}
}
}
call_headers = {"Mcp-Session-Id": session_id, "Content-Type": "application/json"}
call_resp = requests.post(mcp_url, json=call_payload, headers=call_headers)
result = call_resp.json()["result"]
# 4. Generate HTML and preview locally
option = result.get("option")
html = f"""
<html><head><script src='https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js'></script></head>
<body><div id='main' style='width:80vw;height:80vh;'></div>
<script>var option={json.dumps(option,ensure_ascii=False)};echarts.init(document.getElementById('main')).setOption(option);</script></body></html>
"""
with open('generated_chart.html', 'w', encoding='utf-8') as f:
f.write(html)
```
## Testing & Extension
- `test/test.py`: End-to-end automation and AI parameter generation example
- `test/mcp_echarts_tools.py`: Auto-exported tool schemas
- `test/generated_chart.html`: Example generated chart HTML
# Map Data Attribution
- World map data source: [ECharts Official Example world.json](https://echarts.apache.org/examples/data/asset/geo/world.json)
- China map data source: [Aliyun DataV Area Selector](https://datav.aliyun.com/portal/school/atlas/area_selector)
## License
MIT License
