MCP Server Chart

Instructions

Implementation Reference

• src/charts/fishbone-diagram.ts:1-72 (schema)

  Defines the Zod schemas for input validation (FishboneNodeSchema and main schema) and the tool metadata (name, description, inputSchema) for the generate_fishbone_diagram tool.

  import { z } from "zod";
  import { zodToJsonSchema } from "../utils";
  import { type TreeDataType, validatedTreeDataSchema } from "../utils/validator";
  import { HeightSchema, TextureSchema, ThemeSchema, WidthSchema } from "./base";
  
  // Fishbone node schema
  // The recursive schema is not supported by gemini, and other clients, so we use a non-recursive schema which can represent a tree structure with a fixed depth.
  // Ref: https://github.com/antvis/mcp-server-chart/issues/155
  // Ref: https://github.com/antvis/mcp-server-chart/issues/132
  export const FishboneNodeSchema: z.ZodType<TreeDataType> = z.object({
    name: z.string(),
    children: z
      .array(
        z.object({
          name: z.string(),
          children: z
            .array(
              z.object({
                name: z.string(),
                children: z
                  .array(
                    z.object({
                      name: z.string(),
                    }),
                  )
                  .optional(),
              }),
            )
            .optional(),
        }),
      )
      .optional(),
  });
  
  // Fishbone diagram input schema
  const schema = {
    data: FishboneNodeSchema.describe(
      "Data for fishbone diagram chart which is a hierarchical structure, such as, { name: 'main topic', children: [{ name: 'topic 1', children: [{ name: 'subtopic 1-1' }] }] }, and the maximum depth is 3.",
    ).refine(validatedTreeDataSchema, {
      message: "Invalid parameters: node name is not unique.",
      path: ["data"],
    }),
    style: z
      .object({
        texture: TextureSchema,
      })
      .optional()
      .describe(
        "Style configuration for the chart with a JSON object, optional.",
      ),
    theme: ThemeSchema,
    width: WidthSchema,
    height: HeightSchema,
  };
  
  // Fishbone diagram tool descriptor
  const tool = {
    name: "generate_fishbone_diagram",
    description:
      "Generate a fishbone diagram chart to uses a fish skeleton, like structure to display the causes or effects of a core problem, with the problem as the fish head and the causes/effects as the fish bones. It suits problems that can be split into multiple related factors.",
    inputSchema: zodToJsonSchema(schema),
    annotations: {
      title: "Generate Fishbone Diagram",
      readOnlyHint: true,
    },
  };
  
  export const fishboneDiagram = {
    schema,
    tool,
  };

• src/utils/callTool.ts:9-36 (registration)

  CHART_TYPE_MAP registers the tool name 'generate_fishbone_diagram' to the internal chart type 'fishbone-diagram', enabling dispatch to the correct schema and generator.

  const CHART_TYPE_MAP = {
    generate_area_chart: "area",
    generate_bar_chart: "bar",
    generate_boxplot_chart: "boxplot",
    generate_column_chart: "column",
    generate_district_map: "district-map",
    generate_dual_axes_chart: "dual-axes",
    generate_fishbone_diagram: "fishbone-diagram",
    generate_flow_diagram: "flow-diagram",
    generate_funnel_chart: "funnel",
    generate_histogram_chart: "histogram",
    generate_line_chart: "line",
    generate_liquid_chart: "liquid",
    generate_mind_map: "mind-map",
    generate_network_graph: "network-graph",
    generate_organization_chart: "organization-chart",
    generate_path_map: "path-map",
    generate_pie_chart: "pie",
    generate_pin_map: "pin-map",
    generate_radar_chart: "radar",
    generate_sankey_chart: "sankey",
    generate_scatter_chart: "scatter",
    generate_treemap_chart: "treemap",
    generate_venn_chart: "venn",
    generate_violin_chart: "violin",
    generate_waterfall_chart: "waterfall",
    generate_word_cloud_chart: "word-cloud",
  } as const;

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

  The core handler function that executes generate_fishbone_diagram: maps name to type, validates arguments using the chart-specific schema, generates the chart URL via generateChartUrl, and returns the MCP tool result.

  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/server.ts:64-77 (registration)

  Registers the MCP tool request handlers: lists all chart tools dynamically from Charts exports (including fishbone-diagram.tool), and handles tools/call by delegating to callTool with the tool name.

  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");
  }