MCP Server Chart

Instructions

Implementation Reference

• src/utils/callTool.ts:43-110 (handler)

  The central handler function for all MCP chart tools. For 'generate_district_map', it maps to chartType 'district-map', validates args against the schema from Charts['district-map'], detects it as a map chart, and calls generateMap(tool, args) to proxy to the vis server.
  export async function callTool(tool: string, args: object = {}) { logger.info(`Calling tool: ${tool}`); const chartType = CHART_TYPE_MAP[tool as keyof typeof CHART_TYPE_MAP]; if (!chartType) { logger.error(`Unknown tool: ${tool}`); throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${tool}.`); } try { // Validate input using Zod before sending to API. // Select the appropriate schema based on the chart type. const schema = Charts[chartType].schema; if (schema) { // Use safeParse instead of parse and try-catch. const result = z.object(schema).safeParse(args); if (!result.success) { logger.error(`Invalid parameters: ${result.error.message}`); throw new McpError( ErrorCode.InvalidParams, `Invalid parameters: ${result.error.message}`, ); } } const isMapChartTool = [ "generate_district_map", "generate_path_map", "generate_pin_map", ].includes(tool); if (isMapChartTool) { // For map charts, we use the generateMap function, and return the mcp result. const { metadata, ...result } = await generateMap(tool, args); return result; } const url = await generateChartUrl(chartType, args); logger.info(`Generated chart URL: ${url}`); return { content: [ { type: "text", text: url, }, ], _meta: { description: "This is the chart's spec and configuration, which can be renderred to corresponding chart by AntV GPT-Vis chart components.", spec: { type: chartType, ...args }, }, }; // biome-ignore lint/suspicious/noExplicitAny: <explanation> } catch (error: any) { logger.error( `Failed to generate chart: ${error.message || "Unknown error"}.`, ); if (error instanceof McpError) throw error; if (error instanceof ValidateError) throw new McpError(ErrorCode.InvalidParams, error.message); throw new McpError( ErrorCode.InternalError, `Failed to generate chart: ${error?.message || "Unknown error."}`, ); } }
• src/charts/district-map.ts:30-82 (schema)

  Input schema definition for 'generate_district_map', including Zod validators for title, data (district name, styles, colors, data values, subdistricts), width, and height. Converted to JSON schema via zodToJsonSchema.
  const schema = { title: MapTitleSchema, data: z .object({ name: DistrictNameSchema, style: StyleSchema, colors: z .array(z.string()) .default([ "#1783FF", "#00C9C9", "#F0884D", "#D580FF", "#7863FF", "#60C42D", "#BD8F24", "#FF80CA", "#2491B3", "#17C76F", ]) .optional() .describe("Data color list, in rgb or rgba format."), dataType: z .enum(["number", "enum"]) .optional() .describe("The type of the data value, numeric or enumeration type"), dataLabel: z.string().optional().describe('Data label, such as "GDP"'), dataValue: z .string() .optional() .describe("Data value, numeric string or enumeration string."), dataValueUnit: z .string() .optional() .describe('Data unit, such as "万亿"'), showAllSubdistricts: z .boolean() .optional() .default(false) .describe("Whether to display all subdistricts."), subdistricts: z .array(SubDistrictSchema) .optional() .describe( "Sub-administrative regions are used to display the regional composition or regional distribution of related data.", ), }) .describe( 'Administrative division data, lower-level administrative divisions are optional. There are usually two scenarios: one is to simply display the regional composition, only `fillColor` needs to be configured, and all administrative divisions are consistent, representing that all blocks are connected as one; the other is the regional data distribution scenario, first determine the `dataType`, `dataValueUnit` and `dataLabel` configurations, `dataValue` should be a meaningful value and consistent with the meaning of dataType, and then determine the style configuration. The `fillColor` configuration represents the default fill color for areas without data. Lower-level administrative divisions do not need `fillColor` configuration, and their fill colors are determined by the `colors` configuration (If `dataType` is "number", only one base color (warm color) is needed in the list to calculate the continuous data mapping color band; if `dataType` is "enum", the number of color values in the list is equal to the number of enumeration values (contrast colors)). If `subdistricts` has a value, `showAllSubdistricts` must be set to true. For example, {"title": "陕西省地级市分布图", "data": {"name": "陕西省", "showAllSubdistricts": true, "dataLabel": "城市", "dataType": "enum", "colors": ["#4ECDC4", "#A5D8FF"], "subdistricts": [{"name": "西安市", "dataValue": "省会"}, {"name": "宝鸡市", "dataValue": "地级市"}, {"name": "咸阳市", "dataValue": "地级市"}, {"name": "铜川市", "dataValue": "地级市"}, {"name": "渭南市", "dataValue": "地级市"}, {"name": "延安市", "dataValue": "地级市"}, {"name": "榆林市", "dataValue": "地级市"}, {"name": "汉中市", "dataValue": "地级市"}, {"name": "安康市", "dataValue": "地级市"}, {"name": "商洛市", "dataValue": "地级市"}]}, "width": 1000, "height": 1000}.', ), width: MapWidthSchema, height: MapHeightSchema, };
• src/server.ts:64-77 (registration)

  Sets up MCP tool handlers: ListTools returns tool definitions from all enabled charts (including generate_district_map via Charts), CallTool dispatches to callTool function.
  function setupToolHandlers(server: Server): void { logger.info("setting up tool handlers..."); server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: getEnabledTools().map((chart) => chart.tool), })); // biome-ignore lint/suspicious/noExplicitAny: <explanation> server.setRequestHandler(CallToolRequestSchema, async (request: any) => { logger.info("calling tool", request.params.name, request.params.arguments); return await callTool(request.params.name, request.params.arguments); }); logger.info("tool handlers set up"); }
• src/utils/generate.ts:56-82 (helper)

  generateMap helper invoked by callTool for map tools like generate_district_map. Proxies the tool name and input to the visualization request server via POST, returning the result.
  export async function generateMap( tool: string, input: unknown, ): Promise<ResponseResult> { const url = getVisRequestServer(); const response = await axios.post( url, { serviceId: getServiceIdentifier(), tool, input, source: "mcp-server-chart", }, { headers: { "Content-Type": "application/json", }, }, ); const { success, errorMessage, resultObj } = response.data; if (!success) { throw new Error(errorMessage); } return resultObj; }
• src/charts/district-map.ts:85-95 (schema)

  Tool metadata definition including name 'generate_district_map', description, and inputSchema derived from the Zod schema.
  const tool = { name: "generate_district_map", description: "Generates regional distribution maps, which are usually used to show the administrative divisions and coverage of a dataset. It is not suitable for showing the distribution of specific locations, such as urban administrative divisions, GDP distribution maps of provinces and cities across the country, etc. This tool is limited to generating data maps within China.", inputSchema: zodToJsonSchema(schema), }; export const districtMap = { schema, tool, };