# MCPDemo - AI驱动的数据可视化与SQL Chat平台
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](LICENSE)
本项目是一个基于**模型上下文协议（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. 终端执行：
```bash
npm install
npm --prefix web install
cp .env.example .env # 按需修改数据库/AI 配置
npm run dev # 启动后端，默认 3000 端口
npm --prefix web run dev # 启动前端，默认 5173 端口
```
3. 浏览器打开 `http://localhost:5173` 即可。
### 4. SQL Chat + 图表最常见的使用流程
1. 在 SQL Chat 配好数据库连接，写一句自然语言（例如：“按日期统计最近 7 天的订单数”）。
2. 让 AI 帮你生成并执行 SQL，确认结果表格正确。
3. 点击结果上方的「可视化」按钮：
- 选图表类型（不知道选啥就选「自动」）。
- 选 X 轴字段（一般是时间或分类）、Y 轴字段（一般是数值）。
4. 点「生成图表」，系统会给你一个图表链接，可以直接分享或添加到 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` 测一遍：
```bash path=null start=null
# 假设已经有 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 里，建议先把敏感信息放进环境变量，然后再用它们：
```powershell path=null start=null
$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 工具源」接进去了。