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, 예제, 기여 문서 및 릴리스 준비가 완료된 패키징과 함께 제공

Related MCP server: ECharts MCP Server

지원되는 목표

• 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 옵션 또는 표 폴백(fallback)을 위한 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로 폴백(fallback)됩니까?

빌더는 보수적인 화이트리스트를 사용합니다. 매핑이나 데이터 유형이 제어된 차트 출력과 호환되지 않으면 안정적인 표 렌더링으로 폴백됩니다.

생성된 HTML에 빌드 단계가 필요합니까?

아니요. 브라우저에서 직접 열 수 있도록 의도된 단일 HTML 파일입니다.

차트 유형을 강제할 수 있습니까?

네. 입력에서 chartType을 설정하세요. 요청된 차트가 데이터 매핑과 호환되지 않으면 검증 경고가 반환되고 생성이 table로 폴백될 수 있습니다.

보안

• 임의의 스크립트 주입 없음

• 고정된 ECharts CDN 외의 임의의 외부 JS 주입 없음

• 포맷터 함수 주입 없음

• 제어된 HTML 템플릿 형태

• 생성 전 스키마 검증

이 프로젝트는 신뢰할 수 있는 구조화된 데이터 파이프라인을 위한 것입니다. 외부 사용자로부터 신뢰할 수 없는 입력을 받는 경우, 자체 경계에서 이를 검증하고 삭제(sanitize)하십시오.

전체 저장소 정책은 SECURITY.md를 참조하세요.

ECharts 통합 참고 사항

이 프로젝트는 두 곳에서 ECharts를 사용합니다:

• 소스 코드는 타입이 지정된 옵션 생성을 위해 공식 echarts npm 패키지에 의존합니다.

• 생성된 HTML은 번들러 없이 브라우저에서 직접 열 수 있도록 고정된 Apache ECharts CDN 런타임을 사용합니다.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.