ECharts ChartPage

echarts-chartpage は、構造化された JSON データ、可視化の目標、フィールドマッピングを、Apache ECharts を利用した安全で実行可能な HTML チャートページに変換する TypeScript ツールキットです。

以下の形式で提供されます：

• プログラム利用のための npm パッケージ

• ローカル自動化のための CLI

• エージェントワークフローのための MCP サーバー

このプロジェクトは、決定論的な出力、制御されたオプション生成、厳格な検証、およびパブリックなオープンソースとしての保守性を考慮して設計されています。

特徴

• Apache ECharts CDN を含む完全な単一ファイルの HTML チャートページを生成

• 型定義と統合の正確性のために、ソースコードで公式の echarts npm パッケージに依存

• 構造化データに加え、goal（目標）、theme（テーマ）、フィールドマッピングの入力を受け付け

• 制御されたホワイトリストから安全なチャートタイプを推奨

• 任意の JS フォーマッタの注入を行わず、制御された ECharts オプションを構築

• スキーマ、フィールドマッピング、チャートの互換性、および生成された HTML の基本を検証

• 既存のチャート仕様にパッチを適用し、出力を再生成

• npm API、CLI、MCP サーバー間で単一の共有コアを再利用

• テスト、CI、サンプル、貢献ドキュメント、リリース準備が整ったパッケージングを同梱

サポートされている目標

• trend（トレンド）

• compare（比較）

• composition（構成）

• distribution（分布）

• ranking（ランキング）

• correlation（相関）

サポートされているチャートタイプ

• line（折れ線）

• bar（棒）

• stacked_bar（積み上げ棒）

• pie（円）

• donut（ドーナツ）

• scatter（散布図）

• area（面）

• table（テーブル）

インストール

npm install echarts-chartpage

ローカル開発用:

npm install

クイックスタート

CLI

npx echarts-chartpage generate \
  --input examples/inputs/line-chart.json \
  --output revenue-trend.html

npm API

import { generateChartPage } from "echarts-chartpage";

const result = generateChartPage({
  title: "Monthly Revenue Trend",
  goal: "trend",
  theme: "light",
  outputMode: "single_html",
  data: [
    { month: "2025-01", revenue: 120 },
    { month: "2025-02", revenue: 132 },
    { month: "2025-03", revenue: 148 }
  ],
  fields: {
    x: "month",
    y: "revenue"
  }
});

console.log(result.chartType);
console.log(result.html);

MCP サーバー

最初にビルドしてから、stdio サーバーを起動します:

npm run build
npm run mcp:start

入力モデル

type GenerateChartPageInput = {
  title: string;
  description?: string;
  goal: "trend" | "compare" | "composition" | "distribution" | "ranking" | "correlation";
  data: Array<Record<string, string | number | boolean | null>>;
  fields: {
    x: string;
    y: string | string[];
    series?: string;
    category?: string;
  };
  theme?: "light" | "dark";
  outputMode?: "single_html";
  chartType?: "line" | "bar" | "stacked_bar" | "pie" | "donut" | "scatter" | "area" | "table";
};

出力

generateChartPage() は以下を返します:

• 正規化された仕様

• 解決されたチャートタイプ

• 警告

• 制御された ECharts オプション、またはテーブルフォールバックの場合は null

• 完全な実行可能な HTML

CLI の使用方法

CLI バイナリ名は echarts-chartpage です。

generate

JSON 入力から単一の HTML ページを生成します:

echarts-chartpage generate \
  --input examples/inputs/line-chart.json \
  --output examples/generated/line-chart.html

recommend

チャートタイプを推奨します:

echarts-chartpage recommend \
  --input examples/inputs/bar-chart.json

validate

入力を検証し、オプションで生成された HTML を検証します:

echarts-chartpage validate \
  --input examples/inputs/pie-chart.json \
  --html examples/generated/pie-chart.html

patch

ベースのチャート仕様にパッチを適用し、HTML を再生成します:

echarts-chartpage patch \
  --base examples/inputs/patch-base.json \
  --patch examples/inputs/patch-update.json \
  --output examples/generated/patch-example.html

MCP の使用方法

サーバーは以下のツールを公開しています:

• recommend_chart_type

• generate_chart_page

• validate_chart_page

• patch_chart_page

すべてのツールの入力と出力は構造化された JSON です。一般的な MCP クライアント設定は、ビルドされた stdio サーバーを指します:

{
  "mcpServers": {
    "echarts-chartpage": {
      "command": "node",
      "args": ["dist/mcp/server.js"]
    }
  }
}

リクエストペイロードのサンプルについては、examples/mcp-usage.md を参照してください。

プログラミング API

公開 API サーフェス:

• generateChartPage

• recommendChartType

• validateChartInput

• validateChartPageRequest

• validateGeneratedHtml

• patchChartPage

• buildChartOption

• buildChartHtml

ランタイムスキーマもエクスポートされます:

• generateChartPageInputSchema

• patchChartPageChangesSchema

• patchChartPageInputSchema

• validateChartPageInputSchema

入出力例

入力:

{
  "title": "Traffic Source Mix",
  "goal": "composition",
  "theme": "light",
  "outputMode": "single_html",
  "data": [
    { "source": "Organic", "sessions": 4200 },
    { "source": "Paid", "sessions": 2100 },
    { "source": "Referral", "sessions": 1100 }
  ],
  "fields": {
    "x": "source",
    "y": "sessions",
    "category": "source"
  }
}

出力の概要:

{
  "chartType": "donut",
  "warnings": [],
  "html": "<!doctype html>..."
}

例

リポジトリには以下が含まれています:

• examples/inputs/line-chart.json

• examples/inputs/bar-chart.json

• examples/inputs/pie-chart.json

• examples/inputs/multi-series.json

• examples/inputs/patch-base.json

• examples/inputs/patch-update.json

• examples/cli-usage.md

• examples/mcp-usage.md

すべてのサンプル HTML ファイルを生成するには以下を実行します:

npm run examples:generate

生成された HTML ファイルは examples/generated/ に書き込まれます。

エージェントスキル

このリポジトリには、MCP サーバーを一貫して呼び出す必要があるエージェント向けの再利用可能な Codex スタイルのスキルも含まれています:

• skills/echarts-chartpage-mcp/SKILL.md

以下について文書化されています:

• この MCP をトリガーするタイミング

• 推奨 / 検証 / 生成 / パッチの選択方法

• 構造化された呼び出しルール

• モデルプロンプトのための few-shot 例

バンドルされたスキルをローカルの Codex スキルディレクトリにインストールするには以下を実行します:

npm run build
npm run skill:install

アーキテクチャ

プロジェクトレイアウト:

src/
  core/
    chart-recommender.ts
    option-builder.ts
    html-builder.ts
    validator.ts
    patcher.ts
    generator.ts
  cli/
    index.ts
    commands/
  mcp/
    server.ts
  schemas/
  types/
  utils/

設計ルール:

• コアロジックはすべてのインターフェース間で共有される

• 出力は制御され、決定論的である

• 任意のフォーマッタ関数は受け付けない

• ホワイトリストに登録されたチャートタイプのみが出力される

• 実用的な場合は dataset + encode が優先される

以下も参照してください:

• docs/ARCHITECTURE.md

• docs/BACKGROUND.md

• docs/PUBLISHING.md

• SECURITY.md

開発コマンド

npm install
npm run lint
npm run typecheck
npm run test
npm run build
npm run examples:generate

ビルドコマンド

npm run build

出力は dist/ に生成されます。

テストコマンド

npm run test

公開に関する注意

公開前:

1. package.json のリポジトリ URL を更新します。

2. npm アカウント daqiang901003 が公開マシンで認証されていることを確認します。

3. CHANGELOG.md を確認します。

4. npm run verify を実行します。

5. npm publish で公開します。

パッケージは以下のように設定されています:

• exports

• 生成された .d.ts

• bin

• files

• CommonJS 互換性を持つ ESM ファーストの出力

ロードマップ

• ランキング固有のより詳細なソート制御

• ダッシュボード指向のマルチパネル HTML テンプレート

• より多くのチャート推奨ヒューリスティック

• 設定可能なデザインプリセット

• よりリッチな MCP メタデータとトレース

FAQ

任意のユーザー JavaScript を実行しますか？

いいえ。ジェネレーターは、任意のフォーマッタ関数、スクリプトフラグメント、またはカスタム JS の注入を受け付けません。

なぜ一部の入力が table にフォールバックされるのですか？

ビルダーは保守的なホワイトリストを使用しています。マッピングやデータ型が制御されたチャート出力と互換性がない場合、安定したテーブルレンダリングにフォールバックします。

生成された HTML にビルドステップは必要ですか？

いいえ。ブラウザで直接開くことを目的とした単一の HTML ファイルです。

チャートタイプを強制できますか？

はい。入力で chartType を設定してください。要求されたチャートがデータマッピングと互換性がない場合、検証警告が返され、生成は table にフォールバックされる可能性があります。

セキュリティ

• 任意のスクリプト注入なし

• 固定された ECharts CDN を超える任意の外部 JS 注入なし

• フォーマッタ関数の注入なし

• 制御された HTML テンプレート形状

• 生成前のスキーマ検証

このプロジェクトは、信頼された構造化データパイプラインを対象としています。外部ユーザーからの信頼できない入力を受け入れる場合は、独自の境界で検証およびサニタイズを行ってください。

リポジトリ全体のポリシーについては、SECURITY.md を参照してください。

ECharts 統合に関する注意

このプロジェクトは、以下の 2 箇所で ECharts を使用しています:

• ソースコードは、型付きオプション生成のために公式の echarts npm パッケージに依存しています

• 生成された HTML は、バンドラーなしでブラウザで直接開けるように、固定された Apache ECharts CDN ランタイムを使用しています

貢献

CONTRIBUTING.md を参照してください。

ライセンス

MIT。 LICENSE を参照してください。