MCP Server Chart

Instructions

Implementation Reference

• src/utils/callTool.ts:44-111 (handler)

  Generic execution handler for the generate_violin_chart tool. Maps the tool name to chart type 'violin', validates arguments against the violin schema, generates the chart URL via external API, and returns the result in MCP format.

  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/violin.ts:16-53 (schema)

  Zod schema defining the input structure for generate_violin_chart, including data array with category, value, optional group, and optional style, theme, dimensions, titles.

  const data = z.object({
    category: z
      .string()
      .describe("Category of the data point, such as '分类一'."),
    value: z.number().describe("Value of the data point, such as 10."),
    group: z
      .string()
      .optional()
      .describe(
        "Optional group for the data point, used for grouping in the violin chart.",
      ),
  });
  
  const schema = {
    data: z
      .array(data)
      .describe(
        "Data for violin chart, such as, [{ category: 'Category A', value: 10 }], when the data is grouped, the 'group' field is required, such as, [{ category: 'Category B', value: 20, group: 'Group A' }].",
      )
      .nonempty({ message: "Violin chart data cannot be empty." }),
    style: z
      .object({
        backgroundColor: BackgroundColorSchema,
        palette: PaletteSchema,
        startAtZero: StartAtZeroSchema,
        texture: TextureSchema,
      })
      .optional()
      .describe(
        "Style configuration for the chart with a JSON object, optional.",
      ),
    theme: ThemeSchema,
    width: WidthSchema,
    height: HeightSchema,
    title: TitleSchema,
    axisXTitle: AxisXTitleSchema,
    axisYTitle: AxisYTitleSchema,
  };

• src/server.ts:64-77 (registration)

  Registers the MCP tool handlers: ListTools returns all enabled chart.tools including generate_violin_chart, 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/charts/violin.ts:55-64 (registration)

  Defines the tool specification object for generate_violin_chart used in MCP tool listing and input schema conversion.

  const tool = {
    name: "generate_violin_chart",
    description:
      "Generate a violin chart to show data for statistical summaries among different categories, such as, comparing the distribution of data points across categories.",
    inputSchema: zodToJsonSchema(schema),
    annotations: {
      title: "Generate Violin Chart",
      readOnlyHint: true,
    },
  };

• src/utils/callTool.ts:33-36 (helper)

  Chart type mapping that associates 'generate_violin_chart' tool name with internal chart type 'violin'.

    generate_violin_chart: "violin",
    generate_waterfall_chart: "waterfall",
    generate_word_cloud_chart: "word-cloud",
  } as const;