Flint Chart 中文教程：固定 0.5.1，并收紧 MCP 的文件访问

Flint Chart 是 Microsoft 的语义图表编译器。它用一份 ChartAssemblyInput 生成 Vega-Lite、ECharts、Chart.js、Plotly 或原生 Excel 图表，并提供代理可调用的 MCP server。两个 npm 包当前都是 0.5.1，要求 Node.js 18+。

1. 用固定版本建立临时项目

mkdir flint-eval && cd flint-eval
npm init -y
npm install flint-chart@0.5.1

不要从 Python 教程开始。官方 README 明确写着 Python package 尚未发布，仓库里的 flint-py 是源码预览；普通用户当前应使用 JS/TS 或 MCP。

2. 编译一张最小 Vega-Lite 图表

import { assembleVegaLite } from 'flint-chart';

const spec = assembleVegaLite({
  data: { values: [{ quarter: 'Q1', revenue: 1200 }] },
  semantic_types: { quarter: 'Quarter', revenue: 'Price' },
  chart_spec: {
    chartType: 'Bar Chart',
    encodings: { x: { field: 'quarter' }, y: { field: 'revenue' } },
    baseSize: { width: 480, height: 320 },
  },
});

console.log(JSON.stringify(spec, null, 2));

先检查生成 spec 的字段、聚合、排序、单位和轴范围，再交给 Vega-Lite renderer。Flint 减少代理直接写大型 spec 的错误，但不会知道业务口径是否正确。

3. 同一输入可以换后端

import {
  assembleECharts,
  assembleChartjs,
  assemblePlotly,
  assembleExcel,
} from 'flint-chart';

后端有不同能力。0.5.1 为 Plotly 增加 ThemeSpec 支持，但官方也说明无法实现的主题决定可能近似并写入报告。跨后端验收要对比实际图像、交互和导出的 Excel，而不是只看编译成功。

4. 本地 MCP 优先使用 stdio

{
  "mcpServers": {
    "flint": {
      "command": "npx",
      "args": ["-y", "flint-chart-mcp@0.5.1", "--disable-file-reference"]
    }
  }
}

stdio 只跟启动它的客户端通信。固定版本后，先调用 list_chart_types 和 validate_chart，再用内联 data.values 渲染一张 SVG。支持 MCP Apps 的客户端可以打开交互视图；否则使用静态 render_chart。

5. 文件访问和远程 URL 的边界

只读不等于低风险。代理若能读到工作站上的财务、客户或密钥导出文件，内容仍可能进入模型上下文。应该同时使用隔离工作目录和最小系统权限。

6. 不要直接把 HTTP 模式暴露出去

源码的 HTTP CLI 默认 host 是 0.0.0.0。它方便容器或远程客户端，但会监听全部接口。没有反向代理认证、TLS、网络 ACL、速率限制和文件引用关闭时，不应在共享网络启动。官方也提供公共 HTTP MCP；敏感数据应留在本地 stdio，不能因为项目方提供端点就默认可以上传。

7. 和 Vega-Lite 怎么选

相比 Vega-Lite，Flint 处在更高一层：它用字段语义、自动布局和主题生成 Vega-Lite，也能生成其他后端。Vega-Lite 的声明式 grammar 对变换、通道、组合和交互控制更直接。已有成熟 Vega-Lite 代码时不必增加一层；代理需要跨后端输出时，Flint 更合适。

8. 0.5.1 与验证边界

CHANGELOG 将 0.5.1 标为 2026-08-13，主要把主题支持扩展到 Plotly，并新增 Vega-Lite Calendar Heatmap。0.5.0 引入正式 ThemeSpec、10 个预设、主题发现与 Theme Lab。

验证边界：未验证包完整性、任一后端输出、主题一致性、Excel 文件、MCP 客户端、PNG/SVG、HTTP 暴露或公共远程 MCP 的数据处理。示例要在固定版本和非敏感数据中实跑。

常见问题