mcp-web-validator 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.2.1] - 2026-09-19
+
+### Changed
+
+- Added current Gemini CLI and GitHub Copilot CLI setup guidance for the local stdio package.
+- Migrated the hosted stateless MCP handler to the supported Agents SDK v2 server-factory path and refreshed current minor/patch dependency resolutions.
+
+### Fixed
+
+- Rejected malformed Nu HTML Checker responses that omit the required `messages` member in both local and hosted validation paths.
+- Rejected malformed non-empty W3C CSS Validator JSON that omits the expected `cssvalidation` envelope.
+- Rejected successful non-HTML responses from local URL validation instead of forwarding arbitrary content to the HTML checker.
+- Removed unsupported exact-one-H1 SEO penalties while retaining heading-structure guidance.
+- Resolved relative links from the document's first valid public `<base href>` when no explicit link-check base URL is provided.
+- Recognized parameterized `application/ld+json` media types, including the standards-defined `profile` parameter, in both local and hosted schema scans.
+
+## [1.2.0] - 2026-09-19
+
+### Added
+
+- Added the hosted `audit_public_site` tool for bounded, sitemap-first, same-origin public-site audits with robots enforcement, page continuation, compact coverage, grouped findings, and a transparent health-score denominator.
+- Added the hosted `audit_public_webpage` tool for one-page live URL audits with bounded public fetching, redirect validation, HTML validation, SEO/accessibility-signal checks, JSON-LD syntax checks, and optional link checks.
+
+### Changed
+
+- Organized local MCP tool names under shallow dot-notation paths and documented every local input, including nested screenshot viewport fields.
+- Upgraded the hosted Worker contract to version 0.5.0 and the results widget to v5.
+- Added a dedicated per-client rate limit for bounded public-site audits and cache-busted the site-aware widget resource.
+- Limited hosted link checks to 20 targets so the worst-case live-page audit remains below the Cloudflare Workers Free subrequest ceiling.
+- Corrected non-mutating external tool annotations, clarified tool-selection metadata, and distinguished checked CSS from CSS that was not supplied.
+- Renamed the hosted HTML diagnostic field from `errors` to `messages` because it contains errors, warnings, and informational notes.
+
+### Fixed
+
+- Prevented client-controlled MCP session IDs from bypassing coarse rate limiting.
+- Added bounded Nu response handling and a structured final Worker error boundary.
+- Corrected warning-only next-step copy and the JSON-LD syntax-check title.
+- Refreshed production dependency resolutions to remove newly disclosed transitive vulnerabilities before publishing the npm release.
+
+## [1.1.0] - 2026-07-12
+
+### Added
+
+- Added concise, tool-specific result summaries with prioritized fixes and clear next steps.
+- Added a shared hosted result overview with truthful status, severity, truncation, schema-block, link-health, and partial-report metadata.
+- Added the responsive v3 ChatGPT results widget with accessible severity groups, clean and partial states, dark-mode support, and expandable findings.
+
+### Changed
+
+- Replaced duplicated raw JSON in local MCP narration with polished Markdown while preserving every structured result field.
+- Upgraded the hosted Worker contract to version 0.3.0 and cache-busted its UI resource.
+
+### Fixed
+
+- Fixed CSS errors being presented as informational results in the hosted widget.
+- Fixed healthy links appearing as problems, missing truncation notices, and partial reports hiding completed checks.
+- Distinguished pages with no JSON-LD from pages whose JSON-LD parsed successfully.
+
+## [1.0.1] - 2026-07-11
+
+### Added
+
+- Automated contract, network-safety, report, and hosted Worker tests in CI.
+- Security reporting and contribution guidance.
+- Machine-readable results for every local MCP tool.
+
+### Changed
+
+- Reworked documentation to distinguish the local npm server from the hosted ChatGPT app.
+- Documented exact runtime tool names, external data recipients, filesystem behavior, and production verification commands.
+- Added bounded file and response sizes, network timeouts, capped link concurrency, public-address checks, and safer screenshot output handling.
+- Upgraded the hosted Worker contract to version 0.2.0 with complete report details, a readable results widget, observability, and rate limiting.
+
+### Fixed
+
+- Fixed local tool calls being rejected because advertised output schemas had no matching `structuredContent`.
+- Fixed relative-link resolution, unbounded link fan-out, unsafe redirect handling, and screenshot filename traversal.
+- Fixed hosted HTML warnings being counted as errors.
+- Reject untrusted browser `Origin` headers at the hosted Streamable HTTP boundary as required by MCP.
+
+## [1.0.0] - 2026-07-11
+
+### Added
+
+- Initial public npm release with HTML and CSS validation, technical SEO and accessibility auditing, JSON-LD parsing, broken-link checks, aggregate reports, and responsive screenshots.

package/README.md

@@ -1,99 +1,96 @@
-# mcp-web-validator
+# Web Validator by DigestSEO
 
 [![npm version](https://img.shields.io/npm/v/mcp-web-validator.svg)](https://www.npmjs.com/package/mcp-web-validator)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/AKzar1el/mcp-web-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/AKzar1el/mcp-web-validator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-akzar1el-mcp-web-validator-4b38b48a/badge.svg)](https://tensorblock.co/mcp/servers/github-akzar1el-mcp-web-validator-4b38b48a)
+[![mcp-web-validator MCP server](https://glama.ai/mcp/servers/AKzar1el/mcp-web-validator/badges/score.svg)](https://glama.ai/mcp/servers/AKzar1el/mcp-web-validator)
 
-Part of the **[DigestSEO](https://digestseo.com/)** suite of open-source SEO tools.
 
-Product home: [digestseo.com/validator-mcp](https://digestseo.com/validator-mcp/)
-· Support: [digestseo.com/support](https://digestseo.com/support/)
+An MCP server for HTML and CSS validation, technical SEO and accessibility checks, JSON-LD syntax validation, broken-link checks, and responsive screenshots. It is part of the [DigestSEO](https://digestseo.com/) suite of open-source SEO tools.
 
-The public, read-only ChatGPT app is hosted at
-`https://web-validator-mcp.digestseo.com/mcp`. It accepts HTML, CSS, and authorized public
-URLs you explicitly supply; the local MCP described below remains the option
-for workspace files and responsive screenshots.
+- Product: [digestseo.com/validator-mcp](https://digestseo.com/validator-mcp/)
+- Engineering case study: [DigestSEO MCP Suite — AI visibility, Search Console, web validation, and trend intelligence](https://tomiseregi.si/projects/digestseo-mcp-suite)
+- Documentation: [this README](https://github.com/AKzar1el/mcp-web-validator#readme)
+- Support: [digestseo.com/support](https://digestseo.com/support/)
+- Privacy: [digestseo.com/privacy](https://digestseo.com/privacy/)
 
-A **Model Context Protocol (MCP) server** that empowers AI coding assistants (like Claude, Cursor, ChatGPT, etc.) to validate HTML/CSS markup against the official W3C specification engine and perform technical SEO/accessibility audits directly inside local workspaces.
+## Choose the right surface
 
----
+This repository contains two deliberately separate MCP surfaces:
 
-## 💬 How It Works (Visual Flow)
+| Surface | Transport | Best for | Access and side effects |
+| --- | --- | --- | --- |
+| Local npm server | stdio | Claude Desktop, Cursor, and other local MCP clients | Can read user-selected workspace files, contact validation and link targets, and write screenshot files. |
+| Hosted app | Streamable HTTP | ChatGPT and remote MCP clients | Can fetch one authorized public HTML page, run a bounded sitemap-first site audit, or process supplied markup. It cannot access local files, authenticate, recursively crawl links, execute page JavaScript, or create screenshots. |
 
-Imagine asking your AI coding assistant:
+Local installation:
 
-> **User:** *"I just finished building my homepage. Can you validate it, check for SEO issues, and take responsive screenshots to see if it looks correct?"*
+```bash
+npx -y mcp-web-validator
+```
+
+Hosted endpoint:
+
+```text
+https://web-validator-mcp.digestseo.com/mcp
+```
+
+## Requirements
 
-Here is the exact flow of how the assistant uses `mcp-web-validator` to audit the code and present results:
+- Node.js 22.12.0 or newer
+- An MCP client that supports stdio, or a client that supports Streamable HTTP for the hosted endpoint
 
-### 1️⃣ Step 1: Technical & SEO Score Card
-The assistant automatically runs `generate_validation_report` which aggregates standard specs and outputs a unified PageSpeed-style scorecard directly in your chat:
+Puppeteer may download a compatible browser during npm installation. The browser is used only by the local `screenshot.capture` tool.
 
-# 📋 Web Validation & SEO Audit Report — 🟢 **92**/100
-*Generated for: `index.html`*
+## Local server tools
 
-#### ⚡ Page Health Scores (PageSpeed Inspired)
-| Score Card | Status | Score |
-| :--- | :---: | :---: |
-| **W3C HTML Validation** | 🟠 Needs Work | **88** / 100 |
-| **SEO & Accessibility** | 🟠 Warnings | **88** / 100 |
-| **Links Integrity** | 🟢 All Good | **100** / 100 |
+The npm package exposes these exact runtime tool names:
 
-### 2️⃣ Step 2: Responsive Viewport Screenshot Audits
-The assistant launches local Puppeteer using `capture_screenshots` to render the page across multiple devices:
+| Tool | Purpose | Network or filesystem behavior |
+| --- | --- | --- |
+| `html.local` | Validate a local HTML file. | Reads the selected file and submits its markup to the external W3C Nu HTML Checker at `validator.w3.org/nu/`. |
+| `html.url` | Validate the markup returned by a public URL. | Fetches the URL, then submits the returned markup to the external Nu checker. |
+| `css.local` | Validate a local CSS file. | Reads the selected file and submits its CSS to the external W3C Jigsaw CSS Validator. |
+| `seo.metadata` | Audit titles, descriptions, canonical tags, headings, viewport metadata, image alt attributes, and Open Graph metadata. | Processes supplied HTML locally. |
+| `links.broken` | Check links extracted from supplied HTML. | Sends bounded HTTP requests to eligible public links. |
+| `schema.markup` | Parse JSON-LD blocks and report JSON syntax errors. | Processes supplied HTML locally. |
+| `report.validation` | Combine HTML, optional CSS, SEO, JSON-LD, and bounded link checks in a Markdown report. | Reads selected files, contacts the validators, and checks eligible public links found in the HTML. |
+| `screenshot.capture` | Capture desktop, tablet, mobile, or custom viewport screenshots. | Opens a selected local file or eligible public URL and writes PNG files to the selected output directory; existing matching files may be replaced. |
 
-| Desktop (1440x900) | Tablet (768x1024) | Mobile (375x812) |
-| :---: | :---: | :---: |
-| 🖥️ `desktop.png` | 📟 `tablet.png` | 📱 `mobile.png` |
+## Hosted app tools
 
----
+The hosted app exposes eight tools:
 
-## ✨ Features
+| Tool | Purpose |
+| --- | --- |
+| `audit_public_webpage` | Fetch one authorized public HTML page and run the combined HTML, SEO/accessibility-signal, and JSON-LD syntax audit. Link checks are optional. |
+| `audit_public_site` | Run a bounded sitemap-first audit of up to eight authorized, same-origin public pages. It respects `robots.txt`, returns compact page coverage and deduplicated findings, and does not run site-wide link checks. |
+| `validate_html` | Validate raw HTML markup already supplied in the conversation. |
+| `validate_css` | Parse supplied CSS for syntax errors inside the Worker. |
+| `audit_seo_metadata` | Audit supplied HTML for covered on-page SEO and accessibility signals. |
+| `validate_schema_markup` | Check JSON-LD blocks in supplied HTML for JSON syntax errors. |
+| `check_broken_links` | Check up to 20 authorized public links extracted from supplied HTML. |
+| `generate_validation_report` | Combine the checks for supplied markup; `base_url` resolves relative links but does not fetch a page. |
 
-- **HTML Validation**: Leverages the official W3C Nu HTML Checker API (no API keys required).
-- **CSS Validation**: Calls the W3C Jigsaw CSS Validator API to debug stylesheets.
-- **Technical SEO Check**: Audits title/description lengths, viewport responsiveness, heading hierarchies, Open Graph metadata, and image alt attributes.
-- **Broken Link Checker**: Scans HTML documents for broken internal or external URLs.
-- **Schema Validator**: Parses and validates embedded JSON-LD structured schemas.
-- **Visual Viewport Audits**: Uses a headless Puppeteer browser locally to capture responsive layout screenshots (desktop, tablet, mobile) for design auditing.
+`audit_public_webpage` follows at most three validated redirects, accepts a bounded `text/html` response, and records the final URL. It does not crawl additional pages, execute JavaScript, authenticate, or fetch linked stylesheets and assets. `audit_public_site` first locks the final public origin, reads bounded same-origin `robots.txt` and XML sitemap documents, then audits at most eight eligible sitemap pages in one call. It never follows HTML links, subdomains, external sitemap entries, private/reserved destinations, custom ports, or cross-origin redirects; use `page_offset` when the response says more eligible pages remain. The fetched HTML is sent to `https://html5.validator.nu/`, the same external Nu HTML Checker used by `validate_html` and the report tool. CSS parsing, SEO analysis, and JSON-LD parsing run inside the DigestSEO Worker. Optional link checks make capped `HEAD` requests, with a bounded `GET` fallback where necessary, to eligible public HTTP(S) URLs; link redirects are reported but not followed. The site tool intentionally does not perform site-wide link checking. The hosted app does not retain tool inputs, fetched HTML, or results.
 
----
+## Privacy Policy
 
-## 🛠️ Tools Exposed
+Only validate files, markup, and public webpages that you own or are authorized to inspect. Public page URLs can contain sensitive query values, so remove tokens and private identifiers before submitting them. Do not submit passwords, API keys, access tokens, payment data, health data, private source code, or other sensitive personal data.
 
-1. `validate_local_html`
-   - **Arguments**: `filePath: string` (Absolute or relative path to the local HTML file)
-   - **Description**: Submits local HTML to the W3C Nu Checker and returns syntax errors/warnings.
-2. `validate_url`
-   - **Arguments**: `url: string` (The live public URL to audit)
-   - **Description**: Validates live page markup against W3C standards.
-3. `validate_local_css`
-   - **Arguments**: `filePath: string` (Absolute or relative path to the CSS file)
-   - **Description**: Checks local CSS syntax against the W3C Jigsaw API.
-4. `audit_seo_metadata`
-   - **Arguments**: `htmlContent: string` (Raw HTML string)
-   - **Description**: Performs a fast, local SEO audit (titles, descriptions, headings, images, alt tags).
-5. `check_broken_links`
-   - **Arguments**: `htmlContent: string`, `baseUrl?: string`
-   - **Description**: Tests all links in the document to detect 404s or broken URLs.
-6. `validate_schema_markup`
-   - **Arguments**: `htmlContent: string`
-   - **Description**: Validates JSON-LD schema syntax.
-7. `generate_validation_report`
-   - **Arguments**: `htmlFilePath: string`, `cssFilePath?: string`, `baseUrl?: string`
-   - **Description**: Automatically runs all checks (HTML/CSS syntax, SEO audit, JSON-LD, broken links) and generates a unified Markdown report card styled with PageSpeed-inspired scoring.
-8. `capture_screenshots`
-   - **Arguments**: `targetPath: string` (Path to local HTML file or HTTP(S) URL), `outputDir?: string`, `viewports?: Array<{ name: string, width: number, height: number }>`
-   - **Description**: Renders the target in a local headless browser and saves screenshots across desktop, tablet, and mobile views.
+The local server runs with the same operating-system permissions as its MCP client. Review tool inputs before approving file access, outbound validation, link checking, or screenshot creation. The hosted app has no access to your local filesystem.
 
----
+See the published [privacy policy](https://digestseo.com/privacy/) for data-handling details and [SECURITY.md](SECURITY.md) for private vulnerability reporting.
 
-## 🚀 Configuration
+## Configure a local client
 
-### 1. Claude Desktop
-Add this to your `claude_desktop_config.json`:
+### Claude Desktop
 
-* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Add the server to `claude_desktop_config.json`:
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
 ```json
 {
@@ -106,24 +103,93 @@ Add this to your `claude_desktop_config.json`:
 }
 ```
 
-### 2. Cursor
-To use this inside **Cursor**, navigate to **Settings > Features > MCP**:
-1. Click **+ Add New MCP Server**.
-2. Set Name: `mcp-web-validator`
-3. Set Type: `command`
-4. Set Command: `npx -y mcp-web-validator`
+Restart Claude Desktop after saving the configuration.
+
+### Cursor and compatible clients
+
+Create a command/stdio MCP server with:
+
+```text
+npx -y mcp-web-validator
+```
+
+This repository also includes a Cursor Marketplace plugin manifest. After the
+plugin is published, install **Web Validator by DigestSEO** from Cursor's
+Marketplace or add the repository from Cursor's plugin UI. The plugin bundles
+the same local stdio server and does not require API keys or environment
+variables.
+
+### Gemini CLI
+
+Gemini CLI supports local stdio MCP servers. Add the published package with:
+
+```bash
+gemini mcp add mcp-web-validator npx -y mcp-web-validator
+```
+
+This writes the server definition to Gemini CLI's MCP configuration. No API
+keys or environment variables are required by Web Validator.
+
+### GitHub Copilot CLI
+
+Add the published local stdio server with:
+
+```bash
+copilot mcp add mcp-web-validator -- npx -y mcp-web-validator
+```
+
+When Copilot CLI is started inside a clone of this repository, it can also
+discover the checked-in root `.mcp.json`, which already points
+`mcp-web-validator` at `npx -y mcp-web-validator`.
+
+### Kiro
+
+[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-web-validator&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-web-validator%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
+
+This installs the local stdio package, preserving its workspace-file and screenshot capabilities. Node.js 22.12.0+ is required.
+
+## Development
+
+Clone the repository and install the locked dependencies:
 
-### 3. Development / Local Execution
-To run and test the server locally:
 ```bash
 git clone https://github.com/AKzar1el/mcp-web-validator.git
 cd mcp-web-validator
-npm install
+npm ci
+```
+
+Run the local quality gates:
+
+```bash
+npm run check
+npm test
 npm run build
-node dist/index.js
+npm pack --dry-run
 ```
 
----
+Run the local stdio server:
+
+```bash
+npm start
+```
+
+Validate the hosted Worker separately:
+
+```bash
+cd chatgpt-plugin
+npm ci
+npm run check
+npm test
+npm run deploy:dry-run
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution expectations. Deployment and marketplace-review notes live in [chatgpt-plugin/SUBMISSION.md](chatgpt-plugin/SUBMISSION.md).
+For agent-assisted installation, see [llms-install.md](llms-install.md).
+
+## Ecosystem
+
+[![smithery badge](https://smithery.ai/badge/digestseo/web-validator)](https://smithery.ai/servers/digestseo/web-validator)
+
+## License
 
-## 📄 License
-This project is licensed under the MIT License - see the LICENSE file for details.
+Licensed under the [MIT License](LICENSE).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the current npm release of `mcp-web-validator` and the currently deployed hosted endpoint at `https://web-validator-mcp.digestseo.com/mcp`. Older npm versions are not supported; upgrade to the latest published version before reporting a problem that may already be fixed.
+
+## Report a vulnerability privately
+
+Do not open a public GitHub issue for a suspected vulnerability.
+
+Use [GitHub private vulnerability reporting](https://github.com/AKzar1el/mcp-web-validator/security/advisories/new). If that form is unavailable, email `tomi.seregi99@gmail.com` with the subject `Security report: mcp-web-validator`. Do not include secrets or unrelated personal data.
+
+Include, where possible:
+
+- the affected surface (local npm server, hosted Worker, website, or packaging metadata);
+- the affected version, commit, endpoint, and tool name;
+- reproducible steps or a minimal proof of concept;
+- the expected and observed impact;
+- any suggested mitigation; and
+- whether the issue has been disclosed elsewhere.
+
+Please avoid accessing data that is not yours, disrupting the public service, or including credentials or personal data in the report. We aim to acknowledge complete reports within three business days and will coordinate remediation and disclosure with the reporter.
+
+## Security boundaries
+
+The local stdio server runs with the permissions of the MCP client that launches it. Its documented features can read user-selected files, make outbound validation and link-check requests, open local files or public URLs in a headless browser, and write screenshot files. Users should review every sensitive tool call and run MCP clients with least privilege.
+
+The hosted app cannot access local files. It can process raw HTML or CSS supplied by the user, fetch one authorized public HTML webpage for a focused audit, and perform a bounded sitemap-first same-origin public-site audit. That audit first fetches the seed page to lock the final public origin, then may retrieve `robots.txt`, eligible same-origin XML sitemap documents, and up to eight eligible same-origin public HTML pages per request. It rejects private or reserved addresses, credentialed URLs, custom ports, external sitemap entries, subdomains, and cross-origin redirects for the site audit. It does not authenticate, execute webpage JavaScript, recursively follow arbitrary HTML links, fetch arbitrary linked assets or stylesheets, or perform site-wide broken-link crawling. Supplied or fetched HTML validation payloads may be sent to the external [Nu HTML Checker](https://html5.validator.nu/); focused authorized broken-link checks may contact eligible public link URLs. See the [privacy policy](https://digestseo.com/privacy/) for data-handling details.
+
+The following are normally outside this project's vulnerability scope unless they expose a project-specific weakness:
+
+- availability or behavior of third-party validation services;
+- social-engineering reports without a technical vulnerability;
+- automated scanner output without a reproducible impact; and
+- denial-of-service testing against the production endpoint without prior written permission.

package/dist/index.d.ts

@@ -1,2 +1,25 @@
 #!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { auditSeoMetadata, checkBrokenLinks, validateSchemaMarkup } from "./seo-auditor.js";
+import { type ValidationReport } from "./report.js";
+import { readTextFile } from "./network.js";
+import { validateCssContent, validateHtmlContent } from "./w3c-validator.js";
+export declare const SERVER_VERSION: string;
+interface ValidationReportDependencies {
+    readTextFile: typeof readTextFile;
+    validateHtmlContent: typeof validateHtmlContent;
+    validateCssContent: typeof validateCssContent;
+    auditSeoMetadata: typeof auditSeoMetadata;
+    validateSchemaMarkup: typeof validateSchemaMarkup;
+    checkBrokenLinks: typeof checkBrokenLinks;
+}
+export interface GenerateValidationReportOptions {
+    htmlFilePath: string;
+    cssFilePath?: string;
+    baseUrl?: string;
+}
+/** Runs independent validation checks without discarding successful results when another check fails. */
+export declare function generateValidationReport({ htmlFilePath, cssFilePath, baseUrl }: GenerateValidationReportOptions, dependencies?: ValidationReportDependencies): Promise<ValidationReport>;
+export declare function createServer(): McpServer;
+export declare function run(): Promise<void>;
 export {};