npm package: @lemonbi/mcp-server
Description: ECharts Agent MCP Server - AI-powered chart generation service
Author: lemonbi
Latest version: 1.0.1

# ECharts Agent MCP Server

🤖 AI驱动的ECharts图表生成MCP服务器，支持通过自然语言指令生成各类数据可视化图表。

## 特性

- ✅ **AI智能生成** - 使用Azure OpenAI GPT-4智能生成图表配置
- 📊 **多种图表类型** - 支持柱状图、饼图、折线图、散点图、雷达图、仪表盘、四象限图等
- 🎨 **自定义样式** - 支持颜色、标题、轴标签等自定义要求
- 🔌 **MCP协议** - 标准化的Model Context Protocol接口
- 🚀 **即插即用** - 通过npx一键启动，无需手动安装

## 快速开始

### 方式1: 使用npx（推荐）

在Windsurf的MCP配置中添加：

```json
{
  "mcpServers": {
    "echarts-agent": {
      "command": "npx",
      "args": [
        "-y",
        "@echarts-agent/mcp-server"
      ],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "https://your-endpoint.openai.azure.com/",
        "OPENAI_API_KEY": "your-api-key-here",
        "AZURE_OPENAI_DEPLOYMENT": "gpt4o",
        "AZURE_API_VERSION": "2023-03-15-preview"
      }
    }
  }
}
```

### 方式2: 本地测试

```bash
# 克隆或下载项目
git clone https://github.com/yourusername/echarts-agent-mcp
cd echarts-agent-mcp

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑.env文件，填入你的API密钥

# 启动服务器
npm start
```

## 支持的图表类型

| 图表类型 | 关键词 | 适用场景 |
|---------|--------|---------|
| 柱状图 | `bar`, `柱状图`, `条形图` | 数据对比、排名展示 |
| 饼图 | `pie`, `饼图` | 占比分析、比例展示 |
| 折线图 | `line`, `曲线图`, `折线图` | 趋势分析、时间序列 |
| 散点图 | `scatter`, `散点图` | 相关性分析、分布展示 |
| 雷达图 | `radar`, `雷达图` | 多维度对比 |
| 仪表盘 | `gauge`, `仪表盘` | 单一指标展示 |
| 四象限图 | `quadrant`, `四象限` | 战略分析、优先级划分 |
| 线性回归 | `linear`, `线性回归` | 趋势预测、数据拟合 |

## 使用示例

### 示例1: 生成柱状图

```
指令: "生成一个红色柱状图显示各平台的广告消耗"
数据: [
  {"category": "京准通", "value": 125000},
  {"category": "小红书", "value": 89000},
  {"category": "万相台", "value": 156000}
]
```

### 示例2: 生成饼图

```
指令: "生成一个饼图展示ROI分布"
数据: [
  {"category": "高ROI", "value": 35},
  {"category": "中等ROI", "value": 28},
  {"category": "低ROI", "value": 15}
]
```

### 示例3: 生成四象限图

```
指令: "生成四象限图分析广告效果"
数据: [
  {"name": "计划A", "x": 3.5, "y": 120000},
  {"name": "计划B", "x": 2.1, "y": 85000},
  {"name": "计划C", "x": 4.2, "y": 95000}
]
```

## MCP工具列表

### 1. get_supported_charts
获取支持的图表类型列表

**输入参数:** 无

**返回示例:**
```json
{
  "success": true,
  "supported_charts": ["bar", "pie", "line", "scatter", "radar", "gauge", "linear", "quadrant"],
  "message": "支持的图表类型列表"
}
```

### 2. generate_chart
根据指令生成ECharts图表配置

**输入参数:**
- `instruction` (string, 必填): 图表生成指令
- `data` (array, 可选): 图表数据

**返回示例:**
```json
{
  "success": true,
  "chart_type": "bar",
  "config": {
    "title": {"text": "广告消耗对比"},
    "xAxis": {"type": "category", "data": ["京准通", "小红书", "万相台"]},
    "yAxis": {"type": "value"},
    "series": [{
      "type": "bar",
      "data": [125000, 89000, 156000],
      "itemStyle": {"color": "#ee6666"}
    }]
  }
}
```

## 环境变量

| 变量名 | 说明 | 必填 |
|-------|------|------|
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI端点URL | ✅ |
| `OPENAI_API_KEY` | OpenAI API密钥 | ✅ |
| `AZURE_OPENAI_DEPLOYMENT` | 部署名称 | ❌ (默认: gpt4o) |
| `AZURE_API_VERSION` | API版本 | ❌ (默认: 2023-03-15-preview) |

## 技术架构

```
┌─────────────────┐
│   Windsurf IDE  │
└────────┬────────┘
         │ MCP Protocol (stdio)
         ↓
┌─────────────────┐
│  Node.js Wrapper│  ← NPM包入口
└────────┬────────┘
         │ spawn
         ↓
┌─────────────────┐
│  Python MCP     │  ← MCP服务器
│  Server         │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  EChartsAgent   │  ← AI图表生成器
│  (Azure OpenAI) │
└─────────────────┘
```

## 开发指南

### 本地开发

```bash
# 安装依赖
npm install
pip install -r requirements.txt

# 运行测试
npm test

# 发布到npm
npm publish --access public
```

### 调试模式

```bash
# 启用详细日志
DEBUG=1 npm start
```

## 常见问题

### Q: 如何获取Azure OpenAI密钥？
A: 访问 [Azure Portal](https://portal.azure.com/)，创建OpenAI资源并获取API密钥。

### Q: 支持其他AI模型吗？
A: 当前仅支持Azure OpenAI，未来计划支持更多模型。

### Q: 图表配置如何使用？
A: 返回的`config`是标准的ECharts配置对象，可直接用于ECharts实例。

### Q: 数据格式有什么要求？
A: 基础格式为`[{"category": "名称", "value": 数值}]`，特殊图表（如四象限图）需要`x`和`y`字段。

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

- GitHub: https://lemonbi.tangelo.com.cn
- Email: lemonbi@tangelo.com.cn

---

Made with ❤️ by Lemonbi Team