# ZERONOVA LAB MCP Server

MCP Server for [ZERONOVA LAB](https://zeronova-lab.com) tools — SEO audit, link checking, OGP validation, config file generation, and more for AI agents.

## Features

### Tier 1: Individual Tools (17 tools)

Single-purpose tools for web page analysis and local project security scanning:

#### Web Inspection (12 tools)

| Tool | Description |
|------|-------------|
| `check_alt_attributes` | Check alt attributes of all images on a webpage |
| `check_links` | Check all links on a webpage for broken URLs |
| `check_page_speed` | Analyze webpage performance and accessibility using PageSpeed Insights |
| `check_ogp` | Check OGP, Twitter Card meta tags, canonical URL, JSON-LD, and favicon |
| `extract_headings` | Extract H1-H6 heading hierarchy |
| `check_x_card` | Check X (Twitter) Card settings and validation |
| `check_site_config` | Check robots.txt and XML sitemap configuration |
| `check_security_headers` | Check 6 HTTP security headers (HSTS, CSP, etc.) with scoring |
| `check_cache_headers` | Check browser/CDN cache headers with scoring |
| `check_schema_completeness` | Check structured data completeness against Schema.org requirements |
| `check_redirect_chain` | Trace redirect chain with loop and HTTP downgrade detection |
| `check_image_optimization` | Check image optimization (format, size, lazy loading, dimensions) with scoring |

#### Vibe Audit — Internal Code Audit (5 tools)

Local project security scanning tools. Read project files only — no HTTP calls.

| Tool | Description |
|------|-------------|
| `check_env_exposure` | Check .env files for secret leaks (Supabase service_role, Stripe, AWS, DB URL, OpenAI, GitHub tokens), verify .gitignore exclusion, .env.example best practice |
| `check_rls_config` | Check Supabase RLS configuration in SQL migrations: ENABLE/FORCE RLS, policy definitions, detect permissive USING(true) anti-pattern |
| `check_api_auth` | Check API route authentication for Next.js App Router and Pages Router: detect 20+ auth patterns, global middleware auth, recognize public routes |
| `check_client_secrets` | Detect secrets exposed in client-side code: NEXT_PUBLIC_ env vars with service keys, hardcoded Stripe/AWS/OpenAI/GitHub/PEM keys |
| `check_injection_risk` | Detect injection risks across 3 categories (SQL: 3 patterns, XSS: 3 patterns, Command: 4 patterns) with context lines and line numbers |

**Vibe Audit features:**
- Path traversal prevention, symlink blocking, 1MB file size limit, 100-file scan limit
- Secret values are masked in output (first 4 + last 4 chars)
- Findings include severity, file path, evidence, and copy-pasteable fix code

### Tier 2: Workflow Tools (4 tools)

"Workflow as a Tool" — chain multiple Tier 1 tools in a single call for comprehensive audits:

| Tool | Description |
|------|-------------|
| `run_seo_audit` | Comprehensive SEO audit with scoring (0-100). Chains 10 tools into a unified report with 20 auto-verified items. |
| `run_web_launch_audit` | Pre-launch quality audit. Chains 11 tools for SEO, performance, accessibility, caching, image optimization, and branding checks (21 auto + 1 manual items). |
| `run_freelance_delivery_audit` | Pre-delivery audit for freelance projects. Chains 8 tools for quality, SEO, accessibility, security, and optimization checks (12 auto + 3 manual items). |
| `run_vibe_audit` | Security audit for vibe-coded projects. Chains 5 internal code audit tools into a scored report (0-100) with per-finding severity (critical: -20, high: -10, medium: -5, low: -2). |

**Workflow features:**
- Checklist-driven evaluation with weighted scoring (pass = full weight, warn = half, fail = 0)
- Partial failure resilience — individual tool failures don't stop the workflow
- Progress reporting via MCP `notifications/progress` protocol
- Bot-blocked links (e.g. X/Twitter 403) are distinguished from true broken links

### Tier 3: Config File Generation Tools (5 tools)

"Config as a Tool" — AI agents can safely generate validated configuration files:

| Tool | Description |
|------|-------------|
| `generate_robots_txt` | Generate a valid robots.txt file from structured input (sitemap URL, disallow/allow paths, user-agent, crawl-delay) |
| `generate_sitemap_xml` | Generate a valid XML sitemap from URL list (up to 50,000 entries with lastmod, changefreq, priority) |
| `generate_htaccess` | Generate an Apache .htaccess file with redirect rules (301/302/307/308), gzip compression, cache control, force HTTPS, trailing slash removal |
| `generate_jsonld` | Generate Schema.org-compliant JSON-LD structured data (16 schema types supported) |
| `generate_meta_tags` | Generate SEO-optimized HTML meta tags (title, description, keywords, OGP, Twitter Card, canonical URL) with SEO analysis |

**Generation features:**
- Output validation per file format (robots.txt directives, XML structure, Apache syntax, JSON parseability, HTML escaping)
- Injection prevention (RewriteRule metacharacter blocking, XML entity escaping, `</script>` XSS prevention, HTML attribute escaping)
- No browser-dependent APIs — safe for Node.js / MCP execution
- 10-second timeout safety net

## Installation

### Claude Code

Add to your Claude Code settings:

```json
{
  "mcpServers": {
    "zeronova-lab": {
      "command": "npx",
      "args": ["-y", "zeronova-lab-mcp"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zeronova-lab": {
      "command": "npx",
      "args": ["-y", "zeronova-lab-mcp"]
    }
  }
}
```

### Manual

```bash
# Run directly
npx zeronova-lab-mcp

# Or install globally
npm install -g zeronova-lab-mcp
zeronova-lab-mcp
```

## Tool Details

### Tier 1 Tools

#### check_alt_attributes

Check alt attributes of all images on a webpage.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** List of images with alt attribute status (present/empty/missing/decorative) and summary counts.

#### check_links

Check all links on a webpage for broken URLs.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** List of links with HTTP status codes, external/internal classification, and warnings for known blocking domains.

#### check_page_speed

Analyze webpage performance and accessibility using Google PageSpeed Insights.

**Parameters:**
- `url` (required): Target webpage URL
- `strategy` (optional): `"mobile"` or `"desktop"` (default: `"mobile"`)

**Returns:** Performance score (0-100), Core Web Vitals (FCP, LCP, TBT, CLS, SI, TTI), top optimization opportunities, accessibility score, and color-contrast violations (snippet + explanation, up to 10 items).

#### check_ogp

Check Open Graph Protocol, Twitter Card meta tags, canonical URL, JSON-LD structured data, and favicon.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** OGP data (title, description, image, url, type, siteName), Twitter Card data with fallback chain resolution, canonical URL (`<link rel="canonical">`), JSON-LD items (type, validity, raw content), and favicon data (icon tags, apple-touch-icon detection, `/favicon.ico` existence check).

#### extract_headings

Extract all headings (H1-H6) from a webpage.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Heading hierarchy with level and text for each heading.

#### check_x_card

Check X (Twitter) Card settings for a webpage.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Card data, validation results with specific issues, and OGP fallback values.

#### check_site_config

Check robots.txt and XML sitemap configuration for a website.

**Parameters:**
- `url` (required): Target webpage URL (domain is extracted automatically)

**Returns:** robots.txt status (exists, content, rules count, Sitemap directives, issues) and sitemap.xml status (exists, URL count, sitemap index detection, issues).

#### check_security_headers

Check HTTP security headers for a website.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** 6 security headers (Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy) with pass/warn/fail status, header values, and overall security score (0-100).

#### check_cache_headers

Check browser and CDN cache headers for a webpage.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Cache-related headers (Cache-Control, ETag, Last-Modified, Expires, Vary, CDN-Cache-Status, CF-Cache-Status) with category (browser/cdn/validation), pass/warn/fail status, and overall cache score (0-100). Includes browser cache and CDN cache status detection.

#### check_schema_completeness

Check structured data (JSON-LD / microdata) completeness against Schema.org requirements.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** List of detected schemas with type, source (json-ld/microdata), property presence (required/optional), pass/warn/fail status per schema, issues list, and overall completeness score (0-100).

#### check_redirect_chain

Trace the redirect chain for a URL.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Redirect hops with URL, HTTP status code, Location header, and server header. Summary includes total hops, final URL, final status, loop detection, HTTP downgrade detection, and chain status (pass/warn/fail).

#### check_image_optimization

Check image optimization for a webpage.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** List of images with src, alt, width/height attributes, lazy loading, format, file size, pass/warn/fail status, and issues. Summary includes next-gen format rate, lazy loading rate, dimension rate, and overall optimization score (0-100).

#### check_env_exposure

Check environment variable security in a project.

**Parameters:**
- `project_path` (required): Absolute path to the project directory

**Returns:** Findings for .env secret leaks (Supabase service_role, Stripe, AWS, database URL, OpenAI, GitHub tokens), .gitignore exclusion status, and .env.example best practice. Evidence values are masked for security.

#### check_rls_config

Check Supabase Row Level Security (RLS) configuration in a project.

**Parameters:**
- `project_path` (required): Absolute path to the project directory

**Returns:** Findings for tables without RLS enabled, tables with RLS but no policies, permissive USING(true) anti-patterns, and missing FORCE ROW LEVEL SECURITY. Includes fix SQL snippets.

#### check_api_auth

Check API route authentication in a Next.js project.

**Parameters:**
- `project_path` (required): Absolute path to the project directory

**Returns:** Findings for unprotected API routes (App Router route.ts, Pages Router pages/api/). Detects 20+ auth patterns (NextAuth, Supabase Auth, Passport, JWT), global middleware auth, and public route exclusions (health, webhooks). Includes fix code snippets.

#### check_client_secrets

Detect secrets exposed in client-side code.

**Parameters:**
- `project_path` (required): Absolute path to the project directory

**Returns:** Findings for dangerous NEXT_PUBLIC_ env vars (service_role, database URL, Stripe secret), hardcoded API keys (Supabase, Stripe, AWS, OpenAI, GitHub, PEM) in client-side files. Distinguishes client-side (fail) from server-side (warn) findings.

#### check_injection_risk

Detect injection vulnerabilities in source code.

**Parameters:**
- `project_path` (required): Absolute path to the project directory

**Returns:** Findings for SQL injection (template literal interpolation, string concatenation, raw queries), XSS (dangerouslySetInnerHTML, innerHTML, document.write), and command injection (exec with interpolation, eval, spawn with shell:true, new Function). Includes file path with line number and evidence snippet.

### Tier 2 Tools

#### run_seo_audit

Comprehensive SEO audit that chains 10 tools into a unified report with scoring.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Audit report with:
- 20 auto-verified checklist items: meta title/description, canonical URL, JSON-LD, robots.txt, XML sitemap, H1 uniqueness, heading hierarchy, alt attributes, performance score, LCP, CLS, OGP image, Twitter Card/image, broken links, cache headers, structured data completeness, redirect chain, image optimization
- Weighted score (0-100)

#### run_web_launch_audit

Pre-launch quality audit for websites about to go live. Chains 11 Tier 1 tools.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Audit report with:
- 21 auto-verified checklist items: meta tags, OGP, Twitter Card, heading structure, robots.txt, sitemap, JSON-LD, performance, LCP, CLS, broken links, alt attributes, color contrast, favicon, security headers, cache headers, structured data completeness, image optimization, redirect chain
- 1 manual check item: OGP brand design
- Weighted score (0-100)

#### run_freelance_delivery_audit

Pre-delivery audit for freelance web projects. Chains 8 Tier 1 tools.

**Parameters:**
- `url` (required): Target webpage URL

**Returns:** Audit report with:
- 12 auto-verified checklist items: broken links, page speed, alt attributes, H1, meta title, meta description, OGP image, color contrast, favicon, security headers, image optimization, redirect chain
- 3 manual check items: proofreading, invoice, pricing
- Weighted score (0-100)

#### run_vibe_audit

Run a comprehensive security audit on a local project (Vibe Audit). Designed for vibe-coded projects using Next.js + Supabase.

**Parameters:**
- `project_path` (required): Absolute path to the project directory (must be a project you own or manage)

**Returns:** Scored security report (0-100) with:
- 5 tool results (env exposure, RLS config, API auth, client secrets, injection risk)
- Per-finding severity deductions (critical: -20, high: -10, medium: -5, low: -2)
- Exact file paths, masked evidence snippets, and copy-pasteable fix code
- Progress notifications during execution
- Partial failure resilience — individual tool errors don't stop the workflow

### Tier 3 Tools

#### generate_robots_txt

Generate a valid robots.txt file from structured input.

**Parameters:**
- `sitemapUrl` (optional): Sitemap URL (must start with http:// or https://)
- `disallowPaths` (optional): Paths to block from crawling (max 100)
- `allowPaths` (optional): Paths to allow crawling (max 100)
- `userAgent` (optional): Target user-agent (default: `"*"`)
- `crawlDelay` (optional): Crawl-delay in seconds (0-60)

**Returns:** Generated robots.txt content, line count, and validation results. Path sanitization removes control characters and ensures leading slash.

#### generate_sitemap_xml

Generate a valid XML sitemap from a list of URLs.

**Parameters:**
- `urls` (required): Array of URL entries (1-50,000), each with:
  - `url` (required): Page URL
  - `lastmod` (optional): Last modification date (YYYY-MM-DD or W3C datetime)
  - `changefreq` (optional): Expected change frequency
  - `priority` (optional): URL priority (0.0-1.0)

**Returns:** Generated XML sitemap content, URL count, byte size, and validation results. XML special characters are safely escaped as entities.

#### generate_htaccess

Generate an Apache .htaccess file with redirect rules, cache control, and compression.

**Parameters:**
- `redirectRules` (optional): Redirect rules (max 100), each with `from`, `to`, and optional `statusCode` (301/302/307/308)
- `cacheControl` (optional): Cache rules per file extension (max 20), each with `extension` and `maxAge`
- `compressionEnabled` (optional): Enable gzip compression
- `forceHttps` (optional): Add HTTP to HTTPS redirect
- `removeTrailingSlash` (optional): Add trailing slash removal rule

**Returns:** Generated .htaccess content, line count, and validation results. Injection prevention blocks backtick execution, `$()` substitution, `%{ENV:}` injection, newline injection, and null bytes in RewriteRule patterns.

#### generate_jsonld

Generate Schema.org-compliant JSON-LD structured data.

**Parameters:**
- `schemaType` (required): Schema.org type (Article, BlogPosting, Product, Organization, Person, LocalBusiness, WebSite, WebPage, FAQPage, BreadcrumbList, SoftwareApplication, Event, Recipe, VideoObject, HowTo, Course)
- `data` (required): Schema.org properties as key-value pairs
- `includeGraph` (optional): Wrap output in `@graph` array

**Returns:** Generated JSON-LD content (raw JSON + `<script>` tag), schema type, and validation results (JSON parseability, required fields check, type validation). Uses `JSON.stringify` for safe serialization with `</script>` XSS prevention.

#### generate_meta_tags

Generate SEO-optimized HTML meta tags.

**Parameters:**
- `title` (required): Page title (recommended: 30-60 characters)
- `description` (required): Meta description (recommended: 70-160 characters)
- `keywords` (optional): SEO keywords (max 30)
- `ogpData` (optional): Open Graph Protocol data (title, description, image, url, type, siteName, locale)
- `twitterCard` (optional): Twitter Card data (card, site, creator, title, description, image)
- `canonicalUrl` (optional): Canonical URL
- `charset` (optional): Character encoding (default: `"UTF-8"`)
- `viewport` (optional): Viewport content (default: `"width=device-width, initial-scale=1.0"`)
- `robots` (optional): Robots directive

**Returns:** Generated HTML meta tags, tag count, SEO analysis (title/description length status), and validation results. HTML attribute escaping prevents injection.

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ZERONOVA_API_URL` | `https://zeronova-lab.com` | API base URL. Set to `http://localhost:3000` for local development. |

Example with custom API URL:

```json
{
  "mcpServers": {
    "zeronova-lab": {
      "command": "npx",
      "args": ["-y", "zeronova-lab-mcp"],
      "env": {
        "ZERONOVA_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

## Security

- **SSRF Protection**: URLs are validated for protocol (http/https only), private IP ranges (localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16), and `.local`/`.internal` domain suffixes are blocked. API routes use `redirect: "manual"` with per-hop validation.
- **File System Safety** (Vibe Audit): Path traversal prevention (`..` blocked, `resolve()`/`relative()` validation), symlink blocking (`lstat`), 1MB file size limit, 100-file scan limit, read-only operations only.
- **Rate Limiting**: Each tool is limited to **10 requests per minute** locally. The ZERONOVA LAB API also enforces its own rate limits.
- **Response Validation**: All API responses are validated against Zod schemas to detect format changes early.
- **Error Sanitization**: Internal paths, stack traces, and API URLs are never exposed in error messages.

## Requirements

- Node.js >= 18.0.0

## License

MIT