Vvk Charts MCP

vvk图表mcp

文件语言：

• 英语： README.md
• 俄语： README_ru.md

用于渲染图表的现代Python MCP服务器(line, bar, pie, scatter, area，以及 combined dashboard)具有可定制的主题，并导出为PNG/SVG/base64。

Example output: dark corporate combined dashboard generated by the MCP tool.

目录

• 特性
• 快速开始
• MCP工具
• 组合仪表板有效载荷示例
• 终端图表有效载荷示例
• 演示图库
• AI预设（技能和代理）
• OpenCode设置（详细）
• Codex设置（详细）
• 本地开发

特性

• 用于单图表和混合仪表板的MCP工具。
• 具有ANSI渲染和单色回退功能的终端图表工具。
• 现代Plotly风格，全主题定制。
• 适用于多系列和更大的数据集。
• 导出格式： png, svg, base64.
• 带有预定义模板的交互式CLI测试客户端。

快速开始

从GitHub安装 uvx:

uvx install git+https://github.com/valderan/vvk-charts-mcp.git

运行MCP服务器：

uvx run vvk-charts-mcp

运行交互式测试客户端：

uvx run vvk-charts-cli

CLI会询问要绘制什么、保存在哪里、输出格式和图像大小。

提示：将输出模式设置为 terminal 在 vvk-charts-cli 预览控制台仪表板。

MCP工具

所有工具支持的常见选项：

• theme_preset, theme, title, width, height
• format (png, svg, base64)
• filename, save_to_disk

图像工具总是返回聊天预览(ImageContent). 要保存文件，请设置 save_to_disk: true 并配置 OUTPUT_DIR 在MCP中 env.

主题预设

使用 list_theme_presets 在运行时获取所有可用的主题名称。

图像主题预设：

• clean_light （默认）
• dark_corporate
• pastel_startup
• medical_monitor

终端主题预设：

• dark_corporate_cli （默认）
• pastel_startup_cli

请求示例：

{
  "tool": "list_theme_presets",
  "arguments": {}
}

组合仪表板有效载荷示例

{
  "title": "Marketing Dashboard",
  "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": "Revenue Trend",
      "x_label": "Month",
      "y_label": "k USD",
      "data": [
        {
          "name": "Revenue",
          "x": ["Jan", "Feb", "Mar", "Apr"],
          "y": [120, 132, 148, 160]
        }
      ],
      "options": {
        "line_shape": "spline"
      }
    },
    {
      "type": "pie",
      "row": 1,
      "col": 2,
      "title": "Budget Split",
      "data": [
        {
          "labels": ["Search", "Social", "Email"],
          "values": [45, 35, 20]
        }
      ],
      "options": {
        "hole": 0.45
      }
    }
  ]
}

终端图表有效载荷示例

{
  "tool": "create_terminal_chart",
  "arguments": {
    "type": "line",
    "title": "Revenue Trend (CLI)",
    "x_label": "Month",
    "y_label": "k USD",
    "theme": "dark_corporate_cli",
    "use_color": true,
    "force_mono": false,
    "raw_output": true,
    "data": [
      {
        "name": "Revenue",
        "x": ["Jan", "Feb", "Mar", "Apr", "May"],
        "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配置片段示例：

{
  "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"
      }
    }
  }
}

演示图库

AI预设（技能和代理）

存储库中包含可重用的AI预设 ai/:

• ai/vvk-charts-skill.md -海图有效载荷构建技能说明。
• ai/vvk-charts-agent.md -绘制专门的子代理配置文件。

使用更方便的工作流。

OpenCode设置（详细）

1） 添加此MCP服务器

创建或编辑 opencode.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技能

mkdir -p .opencode/skills/vvk-charts-mcp
cp ai/vvk-charts-skill.md .opencode/skills/vvk-charts-mcp/SKILL.md

3） 作为OpenCode代理安装

mkdir -p .opencode/agents
cp ai/vvk-charts-agent.md .opencode/agents/vvk-charts.md

4） 验证

• 开始 opencode 在这个存储库中。
• 确保 vvkcharts_* 工具可见。
• 测试提示： Build a monthly revenue line chart and save as png in ./output using vvkcharts.

参考文献

• https://opencode.ai/docs/mcp-servers/
• https://opencode.ai/docs/skills/
• https://opencode.ai/docs/agents/

Codex设置（详细）

兼容Codex的客户端可能会有所不同，但此流程适用于启用MCP的环境。

1） 注册MCP服务器

uvx --from git+https://github.com/valderan/vvk-charts-mcp.git vvk-charts-mcp

许多客户端使用的典型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） 验证

运行一个请求，如下所示：

Use vvkcharts tools to generate a bar chart and save it to ./output/sales-q1.png.

本地开发

uv sync
uv run ruff check .
uv run mypy src

仓库

• https://github.com/valderan/vvk-charts-mcp

______________________________________________________________________

文档俄文版： README_ru.md