内容
# vvk-charts-mcp
<p>
<a href="https://github.com/valderan/vvk-charts-mcp/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0ea5e9" /></a>
<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-2563eb" />
<img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-10b981" />
<img alt="Plotly" src="https://img.shields.io/badge/Plotly-modern%20charts-7c3aed" />
</p>
文档语言:
- 英语: `README.md`
- 繁体中文: 本文档
- 简体中文: [`README_cn.md`](README_cn.md)
现代 Python MCP 服务器，用于渲染图表和图表（`line`，`bar`，`pie`，`scatter`，`area`和`combined dashboard`），具有可自定义的主题和导出到 PNG/SVG/base64。
<p align="center">
<img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate combined dashboard example" width="560" />
<br />
<em>示例输出：由 MCP 工具生成的深色企业风格组合仪表盘。</em>
</p>
## 目录
- [功能](#功能)
- [快速开始](#快速开始)
- [MCP 工具](#mcp-工具)
- [组合仪表盘载入示例](#组合仪表盘载入示例)
- [终端图表载入示例](#终端图表载入示例)
- [演示画廊](#演示画廊)
- [AI 预设（技能和代理）](#ai-预设技能和代理)
- [OpenCode 设置（详细）](#opencode-设置详细)
- [Codex 设置（详细）](#codex-设置详细)
- [本地开发](#本地开发)
## 功能
- 用于单个图表和混合仪表盘的 MCP 工具。
- 带有 ANSI 渲染和单色回落的终端图表工具。
- 现代 Plotly 样式，支持完全自定义主题。
- 支持多系列和较大数据集。
- 导出格式：`png`，`svg`，`base64`。
- 具有预定义模板的交互式 CLI 测试客户端。
## 快速开始
使用 `uvx` 从 GitHub 安装：
```bash
uvx install git+https://github.com/valderan/vvk-charts-mcp.git
```
运行 MCP 服务器：
```bash
uvx run vvk-charts-mcp
```
运行交互式测试客户端：
```bash
uvx run vvk-charts-cli
```
CLI 会询问要绘制的内容、保存位置、输出格式和图像大小。
提示：在 `vvk-charts-cli` 中将输出模式设置为 `terminal` 以预览控制台仪表盘。
## MCP 工具
| 工具 | 用途 |
| --- | --- |
| `list_theme_presets` | 列出可用的图像/终端主题 |
| `create_line_chart` | 时间趋势 |
| `create_bar_chart` | 类别比较 |
| `create_pie_chart` | 部分到整体的分割 |
| `create_scatter_chart` | 相关性和气泡图 |
| `create_area_chart` | 堆积/累积组成 |
| `create_combined_dashboard` | 一个图像中的多个图表类型 |
| `create_terminal_chart` | 用于终端客户端的 ANSI/单色图表输出 |
| `create_terminal_dashboard` | 作为纯文本的多面板终端仪表盘 |
所有工具支持的常用选项：
- `theme_preset`，`theme`，`title`，`width`，`height`
- `format`（`png`，`svg`，`base64`）
- `filename`，`save_to_disk`
图像工具始终返回聊天预览（`ImageContent`）。
要保存文件，请设置 `save_to_disk: true` 并在 MCP `env` 中配置 `OUTPUT_DIR`。
## 主题预设
使用 `list_theme_presets` 获取运行时所有可用的主题名称。
图像主题预设：
- `clean_light`（默认）
- `dark_corporate`
- `pastel_startup`
- `medical_monitor`
终端主题预设：
- `dark_corporate_cli`（默认）
- `pastel_startup_cli`
请求示例：
```json
{
"tool": "list_theme_presets",
"arguments": {}
}
```
## 组合仪表盘载入示例
```json
{
"title": "营销仪表盘",
"rows": 1,
"cols": 2,
"theme_preset": "dark_corporate",
"format": "png",
"save_to_disk": true,
"filename": "combined_dashboard",
"panels": [
{
"type": "line",
"row": 1,
"col": 1,
"title": "收入趋势",
"x_label": "月份",
"y_label": "千美元",
"data": [
{
"name": "收入",
"x": ["一月", "二月", "三月", "四月"],
"y": [120, 132, 148, 160]
}
],
"options": {
"line_shape": "spline"
}
},
{
"type": "pie",
"row": 1,
"col": 2,
"title": "预算分配",
"data": [
{
"labels": ["搜索", "社交", "电子邮件"],
"values": [45, 35, 20]
}
],
"options": {
"hole": 0.45
}
}
]
}
```
## 终端图表载入示例
```json
{
"tool": "create_terminal_chart",
"arguments": {
"type": "line",
"title": "收入趋势（CLI）",
"x_label": "月份",
"y_label": "千美元",
"theme": "dark_corporate_cli",
"use_color": true,
"force_mono": false,
"raw_output": true,
"data": [
{
"name": "收入",
"x": ["一月", "二月", "三月", "四月", "五月"],
"y": [120, 132, 148, 160, 178]
}
]
}
}
```
`raw_output: true` 推荐用于终端客户端：工具仅返回图表文本（无 JSON 包装器）。
## 图像保存行为（`OUTPUT_DIR`）
- `save_to_disk: false`（默认）：不写入文件，预览返回到聊天。
- `save_to_disk: true` 且 `OUTPUT_DIR` 已设置：文件仅保存到 `OUTPUT_DIR`。
- `save_to_disk: true` 且 `OUTPUT_DIR` 未设置：无错误，仅预览（`saved=false` 在元数据中）。
- 不支持 `output_path`。
MCP 配置片段示例：
```json
{
"mcp": {
"vvkcharts": {
"type": "local",
"enabled": true,
"command": ["uvx", "--from", "git+https://github.com/valderan/vvk-charts-mcp.git", "vvk-charts-mcp"],
"env": {
"OUTPUT_DIR": "./output"
}
}
}
}
```
## 演示画廊
<p>
<img src="demo/demo_combined_showcase.png" alt="Combined dashboard showcase" width="420" />
<img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate dashboard" width="420" />
<img src="demo/demo_combined_pastel_startup.png" alt="Pastel startup dashboard" width="420" />
</p>
<p>
<img src="demo/demo_line_chart.png" alt="Line chart demo" width="270" />
<img src="demo/demo_bar_chart.png" alt="Bar chart demo" width="270" />
<img src="demo/demo_pie_chart.png" alt="Pie chart demo" width="270" />
<img src="demo/demo_scatter_chart.png" alt="Scatter chart demo" width="270" />
<img src="demo/demo_area_chart.png" alt="Area chart demo" width="270" />
</p>
## AI 预设（技能和代理）
存储库中包含 `ai/` 中的可重用 AI 预设：
- `ai/vvk-charts-skill.md` - 用于图表载入构建的技能指令。
- `ai/vvk-charts-agent.md` - 图表专用子代理配置文件。
使用任一工作流程。
## OpenCode 设置（详细）
### 1) 添加此 MCP 服务器
创建或编辑 `opencode.json`：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vvkcharts": {
"type": "local",
"enabled": true,
"command": [
"uvx",
"--from",
"git+https://github.com/valderan/vvk-charts-mcp.git",
"vvk-charts-mcp"
]
}
}
}
```
### 2) 安装为 OpenCode 技能
```bash
mkdir -p .opencode/skills/vvk-charts-mcp
cp ai/vvk-charts-skill.md .opencode/skills/vvk-charts-mcp/SKILL.md
```
### 3) 安装为 OpenCode 代理
```bash
mkdir -p .opencode/agents
cp ai/vvk-charts-agent.md .opencode/agents/vvk-charts.md
```
### 4) 验证
- 在此存储库中启动 `opencode`。
- 确保 `vvkcharts_*` 工具可见。
- 测试提示：`生成每月收入线图并以 png 格式保存到 ./output 中，使用 vvkcharts`。
参考：
- https://opencode.ai/docs/mcp-servers/
- https://opencode.ai/docs/skills/
- https://opencode.ai/docs/agents/
## Codex 设置（详细）
Codex 兼容的客户端可能会有所不同，但此流程适用于支持 MCP 的环境。
### 1) 注册 MCP 服务器
```bash
uvx --from git+https://github.com/valderan/vvk-charts-mcp.git vvk-charts-mcp
```
许多客户端使用的典型 JSON 形状：
```json
{
"mcpServers": {
"vvkcharts": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/valderan/vvk-charts-mcp.git",
"vvk-charts-mcp"
]
}
}
}
```
### 2) 重用技能和代理预设
- 使用 `ai/vvk-charts-skill.md` 作为可重用的提示模板。
- 使用 `ai/vvk-charts-agent.md` 作为专用的图表配置文件/系统提示。
### 3) 验证
运行请求：
`使用 vvkcharts 工具生成条形图并将其保存到 ./output/sales-q1.png`。
## 本地开发
```bash
uv sync
uv run ruff check .
uv run mypy src
```
## 存储库
- https://github.com/valderan/vvk-charts-mcp
---
简体中文版本文档： [`README_cn.md`](README_cn.md)
