Graph Visualization MCP App

🚀 图形可视化MCP应用

这是一个使用React和Recharts构建的交互式数据可视化MCP应用。它能根据原始JSON数据或存储的数据集创建美观、交互式的图表。支持10种图表类型，并具备全面的自定义选项，包括工具提示、图例、标签、参考元素、刷选和图表同步等功能。

🚀 快速开始

本应用可根据原始JSON数据或存储的数据集创建交互式图表，支持多种图表类型和丰富的自定义选项。

✨ 主要特性

• 10种图表类型：柱状图、折线图、面积图、饼图、组合图、散点图、雷达图、漏斗图、桑基图、树形图。
• 灵活的数据输入：支持原始JSON数组或数据集ID。
• 智能图表检测：根据数据结构自动选择最优的图表类型。
• 高级交互功能：
  • 支持自定义格式的工具提示。
  • 可通过点击图例进行数据过滤。
  • 支持带格式化器（百分比、货币、小数等）的数据标签。
  • 支持参考线和参考区域。
  • 可使用刷选工具进行范围选择。
  • 支持多图表同步。
• 布局选项：提供水平/垂直布局，以及堆叠模式（包括人口金字塔）。
• 双Y轴：适用于具有不同刻度的组合图。
• 响应式设计：可自适应任何容器大小。
• 主题支持：支持浅色和深色主题，并集成了CSS变量。
• 数据灵活性：可处理任何JSON结构，自动检测数值列。

📦 安装指南

npm install

📦 构建项目

npm run build

此命令会将React UI构建为单个HTML文件，可嵌入到MCP主机中。

📦 运行服务器

npm run serve

或在开发模式下运行：

npm run dev

服务器会监听标准输入输出，并与MCP主机（如Claude Desktop）进行通信。

💻 使用示例

基础用法

以下是创建柱状图的示例：

{
  "data": [
    { "month": "Jan", "sales": 4000, "revenue": 2400 },
    { "month": "Feb", "sales": 3000, "revenue": 1398 },
    { "month": "Mar", "sales": 2000, "revenue": 9800 }
  ],
  "chartType": "bar",
  "title": "Monthly Sales",
  "xAxis": "month",
  "series": ["sales", "revenue"],
  "theme": "light"
}

高级用法

以下是创建组合图并使用双Y轴的示例：

{
  "data": [
    { "month": "Jan", "sales": 4000, "margin": 24 },
    { "month": "Feb", "sales": 3000, "margin": 22 },
    { "month": "Mar", "sales": 2000, "margin": 32 }
  ],
  "chartType": "composed",
  "title": "Sales and Profit Margin",
  "seriesConfig": { "sales": "bar", "margin": "line" },
  "label": { "enabled": true },
  "yAxis": "sales",
  "yAxis2": "margin"
}

📚 详细文档

工具：create_visualization

根据数据创建交互式图表。

必需参数

图表配置

坐标轴配置

系列和数据配置

柱状图选项

折线图和面积图选项

动画

标签

组件

样式

交互性

饼图/雷达图特定参数

散点图特定参数

配置详情

标签配置

控制数据标签在图表元素上的显示方式：

{
  "label": {
    "enabled": true,
    "position": "top",
    "formatter": "Percentage",
    "offset": 5,
    "angle": 0,
    "color": "#333",
    "fontSize": 12
  }
}

格式化器选项：

• 标准格式化器：Percentage、Currency、Decimal、default
• 特定图表格式化器：percentage、value、name、conversion

工具提示配置

自定义悬停/点击工具提示：

{
  "tooltip": {
    "enabled": true,
    "trigger": "hover",
    "shared": true,
    "position": "auto",
    "contentStyle": { "backgroundColor": "#fff", "border": "1px solid #ccc" },
    "wrapperStyle": { "outline": "none" }
  }
}

图例配置

控制图例的外观和行为：

{
  "legend": {
    "enabled": true,
    "layout": "horizontal",
    "align": "center",
    "verticalAlign": "bottom",
    "iconType": "square",
    "onClick": "filter"
  }
}

onClick 值：filter（隐藏系列）、highlight、none

刷选配置

为图表添加范围选择工具：

{
  "brush": {
    "enabled": true,
    "dataStartIndex": 0,
    "dataEndIndex": 10,
    "height": 40,
    "fill": "rgba(0,0,0,0.1)",
    "stroke": "#999"
  }
}

参考元素

添加参考线和参考区域：

{
  "referenceElements": [
    {
      "type": "line",
      "value": 5000,
      "stroke": "#ff0000",
      "strokeDasharray": "5 5",
      "label": "Target"
    },
    {
      "type": "area",
      "value": [3000, 7000],
      "fill": "#00ff00",
      "fillOpacity": 0.1
    }
  ]
}

坐标轴配置

高级坐标轴自定义：

{
  "axisConfig": {
    "x": {
      "type": "category",
      "label": "Time",
      "labelAngle": 45,
      "hide": false,
      "scale": "linear",
      "tickCount": 5
    },
    "y": {
      "type": "number",
      "label": "Value",
      "scale": "linear",
      "domain": [0, 10000]
    },
    "y2": {
      "type": "number",
      "label": "Other",
      "scale": "logarithmic"
    }
  }
}

样式配置

{
  "styling": {
    "margin": { "top": 20, "right": 20, "bottom": 20, "left": 60 },
    "padding": 10,
    "backgroundColor": "#ffffff",
    "borderRadius": 4,
    "borderColor": "#e0e0e0",
    "borderWidth": 1
  }
}

示例

以下是更多不同图表类型的配置示例：

散点图 - 二维分析

{
  "data": [
    { "temperature": 20, "humidity": 40, "location": "A" },
    { "temperature": 25, "humidity": 55, "location": "B" }
  ],
  "chartType": "scatter",
  "title": "Temperature vs Humidity",
  "xAxis": "temperature",
  "series": ["humidity"],
  "bubbleSize": "auto"
}

堆叠柱状图 - 人口金字塔

{
  "data": [
    { "ageGroup": "0-10", "male": -50, "female": 48 },
    { "ageGroup": "10-20", "male": -60, "female": 58 }
  ],
  "chartType": "bar",
  "title": "Population Pyramid",
  "layout": "horizontal",
  "stackOffset": "sign",
  "barGap": "-100%",
  "series": ["male", "female"]
}

雷达图 - 多指标比较

{
  "data": [
    { "metric": "Speed", "product_a": 85, "product_b": 70 },
    { "metric": "Reliability", "product_a": 78, "product_b": 90 }
  ],
  "chartType": "radar",
  "title": "Product Comparison",
  "theme": "dark"
}

饼图 - 市场份额

{
  "data": [
    { "company": "A", "share": 30 },
    { "company": "B", "share": 25 },
    { "company": "C", "share": 45 }
  ],
  "chartType": "pie",
  "title": "Market Share",
  "label": { "enabled": true, "formatter": "percentage" }
}

桑基图 - 数据流

{
  "data": [
    { "source": "A", "target": "B", "value": 100 },
    { "source": "B", "target": "C", "value": 80 }
  ],
  "chartType": "sankey",
  "title": "Data Flow"
}

树形图 - 层次结构数据

{
  "data": [
    { "name": "A", "value": 100 },
    { "name": "B", "value": 200 }
  ],
  "chartType": "treemap",
  "title": "Hierarchy"
}

同步图表

{
  "data": [...],
  "syncId": "chart-group-1",
  "syncMethod": "index"
}

🔧 图表类型自动检测

当未指定 chartType 时，应用会智能分析数据结构并检测最佳可视化方式：

🔧 支持的数据集

模拟数据库目前包含：

• sales-2024：月度销售、收入和利润数据（1月 - 6月，值最高可达9800）

🔧 项目结构

src/
├── app.tsx                 # 包含MCP应用生命周期的React应用入口点
├── types.ts               # TypeScript类型定义（ChartConfig, ParsedChartConfig）
├── components/
│   ├── ChartRenderer.tsx   # 主要的图表路由组件
│   └── charts/
│       ├── BarChart.tsx         # 柱状图（水平和垂直布局）
│       ├── LineChart.tsx        # 折线图和样条图
│       ├── AreaChart.tsx        # 面积图和堆叠面积图
│       ├── PieChart.tsx         # 饼图和环形图
│       ├── ComposedChart.tsx    # 具有双Y轴的混合柱状图/折线图/面积图
│       ├── ScatterChart.tsx     # 支持分类的散点图和气泡图
│       ├── RadarChart.tsx       # 具有自动转置功能的雷达图
│       ├── FunnelChart.tsx      # 漏斗图和转化图
│       ├── SankeyChart.tsx      # 桑基图/流程图
│       ├── TreemapChart.tsx     # 树形图层次结构图表
│       └── CustomTooltip.tsx    # 共享的工具提示组件
├── utils/
│   ├── parseConfig.ts       # 配置解析、图表类型推断、数据验证
│   ├── chartColors.ts       # 主题调色板（浅色和深色）
│   ├── labelConfig.ts       # 标签格式化器实现
│   ├── tooltipConfig.ts     # 工具提示配置助手
│   └── legendConfig.ts      # 图例配置和点击处理程序
├── index.html              # HTML模板
server.ts                   # 带有工具和资源注册的MCP服务器
vite.config.ts             # 具有单文件打包功能的Vite构建配置
package.json               # 依赖项和构建脚本

🔧 高级功能

标签格式化器

应用支持多种标签格式化选项，以不同方式显示数据：

• 标准格式化器（所有图表类型）：
  • Percentage：以占总数的百分比显示值。
  • Currency：以货币格式显示。
  • Decimal：显示数值。
  • default：显示原始值。
• 特定图表格式化器：
  • percentage：特定图表的百分比格式化。
  • value：原始数值。
  • name：系列/类别名称。
  • conversion：转化率格式化。

堆叠模式

对于柱状图和面积图，可选择重叠系列的堆叠方式：

• none：柱子并排显示。
• expand：堆叠至100%。
• positive：正数值向上堆叠。
• sign：正数值向上堆叠，负数值向下堆叠（用于人口金字塔）。
• silhouette：堆叠区域居中。
• wiggle：最小化堆叠区域的摆动。

人口金字塔

使用以下配置创建年龄/性别金字塔：

{
  "chartType": "bar",
  "layout": "horizontal",
  "stackOffset": "sign",
  "barGap": "-100%",
  "series": ["male", "female"]
}

左侧使用负值，右侧使用正值。

双Y轴

使用 composed 图表类型组合具有不同刻度的图表：

{
  "chartType": "composed",
  "series": ["sales", "margin"],
  "seriesConfig": { "sales": "bar", "margin": "line" },
  "yAxis": "sales",
  "yAxis2": "margin"
}

图例点击过滤

点击图例项可显示/隐藏系列（将 legend.onClick 设置为 "filter"）。

范围选择刷选工具

通过 brush 配置添加交互式范围选择器，以放大数据范围。

多图表同步

使用 syncId 同步多个图表的工具提示和选择：

{
  "syncId": "dashboard-1",
  "syncMethod": "index"
}

雷达图数据转置

雷达图会自动检测和处理两种数据模式：

• 标准模式：数据项为角度点，系列为多边形。
• 转置模式：系列为角度点，数据项为多边形。 当系列数量超过数据项数量时，应用会自动进行转置。

分类散点图

散点图会自动检测分类数据，并使用适当的图例和不同类别颜色进行渲染。

🔧 主题自定义

主题是预设的，在可用时会自动匹配主机的主题：

• 浅色主题：明亮背景（#fff）搭配深色文本（#333）。
• 深色主题：深色背景（#1e1e1e）搭配浅色文本（#e0e0e0）。 两种主题都使用了精心选择的调色板，以优化可读性和可访问性。

🔧 开发

技术栈

• React 19：现代UI框架，支持钩子和自动批处理。
• Recharts：基于D3构建的可组合图表库，支持响应式容器。
• MCP Apps SDK：用于交互式UI的模型上下文协议扩展。
• TypeScript：为配置和组件提供严格的类型安全。
• Zod：用于工具输入的模式验证。
• Vite：快速构建工具，支持热更新。
• Node.js：JavaScript运行时环境。

前提条件

• Node.js 16+（安装地址：https://nodejs.org/）

本地开发

安装依赖：

npm install

启动带有热更新的开发服务器：

npm run dev

构建生产版本：

npm run build

运行MCP服务器（生产环境）：

npm run serve

构建输出

构建过程会生成：

• dist/src/index.html - 包含所有JS、CSS和依赖项的单文件HTML，可部署到任何支持MCP的主机。

架构说明

1. 服务器端 (server.ts)：
   • 使用Zod模式验证注册 create_visualization MCP工具。
   • 注册提供打包HTML的UI资源端点。
   • 工具接收配置并将其回显到UI。
2. 客户端 (src/app.tsx)：
   • MCP应用生命周期处理程序接收工具输入和结果。
   • 使用 parseConfig() 实用工具解析配置。
   • 根据类型路由到相应的图表组件。
   • 处理响应式大小调整和主题集成。
3. 图表组件：
   • 每种图表类型都是一个单独的React组件。
   • 共享颜色、标签、工具提示、图例的实用工具。
   • 响应式容器自适应父容器大小。
   • 支持图例过滤的点击处理程序。
4. 数据流：
   • 用户调用工具 → 服务器使用Zod验证 → 以文本形式返回配置。
   • UI接收并解析配置 → 检测图表类型 → 渲染图表。
   • 用户与图表进行交互（点击图例、悬停工具提示等）。

🔧 测试

测试设置

首先，构建应用：

npm run build

这将在 dist/main.js 生成编译后的服务器，并在 dist/src/index.html 生成打包后的UI。

使用Claude Desktop进行测试

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或相应操作系统的配置文件：

{
  "mcpServers": {
    "graph_visualization": {
      "command": "node",
      "args": ["/path/to/graph_visualization_mcp_app/dist/main.js"],
      "cwd": "/path/to/graph_visualization_mcp_app"
    }
  }
}

将 /path/to/graph_visualization_mcp_app 替换为实际的仓库路径。 然后重启Claude Desktop并使用 create_visualization 工具。

使用Claude Code（VS Code）进行测试

编辑Claude Code VS Code扩展配置中的设置：

{
  "mcpServers": {
    "graph_visualization": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/graph_visualization_mcp_app/dist/main.js"],
      "cwd": "/path/to/graph_visualization_mcp_app"
    }
  }
}

注意：使用系统上 node 二进制文件的完整路径：

• macOS（Homebrew）：/opt/homebrew/bin/node
• macOS（NVM）：~/.nvm/versions/node/v<版本号>/bin/node
• Linux：/usr/bin/node 或Node安装的位置
• Windows：C:\Program Files\nodejs\node.exe 然后重启VS Code，工具将在Claude Code中可用。

使用HTTP传输进行测试

在开发过程中进行测试时，修改 server.ts 以使用HTTP而不是标准输入输出：

const server = createServer();
// 导出HTTP处理程序以进行测试
export default {
  fetch: async (req: Request) => {
    // 在此处理JSON-RPC请求
    return new Response(JSON.stringify({ error: "Not implemented" }));
  }
};

🔧 性能说明

• 数据集大小约为10,000项时，渲染流畅。
• Recharts能高效处理响应式大小调整。
• 对于大型数据集，标签默认禁用（可通过 label.enabled 启用）。
• 对于数据集大于1,000项的情况，建议使用刷选组件进行交互式过滤。

🔧 注意事项

• 数据格式：灵活 - 任何JSON对象数组均可。数值列会自动检测。
• 缺失数据：非数值值会被跳过；系列会从数值列中自动检测。
• 坐标轴标签：对于类别轴，假设数据具有重复值。对于数值轴，使用连续范围。
• 主题集成：在可用时（如Claude Desktop），自动使用主机的主题CSS变量。
• 可访问性：图表在Recharts中包含适当的ARIA标签和键盘导航支持。
• 导出：图表可以截图，但没有内置的导出功能。