mcp-web-validator 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,682 +1,457 @@
 #!/usr/bin/env node
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import * as fs from "fs/promises";
-import * as path from "path";
-import { validateHtmlContent, validateCssContent } from "./w3c-validator.js";
-import { auditSeoMetadata, validateSchemaMarkup, checkBrokenLinks } from "./seo-auditor.js";
+import { z } from "zod";
 import { captureScreenshots } from "./screenshot.js";
-// Initialize MCP Server
-const server = new Server({
-    name: "mcp-web-validator",
-    version: "1.0.0",
-}, {
-    capabilities: {
-        tools: {},
-    },
+import { auditSeoMetadata, auditSeoMetadataDetailed, checkBrokenLinks, validateSchemaMarkup, validateSchemaMarkupDetailed, } from "./seo-auditor.js";
+import { createValidationReport, validationReportChecks, } from "./report.js";
+import { fetchPublicText, getErrorMessage, readTextFile } from "./network.js";
+import { cssValidationContent, failureContent, htmlValidationContent, linkCheckContent, reportContent, schemaValidationContent, screenshotCaptureContent, seoAuditContent, } from "./presentation.js";
+import { PACKAGE_VERSION } from "./version.js";
+import { MAX_CSS_VALIDATION_BYTES, validateCssContent, validateHtmlContent, } from "./w3c-validator.js";
+export const SERVER_VERSION = PACKAGE_VERSION;
+const HTML_MAX_BYTES = 2_000_000;
+const CSS_MAX_BYTES = MAX_CSS_VALIDATION_BYTES;
+const PATH_MAX_LENGTH = 4_096;
+const MAX_VIEWPORTS = 8;
+const filePathSchema = z.string().trim().min(1).max(PATH_MAX_LENGTH);
+const htmlContentSchema = z.string().min(1).max(HTML_MAX_BYTES);
+const publicUrlSchema = z
+    .string()
+    .url()
+    .refine((value) => {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+}, "URL must use HTTP or HTTPS.");
+const w3cMessageSchema = z.object({
+    type: z.string(),
+    message: z.string(),
+    lastLine: z.number().int().optional(),
+    lastColumn: z.number().int().optional(),
+    firstLine: z.number().int().optional(),
+    firstColumn: z.number().int().optional(),
+    extract: z.string().optional(),
 });
-// Register Tool Definitions
-server.setRequestHandler(ListToolsRequestSchema, async () => {
+const cssMessageSchema = z.object({
+    line: z.number().int(),
+    type: z.string(),
+    message: z.string(),
+    context: z.string().optional(),
+});
+const seoIssueSchema = z.object({
+    severity: z.enum(["error", "warning", "info"]),
+    category: z.enum(["SEO", "Schema", "BrokenLinks", "Accessibility"]),
+    message: z.string(),
+    element: z.string().optional(),
+});
+const linkStatusSchema = z.object({
+    url: z.string(),
+    status: z.union([z.number().int(), z.enum(["blocked", "failed"])]),
+    ok: z.boolean(),
+    message: z.string().optional(),
+});
+const screenshotSchema = z.object({
+    viewportName: z.string(),
+    width: z.number().int(),
+    height: z.number().int(),
+    outputPath: z.string(),
+});
+const reportSummarySchema = z.object({
+    overallScore: z.number().int().min(0).max(100).nullable(),
+    htmlScore: z.number().int().min(0).max(100).nullable(),
+    cssScore: z.number().int().min(0).max(100).nullable(),
+    seoScore: z.number().int().min(0).max(100).nullable(),
+    linkScore: z.number().int().min(0).max(100).nullable(),
+    htmlErrors: z.number().int().nonnegative(),
+    htmlWarnings: z.number().int().nonnegative(),
+    cssErrors: z.number().int().nonnegative(),
+    seoErrors: z.number().int().nonnegative(),
+    seoWarnings: z.number().int().nonnegative(),
+    schemaErrors: z.number().int().nonnegative(),
+    linksChecked: z.number().int().nonnegative(),
+    brokenLinks: z.number().int().nonnegative(),
+});
+const externalReadOnlyAnnotations = {
+    // These calls contact external recipients but do not modify external state.
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const localReadOnlyAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+function result(structuredContent, content, isError = false) {
     return {
-        tools: [
+        structuredContent: structuredContent,
+        content: [
             {
-                name: "html_validate_local",
-                description: "Validates a local HTML file against the official W3C Nu HTML Checker API. Catches syntax, tags, and compliance errors.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        filePath: {
-                            type: "string",
-                            description: "Absolute or relative path to the local HTML file.",
-                        },
-                    },
-                    required: ["filePath"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Validation result containing W3C HTML parser validation messages.",
-                    properties: {
-                        errors: {
-                            type: "array",
-                            description: "List of HTML validation error and warning objects returned from W3C.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    type: { "type": "string", "description": "The category of message: 'error', 'info', or 'non-document-error'." },
-                                    message: { "type": "string", "description": "The specific validation or parsing error message." },
-                                    extract: { "type": "string", "description": "The HTML snippet around the validation location." },
-                                    lastLine: { "type": "number", "description": "Line number where the issue occurred." },
-                                    lastColumn: { "type": "number", "description": "Column number where the issue occurred." }
-                                },
-                                required: ["type", "message"]
-                            }
-                        }
-                    },
-                    required: ["errors"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "html_validate_url",
-                description: "Validates the markup of a live public URL using the W3C HTML validation engine.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        url: {
-                            type: "string",
-                            description: "The live URL to validate (must start with http:// or https://).",
-                        },
-                    },
-                    required: ["url"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Validation result containing W3C HTML parser validation messages.",
-                    properties: {
-                        errors: {
-                            type: "array",
-                            description: "List of HTML validation error and warning objects returned from W3C.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    type: { "type": "string", "description": "The category of message: 'error', 'info', or 'non-document-error'." },
-                                    message: { "type": "string", "description": "The specific validation or parsing error message." },
-                                    extract: { "type": "string", "description": "The HTML snippet around the validation location." },
-                                    lastLine: { "type": "number", "description": "Line number where the issue occurred." },
-                                    lastColumn: { "type": "number", "description": "Column number where the issue occurred." }
-                                },
-                                required: ["type", "message"]
-                            }
-                        }
-                    },
-                    required: ["errors"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "css_validate_local",
-                description: "Validates a local CSS file against the W3C Jigsaw CSS Validator API. Finds styling syntax errors.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        filePath: {
-                            type: "string",
-                            description: "Absolute or relative path to the local CSS file.",
-                        },
-                    },
-                    required: ["filePath"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "CSS validation results.",
-                    properties: {
-                        errors: {
-                            type: "array",
-                            description: "List of CSS validation errors from W3C Jigsaw API.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    line: { "type": "number", "description": "Line number of the CSS error." },
-                                    context: { "type": "string", "description": "The CSS selector or context where the error occurred." },
-                                    message: { "type": "string", "description": "The specific CSS validation warning or error message." }
-                                },
-                                required: ["line", "message"]
-                            }
-                        }
-                    },
-                    required: ["errors"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "seo_audit_metadata",
-                description: "Runs a fast offline audit of HTML metadata, heading structure, viewport responsive tags, image alt tags, and Open Graph cards.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        htmlContent: {
-                            type: "string",
-                            description: "The raw HTML string content to analyze.",
-                        },
-                    },
-                    required: ["htmlContent"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Audited Technical SEO results.",
-                    properties: {
-                        issues: {
-                            type: "array",
-                            description: "List of audited Technical SEO issues, warnings, and error indicators.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    category: { "type": "string", "description": "SEO audit category (e.g. metadata, structure, accessibility)." },
-                                    severity: { "type": "string", "description": "Severity of the issue: 'error' or 'warning'." },
-                                    message: { "type": "string", "description": "Detailed explanation of the SEO issue." },
-                                    element: { "type": "string", "description": "Relevant HTML snippet or element if applicable." }
-                                },
-                                required: ["category", "severity", "message"]
-                            }
-                        }
-                    },
-                    required: ["issues"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
+                type: "text",
+                text: content,
             },
-            {
-                name: "links_check_broken",
-                description: "Extracts all links (a href tags) in the HTML content and tests their HTTP status codes to detect broken internal or external URLs.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        htmlContent: {
-                            type: "string",
-                            description: "The raw HTML string content to inspect.",
-                        },
-                        baseUrl: {
-                            type: "string",
-                            description: "Optional base URL to resolve relative paths (e.g., https://example.com).",
-                        },
-                    },
-                    required: ["htmlContent"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Reachability report of page links.",
-                    properties: {
-                        links: {
-                            type: "array",
-                            description: "Status details of all checked links on the page.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    url: { "type": "string", "description": "The destination URL that was tested." },
-                                    status: { "type": "number", "description": "HTTP status code response (e.g., 200, 404)." },
-                                    ok: { "type": "boolean", "description": "Whether the link is reachable and returned a successful status code." },
-                                    message: { "type": "string", "description": "Reachable status details or error description." }
-                                },
-                                required: ["url", "status", "ok"]
-                            }
-                        }
-                    },
-                    required: ["links"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "schema_validate_markup",
-                description: "Finds and validates the JSON-LD schema blocks within the HTML, catching syntax issues.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        htmlContent: {
-                            type: "string",
-                            description: "The raw HTML string containing <script type=\"application/ld+json\"> blocks.",
-                        },
-                    },
-                    required: ["htmlContent"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Parsed JSON-LD validation report.",
-                    properties: {
-                        issues: {
-                            type: "array",
-                            description: "List of parsed JSON-LD validation results.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    category: { "type": "string", "description": "Always 'Schema Markup'." },
-                                    severity: { "type": "string", "description": "Severity level: 'error' or 'warning'." },
-                                    message: { "type": "string", "description": "Validation message explaining JSON parsing errors or schema problems." }
-                                },
-                                required: ["category", "severity", "message"]
-                            }
-                        }
-                    },
-                    required: ["issues"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "report_generate_validation",
-                description: "Runs all validation checks (HTML, CSS, SEO, Schema, Links) on local files and aggregates them into a beautifully formatted Markdown report with summary tables.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        htmlFilePath: {
-                            type: "string",
-                            description: "Absolute or relative path to the local HTML file to validate.",
-                        },
-                        cssFilePath: {
-                            type: "string",
-                            description: "Optional absolute or relative path to the local CSS file to validate.",
-                        },
-                        baseUrl: {
-                            type: "string",
-                            description: "Optional base URL to resolve relative link paths.",
-                        },
-                    },
-                    required: ["htmlFilePath"],
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Aggregated Markdown validation and SEO report details.",
-                    properties: {
-                        content: {
-                            type: "array",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    type: { "type": "string", "enum": ["text"] },
-                                    text: { "type": "string", "description": "Formatted Markdown report." }
-                                },
-                                required: ["type", "text"]
-                            }
-                        }
-                    },
-                    required: ["content"]
-                },
-                annotations: {
-                    readOnlyHint: true,
-                    openWorldHint: false
-                }
-            },
-            {
-                name: "screenshot_capture",
-                description: "Renders a local HTML file or remote URL using Puppeteer and captures screenshots at different viewport sizes (desktop, tablet, mobile).",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        targetPath: {
-                            type: "string",
-                            description: "Path to the local HTML file or remote URL (e.g. http:// or https://) to screenshot.",
-                        },
-                        outputDir: {
-                            type: "string",
-                            description: "Optional absolute or relative directory path where screenshots will be saved. Defaults to '.mcp-validator/screenshots'.",
-                        },
-                        viewports: {
-                            type: "array",
-                            description: "Optional list of custom viewports to capture. Each viewport object must have name, width, and height.",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    name: { type: "string", description: "Name of the viewport (e.g., mobile-portrait)." },
-                                    width: { type: "number", description: "Width in pixels." },
-                                    height: { type: "number", description: "Height in pixels." }
-                                },
-                                required: ["name", "width", "height"]
-                            }
-                        }
-                    },
-                    required: ["targetPath"]
-                },
-                outputSchema: {
-                    type: "object",
-                    description: "Status report of screenshot file paths and coordinates generated.",
-                    properties: {
-                        content: {
-                            type: "array",
-                            items: {
-                                type: "object",
-                                properties: {
-                                    type: { "type": "string", "enum": ["text"] },
-                                    text: { "type": "string", "description": "Markdown list of screenshots created and their directories." }
-                                },
-                                required: ["type", "text"]
-                            }
-                        }
-                    },
-                    required: ["content"]
-                },
-                annotations: {
-                    readOnlyHint: false,
-                    openWorldHint: true
-                }
-            }
         ],
+        ...(isError ? { isError: true } : {}),
     };
-});
-// Handle Tool Calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-        switch (name) {
-            case "html_validate_local": {
-                const filePath = String(args?.filePath);
-                const resolvedPath = path.resolve(filePath);
-                try {
-                    const content = await fs.readFile(resolvedPath, "utf-8");
-                    const errors = await validateHtmlContent(content);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: JSON.stringify(errors, null, 2),
-                            },
-                        ],
-                    };
-                }
-                catch (e) {
-                    return {
-                        isError: true,
-                        content: [
-                            {
-                                type: "text",
-                                text: `Error reading file at "${resolvedPath}": ${e.message}`,
-                            },
-                        ],
-                    };
-                }
-            }
-            case "html_validate_url": {
-                const url = String(args?.url);
-                try {
-                    const response = await fetch(url);
-                    if (!response.ok) {
-                        return {
-                            isError: true,
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `Failed to fetch URL ${url}. Status code: ${response.status}`,
-                                },
-                            ],
-                        };
-                    }
-                    const content = await response.text();
-                    const errors = await validateHtmlContent(content);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: JSON.stringify(errors, null, 2),
-                            },
-                        ],
-                    };
-                }
-                catch (e) {
-                    return {
-                        isError: true,
-                        content: [
-                            {
-                                type: "text",
-                                text: `Error fetching URL "${url}": ${e.message}`,
-                            },
-                        ],
-                    };
-                }
-            }
-            case "css_validate_local": {
-                const filePath = String(args?.filePath);
-                const resolvedPath = path.resolve(filePath);
-                try {
-                    const content = await fs.readFile(resolvedPath, "utf-8");
-                    const errors = await validateCssContent(content);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: JSON.stringify(errors, null, 2),
-                            },
-                        ],
-                    };
-                }
-                catch (e) {
-                    return {
-                        isError: true,
-                        content: [
-                            {
-                                type: "text",
-                                text: `Error reading CSS file at "${resolvedPath}": ${e.message}`,
-                            },
-                        ],
-                    };
-                }
-            }
-            case "seo_audit_metadata": {
-                const htmlContent = String(args?.htmlContent);
-                const issues = auditSeoMetadata(htmlContent);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify(issues, null, 2),
-                        },
-                    ],
-                };
-            }
-            case "links_check_broken": {
-                const htmlContent = String(args?.htmlContent);
-                const baseUrl = args?.baseUrl ? String(args.baseUrl) : undefined;
-                const linkStatuses = await checkBrokenLinks(htmlContent, baseUrl);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify(linkStatuses, null, 2),
-                        },
-                    ],
-                };
-            }
-            case "schema_validate_markup": {
-                const htmlContent = String(args?.htmlContent);
-                const issues = validateSchemaMarkup(htmlContent);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify(issues, null, 2),
-                        },
-                    ],
-                };
-            }
-            case "report_generate_validation": {
-                const htmlFilePath = String(args?.htmlFilePath);
-                const cssFilePath = args?.cssFilePath ? String(args.cssFilePath) : undefined;
-                const baseUrl = args?.baseUrl ? String(args.baseUrl) : undefined;
-                const resolvedHtmlPath = path.resolve(htmlFilePath);
-                const htmlContent = await fs.readFile(resolvedHtmlPath, "utf-8");
-                // Runs checks
-                const htmlErrors = await validateHtmlContent(htmlContent);
-                const seoIssues = auditSeoMetadata(htmlContent);
-                const schemaIssues = validateSchemaMarkup(htmlContent);
-                const linkStatuses = await checkBrokenLinks(htmlContent, baseUrl);
-                let cssErrors = [];
-                if (cssFilePath) {
-                    try {
-                        const resolvedCssPath = path.resolve(cssFilePath);
-                        const cssContent = await fs.readFile(resolvedCssPath, "utf-8");
-                        cssErrors = await validateCssContent(cssContent);
-                    }
-                    catch (e) {
-                        cssErrors = [{ line: 0, type: "error", message: `Failed to read CSS: ${e.message}` }];
-                    }
-                }
-                // Generate Report Markdown
-                const htmlErrCount = htmlErrors.filter(e => e.type === "error").length;
-                const htmlWarnCount = htmlErrors.filter(e => e.type !== "error").length;
-                const cssErrCount = cssErrors.length;
-                const seoErrCount = seoIssues.filter(i => i.severity === "error").length;
-                const seoWarnCount = seoIssues.filter(i => i.severity !== "error").length;
-                const schemaErrCount = schemaIssues.filter(i => i.severity === "error").length;
-                const brokenLinkCount = linkStatuses.filter(l => !l.ok).length;
-                // Calculate Scores (PageSpeed style: Base 100)
-                let htmlScore = 100 - (htmlErrCount * 15) - (htmlWarnCount * 2);
-                let cssScore = cssFilePath ? (100 - (cssErrCount * 20)) : 100;
-                let seoScore = 100 - (seoErrCount * 15) - (seoWarnCount * 4) - (schemaErrCount * 15);
-                let linkScore = linkStatuses.length > 0 ? (100 - (brokenLinkCount * 25)) : 100;
-                // Clamp to [0, 100]
-                htmlScore = Math.max(0, Math.min(100, htmlScore));
-                cssScore = Math.max(0, Math.min(100, cssScore));
-                seoScore = Math.max(0, Math.min(100, seoScore));
-                linkScore = Math.max(0, Math.min(100, linkScore));
-                const getCircle = (score) => {
-                    if (score >= 90)
-                        return "🟢";
-                    if (score >= 50)
-                        return "🟠";
-                    return "🔴";
-                };
-                const totalAuditCount = cssFilePath ? 4 : 3;
-                const totalScoreSum = htmlScore + seoScore + linkScore + (cssFilePath ? cssScore : 0);
-                const overallScore = Math.round(totalScoreSum / totalAuditCount);
-                const report = [
-                    `# 📋 Web Validation & SEO Audit Report — ${getCircle(overallScore)} **${overallScore}**/100`,
-                    `*Generated for: \`${path.basename(htmlFilePath)}\`*`,
-                    ``,
-                    `## ⚡ Page Health Scores (PageSpeed Inspired)`,
-                    ``,
-                    `| Score Card | Status | Score |`,
-                    `| :--- | :---: | :---: |`,
-                    `| **W3C HTML Validation** | ${getCircle(htmlScore)} ${htmlScore >= 90 ? "Excellent" : (htmlScore >= 50 ? "Needs Work" : "Poor")} | **${htmlScore}** / 100 |`,
-                    `| **W3C CSS Validation** | ${cssFilePath ? `${getCircle(cssScore)} ${cssScore >= 90 ? "Excellent" : (cssScore >= 50 ? "Needs Work" : "Poor")}` : "ℹ️ Not Audited"} | ${cssFilePath ? `**${cssScore}** / 100` : "N/A"} |`,
-                    `| **SEO & Accessibility** | ${getCircle(seoScore)} ${seoScore >= 90 ? "Optimized" : (seoScore >= 50 ? "Warnings" : "Poor")} | **${seoScore}** / 100 |`,
-                    `| **Links Integrity** | ${linkStatuses.length > 0 ? `${getCircle(linkScore)} ${linkScore >= 90 ? "All Good" : "Broken Links"}` : "ℹ️ No Links"} | ${linkStatuses.length > 0 ? `**${linkScore}** / 100` : "N/A"} |`,
-                    ``,
-                    `---`,
-                    ``,
-                    `## 📊 Audit Details Overview`,
-                    `| Audit Category | Status | Details |`,
-                    `| :--- | :---: | :--- |`,
-                    `| **W3C HTML Validation** | ${htmlErrCount > 0 ? "❌ Failed" : "✅ Passed"} | ${htmlErrCount} Errors, ${htmlWarnCount} Warnings |`,
-                    `| **W3C CSS Validation** | ${cssFilePath ? (cssErrCount > 0 ? "❌ Failed" : "✅ Passed") : "ℹ️ Not Audited"} | ${cssErrCount} Errors |`,
-                    `| **Technical SEO & Accessibility** | ${seoErrCount > 0 ? "❌ Critical Issues" : (seoWarnCount > 0 ? "⚠️ Warnings" : "✅ Optimized")} | ${seoErrCount} Errors, ${seoWarnCount} Warnings |`,
-                    `| **JSON-LD Schema Verification** | ${schemaErrCount > 0 ? "❌ Invalid" : "✅ Valid"} | ${schemaErrCount} Syntax Errors |`,
-                    `| **Broken Link Check** | ${brokenLinkCount > 0 ? "❌ Broken Links Found" : "✅ All Links OK"} | ${brokenLinkCount} Dead Links, ${linkStatuses.length} Total Links Checked |`,
-                    `---`,
-                    ``,
-                    `## 🔴 HTML Syntax & Compliance Issues (${htmlErrors.length})`,
-                ];
-                if (htmlErrors.length === 0) {
-                    report.push("*No HTML syntax or markup validation errors found! Excellent job.*");
-                }
-                else {
-                    report.push("| Line | Col | Severity | Message | Extract |");
-                    report.push("| :---: | :---: | :--- | :--- | :--- |");
-                    for (const err of htmlErrors) {
-                        const extract = err.extract ? `\`${err.extract.replace(/\n/g, " ").trim()}\`` : "N/A";
-                        report.push(`| ${err.lastLine || "N/A"} | ${err.lastColumn || "N/A"} | ${err.type === "error" ? "🔴 Error" : "⚠️ Warning"} | ${err.message} | ${extract} |`);
-                    }
-                }
-                if (cssFilePath) {
-                    report.push(``, `---`, ``, `## 🎨 CSS Styling Issues (${cssErrors.length})`);
-                    if (cssErrors.length === 0) {
-                        report.push("*No CSS syntax errors found! Stylesheet is fully compliant.*");
-                    }
-                    else {
-                        report.push("| Line | Context | Message |");
-                        report.push("| :---: | :--- | :--- |");
-                        for (const err of cssErrors) {
-                            report.push(`| ${err.line} | \`${err.context || "N/A"}\` | ${err.message} |`);
-                        }
-                    }
-                }
-                report.push(``, `---`, ``, `## 🔍 Technical SEO & Accessibility Issues (${seoIssues.length + schemaIssues.length})`);
-                const allSeo = [...seoIssues, ...schemaIssues];
-                if (allSeo.length === 0) {
-                    report.push("*No technical SEO or schema issues found! Page is search-engine ready.*");
-                }
-                else {
-                    report.push("| Category | Severity | Message | Element Snippet |");
-                    report.push("| :--- | :--- | :--- | :--- |");
-                    for (const issue of allSeo) {
-                        const severityLabel = issue.severity === "error" ? "🔴 Error" : (issue.severity === "warning" ? "⚠️ Warning" : "ℹ️ Info");
-                        const snippet = issue.element ? `\`${issue.element.trim()}\`` : "N/A";
-                        report.push(`| ${issue.category} | ${severityLabel} | ${issue.message} | ${snippet} |`);
-                    }
-                }
-                report.push(``, `---`, ``, `## 🔗 Link Health Check (${linkStatuses.length} links checked)`);
-                if (linkStatuses.length === 0) {
-                    report.push("*No hyperlinks found in the document.*");
-                }
-                else {
-                    report.push("| Link URL | Status Code | Health | Details |");
-                    report.push("| :--- | :---: | :---: | :--- |");
-                    for (const link of linkStatuses) {
-                        report.push(`| [${link.url}](${link.url}) | ${link.status} | ${link.ok ? "✅ Healthy" : "❌ Broken"} | ${link.message || "Accessible"} |`);
-                    }
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: report.join("\n"),
-                        },
-                    ],
-                };
-            }
-            case "screenshot_capture": {
-                const targetPath = String(args?.targetPath);
-                const outputDir = args?.outputDir ? String(args.outputDir) : ".mcp-validator/screenshots";
-                const viewports = args?.viewports;
-                const resolvedOutputDir = path.resolve(outputDir);
-                const results = await captureScreenshots(targetPath, resolvedOutputDir, viewports);
-                const responseText = [
-                    `# 📸 Viewport Screenshot Generation Complete`,
-                    `Captured **${results.length}** viewport rendering(s):`,
-                    ``,
-                    `| Viewport | Dimensions | Output Path |`,
-                    `| :--- | :---: | :--- |`,
-                    ...results.map(r => `| **${r.viewportName}** | ${r.width}x${r.height} px | [${path.basename(r.outputPath)}](file:///${r.outputPath.replace(/\\/g, "/")}) |`),
-                    ``,
-                    `> [!NOTE]`,
-                    `> Screenshots have been saved successfully to [${outputDir}](file:///${resolvedOutputDir.replace(/\\/g, "/")})`
-                ].join("\n");
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: responseText,
-                        },
-                    ],
-                };
-            }
-            default:
-                throw new Error(`Tool "${name}" not found.`);
+}
+function failedReport(filePath, error) {
+    return {
+        report: `Validation report could not be generated: ${error}`,
+        summary: {
+            overallScore: null,
+            htmlScore: null,
+            cssScore: null,
+            seoScore: null,
+            linkScore: null,
+            htmlErrors: 0,
+            htmlWarnings: 0,
+            cssErrors: 0,
+            seoErrors: 0,
+            seoWarnings: 0,
+            schemaErrors: 0,
+            linksChecked: 0,
+            brokenLinks: 0,
+        },
+        htmlMessages: [],
+        cssMessages: [],
+        seoIssues: [],
+        schemaIssues: [],
+        links: [],
+        failedChecks: ["input"],
+        errors: [`${path.basename(filePath || "document")}: ${error}`],
+    };
+}
+const validationReportDependencies = {
+    readTextFile,
+    validateHtmlContent,
+    validateCssContent,
+    auditSeoMetadata,
+    validateSchemaMarkup,
+    checkBrokenLinks,
+};
+/** Runs independent validation checks without discarding successful results when another check fails. */
+export async function generateValidationReport({ htmlFilePath, cssFilePath, baseUrl }, dependencies = validationReportDependencies) {
+    const html = await dependencies.readTextFile(htmlFilePath, HTML_MAX_BYTES);
+    const failedChecks = [];
+    const errors = [];
+    const recordFailure = (check, label, cause) => {
+        if (!failedChecks.includes(check)) {
+            failedChecks.push(check);
+        }
+        errors.push(`${label} was unavailable: ${getErrorMessage(cause)}`);
+    };
+    let css;
+    if (cssFilePath) {
+        try {
+            css = await dependencies.readTextFile(cssFilePath, CSS_MAX_BYTES);
+        }
+        catch (cause) {
+            recordFailure("css", "CSS validation", cause);
         }
     }
-    catch (error) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: "text",
-                    text: `Server error executing tool "${name}": ${error.message}`,
+    const [htmlResult, cssResult, seoResult, schemaResult, linksResult] = await Promise.allSettled([
+        dependencies.validateHtmlContent(html),
+        css === undefined ? Promise.resolve([]) : dependencies.validateCssContent(css),
+        Promise.resolve().then(() => dependencies.auditSeoMetadata(html)),
+        Promise.resolve().then(() => dependencies.validateSchemaMarkup(html)),
+        dependencies.checkBrokenLinks(html, baseUrl, 25),
+    ]);
+    if (htmlResult.status === "rejected")
+        recordFailure("html", "HTML validation", htmlResult.reason);
+    if (cssResult.status === "rejected")
+        recordFailure("css", "CSS validation", cssResult.reason);
+    if (seoResult.status === "rejected")
+        recordFailure("seo", "SEO analysis", seoResult.reason);
+    if (schemaResult.status === "rejected")
+        recordFailure("schema", "JSON-LD analysis", schemaResult.reason);
+    if (linksResult.status === "rejected")
+        recordFailure("links", "Link checking", linksResult.reason);
+    return createValidationReport({
+        htmlFilePath,
+        cssAudited: css !== undefined,
+        htmlMessages: htmlResult.status === "fulfilled" ? htmlResult.value : [],
+        cssMessages: cssResult.status === "fulfilled" ? cssResult.value : [],
+        seoIssues: seoResult.status === "fulfilled" ? seoResult.value.slice(0, 200) : [],
+        schemaIssues: schemaResult.status === "fulfilled" ? schemaResult.value.slice(0, 200) : [],
+        links: linksResult.status === "fulfilled" ? linksResult.value : [],
+        failedChecks,
+        errors,
+    });
+}
+export function createServer() {
+    const server = new McpServer({ name: "mcp-web-validator", version: SERVER_VERSION }, {
+        instructions: "Validate only files, markup, and public URLs the user owns or is authorized to inspect. HTML and CSS validation send supplied content to W3C-operated validators. Link checks contact public links without following redirects. Screenshot capture executes page content in a sandboxed local browser and writes PNG files.",
+    });
+    server.registerTool("html.local", {
+        title: "Validate local HTML",
+        description: "Reads a bounded local HTML file and sends its markup to the W3C Nu HTML Checker. Use only files the user is authorized to share.",
+        inputSchema: {
+            filePath: filePathSchema.describe("Absolute or workspace-relative path to an HTML file."),
+        },
+        outputSchema: {
+            errors: z.array(w3cMessageSchema),
+            error: z.string().optional(),
+        },
+        annotations: externalReadOnlyAnnotations,
+    }, async ({ filePath }) => {
+        try {
+            const html = await readTextFile(filePath, HTML_MAX_BYTES);
+            const errors = await validateHtmlContent(html);
+            return result({ errors }, htmlValidationContent(errors));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ errors: [], error }, failureContent("HTML validation", error, "Confirm the file exists and is readable, then retry. If the W3C service is unavailable, try again later."), true);
+        }
+    });
+    server.registerTool("html.url", {
+        title: "Validate a public URL",
+        description: "Fetches a bounded public HTTP(S) page, then sends its markup to the W3C Nu HTML Checker. Private, reserved, credentialed, and nonstandard-port destinations are rejected.",
+        inputSchema: {
+            url: publicUrlSchema.describe("Public HTTP(S) URL on port 80 or 443."),
+        },
+        outputSchema: {
+            errors: z.array(w3cMessageSchema),
+            fetchedUrl: z.string().optional(),
+            error: z.string().optional(),
+        },
+        annotations: externalReadOnlyAnnotations,
+    }, async ({ url }) => {
+        try {
+            const fetched = await fetchPublicText(url, {
+                maxBytes: HTML_MAX_BYTES,
+                timeoutMs: 15_000,
+                maxRedirects: 3,
+                headers: {
+                    accept: "text/html,application/xhtml+xml;q=0.9,text/plain;q=0.5",
+                    "user-agent": `DigestSEO-Web-Validator/${SERVER_VERSION} (+https://digestseo.com/validator-mcp/)`,
                 },
-            ],
-        };
-    }
-});
-// Run server using stdio transport
-async function run() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("mcp-web-validator server successfully started on stdio");
+            });
+            if (fetched.status < 200 || fetched.status >= 300) {
+                throw new Error(`Target URL returned HTTP ${fetched.status}.`);
+            }
+            const errors = await validateHtmlContent(fetched.text);
+            return result({ errors, fetchedUrl: fetched.url }, htmlValidationContent(errors, fetched.url));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ errors: [], error }, failureContent("URL validation", error, "Confirm the URL is public, uses HTTP or HTTPS on a standard port, and returns HTML, then retry."), true);
+        }
+    });
+    server.registerTool("css.local", {
+        title: "Validate local CSS",
+        description: "Reads a bounded local CSS file and sends it to the W3C Jigsaw CSS Validator. Use only files the user is authorized to share.",
+        inputSchema: {
+            filePath: filePathSchema.describe("Absolute or workspace-relative path to a CSS file."),
+        },
+        outputSchema: {
+            errors: z.array(cssMessageSchema),
+            error: z.string().optional(),
+        },
+        annotations: externalReadOnlyAnnotations,
+    }, async ({ filePath }) => {
+        try {
+            const css = await readTextFile(filePath, CSS_MAX_BYTES);
+            const errors = await validateCssContent(css);
+            return result({ errors }, cssValidationContent(errors));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ errors: [], error }, failureContent("CSS validation", error, "Confirm the file exists, is readable, and is within the size limit, then retry."), true);
+        }
+    });
+    server.registerTool("seo.metadata", {
+        title: "Audit SEO metadata",
+        description: "Analyzes supplied HTML locally for metadata, heading structure, viewport configuration, image alternatives, and Open Graph fields.",
+        inputSchema: {
+            htmlContent: htmlContentSchema.describe("Raw HTML markup to inspect locally."),
+        },
+        outputSchema: {
+            issues: z.array(seoIssueSchema),
+            totalIssues: z.number().int().nonnegative(),
+            truncated: z.boolean(),
+            error: z.string().optional(),
+        },
+        annotations: localReadOnlyAnnotations,
+    }, async ({ htmlContent }) => {
+        try {
+            const { issues, totalIssues, truncated } = auditSeoMetadataDetailed(htmlContent);
+            return result({ issues, totalIssues, truncated }, seoAuditContent(issues, totalIssues, truncated));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ issues: [], totalIssues: 0, truncated: false, error }, failureContent("SEO audit", error, "Confirm the supplied HTML is complete and within the size limit, then retry."), true);
+        }
+    });
+    server.registerTool("links.broken", {
+        title: "Check public links",
+        description: "Resolves and checks up to 25 public HTTP(S) links in supplied HTML. Redirects are reported but not followed, and response bodies are discarded.",
+        inputSchema: {
+            htmlContent: htmlContentSchema.describe("Raw HTML markup containing links to check."),
+            baseUrl: publicUrlSchema
+                .optional()
+                .describe("Optional public HTTP(S) base URL used to resolve relative links."),
+            maxLinks: z
+                .number()
+                .int()
+                .min(1)
+                .max(25)
+                .default(25)
+                .describe("Maximum number of public HTTP(S) links to check, from 1 to 25."),
+        },
+        outputSchema: {
+            links: z.array(linkStatusSchema),
+            error: z.string().optional(),
+        },
+        annotations: externalReadOnlyAnnotations,
+    }, async ({ htmlContent, baseUrl, maxLinks }) => {
+        try {
+            const links = await checkBrokenLinks(htmlContent, baseUrl, maxLinks);
+            return result({ links }, linkCheckContent(links, baseUrl));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ links: [], error }, failureContent("Link check", error, "Confirm the base URL is public and the supplied HTML is within the size limit, then retry."), true);
+        }
+    });
+    server.registerTool("schema.markup", {
+        title: "Validate JSON-LD syntax",
+        description: "Parses JSON-LD blocks in supplied HTML locally and reports empty blocks or JSON syntax errors. It does not validate vocabulary semantics.",
+        inputSchema: {
+            htmlContent: htmlContentSchema.describe("Raw HTML containing JSON-LD script blocks."),
+        },
+        outputSchema: {
+            issues: z.array(seoIssueSchema),
+            totalIssues: z.number().int().nonnegative(),
+            truncated: z.boolean(),
+            error: z.string().optional(),
+        },
+        annotations: localReadOnlyAnnotations,
+    }, async ({ htmlContent }) => {
+        try {
+            const { issues, totalIssues, truncated } = validateSchemaMarkupDetailed(htmlContent);
+            return result({ issues, totalIssues, truncated }, schemaValidationContent(issues, totalIssues, truncated, htmlContent));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ issues: [], totalIssues: 0, truncated: false, error }, failureContent("JSON-LD syntax", error, "Confirm the supplied HTML is complete and within the size limit, then retry."), true);
+        }
+    });
+    server.registerTool("report.validation", {
+        title: "Generate a validation report",
+        description: "Combines W3C HTML/CSS validation, local SEO/accessibility checks, JSON-LD syntax checks, and a bounded public-link check into a Markdown and structured report.",
+        inputSchema: {
+            htmlFilePath: filePathSchema.describe("Absolute or workspace-relative HTML file path."),
+            cssFilePath: filePathSchema
+                .optional()
+                .describe("Optional absolute or workspace-relative CSS file path."),
+            baseUrl: publicUrlSchema
+                .optional()
+                .describe("Optional public HTTP(S) base URL used to resolve relative links."),
+        },
+        outputSchema: {
+            report: z.string(),
+            summary: reportSummarySchema,
+            htmlMessages: z.array(w3cMessageSchema),
+            cssMessages: z.array(cssMessageSchema),
+            seoIssues: z.array(seoIssueSchema),
+            schemaIssues: z.array(seoIssueSchema),
+            links: z.array(linkStatusSchema),
+            failedChecks: z.array(z.enum(validationReportChecks)),
+            errors: z.array(z.string()).optional(),
+        },
+        annotations: externalReadOnlyAnnotations,
+    }, async ({ htmlFilePath, cssFilePath, baseUrl }) => {
+        try {
+            const reportData = await generateValidationReport({
+                htmlFilePath,
+                cssFilePath,
+                baseUrl,
+            });
+            return result(reportData, reportContent(reportData));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            const reportData = failedReport(htmlFilePath, error);
+            return result(reportData, failureContent("Validation report", error, "Confirm the input paths are readable and any base URL is public, then regenerate the report."), true);
+        }
+    });
+    server.registerTool("screenshot.capture", {
+        title: "Capture responsive screenshots",
+        description: "Renders a local HTML file or HTTP(S) URL in a sandboxed local Chromium browser and writes PNG screenshots to the requested directory. Existing matching files may be replaced.",
+        inputSchema: {
+            targetPath: z
+                .string()
+                .trim()
+                .min(1)
+                .max(PATH_MAX_LENGTH)
+                .describe("Local HTML path or HTTP(S) URL to render."),
+            outputDir: filePathSchema
+                .optional()
+                .default(".mcp-validator/screenshots")
+                .describe("Directory where PNG screenshots will be written."),
+            viewports: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .regex(/^[A-Za-z0-9_-]{1,50}$/)
+                    .describe("Safe filename label for this screenshot viewport."),
+                width: z
+                    .number()
+                    .int()
+                    .min(200)
+                    .max(3_840)
+                    .describe("Viewport width in CSS pixels, from 200 to 3840."),
+                height: z
+                    .number()
+                    .int()
+                    .min(200)
+                    .max(4_320)
+                    .describe("Viewport height in CSS pixels, from 200 to 4320."),
+            }))
+                .min(1)
+                .max(MAX_VIEWPORTS)
+                .optional()
+                .describe("Optional viewport definitions; defaults to desktop, tablet, and mobile sizes."),
+        },
+        outputSchema: {
+            screenshots: z.array(screenshotSchema),
+            outputDirectory: z.string(),
+            error: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ targetPath, outputDir, viewports }) => {
+        const outputDirectory = path.resolve(outputDir);
+        try {
+            const screenshots = await captureScreenshots(targetPath, outputDirectory, viewports);
+            return result({ screenshots, outputDirectory }, screenshotCaptureContent(screenshots.length, outputDirectory));
+        }
+        catch (cause) {
+            const error = getErrorMessage(cause);
+            return result({ screenshots: [], outputDirectory, error }, failureContent("Screenshot capture", error, "Confirm the target is reachable or readable and the output directory is writable, then retry."), true);
+        }
+    });
+    return server;
+}
+export async function run() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    console.error(`mcp-web-validator ${SERVER_VERSION} started on stdio`);
+}
+const invokedPath = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : undefined;
+if (invokedPath === import.meta.url) {
+    run().catch((cause) => {
+        console.error("Fatal error starting mcp-web-validator:", getErrorMessage(cause));
+        process.exitCode = 1;
+    });
 }
-run().catch((error) => {
-    console.error("Fatal error starting mcp-web-validator server:", error);
-    process.exit(1);
-});
 //# sourceMappingURL=index.js.map