mcp-docs-scraper 0.1.0

package/dist/tools/index-docs.js

@@ -0,0 +1,371 @@
+/**
+ * index_docs tool - Fetches and caches documentation from GitHub repositories or websites.
+ */
+import { cacheManager } from "../services/cache-manager.js";
+import { fetchRepoTree, fetchFileContent, } from "../services/github-fetcher.js";
+import { SearchIndex, createIndexableDocument, } from "../services/search-index.js";
+import { crawlWebsite } from "../services/web-scraper.js";
+import { cleanHtml } from "../services/content-cleaner.js";
+import { extractDomain, normalizeUrl } from "../utils/url.js";
+import { detectGitHubRepo } from "../services/github-detector.js";
+import { InvalidUrlError, NoContentError, ScrapingBlockedError, ValidationError, } from "../types/errors.js";
+/**
+ * Parses a GitHub URL to extract owner and repo.
+ * Supports formats:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo/tree/branch/path
+ * - github.com/owner/repo
+ */
+export function parseGitHubUrl(url) {
+    // Normalize URL
+    let normalized = url.trim();
+    if (!normalized.startsWith("http")) {
+        normalized = "https://" + normalized;
+    }
+    try {
+        const parsed = new URL(normalized);
+        // Must be github.com
+        if (!parsed.hostname.endsWith("github.com")) {
+            return null;
+        }
+        // Parse path: /owner/repo[/tree/branch/path]
+        const pathParts = parsed.pathname.split("/").filter(Boolean);
+        if (pathParts.length < 2) {
+            return null;
+        }
+        const owner = pathParts[0];
+        const repo = pathParts[1].replace(/\.git$/, ""); // Remove .git suffix if present
+        let branch;
+        let path;
+        // Check for /tree/branch/path or /blob/branch/path
+        if (pathParts.length > 2 &&
+            (pathParts[2] === "tree" || pathParts[2] === "blob")) {
+            branch = pathParts[3];
+            if (pathParts.length > 4) {
+                path = pathParts.slice(4).join("/");
+            }
+        }
+        return { owner, repo, branch, path };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generates a cache ID from owner and repo.
+ */
+function generateCacheId(owner, repo) {
+    return `${owner}_${repo}`;
+}
+/**
+ * Collects all file paths from a tree structure.
+ */
+function collectFilePaths(nodes) {
+    const paths = [];
+    function walk(nodeList) {
+        for (const node of nodeList) {
+            if (node.type === "file") {
+                paths.push(node.path);
+            }
+            else if (node.children) {
+                walk(node.children);
+            }
+        }
+    }
+    walk(nodes);
+    return paths;
+}
+/**
+ * Indexes documentation from a GitHub repository.
+ */
+async function indexFromGitHub(owner, repo, options = {}) {
+    const cacheId = generateCacheId(owner, repo);
+    const repoString = `${owner}/${repo}`;
+    // Check if already cached (unless force refresh)
+    if (!options.forceRefresh) {
+        const existing = await cacheManager.getMeta("github", cacheId);
+        if (existing && !cacheManager.isExpired(existing)) {
+            // Return cached data
+            return {
+                id: existing.id,
+                source: "github",
+                repo: existing.repo,
+                tree: existing.tree,
+                stats: {
+                    pages: existing.page_count,
+                    total_size_bytes: existing.total_size_bytes,
+                    indexed_at: existing.indexed_at,
+                },
+            };
+        }
+    }
+    // Initialize cache
+    await cacheManager.initialize();
+    // Fetch the tree structure
+    const treeResult = await fetchRepoTree(repoString, {
+        branch: options.branch,
+        path: options.path,
+        extensions: [".md", ".mdx", ".markdown"],
+        maxDepth: 10,
+    });
+    // Collect all file paths to download
+    const filePaths = collectFilePaths(treeResult.tree);
+    // Download all file contents and build search index
+    let totalSize = 0;
+    let downloadedCount = 0;
+    const searchIndex = new SearchIndex();
+    for (const filePath of filePaths) {
+        try {
+            const content = await fetchFileContent(repoString, treeResult.branch, filePath);
+            if (content) {
+                // Store content in cache
+                await cacheManager.storeContent("github", cacheId, filePath, content.content);
+                totalSize += content.size;
+                downloadedCount++;
+                // Add to search index
+                const indexDoc = createIndexableDocument(filePath, content.content);
+                searchIndex.addDocument(indexDoc);
+            }
+        }
+        catch (error) {
+            // Log but continue - some files might fail
+            console.error(`Failed to download ${filePath}:`, error);
+        }
+    }
+    // Store search index
+    await cacheManager.storeSearchIndex("github", cacheId, searchIndex.toJSON());
+    // Store metadata
+    const indexedAt = new Date().toISOString();
+    await cacheManager.storeMeta({
+        id: cacheId,
+        source: "github",
+        repo: repoString,
+        branch: treeResult.branch,
+        indexed_at: indexedAt,
+        page_count: downloadedCount,
+        total_size_bytes: totalSize,
+        tree: treeResult.tree,
+    });
+    return {
+        id: cacheId,
+        source: "github",
+        repo: repoString,
+        tree: treeResult.tree,
+        stats: {
+            pages: downloadedCount,
+            total_size_bytes: totalSize,
+            indexed_at: indexedAt,
+        },
+    };
+}
+/**
+ * Generates a cache ID from a URL for scraped content.
+ */
+function generateScrapedCacheId(url) {
+    const domain = extractDomain(url);
+    if (!domain) {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    // Clean up domain for use as ID
+    return domain
+        .replace(/^www\./, "")
+        .replace(/\./g, "_")
+        .replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+ * Indexes documentation from a website via scraping.
+ */
+async function indexFromScraping(url, options = {}) {
+    const normalizedUrl = normalizeUrl(url);
+    const cacheId = generateScrapedCacheId(normalizedUrl);
+    // Check if already cached (unless force refresh)
+    if (!options.forceRefresh) {
+        const existing = await cacheManager.getMeta("scraped", cacheId);
+        if (existing && !cacheManager.isExpired(existing)) {
+            // Return cached data
+            return {
+                id: existing.id,
+                source: "scraped",
+                base_url: existing.base_url,
+                tree: existing.tree,
+                stats: {
+                    pages: existing.page_count,
+                    total_size_bytes: existing.total_size_bytes,
+                    indexed_at: existing.indexed_at,
+                },
+            };
+        }
+    }
+    // Initialize cache
+    await cacheManager.initialize();
+    // Crawl the website
+    console.error(`[index_docs] Starting crawl of ${normalizedUrl}...`);
+    const crawlResult = await crawlWebsite(normalizedUrl, {
+        maxDepth: options.depth ?? 2,
+        maxPages: 100,
+        requestDelay: 500,
+    });
+    if (crawlResult.pages.length === 0) {
+        // Check if crawling was blocked
+        if (crawlResult.skipped.some((s) => s.reason.includes("robots.txt") || s.reason.includes("403"))) {
+            throw new ScrapingBlockedError(normalizedUrl, "Site blocked automated access");
+        }
+        throw new NoContentError(normalizedUrl);
+    }
+    console.error(`[index_docs] Crawled ${crawlResult.pages.length} pages, converting to markdown...`);
+    // Process pages: clean HTML to markdown and store
+    let totalSize = 0;
+    let processedCount = 0;
+    const searchIndex = new SearchIndex();
+    const treeNodes = [];
+    for (const page of crawlResult.pages) {
+        try {
+            // Clean HTML to markdown
+            const cleaned = cleanHtml(page.html, {
+                baseUrl: page.url,
+                extractMainContent: true,
+            });
+            // Skip pages with very little content
+            if (cleaned.markdown.trim().length < 100) {
+                console.error(`[index_docs] Skipping ${page.filename} - too little content`);
+                continue;
+            }
+            // Add title as H1 if not present and we have a title
+            let markdown = cleaned.markdown;
+            if (cleaned.title && !markdown.startsWith("# ")) {
+                markdown = `# ${cleaned.title}\n\n${markdown}`;
+            }
+            // Store content in cache
+            await cacheManager.storeContent("scraped", cacheId, page.filename, markdown);
+            const size = Buffer.byteLength(markdown, "utf8");
+            totalSize += size;
+            processedCount++;
+            // Add to tree
+            treeNodes.push({
+                name: page.filename,
+                path: page.filename,
+                type: "file",
+                size_bytes: size,
+            });
+            // Add to search index
+            const indexDoc = createIndexableDocument(page.filename, markdown);
+            searchIndex.addDocument(indexDoc);
+        }
+        catch (error) {
+            console.error(`[index_docs] Failed to process ${page.url}:`, error);
+        }
+    }
+    if (processedCount === 0) {
+        throw new NoContentError(normalizedUrl);
+    }
+    // Sort tree nodes
+    treeNodes.sort((a, b) => a.name.localeCompare(b.name));
+    // Store search index
+    await cacheManager.storeSearchIndex("scraped", cacheId, searchIndex.toJSON());
+    // Store metadata
+    const indexedAt = new Date().toISOString();
+    await cacheManager.storeMeta({
+        id: cacheId,
+        source: "scraped",
+        base_url: normalizedUrl,
+        indexed_at: indexedAt,
+        page_count: processedCount,
+        total_size_bytes: totalSize,
+        tree: treeNodes,
+    });
+    console.error(`[index_docs] Indexed ${processedCount} pages (${(totalSize / 1024).toFixed(1)} KB)`);
+    return {
+        id: cacheId,
+        source: "scraped",
+        base_url: normalizedUrl,
+        tree: treeNodes,
+        stats: {
+            pages: processedCount,
+            total_size_bytes: totalSize,
+            indexed_at: indexedAt,
+        },
+    };
+}
+/**
+ * Main index_docs implementation.
+ * Supports GitHub URLs and website scraping.
+ */
+export async function indexDocs(input) {
+    const { url, type = "auto", depth, force_refresh = false, include_patterns, exclude_patterns, } = input;
+    // Validate required parameters
+    if (!url) {
+        throw new ValidationError("Missing required parameter: url", "url");
+    }
+    // Parse URL to determine source
+    const githubInfo = parseGitHubUrl(url);
+    // Handle explicit type requests
+    if (type === "github") {
+        if (!githubInfo) {
+            throw new InvalidUrlError(url, "Expected GitHub URL format: https://github.com/owner/repo");
+        }
+        return indexFromGitHub(githubInfo.owner, githubInfo.repo, {
+            branch: githubInfo.branch,
+            path: githubInfo.path,
+            forceRefresh: force_refresh,
+        });
+    }
+    if (type === "scrape") {
+        return indexFromScraping(url, {
+            depth,
+            forceRefresh: force_refresh,
+            includePatterns: include_patterns,
+            excludePatterns: exclude_patterns,
+        });
+    }
+    // Auto mode: prefer GitHub if detected, otherwise scrape
+    if (type === "auto") {
+        // If URL is already a GitHub URL, use it directly
+        if (githubInfo) {
+            console.error(`[index_docs] Auto-detected: direct GitHub URL`);
+            const result = await indexFromGitHub(githubInfo.owner, githubInfo.repo, {
+                branch: githubInfo.branch,
+                path: githubInfo.path,
+                forceRefresh: force_refresh,
+            });
+            return { ...result, detection_method: "direct_github_url" };
+        }
+        // Try to detect GitHub repo from the docs site
+        console.error(`[index_docs] Auto-detecting GitHub repo from ${url}...`);
+        const detection = await detectGitHubRepo(url);
+        if (detection.found && detection.repo && detection.confidence !== "low") {
+            console.error(`[index_docs] Found GitHub repo: ${detection.repo} (${detection.confidence} confidence via ${detection.detection_method})`);
+            // Parse the detected repo
+            const [owner, repo] = detection.repo.split("/");
+            if (owner && repo) {
+                try {
+                    const result = await indexFromGitHub(owner, repo, {
+                        path: detection.docs_path,
+                        forceRefresh: force_refresh,
+                    });
+                    return {
+                        ...result,
+                        detection_method: `auto_github_${detection.detection_method}`,
+                    };
+                }
+                catch (error) {
+                    // GitHub fetch failed, fall back to scraping
+                    console.error(`[index_docs] GitHub fetch failed, falling back to scraping:`, error instanceof Error ? error.message : error);
+                }
+            }
+        }
+        else {
+            console.error(`[index_docs] No GitHub repo detected (${detection.detection_method}), using scraping`);
+        }
+        // Fall back to scraping
+        const result = await indexFromScraping(url, {
+            depth,
+            forceRefresh: force_refresh,
+            includePatterns: include_patterns,
+            excludePatterns: exclude_patterns,
+        });
+        return { ...result, detection_method: "scraping_fallback" };
+    }
+    // Should not reach here
+    throw new Error(`Invalid type: "${type}". Expected "github", "scrape", or "auto".`);
+}
+//# sourceMappingURL=index-docs.js.map

package/dist/tools/index-docs.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tool registry - exports all tool implementations.
+ */
+export { listCachedDocs, type ListCachedDocsOutput } from "./list-cached.js";
+export { clearCache, type ClearCacheInput, type ClearCacheOutput, } from "./clear-cache.js";
+export { indexDocs, parseGitHubUrl, type IndexDocsInput, type IndexDocsOutput, } from "./index-docs.js";
+export { getDocsTree, type GetDocsTreeInput, type GetDocsTreeOutput, } from "./get-tree.js";
+export { getDocsContent, type GetDocsContentInput, type GetDocsContentOutput, type FileContent, } from "./get-content.js";
+export { searchDocs, type SearchDocsInput, type SearchDocsOutput, } from "./search-docs.js";
+export { detectGitHub, type DetectGitHubInput, type DetectGitHubOutput, } from "./detect-github.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * Tool registry - exports all tool implementations.
+ */
+export { listCachedDocs } from "./list-cached.js";
+export { clearCache, } from "./clear-cache.js";
+export { indexDocs, parseGitHubUrl, } from "./index-docs.js";
+export { getDocsTree, } from "./get-tree.js";
+export { getDocsContent, } from "./get-content.js";
+export { searchDocs, } from "./search-docs.js";
+export { detectGitHub, } from "./detect-github.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAA6B,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,UAAU,GAGX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,cAAc,GAGf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,GAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,GAIf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,UAAU,GAGX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,YAAY,GAGb,MAAM,oBAAoB,CAAC"}

package/dist/tools/list-cached.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Output type for list_cached_docs tool.
+ */
+export interface ListCachedDocsOutput {
+    docs: Array<{
+        id: string;
+        source: "github" | "scraped";
+        repo?: string;
+        base_url?: string;
+        indexed_at: string;
+        page_count: number;
+        total_size_bytes: number;
+    }>;
+}
+/**
+ * Lists all documentation sets in the local cache.
+ */
+export declare function listCachedDocs(): Promise<ListCachedDocsOutput>;
+//# sourceMappingURL=list-cached.d.ts.map

package/dist/tools/list-cached.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-cached.d.ts","sourceRoot":"","sources":["../../src/tools/list-cached.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,KAAK,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAepE"}

package/dist/tools/list-cached.js

@@ -0,0 +1,20 @@
+import { cacheManager } from "../services/cache-manager.js";
+/**
+ * Lists all documentation sets in the local cache.
+ */
+export async function listCachedDocs() {
+    await cacheManager.initialize();
+    const entries = await cacheManager.listEntries();
+    return {
+        docs: entries.map((entry) => ({
+            id: entry.id,
+            source: entry.source,
+            repo: entry.repo,
+            base_url: entry.base_url,
+            indexed_at: entry.indexed_at,
+            page_count: entry.page_count,
+            total_size_bytes: entry.total_size_bytes,
+        })),
+    };
+}
+//# sourceMappingURL=list-cached.js.map

package/dist/tools/list-cached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-cached.js","sourceRoot":"","sources":["../../src/tools/list-cached.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAiB5D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,YAAY,CAAC,UAAU,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,CAAC;IAEjD,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5B,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;SACzC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/tools/search-docs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * search_docs tool - Full-text search within cached documentation.
+ */
+import { type SearchResult } from "../services/search-index.js";
+/**
+ * Input for the search_docs tool.
+ */
+export interface SearchDocsInput {
+    /** The docs ID from index_docs response */
+    docs_id: string;
+    /** Search query */
+    query: string;
+    /** Max results to return (default: 10) */
+    limit?: number;
+}
+/**
+ * Output for the search_docs tool.
+ */
+export interface SearchDocsOutput {
+    /** The docs ID that was searched */
+    docs_id: string;
+    /** The query that was executed */
+    query: string;
+    /** Search results with snippets */
+    results: SearchResult[];
+}
+/**
+ * Searches within cached documentation using full-text search.
+ */
+export declare function searchDocs(input: SearchDocsInput): Promise<SearchDocsOutput>;
+//# sourceMappingURL=search-docs.d.ts.map

package/dist/tools/search-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-docs.d.ts","sourceRoot":"","sources":["../../src/tools/search-docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG7E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAYD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAoD3B"}

package/dist/tools/search-docs.js

@@ -0,0 +1,64 @@
+/**
+ * search_docs tool - Full-text search within cached documentation.
+ */
+import { cacheManager } from "../services/cache-manager.js";
+import { SearchIndex } from "../services/search-index.js";
+import { CacheNotFoundError, ValidationError, DocsError } from "../types/errors.js";
+/**
+ * Default limit for search results.
+ */
+const DEFAULT_LIMIT = 10;
+/**
+ * Maximum allowed limit for search results.
+ */
+const MAX_LIMIT = 50;
+/**
+ * Searches within cached documentation using full-text search.
+ */
+export async function searchDocs(input) {
+    const { docs_id, query, limit = DEFAULT_LIMIT } = input;
+    // Validate required parameters
+    if (!docs_id) {
+        throw new ValidationError("Missing required parameter: docs_id", "docs_id");
+    }
+    if (!query || typeof query !== "string") {
+        throw new ValidationError("Missing required parameter: query", "query");
+    }
+    // Validate limit
+    const effectiveLimit = Math.min(Math.max(1, limit), MAX_LIMIT);
+    // Find the cached docs entry to determine source type
+    const meta = await cacheManager.findById(docs_id);
+    if (!meta) {
+        throw new CacheNotFoundError(docs_id);
+    }
+    // Load the search index
+    const indexJson = await cacheManager.getSearchIndex(meta.source, docs_id);
+    if (!indexJson) {
+        throw new DocsError("CACHE_NOT_FOUND", `Search index not found for "${docs_id}"`, {
+            userMessage: `Search index not found for "${docs_id}". Please re-index the documentation.`,
+            suggestions: ["Run index_docs with force_refresh: true to rebuild the search index"],
+            context: { docs_id },
+        });
+    }
+    // Parse and search
+    let searchIndex;
+    try {
+        searchIndex = SearchIndex.fromJSON(indexJson);
+    }
+    catch (error) {
+        throw new DocsError("PARSE_ERROR", "Failed to load search index", {
+            userMessage: "Search index is corrupted. Please re-index the documentation.",
+            suggestions: ["Run index_docs with force_refresh: true to rebuild the search index"],
+            context: { docs_id },
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    // Perform the search
+    const results = searchIndex.search(query, effectiveLimit);
+    return {
+        docs_id,
+        query,
+        results,
+    };
+}
+//# sourceMappingURL=search-docs.js.map

package/dist/tools/search-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-docs.js","sourceRoot":"","sources":["../../src/tools/search-docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAqB,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA0BpF;;GAEG;AACH,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB;;GAEG;AACH,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAsB;IAEtB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,aAAa,EAAE,GAAG,KAAK,CAAC;IAExD,+BAA+B;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,qCAAqC,EAAE,SAAS,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,eAAe,CAAC,mCAAmC,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED,iBAAiB;IACjB,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;IAE/D,sDAAsD;IACtD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,wBAAwB;IACxB,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1E,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CAAC,iBAAiB,EAAE,+BAA+B,OAAO,GAAG,EAAE;YAChF,WAAW,EAAE,+BAA+B,OAAO,uCAAuC;YAC1F,WAAW,EAAE,CAAC,qEAAqE,CAAC;YACpF,OAAO,EAAE,EAAE,OAAO,EAAE;SACrB,CAAC,CAAC;IACL,CAAC;IAED,mBAAmB;IACnB,IAAI,WAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,WAAW,GAAG,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,6BAA6B,EAAE;YAChE,WAAW,EAAE,+DAA+D;YAC5E,WAAW,EAAE,CAAC,qEAAqE,CAAC;YACpF,OAAO,EAAE,EAAE,OAAO,EAAE;YACpB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;SAClD,CAAC,CAAC;IACL,CAAC;IAED,qBAAqB;IACrB,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IAE1D,OAAO;QACL,OAAO;QACP,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/types/cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents a node in the documentation tree structure.
+ */
+export interface DocsTreeNode {
+    /** File or folder name */
+    name: string;
+    /** Full path from root */
+    path: string;
+    /** Node type */
+    type: "file" | "folder";
+    /** File size in bytes (for files only) */
+    size_bytes?: number;
+    /** Child nodes (for folders only) */
+    children?: DocsTreeNode[];
+}
+/**
+ * Metadata stored for each cached documentation set.
+ */
+export interface CacheMeta {
+    /** Unique identifier for this docs set */
+    id: string;
+    /** Source type */
+    source: "github" | "scraped";
+    /** Repository in "owner/repo" format */
+    repo?: string;
+    /** Branch name */
+    branch?: string;
+    /** Base URL of the scraped documentation */
+    base_url?: string;
+    /** ISO timestamp when docs were indexed */
+    indexed_at: string;
+    /** ISO timestamp when cache expires */
+    expires_at: string;
+    /** Number of pages/files in the docs */
+    page_count: number;
+    /** Total size of all content in bytes */
+    total_size_bytes: number;
+    /** Hierarchical file tree */
+    tree: DocsTreeNode[];
+}
+/**
+ * Summary information about a cached docs entry (for listing).
+ */
+export interface CacheEntrySummary {
+    id: string;
+    source: "github" | "scraped";
+    repo?: string;
+    base_url?: string;
+    indexed_at: string;
+    page_count: number;
+    total_size_bytes: number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/types/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/types/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB;IAClB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAG7B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,6BAA6B;IAC7B,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B"}

package/dist/types/cache.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.js.map

package/dist/types/cache.js.map

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