@maz-ui/mcp 4.8.0 → 4.9.0

package/dist/mcp.mjs

@@ -7,7 +7,237 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const version = "4.7.9";
+const version = "4.8.0";
+
+class MetadataExtractor {
+  extract(name, type, content, manualTags = []) {
+    const frontmatter = this.extractFrontmatter(content);
+    const sections = this.extractSections(content);
+    const props = this.extractProps(content);
+    const slots = this.extractSlots(content);
+    const events = this.extractEvents(content);
+    const displayName = frontmatter.title ?? this.nameToDisplayName(name);
+    const description = frontmatter.description ?? this.extractFirstParagraph(content);
+    const extractedTags = this.buildTags(name, displayName, props, slots, events);
+    const tags = this.mergeTags(manualTags, extractedTags);
+    return {
+      name,
+      displayName,
+      type,
+      description,
+      tags,
+      ...props.length > 0 && { props },
+      ...slots.length > 0 && { slots },
+      ...events.length > 0 && { events },
+      sections
+    };
+  }
+  extractFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      return {};
+    }
+    const result = {};
+    const yaml = match[1];
+    for (const line of yaml.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("title:")) {
+        result.title = trimmed.slice("title:".length).trim();
+      } else if (trimmed.startsWith("description:")) {
+        result.description = trimmed.slice("description:".length).trim();
+      }
+    }
+    return result;
+  }
+  extractSections(content) {
+    const sections = [];
+    const contentWithoutFrontmatter = this.stripFrontmatter(content);
+    const lines = contentWithoutFrontmatter.split("\n");
+    let currentSection;
+    const flushSection = () => {
+      if (currentSection) {
+        const sectionContent = currentSection.contentLines.join("\n").trim();
+        sections.push({
+          title: currentSection.title,
+          level: currentSection.level,
+          content: this.extractSectionLeadText(sectionContent)
+        });
+      }
+    };
+    for (const line of lines) {
+      const headingMatch = line.match(/^(#{2,3}) +(\S.*)$/);
+      if (headingMatch) {
+        flushSection();
+        currentSection = {
+          level: headingMatch[1].length,
+          title: this.cleanHeadingText(headingMatch[2]),
+          contentLines: []
+        };
+      } else if (currentSection) {
+        currentSection.contentLines.push(line);
+      }
+    }
+    flushSection();
+    return sections;
+  }
+  extractProps(content) {
+    return this.extractTableColumn(content, "Props", "Name");
+  }
+  extractSlots(content) {
+    return this.extractTableColumn(content, "Slots", "Name");
+  }
+  extractEvents(content) {
+    return this.extractTableColumn(content, "Events", "Event name");
+  }
+  mergeTags(manualTags, extractedTags) {
+    const tagSet = /* @__PURE__ */ new Set();
+    for (const tag of manualTags) {
+      tagSet.add(tag.toLowerCase());
+    }
+    for (const tag of extractedTags) {
+      tagSet.add(tag.toLowerCase());
+    }
+    return Array.from(tagSet);
+  }
+  extractTableColumn(content, sectionName, columnName) {
+    const sectionRegex = new RegExp(`## ${sectionName} *\\n`, "i");
+    const sectionMatch = content.match(sectionRegex);
+    if (!sectionMatch || sectionMatch.index === void 0) {
+      return [];
+    }
+    const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length);
+    const lines = afterSection.split("\n");
+    const headerLine = lines.find((l) => l.includes("|") && l.toLowerCase().includes(columnName.toLowerCase()));
+    if (!headerLine) {
+      return [];
+    }
+    const headerIndex = lines.indexOf(headerLine);
+    const columns = headerLine.split("|").map((c) => c.trim()).filter(Boolean);
+    const nameColumnIndex = columns.findIndex((c) => c.toLowerCase().includes(columnName.toLowerCase()));
+    if (nameColumnIndex === -1) {
+      return [];
+    }
+    const results = [];
+    for (let i = headerIndex + 2; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.includes("|") || line.match(/^#{1,6}\s/)) {
+        break;
+      }
+      if (line.match(/^ *\|[-\s|]+\| *$/)) {
+        continue;
+      }
+      const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
+      if (cells[nameColumnIndex]) {
+        const name = cells[nameColumnIndex].replace(/\*\*/g, "").trim();
+        if (name) {
+          results.push(name);
+        }
+      }
+    }
+    return results;
+  }
+  stripFrontmatter(content) {
+    return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+  }
+  cleanHeadingText(text) {
+    let result = this.removeTemplateTags(text);
+    result = this.resolveMarkdownLinks(result);
+    return result.trim();
+  }
+  removeTemplateTags(text) {
+    let result = "";
+    let i = 0;
+    while (i < text.length) {
+      if (text[i] === "{" && text[i + 1] === "{") {
+        const end = text.indexOf("}}", i + 2);
+        i = end === -1 ? text.length : end + 2;
+      } else {
+        result += text[i];
+        i++;
+      }
+    }
+    return result;
+  }
+  resolveMarkdownLinks(text) {
+    let result = "";
+    let i = 0;
+    while (i < text.length) {
+      if (text[i] === "[") {
+        const closeBracket = text.indexOf("]", i + 1);
+        if (closeBracket !== -1 && text[closeBracket + 1] === "(") {
+          const closeParen = text.indexOf(")", closeBracket + 2);
+          if (closeParen !== -1) {
+            result += text.slice(i + 1, closeBracket);
+            i = closeParen + 1;
+            continue;
+          }
+        }
+      }
+      result += text[i];
+      i++;
+    }
+    return result;
+  }
+  extractSectionLeadText(content) {
+    const lines = content.split("\n");
+    const paragraphLines = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        if (paragraphLines.length > 0) {
+          break;
+        }
+        continue;
+      }
+      if (trimmed.startsWith("#") || trimmed.startsWith("<") || trimmed.startsWith("```") || trimmed.startsWith(":::") || trimmed.startsWith("|")) {
+        if (paragraphLines.length > 0) {
+          break;
+        }
+        continue;
+      }
+      paragraphLines.push(trimmed);
+    }
+    return paragraphLines.join(" ");
+  }
+  extractFirstParagraph(content) {
+    const stripped = this.stripFrontmatter(content);
+    const lines = stripped.split("\n");
+    const paragraphLines = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        if (paragraphLines.length > 0) {
+          break;
+        }
+        continue;
+      }
+      if (trimmed.startsWith("#") || trimmed.startsWith("<") || trimmed.startsWith("```") || trimmed.startsWith(":::") || trimmed.startsWith("|") || trimmed.startsWith("{{")) {
+        if (paragraphLines.length > 0) {
+          break;
+        }
+        continue;
+      }
+      paragraphLines.push(trimmed);
+    }
+    return paragraphLines.join(" ");
+  }
+  nameToDisplayName(name) {
+    return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  }
+  buildTags(name, displayName, props, slots, events) {
+    const tags = [name, displayName.toLowerCase()];
+    for (const prop of props.slice(0, 10)) {
+      tags.push(`prop:${prop}`);
+    }
+    for (const slot of slots.slice(0, 10)) {
+      tags.push(`slot:${slot}`);
+    }
+    for (const event of events.slice(0, 10)) {
+      tags.push(`event:${event}`);
+    }
+    return tags;
+  }
+}
 
 const _dirname = dirname(fileURLToPath(import.meta.url));
 class DocumentationService {
@@ -19,6 +249,7 @@ class DocumentationService {
   directivesDir;
   pluginsDir;
   helpersDir;
+  metadataExtractor = new MetadataExtractor();
   constructor() {
     const localDocsRoot = resolve(_dirname, "../docs/src");
     const localGeneratedDocsDir = resolve(_dirname, "../docs/generated-docs");
@@ -130,12 +361,45 @@ ${generatedDoc}`;
   getAllHelpers() {
     return this.listMarkdownFiles(this.helpersDir);
   }
+  // ========== UNIFIED LOADING ==========
+  getAllDocuments() {
+    const documents = [];
+    for (const name of this.getAllComponents()) {
+      const content = this.getComponentDocumentation(name);
+      if (content) {
+        documents.push(this.buildDocument(name, "component", content));
+      }
+    }
+    const categories = [
+      { type: "guide", names: this.getAllGuides(), getContent: (name) => this.getGuideDocumentation(name) },
+      { type: "composable", names: this.getAllComposables(), getContent: (name) => this.getComposableDocumentation(name) },
+      { type: "directive", names: this.getAllDirectives(), getContent: (name) => this.getDirectiveDocumentation(name) },
+      { type: "plugin", names: this.getAllPlugins(), getContent: (name) => this.getPluginDocumentation(name) },
+      { type: "helper", names: this.getAllHelpers(), getContent: (name) => this.getHelperDocumentation(name) }
+    ];
+    for (const category of categories) {
+      for (const name of category.names) {
+        const content = category.getContent(name);
+        if (content) {
+          documents.push(this.buildDocument(name, category.type, content));
+        }
+      }
+    }
+    return documents;
+  }
+  buildDocument(name, type, content) {
+    return {
+      name,
+      type,
+      content,
+      metadata: this.metadataExtractor.extract(name, type, content)
+    };
+  }
   // ========== UTILITAIRES ==========
   getOverview() {
     const overviewPath = join(this.docsRoot, "index.md");
     return this.readMarkdownFile(overviewPath);
   }
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   searchDocumentation(query) {
     const searchTerm = query.toLowerCase();
     const results = [];
@@ -240,9 +504,293 @@ ${generatedDoc}`;
   }
 }
 
+const SNIPPET_LENGTH = 150;
+class SearchEngine {
+  documents = [];
+  invertedIndex = /* @__PURE__ */ new Map();
+  documentLengths = [];
+  buildIndex(documents) {
+    this.documents = documents;
+    this.invertedIndex.clear();
+    this.documentLengths = [];
+    for (let docIndex = 0; docIndex < documents.length; docIndex++) {
+      const tokens = this.tokenize(documents[docIndex].content);
+      this.documentLengths.push(tokens.length);
+      const termFrequencies = /* @__PURE__ */ new Map();
+      for (let pos = 0; pos < tokens.length; pos++) {
+        const token = tokens[pos];
+        const entry = termFrequencies.get(token);
+        if (entry) {
+          entry.count++;
+          entry.positions.push(pos);
+        } else {
+          termFrequencies.set(token, { count: 1, positions: [pos] });
+        }
+      }
+      for (const [term, { count, positions }] of termFrequencies) {
+        let postings = this.invertedIndex.get(term);
+        if (!postings) {
+          postings = [];
+          this.invertedIndex.set(term, postings);
+        }
+        postings.push({ docIndex, frequency: count, positions });
+      }
+    }
+  }
+  search(query, maxResults = 20) {
+    if (this.documents.length === 0 || !query.trim()) {
+      return [];
+    }
+    const exactPhrases = this.extractExactPhrases(query);
+    const remainingQuery = query.replace(/"[^"]*"/g, "").trim();
+    const singleTerms = remainingQuery ? this.tokenize(remainingQuery) : [];
+    const scores = /* @__PURE__ */ new Map();
+    const matchPositions = /* @__PURE__ */ new Map();
+    for (const term of singleTerms) {
+      this.scoreTerm(term, scores, matchPositions);
+    }
+    for (const phrase of exactPhrases) {
+      this.scorePhrase(phrase, scores, matchPositions);
+    }
+    return Array.from(scores.entries()).filter(([, score]) => score > 0).sort(([, a], [, b]) => b - a).slice(0, maxResults).map(([docIndex, score]) => {
+      const doc = this.documents[docIndex];
+      const positions = matchPositions.get(docIndex) ?? [];
+      return {
+        id: doc.id,
+        type: doc.type,
+        name: doc.name,
+        score: Math.round(score * 1e4) / 1e4,
+        snippet: this.extractSnippet(doc.content, positions)
+      };
+    });
+  }
+  getIndexedTermCount() {
+    return this.invertedIndex.size;
+  }
+  getDocumentCount() {
+    return this.documents.length;
+  }
+  scoreTerm(term, scores, matchPositions) {
+    const postings = this.invertedIndex.get(term);
+    if (!postings) {
+      return;
+    }
+    const totalDocs = this.documents.length;
+    const df = postings.length;
+    const idf = Math.log(1 + totalDocs / df);
+    for (const posting of postings) {
+      const docLength = this.documentLengths[posting.docIndex];
+      const tf = docLength > 0 ? posting.frequency / docLength : 0;
+      const tfidf = tf * idf;
+      scores.set(posting.docIndex, (scores.get(posting.docIndex) ?? 0) + tfidf);
+      const existing = matchPositions.get(posting.docIndex) ?? [];
+      existing.push(posting.positions[0]);
+      matchPositions.set(posting.docIndex, existing);
+    }
+  }
+  scorePhrase(phrase, scores, matchPositions) {
+    const phraseTokens = this.tokenize(phrase);
+    if (phraseTokens.length === 0) {
+      return;
+    }
+    const phraseMatches = this.findPhraseMatches(phraseTokens);
+    const matchedDocs = new Set(phraseMatches.map((m) => m.docIndex));
+    if (matchedDocs.size === 0) {
+      return;
+    }
+    const totalDocs = this.documents.length;
+    const idf = Math.log(1 + totalDocs / matchedDocs.size);
+    for (const docIndex of matchedDocs) {
+      const docMatches = phraseMatches.filter((m) => m.docIndex === docIndex);
+      const docLength = this.documentLengths[docIndex];
+      const tf = docLength > 0 ? docMatches.length / docLength : 0;
+      const tfidf = tf * idf * phraseTokens.length;
+      scores.set(docIndex, (scores.get(docIndex) ?? 0) + tfidf);
+      const existing = matchPositions.get(docIndex) ?? [];
+      existing.push(docMatches[0].position);
+      matchPositions.set(docIndex, existing);
+    }
+  }
+  findPhraseMatches(phraseTokens) {
+    const firstTermPostings = this.invertedIndex.get(phraseTokens[0]);
+    if (!firstTermPostings) {
+      return [];
+    }
+    const matches = [];
+    for (const posting of firstTermPostings) {
+      for (const startPos of posting.positions) {
+        if (this.isPhraseAtPosition(phraseTokens, posting.docIndex, startPos)) {
+          matches.push({ docIndex: posting.docIndex, position: startPos });
+        }
+      }
+    }
+    return matches;
+  }
+  isPhraseAtPosition(phraseTokens, docIndex, startPos) {
+    for (let i = 1; i < phraseTokens.length; i++) {
+      const nextPostings = this.invertedIndex.get(phraseTokens[i]);
+      if (!nextPostings) {
+        return false;
+      }
+      const nextPosting = nextPostings.find((p) => p.docIndex === docIndex);
+      if (!nextPosting || !nextPosting.positions.includes(startPos + i)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  extractExactPhrases(query) {
+    const phrases = [];
+    const regex = /"([^"]+)"/g;
+    for (const match of query.matchAll(regex)) {
+      if (match[1].trim()) {
+        phrases.push(match[1].trim());
+      }
+    }
+    return phrases;
+  }
+  tokenize(text) {
+    return text.toLowerCase().replace(/[#*`|[\](){}!@$%^&+=~<>/\\,;:.?'"_-]+/g, " ").split(/\s+/).filter((token) => token.length > 1);
+  }
+  extractSnippet(content, tokenPositions) {
+    if (!content || tokenPositions.length === 0) {
+      return content.slice(0, SNIPPET_LENGTH).trim();
+    }
+    const tokens = this.tokenize(content);
+    if (tokens.length === 0) {
+      return content.slice(0, SNIPPET_LENGTH).trim();
+    }
+    const bestPosition = tokenPositions[0];
+    const targetToken = tokens[Math.min(bestPosition, tokens.length - 1)];
+    const contentLower = content.toLowerCase();
+    const charIndex = contentLower.indexOf(targetToken);
+    if (charIndex === -1) {
+      return content.slice(0, SNIPPET_LENGTH).trim();
+    }
+    const halfSnippet = Math.floor(SNIPPET_LENGTH / 2);
+    let start = Math.max(0, charIndex - halfSnippet);
+    let end = Math.min(content.length, start + SNIPPET_LENGTH);
+    if (end === content.length) {
+      start = Math.max(0, end - SNIPPET_LENGTH);
+    }
+    if (start > 0) {
+      const spaceIndex = content.indexOf(" ", start);
+      if (spaceIndex !== -1 && spaceIndex < start + 20) {
+        start = spaceIndex + 1;
+      }
+    }
+    if (end < content.length) {
+      const spaceIndex = content.lastIndexOf(" ", end);
+      if (spaceIndex !== -1 && spaceIndex > end - 20) {
+        end = spaceIndex;
+      }
+    }
+    let snippet = content.slice(start, end).trim();
+    if (start > 0) {
+      snippet = `...${snippet}`;
+    }
+    if (end < content.length) {
+      snippet = `${snippet}...`;
+    }
+    return snippet;
+  }
+}
+
+const NAME_BOOST = 3;
+const TAG_BOOST = 2;
+const CONTENT_BOOST = 1;
+const DEFAULT_MAX_RESULTS = 10;
+class UnifiedSearchService {
+  searchEngine = new SearchEngine();
+  documents = [];
+  initialize(documents) {
+    this.documents = documents;
+    this.searchEngine.buildIndex(
+      documents.map((doc) => ({
+        id: doc.name,
+        type: doc.type,
+        name: doc.name,
+        content: doc.content
+      }))
+    );
+  }
+  search(query, options = {}) {
+    const { category, maxResults = DEFAULT_MAX_RESULTS } = options;
+    if (!query.trim()) {
+      return [];
+    }
+    const normalizedQuery = query.toLowerCase().trim();
+    const queryTokens = this.searchEngine.tokenize(query);
+    let candidates = this.documents;
+    if (category) {
+      candidates = candidates.filter((doc) => doc.type === category);
+    }
+    const tfidfResults = this.searchEngine.search(query, candidates.length || this.documents.length);
+    const tfidfScoreMap = /* @__PURE__ */ new Map();
+    for (const result of tfidfResults) {
+      tfidfScoreMap.set(result.id, { score: result.score, snippet: result.snippet });
+    }
+    const scored = [];
+    for (const doc of candidates) {
+      const nameScore = this.scoreNameMatch(normalizedQuery, doc) * NAME_BOOST;
+      const tagScore = this.scoreTagMatch(normalizedQuery, queryTokens, doc) * TAG_BOOST;
+      const tfidfEntry = tfidfScoreMap.get(doc.name);
+      const contentScore = (tfidfEntry?.score ?? 0) * CONTENT_BOOST;
+      const totalScore = nameScore + tagScore + contentScore;
+      if (totalScore > 0) {
+        scored.push({
+          name: doc.name,
+          displayName: doc.metadata.displayName,
+          type: doc.type,
+          description: doc.metadata.description,
+          score: Math.round(totalScore * 1e4) / 1e4,
+          snippet: tfidfEntry?.snippet ?? doc.content.slice(0, 150).trim()
+        });
+      }
+    }
+    return scored.sort((a, b) => b.score - a.score).slice(0, maxResults);
+  }
+  scoreNameMatch(normalizedQuery, doc) {
+    const name = doc.name.toLowerCase();
+    const displayName = doc.metadata.displayName.toLowerCase();
+    if (name === normalizedQuery || displayName === normalizedQuery) {
+      return 1;
+    }
+    if (name.includes(normalizedQuery) || displayName.includes(normalizedQuery)) {
+      return 0.7;
+    }
+    if (normalizedQuery.includes(name)) {
+      return 0.5;
+    }
+    return 0;
+  }
+  scoreTagMatch(normalizedQuery, queryTokens, doc) {
+    const tags = doc.metadata.tags;
+    for (const tag of tags) {
+      if (tag === normalizedQuery) {
+        return 1;
+      }
+    }
+    if (queryTokens.length === 0) {
+      return 0;
+    }
+    let matchedTokens = 0;
+    for (const token of queryTokens) {
+      for (const tag of tags) {
+        if (tag.includes(token) || token.includes(tag)) {
+          matchedTokens++;
+          break;
+        }
+      }
+    }
+    return matchedTokens / queryTokens.length * 0.8;
+  }
+}
+
 class MazUiMcpServer {
   server;
   documentationService = new DocumentationService();
+  unifiedSearchService = new UnifiedSearchService();
   documentationIndex = [];
   constructor() {
     this.server = new Server(
@@ -399,6 +947,7 @@ class MazUiMcpServer {
       });
     }
     this.documentationIndex = index;
+    this.unifiedSearchService.initialize(this.documentationService.getAllDocuments());
   }
   /**
    * Generate additional search tags based on common patterns
@@ -486,59 +1035,205 @@ class MazUiMcpServer {
     return "general";
   }
   /**
-   * Fuzzy search implementation
-   */
-  fuzzySearch(query, targets) {
-    const normalizedQuery = query.toLowerCase().trim();
-    return targets.map((target) => ({
-      target,
-      score: this.calculateFuzzyScore(normalizedQuery, target.toLowerCase())
-    })).filter((item) => item.score > 0.3).sort((a, b) => b.score - a.score).map((item) => item.target);
-  }
-  /**
-   * Calculate fuzzy match score
+   * Resolve a document name using intelligent matching:
+   * PascalCase (MazBtn), kebab-case (maz-btn), short name (btn), aliases
    */
-  calculateFuzzyScore(query, target) {
-    if (target.includes(query))
-      return 1;
-    if (query.length === 0)
-      return 0;
-    let score = 0;
-    let queryIndex = 0;
-    for (let i = 0; i < target.length && queryIndex < query.length; i++) {
-      if (target[i] === query[queryIndex]) {
-        score += 1 / target.length;
-        queryIndex++;
+  resolveDocumentName(name, type) {
+    const normalizedName = name.toLowerCase().trim();
+    const candidates = type && type !== "auto" ? this.documentationIndex.filter((item) => item.type === type) : this.documentationIndex;
+    const exactMatch = candidates.find((item) => item.name.toLowerCase() === normalizedName);
+    if (exactMatch) {
+      return exactMatch;
+    }
+    if (/[A-Z]/.test(name)) {
+      const kebabName = name.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+      const kebabMatch = candidates.find((item) => item.name.toLowerCase() === kebabName);
+      if (kebabMatch) {
+        return kebabMatch;
       }
     }
-    return queryIndex === query.length ? score : 0;
-  }
-  /**
-   * Search in documentation index with fuzzy matching
-   */
-  searchInIndex(query) {
-    const normalizedQuery = query.toLowerCase().trim();
-    const results = [];
-    for (const item of this.documentationIndex) {
-      let maxScore = 0;
-      if (item.name.toLowerCase() === normalizedQuery) {
-        maxScore = 1;
-      } else if (item.displayName.toLowerCase().includes(normalizedQuery)) {
-        maxScore = Math.max(maxScore, 0.9);
-      } else {
-        const tagMatches = this.fuzzySearch(normalizedQuery, item.tags);
-        if (tagMatches.length > 0) {
-          maxScore = Math.max(maxScore, 0.8);
-        }
-        const nameScore = this.calculateFuzzyScore(normalizedQuery, item.name.toLowerCase());
-        const displayScore = this.calculateFuzzyScore(normalizedQuery, item.displayName.toLowerCase());
-        maxScore = Math.max(maxScore, nameScore * 0.7, displayScore * 0.6);
+    if (!normalizedName.startsWith("maz-")) {
+      const prefixedName = `maz-${normalizedName}`;
+      const prefixMatch = candidates.find((item) => item.name.toLowerCase() === prefixedName);
+      if (prefixMatch) {
+        return prefixMatch;
       }
-      if (maxScore > 0.3) {
-        results.push({ item, score: maxScore });
+    }
+    const displayMatch = candidates.find(
+      (item) => item.displayName.toLowerCase() === normalizedName
+    );
+    if (displayMatch) {
+      return displayMatch;
+    }
+    const tagMatch = candidates.find(
+      (item) => item.tags.some((tag) => tag.toLowerCase() === normalizedName)
+    );
+    if (tagMatch) {
+      return tagMatch;
+    }
+    const partialMatch = candidates.find(
+      (item) => item.name.toLowerCase().includes(normalizedName) || item.displayName.toLowerCase().includes(normalizedName)
+    );
+    if (partialMatch) {
+      return partialMatch;
+    }
+    return void 0;
+  }
+  handleSearch(args) {
+    const query = args?.query;
+    const category = args?.category;
+    const maxResults = args?.maxResults || 10;
+    if (!query) {
+      throw new Error("Search query is required. Provide a component name, description, prop name, or use case.");
+    }
+    const results = this.unifiedSearchService.search(query, {
+      category,
+      maxResults
+    });
+    if (results.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `No results found for "${query}".${category ? ` (filtered by category: ${category})` : ""}
+
+**Suggestions:**
+- Try broader or different terms (e.g. "button" instead of "btn")
+- Remove the category filter to search all documentation
+- Use \`list\` to browse all available documentation`
+        }]
+      };
+    }
+    let resultText = `# Search Results for "${query}" (${results.length} found)
+
+`;
+    for (const item of results) {
+      resultText += `## ${item.displayName}
+`;
+      resultText += `- **Name**: \`${item.name}\`
+`;
+      resultText += `- **Type**: ${item.type}
+`;
+      resultText += `- **Description**: ${item.description}
+`;
+      resultText += `- **Score**: ${item.score}
+`;
+      resultText += `- **Snippet**: ${item.snippet}
+`;
+      resultText += `- **Get full doc**: Use \`get_doc\` with name \`${item.name}\`
+
+`;
+    }
+    return {
+      content: [{
+        type: "text",
+        text: resultText
+      }]
+    };
+  }
+  handleList(args) {
+    const category = args?.category || "all";
+    const filteredIndex = category === "all" ? this.documentationIndex : this.documentationIndex.filter((item) => item.type === category);
+    const groupedDocs = filteredIndex.reduce((acc, item) => {
+      if (!acc[item.type])
+        acc[item.type] = [];
+      acc[item.type].push(item);
+      return acc;
+    }, {});
+    const typeLabels = {
+      component: "Components",
+      guide: "Guides",
+      composable: "Composables",
+      directive: "Directives",
+      plugin: "Plugins",
+      helper: "Helpers"
+    };
+    const typeOrder = ["component", "guide", "composable", "directive", "plugin", "helper"];
+    let result = `# Maz-UI Documentation (${filteredIndex.length} items)
+
+`;
+    for (const type of typeOrder) {
+      if (!groupedDocs[type])
+        continue;
+      const items = groupedDocs[type].sort((a, b) => a.name.localeCompare(b.name));
+      result += `## ${typeLabels[type]} (${items.length})
+
+`;
+      for (const item of items) {
+        result += `- **${item.displayName}** (\`${item.name}\`) \u2014 ${item.description}
+`;
       }
+      result += "\n";
     }
-    return results.sort((a, b) => b.score - a.score).slice(0, 10).map((r) => r.item);
+    return {
+      content: [{
+        type: "text",
+        text: result.trim()
+      }]
+    };
+  }
+  handleGetDoc(args) {
+    const docName = args?.name;
+    const docType = args?.type || "auto";
+    if (!docName) {
+      throw new Error("Name is required");
+    }
+    const found = this.resolveDocumentName(docName, docType);
+    if (!found) {
+      return this.handleDocNotFound(docName);
+    }
+    const content = this.getDocumentContent(found);
+    if (!content) {
+      return {
+        content: [{
+          type: "text",
+          text: `Found "${found.displayName}" but documentation content is not available. This might be a documentation file that needs to be created.`
+        }]
+      };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: content
+      }]
+    };
+  }
+  handleDocNotFound(docName) {
+    const searchResults = this.unifiedSearchService.search(docName, { maxResults: 3 });
+    if (searchResults.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `Documentation not found for "${docName}".
+
+**Available options:**
+- Use \`search\` to find similar items
+- Use \`list\` to see all available documentation`
+        }]
+      };
+    }
+    const suggestions = searchResults.map((item) => `- **${item.displayName}** (\`${item.name}\`) - ${item.description}`).join("\n");
+    return {
+      content: [{
+        type: "text",
+        text: `Exact match not found for "${docName}". Did you mean:
+
+${suggestions}
+
+**Use \`get_doc\` with the exact name from above.**`
+      }]
+    };
+  }
+  getDocumentContent(doc) {
+    const contentMethods = {
+      component: (name) => this.documentationService.getComponentDocumentation(name),
+      guide: (name) => this.documentationService.getGuideDocumentation(name),
+      composable: (name) => this.documentationService.getComposableDocumentation(name),
+      directive: (name) => this.documentationService.getDirectiveDocumentation(name),
+      plugin: (name) => this.documentationService.getPluginDocumentation(name),
+      helper: (name) => this.documentationService.getHelperDocumentation(name)
+    };
+    const getContent = contentMethods[doc.type];
+    return getContent ? getContent(doc.name) : "";
   }
   setupHandlers() {
     this.server.setRequestHandler(ListResourcesRequestSchema, () => {
@@ -587,8 +1282,8 @@ class MazUiMcpServer {
 
 ## Getting Started
 Use the MCP tools to explore components and features:
-- \`list_all_docs\` - See everything available
-- \`smart_search\` - Find specific features
+- \`list\` - See everything available
+- \`search\` - Find specific features
 - \`get_doc\` - Get detailed documentation`;
             }
             break;
@@ -631,38 +1326,23 @@ Use the MCP tools to explore components and features:
       return {
         tools: [
           {
-            name: "list_all_docs",
-            description: "Get a complete, categorized index of ALL available documentation in Maz-UI. This is the best starting point to understand what's available. Returns components, guides, composables, directives, plugins, and helpers with descriptions and search tags.",
+            name: "search",
+            description: 'Search across ALL Maz-UI documentation using a powerful unified search engine. Combines exact name matching, tag/alias matching, and full-text content search with TF-IDF scoring. Use this tool for any search query: component names (e.g. "MazBtn"), functional descriptions (e.g. "date picker"), prop names (e.g. "model-value"), use cases (e.g. "form validation"), or aliases (e.g. "modal" for dialog). Returns ranked results with contextual snippets.',
             inputSchema: {
               type: "object",
               properties: {
-                category: {
+                query: {
                   type: "string",
-                  enum: ["all", "components", "guides", "composables", "directives", "plugins", "helpers"],
-                  description: 'Filter by category (optional). Use "all" or omit to see everything.',
-                  default: "all"
+                  description: 'Search query \u2014 can be a component name, description, prop name, use case, or alias. Examples: "button", "MazDialog", "model-value", "phone number input", "lazy loading"'
                 },
-                includeDescriptions: {
-                  type: "boolean",
-                  description: "Include detailed descriptions for each item",
-                  default: true
-                }
-              }
-            }
-          },
-          {
-            name: "smart_search",
-            description: `Intelligent search across ALL Maz-UI documentation with fuzzy matching and suggestions. Searches names, descriptions, and tags. Perfect when you know roughly what you're looking for but not the exact name (e.g., "button", "dropdown", "form validation", "dark mode").`,
-            inputSchema: {
-              type: "object",
-              properties: {
-                query: {
+                category: {
                   type: "string",
-                  description: 'Search term - can be partial, fuzzy, or describe functionality. Examples: "button", "modal", "form", "tooltip", "validation", "date picker"'
+                  enum: ["component", "guide", "composable", "directive", "plugin", "helper"],
+                  description: "Optional filter to restrict results to a specific documentation category"
                 },
                 maxResults: {
                   type: "number",
-                  description: "Maximum number of results to return",
+                  description: "Maximum number of results to return (default: 10)",
                   default: 10,
                   minimum: 1,
                   maximum: 50
@@ -692,41 +1372,19 @@ Use the MCP tools to explore components and features:
             }
           },
           {
-            name: "get_installation_guide",
-            description: "Get comprehensive installation and setup instructions for Maz-UI, including npm installation, Vue.js integration, and initial configuration.",
-            inputSchema: {
-              type: "object",
-              properties: {}
-            }
-          },
-          {
-            name: "get_components_by_category",
-            description: "Get components organized by functional category (form, layout, navigation, overlay, data, feedback, display, animation). Helps discover related components and understand the library structure.",
+            name: "list",
+            description: "Browse all available Maz-UI documentation grouped by category. Returns a structured list with counters per category and for each item: name, displayName, description. Use this tool to discover what components, composables, directives, plugins, helpers, and guides are available. Examples: list all docs, list only components, list composables.",
             inputSchema: {
               type: "object",
               properties: {
                 category: {
                   type: "string",
-                  enum: ["all", "form", "layout", "navigation", "overlay", "data", "feedback", "display", "animation", "general"],
-                  description: "Component category to filter by",
+                  enum: ["all", "component", "guide", "composable", "directive", "plugin", "helper"],
+                  description: 'Filter by documentation category. Use "all" or omit to see everything.',
                   default: "all"
                 }
               }
             }
-          },
-          {
-            name: "suggest_similar",
-            description: "When you can't find exactly what you're looking for, this tool suggests similar or related documentation based on functionality, naming patterns, and common use cases.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                description: {
-                  type: "string",
-                  description: `Describe what you're trying to achieve or find. Example: "I need a way to show notifications", "looking for form validation", "need a date selector"`
-                }
-              },
-              required: ["description"]
-            }
           }
         ]
       };
@@ -735,398 +1393,25 @@ Use the MCP tools to explore components and features:
       const { name, arguments: args } = request.params;
       try {
         switch (name) {
-          case "list_all_docs": {
-            const category = args?.category || "all";
-            const includeDescriptions = args?.includeDescriptions ?? true;
-            let filteredIndex = this.documentationIndex;
-            if (category !== "all") {
-              filteredIndex = this.documentationIndex.filter(
-                (item) => category === "components" ? item.type === "component" : item.type === category
-              );
-            }
-            const groupedDocs = filteredIndex.reduce((acc, item) => {
-              if (!acc[item.type])
-                acc[item.type] = [];
-              acc[item.type].push(item);
-              return acc;
-            }, {});
-            let result = `# Maz-UI Documentation Index (${filteredIndex.length} items)
-
-`;
-            const typeOrder = ["component", "guide", "composable", "directive", "plugin", "helper"];
-            const typeLabels = {
-              component: "Vue Components",
-              guide: "Documentation Guides",
-              composable: "Vue 3 Composables",
-              directive: "Vue Directives",
-              plugin: "Vue Plugins",
-              helper: "Utility Helpers"
-            };
-            for (const type of typeOrder) {
-              if (!groupedDocs[type])
-                continue;
-              result += `## ${typeLabels[type]} (${groupedDocs[type].length})
-
-`;
-              for (const item of groupedDocs[type].sort((a, b) => a.name.localeCompare(b.name))) {
-                result += `### ${item.displayName}
-`;
-                result += `- **Name**: \`${item.name}\`
-`;
-                if (includeDescriptions) {
-                  result += `- **Description**: ${item.description}
-`;
-                  result += `- **Tags**: ${item.tags.slice(0, 5).join(", ")}
-`;
-                }
-                result += `- **Get docs**: Use \`get_doc\` with name \`${item.name}\`
-
-`;
-              }
-            }
-            result += `
----
-**\u{1F4A1} Tips:**
-- Use \`smart_search\` to find specific functionality
-- Use \`get_doc\` with any name from above
-- Use \`get_components_by_category\` to explore by function`;
-            return {
-              content: [{
-                type: "text",
-                text: result
-              }]
-            };
-          }
-          case "smart_search": {
-            const query = args?.query;
-            const maxResults = args?.maxResults || 10;
-            if (!query) {
-              throw new Error("Search query is required");
-            }
-            const results = this.searchInIndex(query).slice(0, maxResults);
-            if (results.length === 0) {
-              const suggestions = this.documentationIndex.map((item) => item.name).slice(0, 10).join(", ");
-              return {
-                content: [{
-                  type: "text",
-                  text: `No results found for "${query}".
-
-**Suggestions:**
-- Try broader terms like "button", "form", "modal"
-- Check available items: ${suggestions}
-- Use \`list_all_docs\` to see everything available
-- Use \`suggest_similar\` if you're looking for specific functionality`
-                }]
-              };
-            }
-            let resultText = `# Search Results for "${query}" (${results.length} found)
-
-`;
-            for (const item of results) {
-              resultText += `## ${item.displayName}
-`;
-              resultText += `- **Type**: ${item.type}
-`;
-              resultText += `- **Name**: \`${item.name}\`
-`;
-              resultText += `- **Description**: ${item.description}
-`;
-              resultText += `- **Use**: \`get_doc\` with name \`${item.name}\`
-
-`;
-            }
-            resultText += `
-**\u{1F4A1} Use \`get_doc\` with any name above to see full documentation.**`;
-            return {
-              content: [{
-                type: "text",
-                text: resultText
-              }]
-            };
-          }
-          case "get_doc": {
-            const name2 = args?.name;
-            const type = args?.type || "auto";
-            if (!name2) {
-              throw new Error("Name is required");
-            }
-            let found = this.documentationIndex.find(
-              (item) => item.name.toLowerCase() === name2.toLowerCase() || item.displayName.toLowerCase() === name2.toLowerCase() || item.tags.some((tag) => tag.toLowerCase() === name2.toLowerCase())
-            );
-            if (!found && type !== "auto") {
-              found = this.documentationIndex.find(
-                (item) => item.type === type && (item.name.toLowerCase().includes(name2.toLowerCase()) || item.displayName.toLowerCase().includes(name2.toLowerCase()))
-              );
-            }
-            if (!found) {
-              const fuzzyResults = this.searchInIndex(name2).slice(0, 5);
-              const allNames = this.documentationIndex.map((item) => item.name);
-              const fuzzyNameMatches = this.fuzzySearch(name2, allNames).slice(0, 3);
-              const combinedResults = /* @__PURE__ */ new Set([
-                ...fuzzyResults.map((item) => item.name),
-                ...fuzzyNameMatches
-              ]);
-              if (combinedResults.size === 0) {
-                return {
-                  content: [{
-                    type: "text",
-                    text: `Documentation not found for "${name2}".
-
-**Available options:**
-- Use \`smart_search\` to find similar items
-- Use \`list_all_docs\` to see all available documentation
-- Use \`suggest_similar\` to describe what you're looking for`
-                  }]
-                };
-              }
-              const suggestions = Array.from(combinedResults).slice(0, 5).map((itemName) => {
-                const item = this.documentationIndex.find((i) => i.name === itemName);
-                return item ? `- **${item.displayName}** (\`${item.name}\`) - ${item.description}` : `- \`${itemName}\``;
-              }).join("\n");
-              return {
-                content: [{
-                  type: "text",
-                  text: `Exact match not found for "${name2}". Did you mean:
-
-${suggestions}
-
-**\u{1F4A1} Use \`get_doc\` with the exact name from above.**`
-                }]
-              };
-            }
-            let content = "";
-            const docName = found.name;
-            switch (found.type) {
-              case "component":
-                content = this.documentationService.getComponentDocumentation(docName);
-                break;
-              case "guide":
-                content = this.documentationService.getGuideDocumentation(docName);
-                break;
-              case "composable":
-                content = this.documentationService.getComposableDocumentation(docName);
-                break;
-              case "directive":
-                content = this.documentationService.getDirectiveDocumentation(docName);
-                break;
-              case "plugin":
-                content = this.documentationService.getPluginDocumentation(docName);
-                break;
-              case "helper":
-                content = this.documentationService.getHelperDocumentation(docName);
-                break;
-            }
-            if (!content) {
-              return {
-                content: [{
-                  type: "text",
-                  text: `Found "${found.displayName}" but documentation content is not available. This might be a documentation file that needs to be created.`
-                }]
-              };
-            }
-            return {
-              content: [{
-                type: "text",
-                text: content
-              }]
-            };
-          }
-          case "get_installation_guide": {
-            const installationGuides = ["getting-started", "installation", "setup", "quick-start"];
-            let guide = "";
-            for (const guideName of installationGuides) {
-              guide = this.documentationService.getGuideDocumentation(guideName);
-              if (guide)
-                break;
-            }
-            if (!guide) {
-              guide = this.documentationService.getOverview();
-            }
-            if (!guide) {
-              guide = `# Maz-UI Installation
-
-## Quick Start
-
-\`\`\`bash
-npm install maz-ui
-# or
-yarn add maz-ui
-# or  
-pnpm add maz-ui
-\`\`\`
-
-## Vue.js Integration
-
-\`\`\`javascript
-import { createApp } from 'vue'
-import MazUI from 'maz-ui'
-import 'maz-ui/dist/style.css'
-
-const app = createApp(App)
-app.use(MazUI)
-app.mount('#app')
-\`\`\`
-
-**\u{1F4A1} Use \`smart_search\` with "setup" or "configuration" for more detailed guides.**`;
-            }
-            return {
-              content: [{
-                type: "text",
-                text: guide
-              }]
-            };
-          }
-          case "get_components_by_category": {
-            const category = args?.category || "all";
-            const componentsByCategory = this.documentationIndex.filter((item) => item.type === "component").reduce((acc, item) => {
-              const componentType = this.getComponentType(item.name);
-              if (!acc[componentType])
-                acc[componentType] = [];
-              acc[componentType].push(item);
-              return acc;
-            }, {});
-            let result = "";
-            if (category === "all") {
-              result = `# Components by Category
-
-`;
-              const categoryDescriptions = {
-                form: "Input elements and form controls",
-                layout: "Structure and positioning components",
-                navigation: "Navigation and wayfinding components",
-                overlay: "Modal dialogs and overlay components",
-                data: "Data visualization and table components",
-                feedback: "Loading states and progress indicators",
-                display: "Media display and visual components",
-                animation: "Animated and interactive elements",
-                general: "General purpose components"
-              };
-              for (const [cat, components] of Object.entries(componentsByCategory)) {
-                result += `## ${cat.charAt(0).toUpperCase() + cat.slice(1)} Components (${components.length})
-`;
-                result += `*${categoryDescriptions[cat]}*
-
-`;
-                for (const component of components.sort((a, b) => a.name.localeCompare(b.name))) {
-                  result += `- **${component.displayName}** (\`${component.name}\`) - ${component.description.split(" - ")[1]}
-`;
-                }
-                result += "\n";
-              }
-            } else {
-              const components = componentsByCategory[category] || [];
-              result = `# ${category.charAt(0).toUpperCase() + category.slice(1)} Components (${components.length})
-
-`;
-              for (const component of components.sort((a, b) => a.name.localeCompare(b.name))) {
-                result += `## ${component.displayName}
-`;
-                result += `- **Name**: \`${component.name}\`
-`;
-                result += `- **Description**: ${component.description}
-`;
-                result += `- **Get docs**: Use \`get_doc\` with name \`${component.name}\`
-
-`;
-              }
-            }
-            result += `
-**\u{1F4A1} Use \`get_doc\` with any component name to see full documentation.**`;
-            return {
-              content: [{
-                type: "text",
-                text: result
-              }]
-            };
-          }
-          case "suggest_similar": {
-            const description = args?.description;
-            if (!description) {
-              throw new Error("Description is required");
-            }
-            const keywords = description.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((word) => word.length > 2);
-            const suggestions = /* @__PURE__ */ new Map();
-            for (const item of this.documentationIndex) {
-              let score = 0;
-              const itemText = `${item.name} ${item.displayName} ${item.description} ${item.tags.join(" ")}`.toLowerCase();
-              for (const keyword of keywords) {
-                if (itemText.includes(keyword)) {
-                  score += 1;
-                }
-              }
-              for (const keyword of keywords) {
-                const fuzzyMatches = this.fuzzySearch(keyword, item.tags);
-                if (fuzzyMatches.length > 0) {
-                  score += 0.5 * fuzzyMatches.length;
-                }
-              }
-              if (score > 0) {
-                suggestions.set(`${item.type}:${item.name}`, score);
-              }
-            }
-            const fuzzyResults = this.searchInIndex(description);
-            const allSuggestions = /* @__PURE__ */ new Set([
-              ...Array.from(suggestions.entries()).sort(([, a], [, b]) => b - a).slice(0, 5).map(([key]) => key),
-              ...fuzzyResults.slice(0, 3).map((item) => `${item.type}:${item.name}`)
-            ]);
-            if (allSuggestions.size === 0) {
-              return {
-                content: [{
-                  type: "text",
-                  text: `No direct suggestions found for "${description}".
-
-**Try these approaches:**
-- Use \`list_all_docs\` to browse all available features
-- Use \`smart_search\` with simpler keywords
-- Use \`get_components_by_category\` to explore by function
-
-Common categories: form, layout, navigation, feedback, display, action`
-                }]
-              };
-            }
-            let result = `# Suggestions based on: "${description}"
-
-`;
-            for (const suggestionKey of Array.from(allSuggestions).slice(0, 8)) {
-              const [type, name2] = suggestionKey.split(":");
-              const item = this.documentationIndex.find((i) => i.type === type && i.name === name2);
-              if (item) {
-                result += `## ${item.displayName}
-`;
-                result += `- **Type**: ${item.type}
-`;
-                result += `- **Description**: ${item.description}
-`;
-                result += `- **Get docs**: Use \`get_doc\` with name \`${item.name}\`
-
-`;
-              }
-            }
-            result += `
-**\u{1F4A1} Use \`get_doc\` with any name above, or try \`smart_search\` with specific terms.**`;
-            return {
-              content: [{
-                type: "text",
-                text: result
-              }]
-            };
-          }
+          case "search":
+            return this.handleSearch(args);
+          case "list":
+            return this.handleList(args);
+          case "get_doc":
+            return this.handleGetDoc(args);
           default:
-            throw new Error(`Unknown tool: ${name}. Available tools: list_all_docs, smart_search, get_doc, get_installation_guide, get_components_by_category, suggest_similar`);
+            throw new Error(`Unknown tool: ${name}. Available tools: search, get_doc, list`);
         }
       } catch (error) {
         return {
           content: [{
             type: "text",
-            text: `\u274C **Error**: ${getErrorMessage(error)}
+            text: `Error: ${getErrorMessage(error)}
 
 **Available tools:**
-- \`list_all_docs\` - See all documentation
-- \`smart_search\` - Search by keyword
+- \`search\` - Search across all documentation
 - \`get_doc\` - Get specific documentation
-- \`get_installation_guide\` - Setup instructions
-- \`get_components_by_category\` - Browse by function
-- \`suggest_similar\` - Find related items`
+- \`list\` - Browse all available documentation`
           }],
           isError: true
         };