# Heading Structure Validator MCP

> Heading Structure Validator checks your HTML outline for structural integrity, keyword placement, and content richness. It tells you if your headings follow proper rules—like H2 after an H1—and provides a score showing how deep and varied your information is. Use it when you need to audit page structure for SEO or accessibility compliance.

## Overview
- **Category:** web-development
- **Price:** Free
- **Tags:** html, headings, seo, accessibility, web-audit

## Description

Writing good web content isn't just about filling space; it's about making sure search engines can actually read the hierarchy. This MCP audits webpage document outlines, giving you a clear picture of structural integrity. You feed it your heading data, and it checks everything: whether levels are skipped, if you repeated H1 tags accidentally, or if critical keywords are missing from key sections. It even calculates semantic density to measure how rich your content is across different headings. When you use this MCP through Vinkius's catalog, your agent handles the whole process. You get instant feedback on compliance and structure, letting you fix technical SEO issues before a human ever sees the page.

## Prompt Examples

**Prompt:** 
```
Check if this list of headings has any hierarchy errors: [{'level': 'h1', 'text': 'Title'}, {'level': 'h3', 'text': 'Subtitle'}]
```

**Response:** 
```
The hierarchy is invalid because an H3 follows an H1, skipping the H2 level.
```

**Prompt:** 
```
Are the keywords 'SEO' and 'HTML' present in my headings?
```

**Response:** 
```
Yes, both 'SEO' and 'HTML' were found in your heading structure.
```

**Prompt:** 
```
Calculate the semantic density for these headings: [{'level': 'h1', 'text': 'Main Title'}, {'level': 'h2', 'text': 'Section 1'}]
```

**Response:** 
```
The density score for h1 is 1.0 and for h2 is 1.0.
```

## Capabilities

### Audit heading nesting
Checks if headings follow proper structural rules by detecting skipped levels or multiple top-level tags.

### Confirm keyword presence
Verifies that required SEO keywords are actually included in your heading structure.

### Assess content depth score
Generates a numerical density score to measure the variety and informational richness across different heading levels.

## Use Cases

### The client needs an instant SEO health report.
A content manager provides a list of 50 headings. They ask their agent to run `verify_keywords` and `check_hierarchy`. The agent immediately reports that 12 keywords are missing and three sections violate the H1-H6 structure, saving hours of manual QA.

### The dev team needs a pre-launch structural gate.
A developer pastes raw heading data from a new page draft. They use `check_hierarchy` to ensure no level jumps occurred (like H1 straight to H3). The agent flags the issue, preventing a bad structure bug from ever reaching staging.

### The strategist needs proof of content depth.
A copywriter finishes a long article draft. They use `calculate_semantic_density` on the headings to prove the topic is covered comprehensively. The agent gives them the score, allowing them to justify adding a missing H2 section.

### Auditing an old site with mixed standards.
An auditor inputs data from several pages across different years. They run all three checks—`check_hierarchy`, `verify_keywords`, and `calculate_semantic_density`—to get a single, unified report on the entire site's structural weaknesses.

## Benefits

- Fix structural errors instantly. Use `check_hierarchy` to immediately spot skipped levels or multiple H1s that hurt your page's score.
- Boost search visibility with targeted checks. Run `verify_keywords` against your headings to confirm you’re hitting all necessary SEO terms.
- Measure content depth objectively. Get a density score using `calculate_semantic_density` so you know exactly how rich your writing is.
- Save time on manual audits. Instead of manually inspecting code, let your agent handle the entire structural review process in one go.
- Improve accessibility compliance. By validating proper nesting and structure, you're building sites that are easier for screen readers to use.

## How It Works

The bottom line is that you get an immediate, actionable audit of your page's structure without having to manually check every tag.

1. Provide your agent with a list of headings, including their HTML level (H1, H2, etc.) and text.
2. The MCP processes the data, running checks for structural errors, keyword matches, and semantic density scores.
3. You receive a detailed report outlining compliance failures or providing the calculated richness score.

## Frequently Asked Questions

**How do I check for heading hierarchy errors?**
Use the `check_hierarchy` tool by providing an array of objects containing the level and text of your headings. Tools available: `your_tool_name`.

**Can I verify specific keywords in my H2 tags?**
Yes, use `verify_keywords` and specify the target level as 'h2' to check for your required terms.

**What is semantic density?**
It is a measure of how much unique, meaningful information is present in each heading level compared to the total word count, calculated via `calculate_semantic_density`.

**What input format does `check_hierarchy` require?**
It requires a list of heading objects, structured with both a 'level' and 'text'. You must pass an array like this: `[{'level': 'h1', 'text': 'Title'}, {'level': 'h2', 'text': 'Section'}]`.

**If I run `verify_keywords` with invalid heading data, what error message do I get?**
The system returns a structured validation failure. It flags missing required fields or non-existent HTML tags in the input list. You'll see specific details about where the structure broke.

**Are there rate limits when using `calculate_semantic_density` on multiple sections?**
Yes, the MCP has standard usage rate limits to manage load. To process large batches of data, submit them through Vinkius's dedicated batch endpoint rather than making repeated single calls.

**When I use `check_hierarchy`, does it validate an entire webpage or just specific sections?**
This MCP validates the document outline you provide, not a live URL. You must input a structured list of headings; it cannot scrape content from actual webpages.

**Are there restrictions on the type of keywords I can pass to `verify_keywords`?**
No, it supports standard Unicode characters and complex regular expressions. Just ensure your keyword list is properly sanitized for safe query execution before submitting the tool call.