search_brand

Instructions

Implementation Reference

• src/tools/search-brand.ts:29-46 (handler)

  The main handler function for the search_brand tool. It calls searchIndex() to perform full-text search across the design system index, then formats results as text output.

  export function handler(index: DesignSystemIndex, args: SearchBrandArgs) {
    const results = searchIndex(args.query, index.searchIndex, args.limit ?? 10, args.context);
  
    if (results.length === 0) {
      return [{ type: 'text' as const, text: `No results found for "${args.query}".` }];
    }
  
    const output = results.map((r) => ({
      type: r.type,
      name: r.name,
      context: r.context,
      score: r.score,
      snippet: r.snippet,
      source: r.source,
    }));
  
    return [{ type: 'text' as const, text: JSON.stringify(output, null, 2) }];
  }

• src/indexer/index.ts:253-291 (helper)

  The searchIndex() helper function that performs the actual full-text search. It scores entries based on term matching, generates snippets, and returns sorted results.

  export function searchIndex(
    query: string,
    entries: SearchIndexEntry[],
    limit: number = 10,
    context?: string,
  ): Array<SearchIndexEntry & { score: number; snippet: string }> {
    const queryLower = query.toLowerCase();
    const queryTerms = queryLower.split(/\s+/).filter(Boolean);
  
    const results: Array<SearchIndexEntry & { score: number; snippet: string }> = [];
  
    for (const entry of entries) {
      if (context && context !== 'all' && entry.context !== context) continue;
  
      const contentLower = entry.content.toLowerCase();
      let score = 0;
  
      for (const term of queryTerms) {
        const idx = contentLower.indexOf(term);
        if (idx !== -1) {
          score += 1;
          // Bonus for name match
          if (entry.name.toLowerCase().includes(term)) score += 2;
        }
      }
  
      if (score > 0) {
        const snippetIdx = contentLower.indexOf(queryTerms[0]);
        const snippetStart = Math.max(0, snippetIdx - 40);
        const snippetEnd = Math.min(entry.content.length, snippetIdx + 120);
        const snippet = (snippetStart > 0 ? '...' : '') + entry.content.slice(snippetStart, snippetEnd).trim() + (snippetEnd < entry.content.length ? '...' : '');
  
        results.push({ ...entry, score, snippet });
      }
    }
  
    results.sort((a, b) => b.score - a.score);
    return results.slice(0, limit);
  }

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

  The INPUT_SCHEMA for search_brand, defining the JSON Schema for query (required string), context (optional enum: marketing/product/shared/all), and limit (optional number, default 10).

  export const INPUT_SCHEMA = {
    type: 'object' as const,
    properties: {
      query: { type: 'string', description: 'Search query' },
      context: { type: 'string', enum: ['marketing', 'product', 'shared', 'all'], default: 'all', description: 'Design context to search within' },
      limit: { type: 'number', default: 10, description: 'Maximum number of results to return' },
    },
    required: ['query'],
  };

• src/types/mcp.ts:135-145 (schema)

  The TypeScript SearchBrandArgs interface defining types for query (string), context (optional union), and limit (optional number).

  /** Arguments for the `search_brand` MCP tool */
  export interface SearchBrandArgs {
    /** Free-text search query across all design-system content */
    query: string;
  
    /** Restrict search to a specific design context */
    context?: 'marketing' | 'product' | 'shared' | 'all';
  
    /** Maximum number of results to return (default: 10) */
    limit?: number;
  }

• src/tools/index.ts:36-49 (registration)

  Registration of the searchBrand module in the ALL_TOOLS array (line 46), plus the case-switch dispatching to searchBrand.handler() (lines 96-97) in CallToolRequestSchema handler.

  const ALL_TOOLS = [
    brandOverview,
    colors,
    typography,
    logos,
    components,
    guidelines,
    tokens,
    textures,
    css,
    searchBrand,
    contextDiff,
    validateUsage,
  ] as const;