get_example

Instructions

Implementation Reference

• src/tools/examples.ts:25-63 (handler)

  The primary handler function for the 'get_example' tool. It loads Vega-Lite examples from a JSON file (if exists), filters by category and optional search term, or falls back to predefined examples.

  export async function getExample(
    category: string,
    search?: string
  ): Promise<ExampleResult> {
    const dataPath = path.join(__dirname, "..", "data", "examples.json");
  
    try {
      // Try to load examples data
      const data = await fs.readFile(dataPath, "utf-8");
      const allExamples: VegaLiteExample[] = JSON.parse(data);
  
      // Filter by category
      let examples = allExamples.filter(
        (ex) => ex.category.toLowerCase() === category.toLowerCase()
      );
  
      // Apply search filter if provided
      if (search) {
        const lowerSearch = search.toLowerCase();
        examples = examples.filter(
          (ex) =>
            ex.name.toLowerCase().includes(lowerSearch) ||
            ex.description.toLowerCase().includes(lowerSearch)
        );
      }
  
      return {
        category,
        examples,
        totalExamples: examples.length,
      };
    } catch (error) {
      // If examples data doesn't exist yet, return fallback examples
      if (error instanceof Error && "code" in error && (error as any).code === "ENOENT") {
        return getFallbackExamples(category);
      }
      throw error;
    }
  }

• src/index.ts:50-64 (schema)

  Input schema definition for the 'get_example' tool, defining the expected parameters: required 'category' string and optional 'search' string.

  inputSchema: {
    type: "object",
    properties: {
      category: {
        type: "string",
        description: "Example category (e.g., 'bar', 'line', 'scatter', 'area', 'histogram', 'heatmap', 'interactive')",
      },
      search: {
        type: "string",
        description: "Optional search term to filter examples within the category",
      },
    },
    required: ["category"],
    additionalProperties: false,
  },

• src/index.ts:47-65 (registration)

  Registration of the 'get_example' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

  {
    name: "get_example",
    description: "Retrieve Vega-Lite example specifications by category or type",
    inputSchema: {
      type: "object",
      properties: {
        category: {
          type: "string",
          description: "Example category (e.g., 'bar', 'line', 'scatter', 'area', 'histogram', 'heatmap', 'interactive')",
        },
        search: {
          type: "string",
          description: "Optional search term to filter examples within the category",
        },
      },
      required: ["category"],
      additionalProperties: false,
    },
  },

• src/index.ts:120-136 (registration)

  Dispatch handler in CallToolRequestSchema that validates input, calls the getExample function, and formats the response as MCP content.

  case "get_example": {
    if (!args?.category) {
      throw new Error("Category parameter is required");
    }
    const examples = await getExample(
      args.category as string,
      args.search as string | undefined
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(examples, null, 2),
        },
      ],
    };
  }

• src/tools/examples.ts:8-20 (schema)

  TypeScript interfaces defining the structure of individual examples (VegaLiteExample) and the function return type (ExampleResult).

  interface VegaLiteExample {
    name: string;
    description: string;
    category: string;
    spec: Record<string, unknown>;
    url: string;
  }
  
  interface ExampleResult {
    category: string;
    examples: VegaLiteExample[];
    totalExamples: number;
  }