# bi-mcp-server

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

## Basic Information

- **Project Name**: bi-mcp-server
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BI-MCP-Server | BI图表MCP服务

<div align="center">

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Java](https://img.shields.io/badge/java-21+-orange.svg)
![Spring Boot](https://img.shields.io/badge/spring%20boot-4.0.5-brightgreen.svg)
![Spring AI](https://img.shields.io/badge/spring%20ai-1.1.4-green.svg)
![MCP](https://img.shields.io/badge/mcp-0.17.0-purple.svg)
![Charts](https://img.shields.io/badge/charts-22+-yellowgreen.svg)


**一个基于Spring AI的MCP服务，支持22+种图表类型的生成。**

样式：

<img src="https://image.jctsm.com.cn/shop/20260421/pie_1776732212244.png" width="500">
<img src="https://image.jctsm.com.cn/shop/20260421/scatter_1776734087477.png" width="500">
<img src="https://image.jctsm.com.cn/shop/20260421/box_plot_1776734154188.png" width="500">
<img src="https://image.jctsm.com.cn/shop/20260421/line_1776734195598.png" width="500">
<img src="https://image.jctsm.com.cn/shop/20260421/spreadsheet_1776756282045.png" width="500">
</div>

---

## 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [支持的图表类型](#支持的图表类型)
- [系统要求](#系统要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [中文字体配置](#中文字体配置)
- [API参考](#api参考)
- [使用示例](#使用示例)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [测试数据](#测试数据)
- [开源协议](#开源协议)

## 项目简介

**BI-MCP-Server** 是一款基于 Spring Boot + Spring AI 实现的标准 MCP 服务端，专注后端原生图表生成，让 AI 具备开箱即用的数据可视化能力。

### 项目概述

BI-MCP-Server 是面向 AI 应用的 Model Context Protocol (MCP) 标准服务，基于 Spring Boot 与 Spring AI 构建。项目核心特色是纯 Java 后端渲染图表，不依赖 ECharts 等前端渲染引擎、无需浏览器环境，即可直接生成折线图、柱状图、饼图、雷达图等 22+ 种专业数据可视化图表，输出标准图片格式供业务直接使用。

通过标准化 MCP 协议，大模型可以自动发现工具、自动组装参数、自动调用图表能力，快速实现对话式 BI、自动报表生成、数据洞察可视化等场景。

### 核心特性

- **标准 MCP 协议兼容**：遵循 Model Context Protocol 规范，AI 模型零改造接入，自动感知可用工具与入参
- **纯后端图表生成**：基于 Java 原生绘图引擎，服务端直接出图，无前端依赖、无浏览器环境、无 JS 运行时
- **22+ 种图表类型覆盖**：折线图、柱状图、饼图、散点图、面积图、直方图、环形图、雷达图、误差图等常用统计图表
- **开箱即用、轻量部署**：基于 Spring Boot 构建，配置简单，可独立部署、接入微服务或嵌入现有数据平台
- **输出标准图片**：支持生成 PNG 图片流 / 文件，可直接用于：自动报表、邮件推送、PDF/Excel 导出、监控大屏、消息通知等
- **AI 友好型设计**：入参结构化、接口统一、返回格式稳定，大模型可自动完成数据查询 → 图表生成 → 结果返回全流程

### 适用场景

- 🤖 **AI 对话式数据分析与可视化**
- 📊 **后端自动化报表、日报 / 周报图表生成**
- 📈 **监控指标趋势图、统计分布图服务**
- 🌐 **无前端环境下的数据可视化需求**
- 📄 **PDF/Excel/ 邮件内嵌图表生成**
- 🏢 **企业内部 BI 平台、数据大屏图表服务**

## 功能特性

- **22+种图表类型**: 支持折线图、柱状图、饼图、雷达图、漏斗图、思维导图等
- **Spring AI集成**: 基于 Spring Boot 4.0.5 和 Spring AI 1.1.4 构建
- **MCP协议**: 标准化的 MCP 服务器实现，支持 Streamable HTTP 传输
- **易于集成**: 可轻松集成到任何兼容 MCP 的 AI 应用中
- **灵活输出**: 支持 PNG、JPEG 和 SVG 图片格式
- **可定制**: 可配置尺寸、标题和输出格式
- **生产就绪**: 为企业级 BI 应用而设计

## 支持的图表类型

| 序号 | 图表类型 | 方法名 | 描述 |
|------|----------|--------|------|
| 1 | 折线图 | `generateLineChart` | 展示数据随时间或顺序变化的趋势 |
| 2 | 柱状图 | `generateBarChart` | 比较不同分类之间的数值大小 |
| 3 | 饼图 | `generatePieChart` | 展示各部分占总体的比例关系 |
| 4 | 面积图 | `generateAreaChart` | 展示数据随时间变化的累积趋势 |
| 5 | 散点图 | `generateScatterChart` | 展示两个变量之间的相关性 |
| 6 | 直方图 | `generateHistogramChart` | 展示数据的频率分布情况 |
| 7 | 箱线图 | `generateBoxPlotChart` | 展示数据的分布特征和异常值 |
| 8 | 双轴图 | `generateDualAxesChart` | 在同一图表中展示两个不同量级的数据系列 |
| 9 | 小提琴图 | `generateViolinChart` | 展示数据分布的密度和形状 |
| 10 | 雷达图 | `generateRadarChart` | 展示多维度数据的综合能力 |
| 11 | 漏斗图 | `generateFunnelChart` | 展示流程转化率的递减情况 |
| 12 | 水球图 | `generateLiquidChart` | 展示百分比完成度 |
| 13 | 桑基图 | `generateSankeyChart` | 展示能量、材料或成本的流向 |
| 14 | 韦恩图 | `generateVennChart` | 展示集合之间的交集关系 |
| 15 | 矩形树图 | `generateTreemapChart` | 展示层次结构数据的比例关系 |
| 16 | 词云图 | `generateWordCloudChart` | 展示文本中词语的频率分布 |
| 17 | 鱼骨图 | `generateFishboneDiagram` | 分析问题产生的原因 |
| 18 | 流程图 | `generateFlowDiagram` | 展示业务流程或操作步骤 |
| 19 | 思维导图 | `generateMindMap` | 整理和展示思路结构 |
| 20 | 网络图 | `generateNetworkGraph` | 可视化实体之间的关系和连接 |
| 21 | 组织结构图 | `generateOrganizationChart` | 展示组织的层次结构 |
| 22 | 电子表格 | `generateSpreadsheet` | 展示表格数据 |

## 系统要求

| 组件 | 版本 |
|------|------|
| Java | 21+ |
| Spring Boot | 4.0.5 |
| Spring AI | 1.1.4 |
| MCP SDK | 0.17.0 |
| Maven | 3.8+ |

## 快速开始

### 1. 克隆仓库

```bash
git clone https://github.com/your-username/bi-mcp-server.git
cd bi-mcp-server
```

### 2. 构建项目

```bash
mvn clean package -DskipTests
```

### 3. 启动服务

```bash
cd bi-mcp-server-api
mvn spring-boot:run
```

服务默认启动在 `http://localhost:8080/mcp/stream/chart`。

### 4. 连接MCP客户端

使用兼容的 MCP 客户端连接到：

```
http://localhost:8080/mcp/stream/chart
```

## 配置说明

### 应用配置 (application.yml)

```yaml
server:
  port: ${SERVER_PORT:8080}

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: bi-chart-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: STREAMABLE
        streamable-http:
          endpoint: /mcp/stream/chart

chart:
  storage-dir: ${CHART_STORAGE_DIR:./charts}
  image-format: ${CHART_IMAGE_FORMAT:png}
  width: ${CHART_WIDTH:800}
  height: ${CHART_HEIGHT:600}
```

### 配置属性

| 属性 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| server.port | SERVER_PORT | 8080 | 服务端口 |
| chart.storage-dir | CHART_STORAGE_DIR | ./charts | 图表存储目录 |
| chart.image-format | CHART_IMAGE_FORMAT | png | 默认图片格式（png/jpeg/svg） |
| chart.width | CHART_WIDTH | 800 | 默认图表宽度 |
| chart.height | CHART_HEIGHT | 600 | 默认图表高度 |

## 中文字体配置

### 问题说明

在 Linux 服务器上部署时，如果生成的图表中中文显示为方框或乱码，是因为服务器缺少中文字体。

### 解决方案

#### 方案一：安装系统中文字体（推荐）

**Ubuntu/Debian:**
```bash
sudo apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei fonts-noto-cjk
sudo fc-cache -fv
```

**CentOS/RHEL:**
```bash
sudo yum install -y wqy-zenhei-fonts wqy-microhei-fonts google-noto-cjk-fonts
sudo fc-cache -fv
```

#### 方案二：使用自定义字体文件

1. 将字体文件（.ttf/.otf）放入项目根目录的 `fonts` 文件夹   chmod 644 /fonts/*
2. 启动应用时指定字体目录：
```bash
java -Dchart.font.dir=./fonts -jar bi-mcp-server-api-1.0.0.jar
```

#### 方案三：Docker 部署

在 Dockerfile 中添加字体安装：
```dockerfile
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    fonts-wqy-zenhei fonts-wqy-microhei fonts-noto-cjk && \
    fc-cache -fv
```

### 详细文档

更多详细信息请参考 [字体安装指南](docs/FONT-INSTALLATION.md)。

## API参考

### MCP端点

- **地址**: `http://localhost:8080/mcp/stream/chart`
- **协议**: Streamable HTTP
- **传输**: MCP协议

### 工具参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| data | String | 是 | - | 数据数组，JSON格式字符串 |
| title | String | 否 | "" | 图表标题 |
| width | Integer | 否 | 800 | 图片宽度（像素） |
| height | Integer | 否 | 600 | 图片高度（像素） |
| format | String | 否 | png | 图片格式（png/jpeg/svg） |
| filename | String | 否 | 自动生成 | 输出文件名 |

## 使用示例

### 生成折线图

**输入数据:**
```json
[
  {"x": "1月", "y": 120},
  {"x": "2月", "y": 150},
  {"x": "3月", "y": 180},
  {"x": "4月", "y": 210}
]
```

**工具调用:**
```json
{
  "tool": "generateLineChart",
  "arguments": {
    "data": "[{\"x\":\"1月\",\"y\":120},{\"x\":\"2月\",\"y\":150},{\"x\":\"3月\",\"y\":180},{\"x\":\"4月\",\"y\":210}]",
    "title": "月度销售趋势",
    "width": 800,
    "height": 600,
    "format": "png"
  }
}
```

**响应:**
```json
{
  "success": true,
  "imageUrl": "http://localhost:8080/charts/line_chart_xxx.png",
  "message": "图表生成成功"
}
```

### 生成饼图

**输入数据:**
```json
[
  {"name": "产品A", "value": 35},
  {"name": "产品B", "value": 25},
  {"name": "产品C", "value": 20},
  {"name": "产品D", "value": 20}
]
```

**工具调用:**
```json
{
  "tool": "generatePieChart",
  "arguments": {
    "data": "[{\"name\":\"产品A\",\"value\":35},{\"name\":\"产品B\",\"value\":25},{\"name\":\"产品C\",\"value\":20},{\"name\":\"产品D\",\"value\":20}]",
    "title": "产品销售占比",
    "width": 800,
    "height": 600
  }
}
```

### 生成漏斗图

**输入数据:**
```json
[
  {"name": "网站访问", "value": 10000},
  {"name": "浏览商品", "value": 6500},
  {"name": "加入购物车", "value": 3200},
  {"name": "提交订单", "value": 1800},
  {"name": "完成支付", "value": 1200}
]
```

**工具调用:**
```json
{
  "tool": "generateFunnelChart",
  "arguments": {
    "data": "[{\"name\":\"网站访问\",\"value\":10000},{\"name\":\"浏览商品\",\"value\":6500},{\"name\":\"加入购物车\",\"value\":3200},{\"name\":\"提交订单\",\"value\":1800},{\"name\":\"完成支付\",\"value\":1200}]",
    "title": "电商转化漏斗",
    "width": 800,
    "height": 600
  }
}
```

## 项目结构

```
bi-mcp-server/
├── pom.xml                          # 父POM文件
├── README.md                        # 主 README（语言选择）
├── README-EN.md                     # 英文文档
├── README-ZH.md                     # 中文文档
├── test-data.md                     # 测试数据示例
├── bi-mcp-server-chart/             # 图表引擎模块
│   ├── pom.xml
│   └── src/main/java/com/bi/mcp/chart/
│       ├── config/
│       │   ├── ChartConfig.java     # 图表配置
│       │   └── ChartProperties.java # 图表属性
│       ├── engine/
│       │   ├── ChartEngine.java     # 图表渲染引擎
│       │   └── ChartValidator.java  # 数据验证
│       ├── model/
│       │   └── ChartType.java       # 图表类型枚举
│       ├── parser/
│       │   └── ChartDataParser.java # 数据解析工具
│       ├── service/
│       │   └── ChartMcpService.java # 包含22个工具的MCP服务
│       └── storage/
│           └── ChartStorageManager.java # 图表存储管理
└── bi-mcp-server-api/               # API模块
    ├── pom.xml
    └── src/main/java/com/bi/mcp/api/
        ├── BiMcpServerApplication.java # 应用入口
        └── config/
            └── ApiMcpServerConfig.java # MCP服务器配置
```

## 开发指南

### 添加新的图表类型

1. 在 `ChartType.java` 中添加新图表类型：
```java
MY_NEW_CHART("我的新图表")
```

2. 在 `ChartMcpService.java` 中添加新方法：
```java
@Tool(description = "生成新类型的图表...")
public String generateMyNewChart(
    @ToolParam(description = "数据数组") String data,
    @ToolParam(description = "图表标题", required = false) String title,
    ...
) {
    return generateChart(ChartType.MY_NEW_CHART, data, title, ...);
}
```

3. 更新图表引擎以处理新类型。

### 运行测试

```bash
mvn test
```

### 生产环境构建

```bash
mvn clean package -DskipTests
java -jar bi-mcp-server-api/target/bi-mcp-server-api-1.0.0.jar
```

## 测试数据

所有 22 种图表类型的详细测试数据和使用示例，请参考 [test-data.md](test-data.md)。

## 开源协议

本项目采用 MIT 开源协议 - 详见 [LICENSE](LICENSE) 文件。

## 作者

**yulang**