Vega-Lite MCP Server

Instructions

Implementation Reference

• src/tools/search.ts:26-85 (handler)

  Main handler function that loads and searches documentation from JSON files (Vega-Lite and Deneb) or uses fallback data, performs fuzzy matching, sorts by relevance, and returns top 10 results.

  export async function searchDocs(query: string): Promise<SearchResult> {
    const vegaLitePath = path.join(__dirname, "..", "data", "documentation.json");
    const denebPath = path.join(__dirname, "..", "data", "deneb-documentation.json");
  
    let allDocs: DocSection[] = [];
    const sources: string[] = [];
  
    try {
      // Try to load Vega-Lite documentation
      const vegaLiteData = await fs.readFile(vegaLitePath, "utf-8");
      const vegaLiteDocs: DocSection[] = JSON.parse(vegaLiteData);
      vegaLiteDocs.forEach(doc => doc.source = 'vega-lite');
      allDocs = allDocs.concat(vegaLiteDocs);
      sources.push('vega-lite');
    } catch (error) {
      // Vega-Lite docs not available, will use fallback
    }
  
    try {
      // Try to load Deneb documentation
      const denebData = await fs.readFile(denebPath, "utf-8");
      const denebDocs: DocSection[] = JSON.parse(denebData);
      denebDocs.forEach(doc => doc.source = 'deneb');
      allDocs = allDocs.concat(denebDocs);
      sources.push('deneb');
    } catch (error) {
      // Deneb docs not available, will use fallback
    }
  
    // If no docs loaded, use fallback
    if (allDocs.length === 0) {
      return getFallbackDocs(query);
    }
  
    // Simple text search (case-insensitive)
    const lowerQuery = query.toLowerCase();
    const results = allDocs.filter((doc) => {
      return (
        doc.title.toLowerCase().includes(lowerQuery) ||
        doc.content.toLowerCase().includes(lowerQuery) ||
        doc.category.toLowerCase().includes(lowerQuery)
      );
    });
  
    // Sort by relevance (simple: title matches first, then content matches)
    results.sort((a, b) => {
      const aTitle = a.title.toLowerCase().includes(lowerQuery);
      const bTitle = b.title.toLowerCase().includes(lowerQuery);
      if (aTitle && !bTitle) return -1;
      if (!aTitle && bTitle) return 1;
      return 0;
    });
  
    return {
      results: results.slice(0, 10), // Return top 10 results
      query,
      totalResults: results.length,
      sources,
    };
  }

• src/index.ts:32-46 (schema)

  Tool schema definition including name, description, and input schema (requires 'query' string) returned by ListTools handler.

  {
    name: "search_docs",
    description: "Search through Vega-Lite documentation for information about charts, encodings, marks, and more",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query (e.g., 'bar chart', 'color encoding', 'scale domain')",
        },
      },
      required: ["query"],
      additionalProperties: false,
    },
  },

• src/index.ts:105-118 (registration)

  Dispatch handler in CallToolRequest that validates input, calls searchDocs, and formats response as JSON text content.

  case "search_docs": {
    if (!args?.query) {
      throw new Error("Query parameter is required");
    }
    const results = await searchDocs(args.query as string);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }

• src/tools/search.ts:16-20 (schema)

  TypeScript interface defining the output structure of the searchDocs function.

  interface SearchResult {
    results: DocSection[];
    query: string;
    totalResults: number;
    sources: string[]; // Which sources were searched

• src/tools/search.ts:8-14 (schema)

  TypeScript interface defining the structure of individual documentation sections used in search.

  interface DocSection {
    title: string;
    url: string;
    content: string;
    category: string;
    source?: string; // 'vega-lite' or 'deneb'
  }