feat: use MinIO to storage chart image (#12)

* feat(图表生成): 实现MinIO集成和统一图片处理逻辑

添加MinIO对象存储支持，将图表图片存储为URL而非Base64数据
重构所有图表工具使用统一的generateChartImageForTool方法
更新文档说明MinIO配置和故障排查指南
添加环境变量配置和调试日志支持

* refactor(imageHandler): 修改图表图片返回格式为纯文本地址

将返回的HTML img标签改为纯文本文件地址显示，提高兼容性

* refactor(utils): 统一图表生成函数并优化MinIO处理逻辑

将`generateChartImageForTool`合并到`generateChartImage`中，简化代码结构
将MinIO相关逻辑抽离到单独模块
更新所有工具文件使用新的统一函数
优化README文档并移除过时的TROUBLESHOOTING文件

* docs: 添加主要云服务提供商集成说明到README

* docs: 更新README中的对象存储提供商集成说明

更新对象存储提供商集成部分，将标题改为更通用的描述并添加MinIO的详细集成信息

* docs: 更新贡献者列表

* test(echarts): 为宽度和高度添加最小最大值限制

Author: Susuperli

.env.example

@@ -0,0 +1,18 @@
+# MinIO Configuration
+# Copy this file to .env and update with your MinIO settings
+
+# MinIO server endpoint (without protocol)
+MINIO_ENDPOINT=localhost
+
+# MinIO server port
+MINIO_PORT=9000
+
+# Use SSL/HTTPS connection (true/false)
+MINIO_USE_SSL=false
+
+# MinIO access credentials
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+
+# Bucket name for storing charts
+MINIO_BUCKET_NAME=mcp-echarts

.gitignore

@@ -31,3 +31,11 @@ coverage
 package-lock.json
 pnpm-lock.yaml
 bun.lock
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Test files
+test-*.js

README.md

@@ -14,6 +14,7 @@ Generate <img src="https://echarts.apache.org/zh/images/favicon.png" height="14"
 
 - Fully support all features and syntax of `ECharts`, include data, style, theme and so on.
 - Support exporting to `png`, `svg`, and `option` formats, with validation for `ECharts` to facilitate the model's multi-round output of correct syntax and graphics.
+- **MinIO Integration**: Store charts in MinIO object storage and return URLs instead of Base64 data for better performance and sharing capabilities.
 - Lightweight, we can install it with `zero dependence`.
 - Extremely `secure`, fully generated locally, without relying on any remote services.
 
@@ -56,6 +57,46 @@ On Window system:
 
 Also, you can use it on aliyun, modelscope, glama.ai, smithery.ai or others with HTTP, SSE Protocol.
 
+## 🗂️ MinIO Configuration (Optional)
+
+For better performance and sharing capabilities, you can configure MinIO object storage to store chart images as URLs instead of Base64 data.
+
+### Setup MinIO
+
+1. **Install and start MinIO locally:**
+   ```bash
+   # Download MinIO (macOS example)
+   brew install minio/stable/minio
+   
+   # Start MinIO server
+   minio server ~/minio-data --console-address :9001
+   ```
+
+2. **Configure environment variables:**
+   ```bash
+   # Copy the example environment file
+   cp .env.example .env
+   
+   # Edit .env with your MinIO settings
+   MINIO_ENDPOINT=localhost
+   MINIO_PORT=9000
+   MINIO_USE_SSL=false
+   MINIO_ACCESS_KEY=minioadmin
+   MINIO_SECRET_KEY=minioadmin
+   MINIO_BUCKET_NAME=mcp-echarts
+   ```
+
+3. **Integration with Object Storage Providers:**
+   - **[MinIO](https://min.io/)**: High-performance, S3-compatible object storage. Use [MinIO JavaScript Client](https://min.io/docs/minio/linux/developers/javascript/minio-javascript.html) for direct integration.
+   - **[Amazon S3](https://aws.amazon.com/s3/)**: Use [AWS SDK](https://aws.amazon.com/sdk-for-javascript/) with compatible API endpoint.
+   - **[Alibaba Cloud OSS](https://www.alibabacloud.com/product/object-storage-service)**: Use the [Alibaba Cloud SDK](https://www.alibabacloud.com/help/en/sdk) for OSS services.
+   - **[Google Cloud Storage](https://cloud.google.com/storage)**: Integrate using [Google Cloud SDK](https://cloud.google.com/sdk) or compatible API.
+   - **[Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs)**: Use [Azure SDK](https://azure.microsoft.com/en-us/downloads/) for Blob storage access.
+   - **[Tencent Cloud COS](https://intl.cloud.tencent.com/product/cos)**: Use the [Tencent Cloud SDK](https://intl.cloud.tencent.com/document/product/436/6474) for COS integration.
+### Fallback Behavior
+
+If MinIO is not configured or unavailable, the system automatically falls back to `Base64` data output, ensuring compatibility.
+
 
 ## 🔨 Development
 
@@ -81,6 +122,7 @@ npm run start
 ## 🧑🏻‍💻 Contributors
 
 - [lyw405](https://github.com/lyw405): Supports 15+ charting MCP tool. [#2](https://github.com/hustcc/mcp-echarts/issues/2)
+- [susuperli](https://github.com/susuperli): use MinIO to save the chart image base64 and return the url. [#10](https://github.com/hustcc/mcp-echarts/issues/10)
 - [BQXBQX](https://github.com/BQXBQX): Use @napi-rs/canvas instead node-canvas. [#3](https://github.com/hustcc/mcp-echarts/issues/3)
 - [hustcc](https://github.com/hustcc): Initial the repo.
 

__tests__/tools/echarts.json

@@ -12,12 +12,16 @@
       "width": {
         "type": "number",
         "description": "The width of the ECharts in pixels. Default is 800.",
-        "default": 800
+        "default": 800,
+        "minimum": 50,
+        "maximum": 5000
       },
       "height": {
         "type": "number",
         "description": "The height of the ECharts in pixels. Default is 600.",
-        "default": 600
+        "default": 600,
+        "minimum": 50,
+        "maximum": 5000
       },
       "theme": {
         "type": "string",

package.json

@@ -19,7 +19,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@napi-rs/canvas": "^0.1.73",
+    "dotenv": "^17.2.1",
     "echarts": "^5.6.0",
+    "minio": "^8.0.5",
     "zod": "^3.25.16"
   },
   "devDependencies": {

src/index.ts

@@ -2,8 +2,13 @@
 import process from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { config } from "dotenv";
 import { tools } from "./tools";
 
+// Load environment variables from .env file (completely silent to avoid stdout contamination)
+process.env.DOTENV_CONFIG_QUIET = "true";
+config({ override: false, debug: false });
+
 /**
  * MCP Server for ECharts.
  * This server provides tools for generating ECharts visualizations and validate ECharts configurations.
@@ -65,6 +70,6 @@ async function main(): Promise<void> {
 
 // Start application
 main().catch((error) => {
-  console.error("Failed to start application:", error);
+  // Don't use console.error in MCP servers as it interferes with JSON protocol
   process.exit(1);
 });

src/tools/bar.ts

@@ -1,6 +1,6 @@
 import type { EChartsOption, SeriesOption } from "echarts";
 import { z } from "zod";
-import { renderECharts } from "../utils/render";
+import { generateChartImage } from "../utils";
 import {
   AxisXTitleSchema,
   AxisYTitleSchema,
@@ -55,7 +55,7 @@ export const generateBarChartTool = {
     title: TitleSchema,
     width: WidthSchema,
   }),
-  run: (params: {
+  run: async (params: {
     axisXTitle?: string;
     axisYTitle?: string;
     data: Array<{ category: string; value: number; group?: string }>;
@@ -164,15 +164,13 @@ export const generateBarChartTool = {
       },
     };
 
-    const imageBase64 = renderECharts(echartsOption, width, height, theme);
-    return {
-      content: [
-        {
-          data: imageBase64,
-          mimeType: "image/png",
-          type: "image",
-        },
-      ],
-    };
+    return await generateChartImage(
+      echartsOption,
+      width,
+      height,
+      theme,
+      "png",
+      "generate_bar_chart",
+    );
   },
 };

src/tools/boxplot.ts

@@ -1,6 +1,6 @@
 import type { EChartsOption, SeriesOption } from "echarts";
 import { z } from "zod";
-import { renderECharts } from "../utils/render";
+import { generateChartImage } from "../utils";
 import {
   AxisXTitleSchema,
   AxisYTitleSchema,
@@ -42,7 +42,7 @@ export const generateBoxplotChartTool = {
     title: TitleSchema,
     width: WidthSchema,
   }),
-  run: (params: {
+  run: async (params: {
     axisXTitle?: string;
     axisYTitle?: string;
     data: Array<{ category: string; value: number; group?: string }>;
@@ -181,15 +181,13 @@ export const generateBoxplotChartTool = {
       return [min, Q1, median, Q3, max];
     }
 
-    const imageBase64 = renderECharts(echartsOption, width, height, theme);
-    return {
-      content: [
-        {
-          data: imageBase64,
-          mimeType: "image/png",
-          type: "image",
-        },
-      ],
-    };
+    return await generateChartImage(
+      echartsOption,
+      width,
+      height,
+      theme,
+      "png",
+      "generate_boxplot_chart",
+    );
   },
 };

src/tools/candlestick.ts

@@ -1,6 +1,6 @@
 import type { EChartsOption, SeriesOption } from "echarts";
 import { z } from "zod";
-import { renderECharts } from "../utils/render";
+import { generateChartImage } from "../utils";
 import {
   HeightSchema,
   ThemeSchema,
@@ -41,7 +41,7 @@ export const generateCandlestickChartTool = {
     title: TitleSchema,
     width: WidthSchema,
   }),
-  run: (params: {
+  run: async (params: {
     data: Array<{
       date: string;
       open: number;
@@ -208,15 +208,13 @@ export const generateCandlestickChartTool = {
       },
     };
 
-    const imageBase64 = renderECharts(echartsOption, width, height, theme);
-    return {
-      content: [
-        {
-          data: imageBase64,
-          mimeType: "image/png",
-          type: "image",
-        },
-      ],
-    };
+    return await generateChartImage(
+      echartsOption,
+      width,
+      height,
+      theme,
+      "png",
+      "generate_candlestick_chart",
+    );
   },
 };

src/tools/echarts.ts

@@ -1,10 +1,30 @@
 import { z } from "zod";
-import { renderECharts } from "../utils";
+import { generateChartImage } from "../utils";
 
 function isValidEChartsOption(option: string): boolean {
   try {
     const parsedOption = JSON.parse(option);
-    return typeof parsedOption === "object" && parsedOption !== null;
+    if (typeof parsedOption !== "object" || parsedOption === null) {
+      return false;
+    }
+
+    // Basic validation for common chart types that require axes
+    if (parsedOption.series && Array.isArray(parsedOption.series)) {
+      const hasCartesianSeries = parsedOption.series.some(
+        (series: { type?: string }) =>
+          series.type && ["bar", "line", "scatter"].includes(series.type),
+      );
+
+      // If chart has cartesian series, it should have proper axis configuration
+      if (hasCartesianSeries && !parsedOption.xAxis && !parsedOption.yAxis) {
+        console.error(
+          "[DEBUG] Chart validation failed: Cartesian chart missing axis configuration",
+        );
+        return false;
+      }
+    }
+
+    return true;
   } catch {
     return false;
   }
@@ -46,11 +66,21 @@ ATTENTION: A valid ECharts option must be a valid JSON string, and cannot be emp
       }),
     width: z
       .number()
+      .min(
+        50,
+        "Width must be at least 50 pixels to ensure proper chart rendering",
+      )
+      .max(5000, "Width cannot exceed 5000 pixels")
       .describe("The width of the ECharts in pixels. Default is 800.")
       .optional()
       .default(800),
     height: z
       .number()
+      .min(
+        50,
+        "Height must be at least 50 pixels to ensure proper chart rendering",
+      )
+      .max(5000, "Height cannot exceed 5000 pixels")
       .describe("The height of the ECharts in pixels. Default is 600.")
       .optional()
       .default(600),
@@ -67,7 +97,7 @@ ATTENTION: A valid ECharts option must be a valid JSON string, and cannot be emp
       .optional()
       .default("png"),
   }),
-  run: (params: {
+  run: async (params: {
     echartsOption: string;
     width?: number;
     height?: number;
@@ -76,6 +106,17 @@ ATTENTION: A valid ECharts option must be a valid JSON string, and cannot be emp
   }) => {
     const { width, height, echartsOption, theme, outputType } = params;
 
+    // Debug logging (writes to stderr, won't interfere with MCP protocol)
+    if (process.env.DEBUG_MCP_ECHARTS) {
+      console.error("[DEBUG] ECharts tool called with params:", {
+        echartsOptionLength: echartsOption?.length,
+        width,
+        height,
+        theme,
+        outputType,
+      });
+    }
+
     if (!isValidEChartsOption(echartsOption)) {
       throw new Error(
         "Invalid ECharts option, a valid ECharts option must be a valid JSON string, and cannot be empty.",
@@ -84,23 +125,14 @@ ATTENTION: A valid ECharts option must be a valid JSON string, and cannot be emp
 
     const option = JSON.parse(echartsOption);
 
-    const r = renderECharts(option, width, height, theme, outputType);
-
-    const isImage = outputType !== "svg" && outputType !== "option";
-
-    const result = isImage
-      ? {
-          type: "image",
-          data: r,
-          mimeType: "image/png",
-        }
-      : {
-          type: "text",
-          text: r,
-        };
-
-    return {
-      content: [result],
-    };
+    // Use the unified image generation method
+    return await generateChartImage(
+      option,
+      width,
+      height,
+      theme,
+      outputType,
+      "generate_echarts_chart",
+    );
   },
 };