react-docs-mcp 1.0.0

package/dist/searchEngine.js

@@ -0,0 +1,261 @@
+/**
+ * searchEngine.ts
+ * Implement search functionality over documentation
+ */
+import { parseMarkdown } from './markdownParser.js';
+import { EmbeddingService } from './embeddingService.js';
+import CONFIG from './config.js';
+export class SearchEngine {
+    docsManager;
+    embeddingService;
+    documentIndex = new Map();
+    indexed = false;
+    embeddingsGenerated = false;
+    /**
+     * Initialize search engine
+     * @param docsManager - Instance of DocsManager
+     */
+    constructor(docsManager) {
+        this.docsManager = docsManager;
+        this.embeddingService = new EmbeddingService();
+    }
+    /**
+     * Index all documents for searching
+     * Should be called after repo update
+     */
+    async indexDocuments() {
+        console.log('Indexing documents...');
+        this.documentIndex.clear();
+        const allDocs = await this.docsManager.getAllDocs();
+        for (const docPath of allDocs) {
+            try {
+                const content = await this.docsManager.readDoc(docPath);
+                const parsedDoc = await parseMarkdown(content, docPath);
+                this.documentIndex.set(parsedDoc.path, parsedDoc);
+            }
+            catch (error) {
+                console.warn(`Failed to index document ${docPath}:`, error);
+            }
+        }
+        this.indexed = true;
+        console.log(`Indexed ${this.documentIndex.size} documents`);
+    }
+    /**
+     * Generate embeddings for all documents
+     * Called lazily when semantic search is first used
+     */
+    async generateEmbeddings() {
+        if (this.embeddingsGenerated)
+            return;
+        console.log('Generating embeddings for documents (first run may take 1-2 minutes)...');
+        try {
+            await this.embeddingService.initialize();
+            let count = 0;
+            for (const doc of this.documentIndex.values()) {
+                // Create embedding text from title + description + first 1000 chars
+                const embeddingText = `${doc.metadata.title}. ${doc.metadata.description || ''}. ${doc.plainText.slice(0, 1000)}`;
+                const embedding = await this.embeddingService.generateEmbedding(embeddingText);
+                doc.embedding = embedding;
+                count++;
+                if (count % 10 === 0) {
+                    console.log(`Generated embeddings for ${count}/${this.documentIndex.size} documents...`);
+                }
+            }
+            this.embeddingsGenerated = true;
+            console.log(`Embeddings generated for all ${this.documentIndex.size} documents`);
+        }
+        catch (error) {
+            console.error('Failed to generate embeddings:', error);
+            throw error;
+        }
+    }
+    /**
+     * Search documents
+     * @param query - Search query string
+     * @param options - Search options (section filter, limit, etc.)
+     * @returns Ranked search results
+     */
+    async search(query, options) {
+        // Ensure documents are indexed
+        if (!this.indexed) {
+            await this.indexDocuments();
+        }
+        // Handle empty query
+        if (!query.trim()) {
+            return [];
+        }
+        const useSemanticSearch = options?.useSemanticSearch ?? CONFIG.search.semanticSearchEnabled;
+        // Use semantic or hybrid search if enabled
+        if (useSemanticSearch) {
+            return await this.semanticSearch(query, options);
+        }
+        // Fall back to keyword search
+        return await this.keywordSearch(query, options);
+    }
+    /**
+     * Keyword-based search
+     */
+    async keywordSearch(query, options) {
+        const limit = Math.min(options?.limit || CONFIG.search.defaultLimit, CONFIG.search.maxLimit);
+        const minScore = options?.minScore ?? CONFIG.search.minScore;
+        const sectionFilter = options?.section?.toLowerCase();
+        // Normalize query
+        const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const results = [];
+        // Score each document
+        for (const doc of this.documentIndex.values()) {
+            // Apply section filter
+            if (sectionFilter && doc.section.toLowerCase() !== sectionFilter) {
+                continue;
+            }
+            const score = this.scoreDocument(doc, queryTerms);
+            if (score >= minScore) {
+                const snippet = this.generateSnippet(doc, queryTerms);
+                results.push({ doc, score, snippet });
+            }
+        }
+        // Sort by score descending
+        results.sort((a, b) => b.score - a.score);
+        // Return top results
+        return results.slice(0, limit);
+    }
+    /**
+     * Semantic search using embeddings (hybrid with keyword search)
+     */
+    async semanticSearch(query, options) {
+        // Ensure embeddings are generated
+        if (!this.embeddingsGenerated) {
+            await this.generateEmbeddings();
+        }
+        const limit = Math.min(options?.limit || CONFIG.search.defaultLimit, CONFIG.search.maxLimit);
+        const sectionFilter = options?.section?.toLowerCase();
+        // Generate query embedding
+        const queryEmbedding = await this.embeddingService.generateEmbedding(query);
+        // Get all docs with embeddings, filtered by section
+        const docs = Array.from(this.documentIndex.values()).filter(doc => {
+            if (sectionFilter && doc.section.toLowerCase() !== sectionFilter) {
+                return false;
+            }
+            return doc.embedding !== undefined;
+        });
+        // Calculate hybrid scores (keyword + semantic)
+        const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const results = [];
+        for (const doc of docs) {
+            // Keyword score (normalized to 0-1)
+            const keywordScore = this.scoreDocument(doc, queryTerms) / 100;
+            // Semantic similarity score (0-1)
+            const semanticScore = this.embeddingService.cosineSimilarity(queryEmbedding, doc.embedding);
+            // Hybrid score (weighted combination)
+            const hybridScore = CONFIG.search.hybridKeywordWeight * keywordScore +
+                CONFIG.search.hybridSemanticWeight * semanticScore;
+            if (semanticScore >= CONFIG.search.semanticMinSimilarity) {
+                const snippet = this.generateSnippet(doc, queryTerms);
+                results.push({ doc, score: hybridScore, snippet });
+            }
+        }
+        // Sort by hybrid score descending
+        results.sort((a, b) => b.score - a.score);
+        // Return top results
+        return results.slice(0, limit);
+    }
+    /**
+     * Score a document based on query terms
+     */
+    scoreDocument(doc, queryTerms) {
+        let score = 0;
+        const titleLower = doc.metadata.title.toLowerCase();
+        const plainTextLower = doc.plainText.toLowerCase();
+        const pathLower = doc.path.toLowerCase();
+        for (const term of queryTerms) {
+            // Title match (high weight)
+            if (titleLower.includes(term)) {
+                score += 10;
+            }
+            // Path match (medium weight)
+            if (pathLower.includes(term)) {
+                score += 5;
+            }
+            // Count occurrences in plain text
+            const regex = new RegExp(term, 'gi');
+            const matches = plainTextLower.match(regex);
+            if (matches) {
+                score += matches.length * 0.5;
+            }
+            // Description match (medium weight)
+            if (doc.metadata.description?.toLowerCase().includes(term)) {
+                score += 3;
+            }
+        }
+        return score;
+    }
+    /**
+     * Generate context snippet showing matched text
+     */
+    generateSnippet(doc, queryTerms) {
+        const plainText = doc.plainText;
+        // Find first occurrence of any query term
+        let firstMatchIndex = -1;
+        let matchedTerm = '';
+        for (const term of queryTerms) {
+            const index = plainText.toLowerCase().indexOf(term);
+            if (index !== -1 && (firstMatchIndex === -1 || index < firstMatchIndex)) {
+                firstMatchIndex = index;
+                matchedTerm = term;
+            }
+        }
+        if (firstMatchIndex === -1) {
+            // No match in content, use description or first 150 chars
+            return doc.metadata.description || plainText.slice(0, 150) + '...';
+        }
+        // Extract context around match (±75 chars)
+        const contextRadius = 75;
+        const start = Math.max(0, firstMatchIndex - contextRadius);
+        const end = Math.min(plainText.length, firstMatchIndex + matchedTerm.length + contextRadius);
+        let snippet = plainText.slice(start, end);
+        // Add ellipsis if truncated
+        if (start > 0)
+            snippet = '...' + snippet;
+        if (end < plainText.length)
+            snippet = snippet + '...';
+        return snippet.trim();
+    }
+    /**
+     * Get document by exact path
+     * @param path - Document path relative to content root
+     * @returns Parsed document or null if not found
+     */
+    async getDocByPath(path) {
+        // Ensure documents are indexed
+        if (!this.indexed) {
+            await this.indexDocuments();
+        }
+        // Normalize path (remove .md if present)
+        const normalizedPath = path.replace(/\.md$/, '');
+        return this.documentIndex.get(normalizedPath) || null;
+    }
+    /**
+     * List all available sections
+     */
+    getSections() {
+        return [...CONFIG.sections];
+    }
+    /**
+     * Get all documents in a section
+     */
+    async getDocsBySection(section) {
+        // Ensure documents are indexed
+        if (!this.indexed) {
+            await this.indexDocuments();
+        }
+        const sectionLower = section.toLowerCase();
+        const docs = [];
+        for (const doc of this.documentIndex.values()) {
+            if (doc.section.toLowerCase() === sectionLower) {
+                docs.push(doc);
+            }
+        }
+        return docs;
+    }
+}
+//# sourceMappingURL=searchEngine.js.map

package/dist/searchEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchEngine.js","sourceRoot":"","sources":["../src/searchEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC,MAAM,OAAO,YAAY;IACf,WAAW,CAAc;IACzB,gBAAgB,CAAmB;IACnC,aAAa,GAA2B,IAAI,GAAG,EAAE,CAAC;IAClD,OAAO,GAAY,KAAK,CAAC;IACzB,mBAAmB,GAAY,KAAK,CAAC;IAE7C;;;OAGG;IACH,YAAY,WAAwB;QAClC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,gBAAgB,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,cAAc;QAClB,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACrC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAE3B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;QAEpD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBACxD,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,4BAA4B,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,aAAa,CAAC,IAAI,YAAY,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,kBAAkB;QACtB,IAAI,IAAI,CAAC,mBAAmB;YAAE,OAAO;QAErC,OAAO,CAAC,GAAG,CAAC,yEAAyE,CAAC,CAAC;QAEvF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,EAAE,CAAC;YAEzC,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC9C,oEAAoE;gBACpE,MAAM,aAAa,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,GAAG,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,KAAK,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;gBAClH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;gBAC/E,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;gBAC1B,KAAK,EAAE,CAAC;gBAER,IAAI,KAAK,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;oBACrB,OAAO,CAAC,GAAG,CAAC,4BAA4B,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,eAAe,CAAC,CAAC;gBAC3F,CAAC;YACH,CAAC;YAED,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,gCAAgC,IAAI,CAAC,aAAa,CAAC,IAAI,YAAY,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC,CAAC;YACvD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAAuB;QAEvB,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC9B,CAAC;QAED,qBAAqB;QACrB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAClB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,iBAAiB,GAAG,OAAO,EAAE,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAE5F,2CAA2C;QAC3C,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnD,CAAC;QAED,8BAA8B;QAC9B,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,aAAa,CACzB,KAAa,EACb,OAAuB;QAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,OAAO,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,EAC5C,MAAM,CAAC,MAAM,CAAC,QAAQ,CACvB,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC7D,MAAM,aAAa,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;QAEtD,kBAAkB;QAClB,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEpE,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,sBAAsB;QACtB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YAC9C,uBAAuB;YACvB,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,aAAa,EAAE,CAAC;gBACjE,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAElD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,2BAA2B;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAE1C,qBAAqB;QACrB,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc,CAC1B,KAAa,EACb,OAAuB;QAEvB,kCAAkC;QAClC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAClC,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,OAAO,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,EAC5C,MAAM,CAAC,MAAM,CAAC,QAAQ,CACvB,CAAC;QACF,MAAM,aAAa,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;QAEtD,2BAA2B;QAC3B,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAE5E,oDAAoD;QACpD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;YAChE,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,aAAa,EAAE,CAAC;gBACjE,OAAO,KAAK,CAAC;YACf,CAAC;YACD,OAAO,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC;QACrC,CAAC,CAAC,CAAC;QAEH,+CAA+C;QAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpE,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,oCAAoC;YACpC,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC;YAE/D,kCAAkC;YAClC,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAC1D,cAAc,EACd,GAAG,CAAC,SAAU,CACf,CAAC;YAEF,sCAAsC;YACtC,MAAM,WAAW,GACf,MAAM,CAAC,MAAM,CAAC,mBAAmB,GAAG,YAAY;gBAChD,MAAM,CAAC,MAAM,CAAC,oBAAoB,GAAG,aAAa,CAAC;YAErD,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;gBACzD,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAE1C,qBAAqB;QACrB,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,GAAc,EAAE,UAAoB;QACxD,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACpD,MAAM,cAAc,GAAG,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QACnD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAEzC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,4BAA4B;YAC5B,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,KAAK,IAAI,EAAE,CAAC;YACd,CAAC;YAED,6BAA6B;YAC7B,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,KAAK,IAAI,CAAC,CAAC;YACb,CAAC;YAED,kCAAkC;YAClC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC;YAChC,CAAC;YAED,oCAAoC;YACpC,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3D,KAAK,IAAI,CAAC,CAAC;YACb,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,GAAc,EAAE,UAAoB;QAC1D,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAEhC,0CAA0C;QAC1C,IAAI,eAAe,GAAG,CAAC,CAAC,CAAC;QACzB,IAAI,WAAW,GAAG,EAAE,CAAC;QAErB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACpD,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,eAAe,CAAC,EAAE,CAAC;gBACxE,eAAe,GAAG,KAAK,CAAC;gBACxB,WAAW,GAAG,IAAI,CAAC;YACrB,CAAC;QACH,CAAC;QAED,IAAI,eAAe,KAAK,CAAC,CAAC,EAAE,CAAC;YAC3B,0DAA0D;YAC1D,OAAO,GAAG,CAAC,QAAQ,CAAC,WAAW,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;QACrE,CAAC;QAED,2CAA2C;QAC3C,MAAM,aAAa,GAAG,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,WAAW,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;QAE7F,IAAI,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAE1C,4BAA4B;QAC5B,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;QACzC,IAAI,GAAG,GAAG,SAAS,CAAC,MAAM;YAAE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;QAEtD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC9B,CAAC;QAED,yCAAyC;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAEjD,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,OAAe;QACpC,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAgB,EAAE,CAAC;QAE7B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YAC9C,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,YAAY,EAAE,CAAC;gBAC/C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/summarizer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * summarizer.ts
+ * Extract concise summaries from markdown content
+ */
+/**
+ * Extract a concise summary from markdown content
+ * @param content - Full markdown content
+ * @param maxLength - Maximum summary length in characters
+ * @returns Concise summary
+ */
+export declare function summarizeContent(content: string, maxLength?: number): string;
+/**
+ * Extract key sections from markdown (headings + first line of each section)
+ * @param content - Full markdown content
+ * @returns Structured overview
+ */
+export declare function extractStructure(content: string): string;
+//# sourceMappingURL=summarizer.d.ts.map

package/dist/summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.d.ts","sourceRoot":"","sources":["../src/summarizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM,CA0ClF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA2BxD"}

package/dist/summarizer.js

@@ -0,0 +1,76 @@
+/**
+ * summarizer.ts
+ * Extract concise summaries from markdown content
+ */
+/**
+ * Extract a concise summary from markdown content
+ * @param content - Full markdown content
+ * @param maxLength - Maximum summary length in characters
+ * @returns Concise summary
+ */
+export function summarizeContent(content, maxLength = 1500) {
+    // Remove code blocks (can be very long)
+    let summary = content.replace(/```[\s\S]*?```/g, '[code example]');
+    // Remove frontmatter if present
+    summary = summary.replace(/^---[\s\S]*?---\n/, '');
+    // Extract first few meaningful paragraphs
+    const paragraphs = summary
+        .split(/\n\n+/)
+        .map(p => p.trim())
+        .filter(p => p.length > 20 && !p.startsWith('#'));
+    // Take first few paragraphs up to maxLength
+    let result = '';
+    let headings = [];
+    // Extract headings for structure
+    const headingMatches = content.match(/^#{1,3}\s+(.+)$/gm);
+    if (headingMatches) {
+        headings = headingMatches.slice(0, 5).map(h => h.replace(/^#+\s*/, '- '));
+    }
+    // Build summary
+    for (const para of paragraphs.slice(0, 3)) {
+        if (result.length + para.length > maxLength) {
+            break;
+        }
+        result += para + '\n\n';
+    }
+    // Add structure if we have headings
+    if (headings.length > 0 && result.length < maxLength * 0.7) {
+        result += '\n**Content structure:**\n' + headings.join('\n');
+    }
+    // Truncate if still too long
+    if (result.length > maxLength) {
+        result = result.slice(0, maxLength) + '...';
+    }
+    return result.trim();
+}
+/**
+ * Extract key sections from markdown (headings + first line of each section)
+ * @param content - Full markdown content
+ * @returns Structured overview
+ */
+export function extractStructure(content) {
+    const lines = content.split('\n');
+    const structure = [];
+    let currentHeading = '';
+    let capturedFirstLine = false;
+    for (const line of lines) {
+        // Match headings
+        const headingMatch = line.match(/^(#{1,3})\s+(.+)$/);
+        if (headingMatch) {
+            currentHeading = headingMatch[2];
+            structure.push(`\n**${currentHeading}**`);
+            capturedFirstLine = false;
+            continue;
+        }
+        // Capture first meaningful line after heading
+        if (currentHeading && !capturedFirstLine && line.trim().length > 20) {
+            const cleaned = line.replace(/[*_`]/g, '').trim();
+            if (!cleaned.startsWith('<') && !cleaned.startsWith('[')) {
+                structure.push(cleaned.slice(0, 100));
+                capturedFirstLine = true;
+            }
+        }
+    }
+    return structure.join('\n');
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../src/summarizer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * types.ts
+ * Define all TypeScript interfaces and types used across the project
+ */
+/**
+ * Document metadata parsed from frontmatter
+ */
+export interface DocMetadata {
+    title: string;
+    description?: string;
+    date?: string;
+    author?: string;
+    tags?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Parsed document with content and metadata
+ */
+export interface ParsedDoc {
+    path: string;
+    section: string;
+    metadata: DocMetadata;
+    content: string;
+    plainText: string;
+    embedding?: number[];
+}
+/**
+ * Search result with relevance
+ */
+export interface SearchResult {
+    doc: ParsedDoc;
+    score: number;
+    snippet: string;
+}
+/**
+ * Search options
+ */
+export interface SearchOptions {
+    section?: string;
+    limit?: number;
+    minScore?: number;
+    useSemanticSearch?: boolean;
+}
+/**
+ * Git repository status
+ */
+export interface RepoStatus {
+    isCloned: boolean;
+    lastUpdated?: Date;
+    currentCommit?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * types.ts
+ * Define all TypeScript interfaces and types used across the project
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "react-docs-mcp",
+  "version": "1.0.0",
+  "description": "MCP server providing AI agents with semantic search over React documentation",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "react-docs-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node dist/index.js --version || echo 'Run: npx react-docs-mcp'"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "react",
+    "react-docs",
+    "documentation",
+    "ai",
+    "claude",
+    "cursor",
+    "semantic-search",
+    "embeddings",
+    "vector-search"
+  ],
+  "author": "Alex",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/react-docs-mcp.git"
+  },
+  "homepage": "https://github.com/yourusername/react-docs-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/yourusername/react-docs-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@xenova/transformers": "^2.17.2",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "remark": "^15.0.1",
+    "simple-git": "^3.28.0",
+    "strip-markdown": "^6.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}