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標籤和鍵盤導航支持。
• 導出：圖表可以截圖，但沒有內置的導出功能。