@antv/mcp-server-chart开发者指南：自定义工具与扩展开发终极指南

@antv/mcp-server-chart开发者指南：自定义工具与扩展开发终极指南

【免费下载链接】mcp-server-chart🤖 A Model Context Protocol server for generating visual charts using @antvis.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-server-chart

想要为你的AI应用添加强大的图表生成功能吗？@antv/mcp-server-chart是一个基于Model Context Protocol（MCP）的服务器，专门用于使用AntV库生成各种可视化图表。这个项目为开发者提供了26+种图表类型的生成能力，从基础的折线图、柱状图到复杂的地图可视化、网络图和思维导图。本文将为你提供完整的自定义工具与扩展开发指南，帮助你将这个强大的图表生成能力集成到你的应用中。

🎯 为什么选择@antv/mcp-server-chart？

在数据驱动的时代，可视化是理解数据的关键。@antv/mcp-server-chart通过MCP协议将AntV的图表生成能力标准化，让你可以：

• 无缝集成AI助手：与Claude、Cursor、VSCode等AI IDE完美兼容
• 丰富的图表类型：支持26+种图表，满足各种数据可视化需求
• 灵活的部署方式：支持SSE、Streamable和Stdio多种传输协议
• 易于扩展：模块化架构让你可以轻松添加自定义图表工具
• 企业级功能：支持私有部署和图表生成记录管理

📁 项目架构深度解析

了解项目结构是进行扩展开发的第一步。让我们来看看关键的文件和目录：

核心目录结构

mcp-server-chart/ ├── src/ │ ├── charts/ # 所有图表类型定义 │ │ ├── area.ts # 面积图工具定义 │ │ ├── bar.ts # 柱状图工具定义 │ │ ├── base.ts # 基础配置Schema │ │ └── index.ts # 图表导出入口 │ ├── services/ # 传输协议服务 │ │ ├── sse.ts # SSE服务实现 │ │ ├── stdio.ts # Stdio服务实现 │ │ └── streamable.ts # Streamable服务实现 │ ├── utils/ # 工具函数 │ │ ├── callTool.ts # 工具调用逻辑 │ │ ├── generate.ts # 图表生成核心 │ │ └── schema.ts # Schema转换工具 │ ├── index.ts # CLI入口点 │ ├── server.ts # MCP服务器主逻辑 │ └── sdk.ts # SDK相关定义 ├── __tests__/ # 测试文件 ├── docker/ # Docker部署配置 ├── manifest.json # MCP清单文件 └── package.json # 项目依赖配置

图表工具定义模式

每个图表工具都遵循相同的模式。以面积图为例，查看src/charts/area.ts：

// 1. 导入必要的依赖 import { z } from "zod"; import { zodToJsonSchema } from "../utils"; // 2. 定义数据Schema const data = z.object({ time: z.string(), value: z.number(), group: z.string().optional(), }); // 3. 定义工具Schema const schema = { data: z.array(data).nonempty(), stack: z.boolean().optional().default(false), // ... 其他配置 }; // 4. 创建工具描述符 const tool = { name: "generate_area_chart", description: "Generate a area chart to show data trends...", inputSchema: zodToJsonSchema(schema), annotations: { title: "Generate Area Chart", readOnlyHint: true, }, }; // 5. 导出工具配置 export const area = { schema, tool, };

🔧 如何添加自定义图表工具

步骤1：创建新的图表文件

在src/charts/目录下创建新的TypeScript文件，例如custom-chart.ts：

import { z } from "zod"; import { zodToJsonSchema } from "../utils"; import { AxisXTitleSchema, AxisYTitleSchema, BackgroundColorSchema, HeightSchema, PaletteSchema, TextureSchema, ThemeSchema, TitleSchema, WidthSchema, } from "./base"; // 定义自定义图表的数据结构 const data = z.object({ category: z.string(), value: z.number(), subcategory: z.string().optional(), }); // 定义工具Schema const schema = { data: z.array(data).nonempty().describe("自定义图表数据"), // 自定义配置参数 showLabels: z.boolean().optional().default(true), animation: z.boolean().optional().default(false), // 继承基础配置 style: z.object({ backgroundColor: BackgroundColorSchema, palette: PaletteSchema, texture: TextureSchema, }).optional(), theme: ThemeSchema, width: WidthSchema, height: HeightSchema, title: TitleSchema, axisXTitle: AxisXTitleSchema, axisYTitle: AxisYTitleSchema, }; // 创建工具描述符 const tool = { name: "generate_custom_chart", // 工具名称 description: "生成自定义图表，用于展示特定类型的数据分析结果", inputSchema: zodToJsonSchema(schema), annotations: { title: "Generate Custom Chart", readOnlyHint: true, }, }; export const customChart = { schema, tool, };

步骤2：导出新图表

编辑src/charts/index.ts，添加你的图表导出：

// 在现有导出后添加 export { customChart } from "./custom-chart";

步骤3：注册图表生成逻辑

编辑src/utils/callTool.ts，添加你的图表处理逻辑：

// 在switch语句中添加新的case case "generate_custom_chart": return await generateChart("custom-chart", args);

步骤4：更新清单文件

编辑manifest.json，在tools数组中添加新工具的描述：

{ "name": "generate_custom_chart", "description": "Generate custom charts for specialized data visualization" }

🚀 高级扩展技巧

自定义图表生成服务

如果你需要私有化的图表生成服务，可以通过环境变量VIS_REQUEST_SERVER配置自定义服务：

# 设置私有服务地址 export VIS_REQUEST_SERVER="https://your-chart-service.com/api/generate"

工具过滤机制

通过DISABLED_TOOLS环境变量可以禁用特定图表工具：

# 禁用思维导图和鱼骨图工具 export DISABLED_TOOLS="generate_mind_map,generate_fishbone_diagram"

服务标识符配置

配置SERVICE_ID可以启用图表生成记录功能：

# 设置服务标识符 export SERVICE_ID="your-unique-service-id"

🧪 测试你的扩展

运行本地测试

# 安装依赖 npm install # 构建项目 npm run build # 启动开发服务器 npm run start

使用Docker测试

# 进入docker目录 cd docker # 启动Docker容器 docker compose up -d # 测试SSE传输 curl http://localhost:1123/sse # 测试Streamable传输 curl http://localhost:1122/mcp

集成测试

查看tests/charts/charts.spec.ts了解如何编写图表测试：

describe("Custom Chart Generation", () => { it("should generate custom chart with valid data", async () => { const result = await callTool("generate_custom_chart", { data: [ { category: "A", value: 100 }, { category: "B", value: 200 }, ], title: "Custom Chart Test", }); expect(result).toHaveProperty("content"); expect(result.content[0]).toHaveProperty("type", "image"); }); });

📊 最佳实践建议

1. 保持Schema一致性

所有图表工具应使用src/charts/base.ts中定义的基础Schema，确保配置的一致性：

// 使用基础配置 import { WidthSchema, HeightSchema, TitleSchema, ThemeSchema, // ... 其他基础Schema } from "./base";

2. 提供清晰的描述

工具描述应该清晰说明图表的用途、适用场景和参数要求：

description: "生成[图表类型]，用于[使用场景]，特别适合[特定数据类型]。示例：[具体示例]",

3. 处理错误情况

在图表生成逻辑中妥善处理错误：

try { const chartUrl = await generateChartUrl(type, options); return { content: [{ type: "image", data: chartUrl }], }; } catch (error) { logger.error(`Failed to generate ${type} chart:`, error); throw new Error(`Chart generation failed: ${error.message}`); }

4. 性能优化

• 使用HTTP连接池减少连接开销
• 实现缓存机制减少重复渲染
• 优化图片生成参数

🔗 相关资源

• 官方文档：README.md
• 图表定义源码：src/charts/
• 工具调用逻辑：src/utils/callTool.ts
• 服务实现：src/services/
• 测试示例：tests/charts/

🎉 开始你的扩展之旅

现在你已经掌握了@antv/mcp-server-chart的扩展开发知识。无论是添加新的图表类型、定制现有功能，还是集成到你的私有服务中，这个项目都提供了灵活的架构和清晰的扩展点。

记住，优秀的扩展应该：

• 遵循现有的代码模式和约定
• 提供完整的类型定义和文档
• 包含充分的测试用例
• 考虑向后兼容性

开始你的图表生成工具扩展之旅吧！如果有任何问题，欢迎查阅项目文档或参考现有实现。🎨📈

提示：在开发过程中，可以使用npm run build -- --watch命令实时编译TypeScript代码，提高开发效率。

【免费下载链接】mcp-server-chart🤖 A Model Context Protocol server for generating visual charts using @antvis.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-server-chart