Graph Visualization MCP App

🚀 グラフ可視化MCPアプリ

ReactとRechartsを用いて構築されたインタラクティブなデータ可視化MCPアプリです。生のJSONデータまたは保存されたデータセットから美しくインタラクティブなチャートを作成できます。ツールチップ、凡例、ラベル、参照要素、ブラッシング、チャート同期などの包括的なカスタマイズオプションを備えた10種類のチャートタイプをサポートしています。

✨ 主な機能

• 10種類のチャートタイプ：棒グラフ、折れ線グラフ、エリアグラフ、円グラフ、複合グラフ、散布図、レーダーチャート、ファネルチャート、サンキーダイアグラム、ツリーマップ
• 柔軟なデータ入力：生のJSON配列またはデータセットID
• スマートなチャート検出：データ構造に基づいて最適なチャートタイプを自動選択
• 高度なインタラクティビティ：
  • カスタムフォーマットのツールチップ
  • クリックでフィルタリング可能な凡例
  • フォーマッタ付きのデータラベル（パーセンテージ、通貨、小数、およびチャート固有のもの）
  • 参照線と参照エリア
  • ブラシツールによる範囲選択
  • 複数チャートの同期
• レイアウトオプション：水平/垂直レイアウト、人口ピラミッドを含む積み上げモード
• 2つのY軸：異なるスケールの複合グラフ用
• レスポンシブデザイン：任意のコンテナサイズに適応
• テーマサポート：CSS変数を統合した明るいテーマと暗いテーマ
• データの柔軟性：任意のJSON構造で動作し、数値列を自動検出

📦 インストール

npm install

ビルド

npm run build

これにより、React UIが単一のHTMLファイルにビルドされ、MCPホストに埋め込むことができます。

サーバーの起動

npm run serve

または開発モードでは：

npm run dev

サーバーは標準入出力を監視し、MCPホスト（Claude Desktopなど）と通信します。

📚 詳細ドキュメント

ツール: 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": [
    { "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"
}

複合グラフ - 利益率付き売上:

{
  "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 }
}

散布図 - 2D分析:

{
  "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    # 2つの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"]
}

左側に負の値、右側に正の値を使用します。

2つの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"
}

レーダーチャートのデータ転置

レーダーチャートは、2つのデータパターンを自動検出して処理します。

• 標準: データ項目が角度の点、シリーズが多角形
• 転置: シリーズが角度の点、データ項目が多角形 シリーズ数がデータ項目数を超えると、アプリは自動的に転置します。

カテゴリ散布図

散布図はカテゴリデータを自動検出し、適切な凡例とカテゴリごとに異なる色でレンダリングします。

テーマのカスタマイズ

テーマは事前設定されており、利用可能な場合にはホストのテーマに自動的に一致します。

• 明るいテーマ: 明るい背景 (#fff) と暗いテキスト (#333)
• 暗いテーマ: 暗い背景 (#1e1e1e) と明るいテキスト (#e0e0e0) どちらのテーマも、読みやすさとアクセシビリティを最適化するために慎重に選択されたカラーパレットを使用しています。

開発

技術

• React 19: フックと自動バッチングを備えた最新のUIフレームワーク
• Recharts: D3をベースに構築されたレスポンシブコンテナ付きのコンポーザブルチャートライブラリ
• MCP Apps SDK: インタラクティブなUI用のモデルコンテキストプロトコル拡張
• TypeScript: 設定とコンポーネントの厳格な型安全性
• Zod: ツール入力のスキーマ検証
• Vite: HMRサポート付きの高速ビルドツール
• 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 に、バンドルされたUIが dist/src/index.html に生成されます。

Claude Desktopでのテスト

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはOSに応じた同等のファイルを編集します。

{
  "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<version>/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ラベルとキーボードナビゲーションサポートが含まれています。
• エクスポート: チャートはスクリーンショットできますが、組み込みのエクスポート機能はありません。