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 옵션 또는 표 폴백(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>..."
}

예제

저장소에는 다음이 포함되어 있습니다:

다음 명령어로 모든 예제 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가 선호됨

참조:

개발 명령

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

게시 참고 사항

게시 전:

package.json의 저장소 URL을 업데이트합니다.
npm 계정 daqiang901003이 게시 머신에서 인증되었는지 확인합니다.
CHANGELOG.md를 검토합니다.
npm run verify를 실행합니다.
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를 참조하세요.

ECharts ChartPage MCP Server

ECharts ChartPage

기능

지원되는 목표

지원되는 차트 유형

설치

빠른 시작

CLI

npm API

MCP 서버

입력 모델

출력

CLI 사용법

`generate`

`validate`

`patch`

MCP 사용법

프로그래밍 API

입력 / 출력 예제

예제

에이전트 스킬

아키텍처

개발 명령

빌드 명령

테스트 명령

게시 참고 사항

로드맵

FAQ

임의의 사용자 JavaScript를 실행합니까?

일부 입력이 왜 `table`로 폴백(fallback)됩니까?

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

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

보안

ECharts 통합 참고 사항

기여

라이선스

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

ECharts ChartPage

기능

지원되는 목표

지원되는 차트 유형

설치

빠른 시작

CLI

npm API

MCP 서버

입력 모델

출력

CLI 사용법

generate

recommend

validate

patch

MCP 사용법

프로그래밍 API

입력 / 출력 예제

예제

에이전트 스킬

아키텍처

개발 명령

빌드 명령

테스트 명령

게시 참고 사항

로드맵

FAQ

임의의 사용자 JavaScript를 실행합니까?

일부 입력이 왜 table로 폴백(fallback)됩니까?

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

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

보안

ECharts 통합 참고 사항

기여

라이선스

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

`generate`

`recommend`

`validate`

`patch`

일부 입력이 왜 `table`로 폴백(fallback)됩니까?