Visual MCP

MCPDemo - AI驱动的数据可视化与SQL Chat平台

本项目是一个基于模型上下文协议（Model Context Protocol, MCP）的综合性数据服务平台，集成了数据可视化、SQL智能查询和链接管理功能。通过 AI 驱动的自然语言处理，让数据查询和可视化变得更加简单高效。

1. 我能用它做什么？

• 用中文/英文和「SQL Chat」对话，让 AI 帮你写 SQL 并执行。
• 把查询结果一键变成图表（折线、柱状、饼图、热力图等），生成可分享的链接。
• 在 Dashboard 里拖拽这些图表，做一个自己的多图表大屏。
• 在支持 MCP 的客户端里，把它当成一个「图表 / SQL 助手」工具源来调用。

2. 如果我只想在线用（不想自己部署）

• 打开网站首页：http://mcp.zha-ji.cn
• 想玩 SQL Chat：直接进 http://mcp.zha-ji.cn/sql
• MCP 端点地址（给 Cherry Studio 等用）：http://mcp.zha-ji.cn/mcp

3. 如果我想在本地跑一套

1. 安装：Node.js 18+，（可选）MySQL + Redis。
2. 终端执行：

npm install
npm --prefix web install
cp .env.example .env  # 按需修改数据库/AI 配置
npm run dev           # 启动后端，默认 3000 端口
npm --prefix web run dev  # 启动前端，默认 5173 端口

1. 浏览器打开 http://localhost:5173 即可。

4. SQL Chat + 图表最常见的使用流程

1. 在 SQL Chat 配好数据库连接，写一句自然语言（例如：“按日期统计最近 7 天的订单数”）。
2. 让 AI 帮你生成并执行 SQL，确认结果表格正确。
3. 点击结果上方的「可视化」按钮：

- 选图表类型（不知道选啥就选「自动」）。 - 选 X 轴字段（一般是时间或分类）、Y 轴字段（一般是数值）。

1. 点「生成图表」，系统会给你一个图表链接，可以直接分享或添加到 Dashboard。

5. MCP 客户端 / AI CLI 里怎么接入（超简版）

5.1 通用配置思路

不管你用的是 Cherry Studio、还是其他支持 MCP / HTTP 的 AI CLI，本质都是：

• MCP 端点：http://mcp.zha-ji.cn/mcp 或你自己的 http://localhost:3000/mcp。
• 必要请求头：

- Content-Type: application/json - Accept: application/json, text/event-stream - AccessID / AccessKey - 可以在网页版里注册账号拿到，或者本地调 /api/auth/register 拿到一对凭证。

• 在你的客户端里，把上面的 URL + 请求头配置进去，就能在对话中看到并调用：

- create_visualization_chart（生成图表）

5.2 如果你用的是命令行 / curl

有些 AI CLI（或者你自己写的脚本）其实就是帮你发 HTTP 请求，这时可以先自己用 curl 测一遍：

# 假设已经有 ACCESS_ID 和 ACCESS_KEY 两个环境变量

curl -N \
  -X POST "http://localhost:3000/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "AccessID: $ACCESS_ID" \
  -H "AccessKey: $ACCESS_KEY" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "create_visualization_chart",
      "arguments": {
        "data": [["学生1", 85], ["学生2", 92]],
        "schema": [
          { "name": "学生", "type": "string" },
          { "name": "分数", "type": "number" }
        ],
        "chartType": "auto",
        "title": "学生成绩分布"
      }
    }
  }'

上面这个请求体是一个示例的 MCP tools/call 结构：真正使用时，建议让你的 AI CLI 按 MCP 协议自动构造外层字段，你只需要准备 arguments 里的内容即可（也就是 data、schema、chartType 等）。

5.3 Windows PowerShell 小贴士

在 PowerShell 里，建议先把敏感信息放进环境变量，然后再用它们：

$env:ACCESS_ID = "你的AccessID"
$env:ACCESS_KEY = "你的AccessKey"

curl -N `
  -X POST "http://localhost:3000/mcp" `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  -H "AccessID: $env:ACCESS_ID" `
  -H "AccessKey: $env:ACCESS_KEY" `
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "create_visualization_chart",
      "arguments": {
        "data": [["学生1", 85], ["学生2", 92]],
        "schema": [
          { "name": "学生", "type": "string" },
          { "name": "分数", "type": "number" }
        ],
        "chartType": "auto",
        "title": "学生成绩分布"
      }
    }
  }'

这样，无论你用哪种 AI CLI，只要它支持：

• 指定 MCP 源的 URL；
• 自定义请求头；

-（可选）给 tools/call 传 arguments； 就能把本项目作为一个「远程图表 / SQL 工具源」接进去了。