documcp

import { z } from 'zod'; import { readFile, readdir, stat } from 'fs/promises'; import { join, extname, resolve, relative, dirname } from 'path'; import { MCPToolResponse } from '../types/api.js'; // Input validation schema const LinkCheckInputSchema = z.object({ documentation_path: z.string().default('./docs'), check_external_links: z.boolean().default(true), check_internal_links: z.boolean().default(true), check_anchor_links: z.boolean().default(true), timeout_ms: z.number().min(1000).max(30000).default(5000), max_concurrent_checks: z.number().min(1).max(20).default(5), allowed_domains: z.array(z.string()).default([]), ignore_patterns: z.array(z.string()).default([]), fail_on_broken_links: z.boolean().default(false), output_format: z.enum(['summary', 'detailed', 'json']).default('detailed'), }); type LinkCheckInput = z.infer<typeof LinkCheckInputSchema>; interface LinkCheckResult { url: string; status: 'valid' | 'broken' | 'warning' | 'skipped'; statusCode?: number; error?: string; responseTime?: number; sourceFile: string; lineNumber?: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; } interface LinkCheckReport { summary: { totalLinks: number; validLinks: number; brokenLinks: number; warningLinks: number; skippedLinks: number; executionTime: number; filesScanned: number; }; results: LinkCheckResult[]; recommendations: string[]; configuration: { checkExternalLinks: boolean; checkInternalLinks: boolean; checkAnchorLinks: boolean; timeoutMs: number; maxConcurrentChecks: number; }; } export async function checkDocumentationLinks( input: Partial<LinkCheckInput>, ): Promise<MCPToolResponse<LinkCheckReport>> { const startTime = Date.now(); try { // Validate input with defaults const validatedInput = LinkCheckInputSchema.parse(input); const { documentation_path, check_external_links, check_internal_links, check_anchor_links, timeout_ms, max_concurrent_checks, allowed_domains, ignore_patterns, fail_on_broken_links, } = validatedInput; // Scan documentation files const documentationFiles = await scanDocumentationFiles(documentation_path); if (documentationFiles.length === 0) { return { success: false, error: { code: 'NO_DOCUMENTATION_FILES', message: 'No documentation files found in the specified path', details: `Searched in: ${documentation_path}`, resolution: 'Verify the documentation_path parameter points to a directory containing markdown files', }, metadata: { toolVersion: '1.0.0', executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } // Extract all links from documentation files const allLinks = await extractLinksFromFiles(documentationFiles, documentation_path); // Filter links based on configuration const filteredLinks = filterLinks(allLinks, { checkExternalLinks: check_external_links, checkInternalLinks: check_internal_links, checkAnchorLinks: check_anchor_links, ignorePatterns: ignore_patterns, }); // Check links with concurrency control const linkResults = await checkLinksWithConcurrency(filteredLinks, { timeoutMs: timeout_ms, maxConcurrent: max_concurrent_checks, allowedDomains: allowed_domains, documentationPath: documentation_path, }); // Generate report const report = generateLinkCheckReport(linkResults, { checkExternalLinks: check_external_links, checkInternalLinks: check_internal_links, checkAnchorLinks: check_anchor_links, timeoutMs: timeout_ms, maxConcurrentChecks: max_concurrent_checks, filesScanned: documentationFiles.length, executionTime: Date.now() - startTime, }); // Check if we should fail on broken links if (fail_on_broken_links && report.summary.brokenLinks > 0) { return { success: false, error: { code: 'BROKEN_LINKS_FOUND', message: `Found ${report.summary.brokenLinks} broken links`, details: `${report.summary.brokenLinks} out of ${report.summary.totalLinks} links are broken`, resolution: 'Fix the broken links or set fail_on_broken_links to false', }, data: report, metadata: { toolVersion: '1.0.0', executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } return { success: true, data: report, metadata: { toolVersion: '1.0.0', executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } catch (error) { return { success: false, error: { code: 'LINK_CHECK_ERROR', message: 'Failed to check documentation links', details: error instanceof Error ? error.message : 'Unknown error occurred', resolution: 'Check the documentation path and ensure files are accessible', }, metadata: { toolVersion: '1.0.0', executionTime: Date.now() - startTime, timestamp: new Date().toISOString(), }, }; } } async function scanDocumentationFiles(basePath: string): Promise<string[]> { const files: string[] = []; async function scanDirectory(dirPath: string): Promise<void> { try { const entries = await readdir(dirPath); for (const entry of entries) { const fullPath = join(dirPath, entry); const stats = await stat(fullPath); if (stats.isDirectory()) { // Skip node_modules and hidden directories if (!entry.startsWith('.') && entry !== 'node_modules') { await scanDirectory(fullPath); } } else if (stats.isFile()) { const ext = extname(entry).toLowerCase(); if (['.md', '.mdx', '.markdown'].includes(ext)) { files.push(fullPath); } } } } catch (error) { // Skip directories we can't read } } await scanDirectory(basePath); return files; } async function extractLinksFromFiles( files: string[], basePath: string, ): Promise< Array<{ url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }> > { const allLinks: Array<{ url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }> = []; // Regex patterns for different link types const markdownLinkRegex = /\[([^\]]*)\]\(([^)]+)\)/g; const htmlLinkRegex = /<a[^>]+href=["']([^"']+)["'][^>]*>/gi; const refLinkRegex = /\[([^\]]+)\]:\s*(.+)/g; for (const file of files) { try { const content = await readFile(file, 'utf-8'); const lines = content.split('\n'); // Create proper relative file path const absoluteBasePath = resolve(basePath); const absoluteFilePath = resolve(file); const relativeFile = relative(absoluteBasePath, absoluteFilePath).replace(/\\/g, '/'); // Extract markdown links lines.forEach((line, index) => { let match; // Markdown links [text](url) while ((match = markdownLinkRegex.exec(line)) !== null) { const url = match[2].trim(); if (url && !url.startsWith('#')) { // Skip empty and anchor-only links allLinks.push({ url, sourceFile: relativeFile, lineNumber: index + 1, linkType: determineLinkType(url), }); } } // HTML links while ((match = htmlLinkRegex.exec(line)) !== null) { const url = match[1].trim(); if (url && !url.startsWith('#')) { allLinks.push({ url, sourceFile: relativeFile, lineNumber: index + 1, linkType: determineLinkType(url), }); } } // Reference links while ((match = refLinkRegex.exec(line)) !== null) { const url = match[2].trim(); if (url && !url.startsWith('#')) { allLinks.push({ url, sourceFile: relativeFile, lineNumber: index + 1, linkType: determineLinkType(url), }); } } }); } catch (error) { // Skip files we can't read } } return allLinks; } function determineLinkType(url: string): 'internal' | 'external' | 'anchor' | 'mailto' | 'tel' { if (url.startsWith('mailto:')) return 'mailto'; if (url.startsWith('tel:')) return 'tel'; if (url.startsWith('#')) return 'anchor'; if (url.startsWith('http://') || url.startsWith('https://')) return 'external'; return 'internal'; } function filterLinks( links: Array<{ url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }>, options: { checkExternalLinks: boolean; checkInternalLinks: boolean; checkAnchorLinks: boolean; ignorePatterns: string[]; }, ) { return links.filter((link) => { // Check if link should be ignored based on patterns if (options.ignorePatterns.some((pattern) => link.url.includes(pattern))) { return false; } // Filter by link type switch (link.linkType) { case 'external': return options.checkExternalLinks; case 'internal': return options.checkInternalLinks; case 'anchor': return options.checkAnchorLinks; case 'mailto': case 'tel': return false; // Skip these for now default: return true; } }); } async function checkLinksWithConcurrency( links: Array<{ url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }>, options: { timeoutMs: number; maxConcurrent: number; allowedDomains: string[]; documentationPath: string; }, ): Promise<LinkCheckResult[]> { const results: LinkCheckResult[] = []; async function checkSingleLink(link: { url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }): Promise<LinkCheckResult> { const startTime = Date.now(); try { if (link.linkType === 'internal') { return await checkInternalLink(link, options.documentationPath); } else if (link.linkType === 'external') { return await checkExternalLink(link, options.timeoutMs, options.allowedDomains); } else if (link.linkType === 'anchor') { return await checkAnchorLink(link, options.documentationPath); } return { url: link.url, status: 'skipped', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } catch (error) { return { url: link.url, status: 'broken', error: error instanceof Error ? error.message : 'Unknown error', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } // Process links with concurrency control const chunks = []; for (let i = 0; i < links.length; i += options.maxConcurrent) { chunks.push(links.slice(i, i + options.maxConcurrent)); } for (const chunk of chunks) { const chunkResults = await Promise.all(chunk.map(checkSingleLink)); results.push(...chunkResults); } return results; } async function checkInternalLink( link: { url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }, documentationPath: string, ): Promise<LinkCheckResult> { const startTime = Date.now(); try { let targetPath = link.url; // Remove anchor if present const [filePath] = targetPath.split('#'); // Handle relative paths properly using Node.js path resolution const absoluteDocPath = resolve(documentationPath); const sourceFileAbsolutePath = resolve(absoluteDocPath, link.sourceFile); const sourceDir = dirname(sourceFileAbsolutePath); if (filePath.startsWith('./')) { // Current directory reference - resolve relative to source file directory targetPath = resolve(sourceDir, filePath.substring(2)); } else if (filePath.startsWith('../')) { // Parent directory reference - resolve relative to source file directory targetPath = resolve(sourceDir, filePath); } else if (filePath.startsWith('/')) { // Absolute path from documentation root targetPath = resolve(absoluteDocPath, filePath.substring(1)); } else { // Relative path - resolve relative to source file directory targetPath = resolve(sourceDir, filePath); } try { await stat(targetPath); return { url: link.url, status: 'valid', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } catch { return { url: link.url, status: 'broken', error: 'File not found', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } catch (error) { return { url: link.url, status: 'broken', error: error instanceof Error ? error.message : 'Unknown error', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } async function checkExternalLink( link: { url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }, timeoutMs: number, allowedDomains: string[], ): Promise<LinkCheckResult> { const startTime = Date.now(); try { // Check if domain is in allowed list (if specified) if (allowedDomains.length > 0) { const url = new URL(link.url); const isAllowed = allowedDomains.some( (domain) => url.hostname === domain || url.hostname.endsWith('.' + domain), ); if (!isAllowed) { return { url: link.url, status: 'skipped', error: 'Domain not in allowed list', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } // Simple HEAD request to check if URL is accessible const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), timeoutMs); try { const response = await fetch(link.url, { method: 'HEAD', signal: controller.signal, headers: { 'User-Agent': 'DocuMCP Link Checker 1.0', }, }); clearTimeout(timeoutId); if (response.ok) { return { url: link.url, status: 'valid', statusCode: response.status, sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } else { return { url: link.url, status: 'broken', statusCode: response.status, error: `HTTP ${response.status}: ${response.statusText}`, sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } catch (fetchError) { clearTimeout(timeoutId); if (fetchError instanceof Error && fetchError.name === 'AbortError') { return { url: link.url, status: 'warning', error: 'Request timeout', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } throw fetchError; } } catch (error) { return { url: link.url, status: 'broken', error: error instanceof Error ? error.message : 'Unknown error', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } } async function checkAnchorLink( link: { url: string; sourceFile: string; lineNumber: number; linkType: 'internal' | 'external' | 'anchor' | 'mailto' | 'tel'; }, _documentationPath: string, ): Promise<LinkCheckResult> { const startTime = Date.now(); // For now, just mark anchor links as valid // In a more sophisticated implementation, we would parse the target file // and check if the anchor exists return { url: link.url, status: 'valid', sourceFile: link.sourceFile, lineNumber: link.lineNumber, linkType: link.linkType, responseTime: Date.now() - startTime, }; } function generateLinkCheckReport( results: LinkCheckResult[], config: { checkExternalLinks: boolean; checkInternalLinks: boolean; checkAnchorLinks: boolean; timeoutMs: number; maxConcurrentChecks: number; filesScanned: number; executionTime: number; }, ): LinkCheckReport { const summary = { totalLinks: results.length, validLinks: results.filter((r) => r.status === 'valid').length, brokenLinks: results.filter((r) => r.status === 'broken').length, warningLinks: results.filter((r) => r.status === 'warning').length, skippedLinks: results.filter((r) => r.status === 'skipped').length, executionTime: config.executionTime, filesScanned: config.filesScanned, }; const recommendations: string[] = []; if (summary.brokenLinks > 0) { recommendations.push( `🔴 Fix ${summary.brokenLinks} broken links to improve documentation quality`, ); } if (summary.warningLinks > 0) { recommendations.push(`🟡 Review ${summary.warningLinks} warning links that may need attention`); } if (summary.validLinks === summary.totalLinks) { recommendations.push('✅ All links are valid - excellent documentation quality!'); } if (summary.totalLinks > 100) { recommendations.push('📊 Consider implementing automated link checking in CI/CD pipeline'); } return { summary, results, recommendations, configuration: { checkExternalLinks: config.checkExternalLinks, checkInternalLinks: config.checkInternalLinks, checkAnchorLinks: config.checkAnchorLinks, timeoutMs: config.timeoutMs, maxConcurrentChecks: config.maxConcurrentChecks, }, }; }