# Web Validator by DigestSEO

[![npm version](https://img.shields.io/npm/v/mcp-web-validator.svg)](https://www.npmjs.com/package/mcp-web-validator)
[![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)


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.

- 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/)

## Choose the right surface

This repository contains two deliberately separate MCP surfaces:

| 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. |

Local installation:

```bash
npx -y mcp-web-validator
```

Hosted endpoint:

```text
https://web-validator-mcp.digestseo.com/mcp
```

## Requirements

- Node.js 22.12.0 or newer
- An MCP client that supports stdio, or a client that supports Streamable HTTP for the hosted endpoint

The validation, SEO, schema, link, and report tools do not download a browser during installation. The local `screenshot.capture` tool installs its pinned headless browser into Puppeteer's cache on first use, then reuses that browser for later screenshots. Set `PUPPETEER_CACHE_DIR` if you need a custom cache location.

## Tools

The npm package exposes these exact runtime tool names:

| Tool | Purpose | Network or filesystem behavior |
| --- | --- | --- |
| `html.local` | Validate a local HTML or XHTML file. | Reads the selected file and submits its markup to the external W3C Nu HTML Checker at `validator.w3.org/nu/`; `.xhtml` paths use `application/xhtml+xml` parsing semantics. |
| `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, robots noindex directives, 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/XHTML, 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 markup; `.xhtml` inputs use XHTML parsing semantics for Nu validation. |
| `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. |

## Hosted app tools

The hosted app exposes eight tools:

| 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, robots noindex, 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. |

`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, then reads bounded `robots.txt` plus same-origin XML Sitemap, RSS 2.0, Atom 1.0, and plain-text sitemap representations before auditing at most eight eligible sitemap pages in one call. Robots discovery may follow up to five validated public redirects across authorities, as defined by the robots protocol; the resulting rules and relative Sitemap directives are still interpreted for the originally audited authority. Sitemap entries and audited pages remain same-origin, and private/reserved destinations, credentials, custom ports, service self-fetches, and HTTPS-to-HTTP redirect downgrades are rejected. The tool never follows HTML links or external sitemap entries; 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

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.

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.

## Configure a local client

### Claude Desktop

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
{
  "mcpServers": {
    "mcp-web-validator": {
      "command": "npx",
      "args": ["-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.

### OpenAI Codex

Codex CLI can add the published local stdio package directly:

```bash
codex mcp add mcp-web-validator -- npx -y mcp-web-validator
```

Or add the existing hosted Streamable HTTP surface instead:

```bash
codex mcp add mcp-web-validator-hosted --url https://web-validator-mcp.digestseo.com/mcp
```

Verify either configuration with:

```bash
codex mcp list
```

The local package includes workspace-file validation and responsive screenshot
capture. The hosted surface is remote-only and cannot access local files or
create screenshots.

### 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:

```bash
git clone https://github.com/AKzar1el/mcp-web-validator.git
cd mcp-web-validator
npm ci
```

Run the local quality gates:

```bash
npm run check
npm test
npm run build
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

Licensed under the [MIT License](LICENSE).