内容
# echart-mcp-view
[](LICENSE)
[](https://www.npmjs.com/package/echart-mcp-view)
[](package.json)
[](https://github.com/modelcontextprotocol/ext-apps)
[](https://echarts.apache.org/)
适用于MCP应用程序的ECharts可视化工具。
`echart-mcp-view`是一个MCP服务器，它将结构化的工具参数转换为精致的交互式图表视图。它为每种图表类型公开一个模型可见的打开工具，为每个图表UI提供独立的MCP应用程序HTML资源，并允许嵌入式应用程序在无需模型编写图表配置的情况下，从验证的数据中重建ECharts选项。
## 亮点
- **16种专注的图表应用程序**，用于表格、笛卡尔图表、关系、层次结构、流程、KPI、财务和分布视图。
- **MCP应用程序优先**：每个打开工具都映射到一个由兼容主机渲染的`ui://` HTML资源。
- **结构化图表输入**：调用者提供数据、编码、轴、呈现和交互控制，而不是原始的ECharts选项。
- **主机感知UI**：应用程序的外壳跟随主机主题、本地化和`inline` / `fullscreen`显示模式（如果可用）。
- **单文件应用程序包**：每个图表表面都构建到`dist/client/`下的自包含HTML资源中。
- **安全的自定义**：`advanced.optionPatch`接受受控的样式/布局键，同时阻止系列、数据集、轴、格式化函数、HTML渲染、时间线和渲染模式。
- **设计可调试**：可选的调试模式显示输入JSON和生成的图表选项，用于本地检查。
## 工作原理
1. 模型调用图表打开工具，例如`echart_mcp_view_open_line`。
2. 工具验证输入并返回结构化内容以及MCP应用程序元数据。
3. 主机获取匹配的`ui://echart-mcp-view/*.html`资源并在沙盒iframe中渲染。
4. 嵌入式React应用程序接收工具输入/结果通知，通过应用程序专用的帮助工具构建ECharts选项，并渲染图表。
这使得模型面向的工具表面保持紧凑，同时将图表渲染、主题处理和交互式UI行为留在应用程序中。
## 图表目录
模型可见的打开工具：
| 图表 | 工具 | 最适合 |
| --- | --- | --- |
| 表格 | `echart_mcp_view_open_table` | 行和列检查 |
| 线图 | `echart_mcp_view_open_line` | 趋势、时间序列、多指标比较 |
| 条形图 | `echart_mcp_view_open_bar` | 类别比较、分组条形图、堆叠条形图 |
| 饼图 | `echart_mcp_view_open_pie` | 总量份额、环形图、玫瑰图 |
| 散点图 | `echart_mcp_view_open_scatter` | 相关性、气泡大小、视觉映射 |
| 雷达图 | `echart_mcp_view_open_radar` | 多维配置文件比较 |
| 热力图 | `echart_mcp_view_open_heatmap` | 矩阵强度和二维密度 |
| 漏斗图 | `echart_mcp_view_open_funnel` | 转换阶段和有序下降 |
| 仪表盘 | `echart_mcp_view_open_gauge` | 单个KPI、进度、阈值状态 |
| 树图 | `echart_mcp_view_open_tree` | 父子层次结构 |
| 树地图 | `echart_mcp_view_open_treemap` | 分层大小比较 |
| 图 | `echart_mcp_view_open_graph` | 节点链接关系网络 |
| 桑基图 | `echart_mcp_view_open_sankey` | 加权源目标流 |
| 蜡烛图 | `echart_mcp_view_open_candlestick` | OHLC市场或范围数据 |
| 箱线图 | `echart_mcp_view_open_boxplot` | 分布摘要和异常值 |
| 混合图 | `echart_mcp_view_open_mixed` | 组合条形图和折线图系列 |
应用程序专用帮助工具：
| 工具 | 用途 |
| --- | --- |
| `echart_mcp_view_app_build_option` | 验证图表输入并返回当前应用程序负载的表格视图模型或ECharts选项 |
| `echart_mcp_view_app_examples` | 返回一个图表类型或所有图表类型的可重用示例输入 |
## 快速入门
要求：
- Node.js 20+
- npm
通过Streamable HTTP运行已发布的软件包：
```bash
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```
默认HTTP端点：
```text
http://127.0.0.1:3338/mcp
http://127.0.0.1:3338/healthz
```
当MCP主机将此服务器作为本地命令启动时，通过stdio运行：
```bash
npx -y echart-mcp-view@latest --stdio
```
对于源代码检查，首先安装并构建：
```bash
npm install
npm run build
npm run start
```
## MCP主机配置
使用`npx`推荐的stdio配置：
```json
{
"mcpServers": {
"echart-mcp-view": {
"command": "npx",
"args": ["-y", "echart-mcp-view@latest", "--stdio"]
}
}
}
```
固定版本以实现可复制的主机设置：
```json
{
"mcpServers": {
"echart-mcp-view": {
"command": "npx",
"args": ["-y", "echart-mcp-view@0.1.0", "--stdio"]
}
}
}
```
源代码检查stdio配置：
```json
{
"mcpServers": {
"echart-mcp-view": {
"command": "node",
"args": ["/absolute/path/to/echart-mcp-view/dist/index.js", "--stdio"]
}
}
}
```
使用`npx`的Streamable HTTP：
```bash
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```
在支持Streamable HTTP MCP连接的主机中使用`/mcp`端点。
## NPM软件包
软件包公开了一个可执行文件：
```bash
echart-mcp-view --stdio
echart-mcp-view --http --host 127.0.0.1 --port 3338
```
本地全局安装是可选的：
```bash
npm install -g echart-mcp-view
echart-mcp-view --stdio
```
对于一次性运行或主机管理的启动，使用`npx`：
```bash
npx -y echart-mcp-view@latest --stdio
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338
```
## 运行时模式
### 传输
- `--stdio`：用于本地MCP主机进程管理的stdio传输。
- `--http`：Streamable HTTP传输，在`/mcp`处提供服务。
- `--host`和 `--port`：覆盖HTTP绑定主机和端口。
### 环境
```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
```
远程HTTP模式需要明确允许的主机、允许的来源和身份验证令牌。
### 调试模式
默认情况下，JSON输入和生成的选项面板是隐藏的。在检查有效载荷或图表输出时启用它：
```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
```
对于直接的本地应用程序页面检查，在构建的应用程序URL后附加`?debug=1`或`?debug=true`。
## MCP应用程序行为
- **主题**：明确的`presentation.theme`获胜；否则应用程序遵循`hostContext.theme`；如果没有主机上下文，则回落到`prefers-color-scheme`。
- **显示模式**：应用程序功能公开`inline`和`fullscreen`；应用程序通过MCP应用程序桥请求模式更改并信任主机结果。
- **本地化**：应用程序外壳使用`hostContext.locale`（如果存在），然后使用`navigator.language`，然后使用`en-US`。
- **主机样式**：支持的主机CSS变量和字体通过MCP应用程序SDK帮助程序应用。
- **应用程序专用工具**：帮助程序工具标记为应用程序可见，以便嵌入式UI可以在不扩展模型可见工具集的情况下重建选项。
## 输入契约
图表打开工具接受图表特定的通用输入模型子集：
| 字段 | 用途 |
| --- | --- |
| `title` | 顶级图表标题 |
| `subtitle` | 顶级图表副标题 |
| `data.source` | 作为对象记录或矩阵的表格行 |
| `data.dimensions` | 可选的有序字段名称 |
| `data.columns` | 表格列元数据 |
| `data.tree` | 分层树或树地图节点 |
| `data.nodes` / `data.links` | 图或桑基图关系数据 |
| `encoding` | 从数据字段到视觉通道的映射 |
| `series` | 可选的每系列覆盖 |
| `presentation` | 主题、调色板、标签、图例、堆叠、平滑、方向 |
| `axes` | 笛卡尔或混合图表轴设置 |
| `interaction` | 提示、图例、缩放、工具箱、视觉地图 |
| `advanced` | 渲染器和受限的ECharts选项补丁 |
对于表格图表，使用`data.source`；对于层次结构图表，使用`data.tree`；对于图或桑基图，使用`data.nodes` / `data.links`。优先使用顶级`title`和`subtitle`；应用程序侧的选项构建接受呈现回落标题。
### 线图示例
```json
{
"title": "按月收入",
"subtitle": "实际和利润趋势",
"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"
}
}
```
### 桑基图示例
```json
{
"title": "预算流动",
"data": {
"nodes": [
{ "name": "Budget" },
{ "name": "Product" },
{ "name": "Marketing" }
],
"links": [
{ "source": "Budget", "target": "Product", "value": 62 },
{ "source": "Budget", "target": "Marketing", "value": 38 }
]
},
"interaction": {
"tooltip": true
}
}
```
## 架构
| 层 | 文件 | 责任 |
| --- | --- | --- |
| MCP服务器 | `src/mcp/createServer.ts` | 注册图表打开工具、应用程序专用帮助程序和资源 |
| 资源注册表 | `src/mcp/resources/registerResources.ts` | 提供`ui://` MCP应用程序HTML资源和JSON元数据资源 |
| 图表服务 | `src/services/ChartService.ts` | 验证打开器有效载荷并生成结构化工具结果 |
| 选项构建器 | `src/domain/optionBuilder.ts` | 将标准化的图表输入转换为表格视图模型或ECharts选项 |
| 应用程序运行时 | `src/app/AppRoot.tsx` | 连接到主机、应用主题/本地化/显示上下文、渲染图表UI |
| 应用程序包 | `src/app/pages/*.tsx` | 每个图表HTML资源的入口点 |
| 测试工具 | `tests/mcp-harness/src/run.ts` | 锻炼stdio和HTTP MCP服务器行为 |
构建输出：
| 路径 | 内容 |
| --- | --- |
| `dist/index.js` | 编译的MCP服务器入口 |
| `dist/client/mcp-app-*.html` | 单文件MCP应用程序HTML资源 |
| `dist/**/*.d.ts` | 编译模块的类型声明 |
## 安全注意事项
- 应用程序HTML资源默认使用MCP应用程序资源MIME类型和限制性空CSP域列表。
- 远程HTTP模式需要主机允许列表、来源允许列表和承载令牌身份验证。
- 外部链接由主机处理；图表应用程序不需要正常的渲染网络访问。
- `advanced.optionPatch`仅限于安全的视觉/布局键：`aria`、`backgroundColor`、`color`、`dataZoom`、`grid`、`legend`、`textStyle`、`title`、`toolbox`、`tooltip`和`visualMap`。
- `optionPatch`拒绝生成的 数据结构和可执行/渲染字段的嵌套覆盖，例如`series`、`dataset`、`axes`、`formatter`、`html`、`rich`、`timeline`、`media`和渲染模式。
## 开发
常用脚本：
| 脚本 | 描述 |
| --- | --- |
| `npm run build` | 编译服务器并构建所有应用程序HTML包 |
| `npm run build:app` | 仅构建单文件MCP应用程序HTML资源 |
| `npm run start` | 从`dist/index.js`启动HTTP传输 |
| `npm run start:stdio` | 从`dist/index.js`启动stdio传输 |
| `npm run typecheck` | 对源代码和测试运行TypeScript检查 |
| `npm test` | 运行单元测试 |
| `npm run test:ui-layout` | 构建应用程序HTML并验证UI布局快照/检查 |
| `npm run test:e2e` | 运行stdio和HTTP MCP工具测试 |
| `npm run check` | 运行类型检查、单元测试、UI布局测试和MCP工具测试 |
## 验证
运行快速本地检查：
```bash
npm run typecheck
npm test
```
运行完整验证：
```bash
npm run check
```
