# mcp-server-bi-web

**Repository Path**: yulang_admin_1/mcp-server-bi-web

## Basic Information

- **Project Name**: mcp-server-bi-web
- **Description**: MCP 图表服务器，支持24种图表
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 图表服务器 (MCP Chart Server)

<p align="center">
  <strong>基于 MCP 协议的企业级数据可视化解决方案</strong>
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> •
  <a href="#技术架构">技术架构</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#使用指南">使用指南</a> •
  <a href="#部署发布">部署发布</a> •
  <a href="#api-文档">API 文档</a> •
  <a href="#许可证">许可证</a>
</p>

---

## 项目简介

MCP 图表服务器是一个基于 [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) 协议构建的开源数据可视化服务。它通过标准化的协议接口，为 AI 助手和应用程序提供强大的图表生成能力。

### 为什么选择 MCP Chart Server？

- **标准化协议**: 基于 MCP 协议，可与任何兼容的 AI 助手无缝集成
- **多种传输方式**: 支持 NPX (stdio) 和 SSE (Server-Sent Events) 两种传输模式
- **丰富的图表类型**: 内置 6 种常用图表类型，支持自定义配置
- **企业级架构**: TypeScript 全栈类型安全，支持大规模部署
- **开箱即用**: 提供完整的 Vue3 前端界面，无需额外开发

---

## 功能特性

### 核心功能

- **MCP 协议支持**: 完全兼容 MCP 1.0 协议规范
- **双传输模式**:
  - NPX 模式：适合本地开发和 CLI 集成
  - SSE 模式：适合 Web 应用和远程服务
- **图表类型支持**:
  - 📈 折线图 (Line Chart)
  - 📊 柱状图 (Bar Chart)
  - 🥧 饼图 (Pie Chart)
  - ⚬ 散点图 (Scatter Chart)
  - 🕸️ 雷达图 (Radar Chart)
  - 📉 面积图 (Area Chart)

### 高级功能

- **响应式配置**: 支持图表尺寸、颜色、标签等自定义配置
- **模板系统**: 内置图表模板，快速上手
- **前端可视化**: Vue3 + ECharts 响应式前端界面
- **类型安全**: 完整的 TypeScript 类型定义

---

## 技术架构

### 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 协议 | MCP SDK | 1.0+ |
| 后端 | Node.js + Express | 20+ |
| 图表引擎 | Apache ECharts | 5.5+ |
| 前端框架 | Vue 3 | 3.4+ |
| 构建工具 | Vite + TypeScript | 5.0+ |
| 测试框架 | Vitest | 1.1+ |

### 项目结构

```
mcp-server-bi-web/
├── server/                    # 服务端代码
│   ├── index.ts               # 服务器入口
│   ├── tools/                 # MCP 工具定义
│   │   └── chart-tools.ts     # 图表工具注册
│   └── charts/                # 图表生成器
│       ├── generator.ts       # 统一生成入口
│       ├── templates.ts       # 图表模板
│       ├── line.ts            # 折线图
│       ├── bar.ts             # 柱状图
│       ├── pie.ts             # 饼图
│       ├── scatter.ts         # 散点图
│       ├── radar.ts           # 雷达图
│       └── area.ts            # 面积图
├── client/                    # Vue3 前端应用
│   ├── src/
│   │   ├── components/        # Vue 组件
│   │   │   ├── ChartComponent.vue
│   │   │   └── ChartConfigPanel.vue
│   │   └── composables/       # 组合式函数
│   │       └── useSSEConnection.ts
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
├── shared/                    # 共享类型
│   └── types.ts
├── tests/                     # 测试文件
│   ├── chart-generator.test.ts
│   └── chart-templates.test.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts
```

---

## 快速开始

### 环境要求

- Node.js >= 20.0.0
- npm >= 10.0.0 或 pnpm >= 8.0.0

### 安装

#### 方式一：从源码安装

```bash
# 克隆仓库
git clone https://github.com/your-org/mcp-server-bi-web.git
cd mcp-server-bi-web

# 安装服务端依赖
npm install

# 安装客户端依赖
cd client && npm install && cd ..
```

#### 方式二：使用 NPX 直接运行

```bash
# 无需安装，直接运行
npx mcp-server-bi-web
```

### 启动服务

#### 开发模式

```bash
# 启动服务器 (stdio 模式)
npm run dev:server

# 启动服务器 (HTTP/SSE 模式)
MODE=http npm run dev:server

# 启动前端开发服务器
npm run dev:client
```

#### 生产模式

```bash
# 构建项目
npm run build

# 启动服务
npm start
```

---

## 使用指南

### 1. NPX 模式使用

NPX 模式通过标准输入输出 (stdio) 与 MCP 客户端通信，适合本地开发。

```bash
# 直接启动
npx mcp-server-bi-web

# 或使用 npm
npm run dev:server
```

**配置 MCP 客户端** (如 Claude Desktop):

```json
{
  "mcpServers": {
    "chart-server": {
      "command": "npx",
      "args": ["mcp-server-bi-web"]
    }
  }
}
```

### 2. SSE 模式使用

SSE 模式提供 HTTP 接口，适合 Web 应用和远程服务。

```bash
# 启动 HTTP 服务器
MODE=http npm run dev:server
```

**服务器启动后会显示**:

```
MCP Chart Server running on http://localhost:3000
SSE endpoint: http://localhost:3000/sse
```

**连接 SSE**:

```javascript
// 浏览器中连接 SSE
const eventSource = new EventSource("http://localhost:3000/sse");

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};
```

### 3. 调用 MCP 工具

#### generate_chart - 生成图表

**请求示例**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_chart",
    "arguments": {
      "type": "line",
      "title": "月度销售趋势",
      "data": [
        { "name": "一月", "value": 120 },
        { "name": "二月", "value": 150 },
        { "name": "三月", "value": 180 }
      ],
      "options": {
        "showLegend": true,
        "colors": ["#5470c6"]
      }
    }
  }
}
```

#### get_chart_config - 获取图表配置模板

**请求示例**:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_chart_config",
    "arguments": {}
  }
}
```

### 4. 使用前端界面

```bash
# 启动前端
npm run dev:client
```

访问 `http://localhost:5173`，您将看到：

- 左侧：图表配置面板
  - 选择图表类型
  - 输入图表标题
  - 添加/删除数据点
- 右侧：图表预览区域
  - 实时渲染 ECharts 图表
  - 支持交互操作

---

## 部署发布

### 1. 构建生产版本

```bash
# 构建服务端
npm run build:server

# 构建客户端
npm run build:client

# 或一键构建
npm run build
```

### 2. Docker 部署

**创建 Dockerfile**:

```dockerfile
FROM node:20-alpine

WORKDIR /app

# 复制依赖文件
COPY package*.json ./
COPY client/package*.json ./client/

# 安装依赖
RUN npm install
RUN cd client && npm install

# 复制源代码
COPY . .

# 构建
RUN npm run build

# 暴露端口
EXPOSE 3000

# 启动服务
CMD ["npm", "start"]
```

**构建和运行**:

```bash
# 构建镜像
docker build -t mcp-chart-server .

# 运行容器
docker run -p 3000:3000 -e MODE=http mcp-chart-server
```

### 3. NPM 发布

```bash
# 登录 NPM
npm login

# 发布包
npm publish

# 或使用 scope
npm publish --access public
```

### 4. CI/CD 部署

**GitHub Actions 示例**:

```yaml
name: Deploy MCP Chart Server

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build
      
      - name: Publish to NPM
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

---

## API 文档

### MCP 工具列表

#### generate_chart

生成指定类型的图表，返回 ECharts 配置 JSON。

**参数说明**:

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | string | 是 | 图表类型：line, bar, pie, scatter, radar, area |
| title | string | 是 | 图表标题 |
| data | array | 是 | 数据点数组 |
| data[].name | string | 是 | 数据点名称 |
| data[].value | number | 是 | 数据点值 |
| data[].x | number | 否 | X 坐标（散点图用） |
| data[].y | number | 否 | Y 坐标（散点图用） |
| options | object | 否 | 图表选项 |
| options.width | number | 否 | 图表宽度 |
| options.height | number | 否 | 图表高度 |
| options.showLegend | boolean | 否 | 是否显示图例 |
| options.showLabel | boolean | 否 | 是否显示标签 |
| options.colors | string[] | 否 | 颜色数组 |
| options.xAxisName | string | 否 | X 轴名称 |
| options.yAxisName | string | 否 | Y 轴名称 |
| outputFormat | string | 否 | 输出格式：config (默认), base64 |

**返回示例**:

```json
{
  "title": { "text": "月度销售趋势" },
  "tooltip": { "trigger": "axis" },
  "xAxis": {
    "type": "category",
    "data": ["一月", "二月", "三月"]
  },
  "yAxis": { "type": "value" },
  "series": [{
    "type": "line",
    "data": [120, 150, 180],
    "smooth": true
  }]
}
```

#### get_chart_config

获取支持的图表类型和配置模板。

**参数**: 无

**返回**: 所有图表类型的模板和示例数据

---

## 测试数据

详细的测试数据请参考 [TEST_DATA.md](./TEST_DATA.md)

---

## 常见问题

### Q: 如何自定义图表颜色？

```json
{
  "type": "bar",
  "title": "销量对比",
  "data": [...],
  "options": {
    "colors": ["#ff6b6b", "#4ecdc4", "#45b7d1"]
  }
}
```

### Q: 如何在散点图中使用？

```json
{
  "type": "scatter",
  "title": "广告投入与销售额",
  "data": [
    { "name": "样本1", "x": 10, "y": 120 },
    { "name": "样本2", "x": 15, "y": 180 }
  ]
}
```

### Q: 如何设置端口？

```bash
PORT=8080 MODE=http npm run dev:server
```

---

## 许可证

[MIT License](./LICENSE)

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 联系方式

- 项目地址: https://github.com/your-org/mcp-server-bi-web
- 问题反馈: https://github.com/your-org/mcp-server-bi-web/issues