Fast HTML MCP

Five-tier MCP server for lightning-fast HTML generation from AI agents.
Assembly-Patch-Read-Raw-Consistency architecture. 15 tools, 22 components, 25 templates — purpose-built for AI-driven page creation with sub-second patch times and AI-grade token compression.

MCP name: io.github.aimino-tech/fast-html-mcp-server

Quick Start

npx -y @aimino/fast-html-mcp-server

Or add to your MCP client config:

Claude Desktop

{
  "mcpServers": {
    "fast-html-mcp-server": {
      "command": "npx",
      "args": ["-y", "@aimino/fast-html-mcp-server"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "fast-html-mcp-server": {
      "command": "npx",
      "args": ["-y", "@aimino/fast-html-mcp-server"]
    }
  }
}

VS Code (via GitHub Copilot MCP extension)

{
  "inputs": [],
  "servers": {
    "fast-html-mcp-server": {
      "command": "npx",
      "args": ["-y", "@aimino/fast-html-mcp-server"]
    }
  }
}

Claude Code

claude mcp add fast-html-mcp-server -e npx -a "-y" -a "@aimino/fast-html-mcp-server"

Working Example

Here's a complete copy-paste workflow that builds a report page:

# 1. List available templates and components
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_templates","arguments":{}}}' | npx -y @aimino/fast-html-mcp-server

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_components","arguments":{}}}' | npx -y @aimino/fast-html-mcp-server

# 2. Render a page
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"render_page","arguments":{"template":"report","sections":[{"component":"hero","props":{"title":"Q3 Report","badge":"Draft"}},{"component":"data-table","props":{"headers":["Metric","Value"],"rows":[["Revenue","$1.2M"],["Users","45K"]]}}],"output_path":"/tmp/report.html","options":{"title":"Q3 Report"}}}}}' | npx -y @aimino/fast-html-mcp-server

# 3. Inspect the output
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_html","arguments":{"path":"/tmp/report.html","mode":"compressed"}}}' | npx -y @aimino/fast-html-mcp-server

Performance Benchmarks

All benchmarks measured from cold start (first tool call after server launch). No warmup or pre-initialization.

Why is it faster?

1. #id fast-path — patch_html and set_attribute detect #id selectors and use direct text substitution instead of full parse5 AST parsing, achieving ~10x speedup for the most common editing pattern

2. Pre-compiled doT.js templates — All 25 templates are compiled at startup, not at render time

3. No browser runtime — Unlike Playwright/Puppeteer-based solutions, Fast HTML MCP operates directly on strings and AST with no headless browser overhead

4. Atomic in-place edits — Read the structure once, edit specific sections, no full DOM re-serialization

Coherence Benchmarks

The Document Consistency Engine (AIM-797) ensures cross-section coherence via entity-aware dependency graph propagation. All benchmarks measured from cold start.

Worst case: 11.47 ms for 100-section propagation. That's ~200,000× faster than manual search-replace across 100 sections.

• Linear chain: Deep A→B→C→... chain (worst case for BFS)

• Star: Single root with 100 dependents (worst case for manifest updates)

• Balanced DAG: Random dependency graph (realistic financial report style)

• 100% stale detection accuracy — zero false positives, zero missed

Tools

Components (22)

Templates (25)

General Purpose

report, exploration, deck, code-review, design, prototyping, illustrations, research, custom-editor, minimal, documentation

Business

invoice, budget, financial-summary, data-sheet, dashboard, financial-dashboard

Communication

newsletter, changelog, faq, meeting-notes, comparison

Technical

api-doc, landing-page, error-page

Research

equity-research, lit-review, research-briefing, scientific-paper, journal-club, earnings-summary, industry-overview

Presentation

pitch-deck

Architecture

Assembly-Patch-Read-Raw (APRR) — four tiers that work together in a feedback loop:

Fast HTML MCP
├── Assembly Tier    — render_page
├── Patch Tier       — patch_html, set_attribute
├── Read Tier        — read_html
├── Raw Tier         — write_raw_html, write_html_file, format_html, preview_html
├── Consistency Tier — propagate_edit, check_consistency
└── Utilities        — list_components, list_templates

Ping-Pong Loop

1. Discover → list_templates + list_components + schema tools

2. Build → render_page with template + sections

3. Inspect → read_html to verify output

4. Refine → patch_html / set_attribute → read again

5. Consistency → check_consistency / propagate_edit to maintain data integrity across interdependent sections

Key Design Decisions

• doT.js for templates (not Handlebars/EJS — 10x faster compile time, critical for AI agent latency)

• #id fast-path — patch_html/set_attribute detects #id selectors for direct string substitution instead of full AST parse (~10x faster for most edits)

• parse5 for full HTML patching (AST manipulation, not regex — safe and correct for complex selectors)

• js-beautify for HTML formatting

• DOMPurify for XSS prevention on all output

• AI compression — Token-aware minification that preserves semantic content while fitting agent token budgets

• Streaming — Real-time HTML streaming for preview use cases, each chunk parseable as valid HTML

• Consistency Engine — Dependency-graph-based cross-section propagation for maintaining data integrity across edits

• Atomic writes: tmp file + rename to prevent partial writes

• ESM: TypeScript compiled to ES modules for Node.js 20+

Token Efficiency

Fast HTML MCP is designed from the ground up for AI agent token budgets. All read and edit modes prioritize token efficiency through progressive disclosure.

Read Modes Comparison (106KB HTML page)

The text mode strips all HTML tags and returns only plain text — the most token-efficient way to consume HTML content. Combined with offset/limit progressive reading, agents read only what they need:

# Read just the first 1K chars (~250 tokens)
read_html(path, mode: "text", offset: 0, limit: 1000)

# Read more if needed
read_html(path, mode: "text", offset: 1000, limit: 1000)

For editing, the edit_html_range tool lets agents replace specific line ranges instead of re-sending entire element content — following the same progressive pattern as Cursor and OpenCode.

Edit Modes Comparison

When an AI agent changes one value in a 500-line HTML file:

For small edits inside large elements (e.g., fixing a value in a table cell deep in a 500-line page), edit_html_range saves 85–99% of the tool call tokens. The agent only sends the changed lines, not the complete element content.

# Fix a typo — send just the one changed line
edit_html_range(file_path: "report.html", start_line: 42, end_line: 42, 
  new_content: "  <p>The quick brown fox jumps over the lazy dog.</p>")

# vs. patch_html which requires the entire element content
patch_html(file_path: "report.html", selector: "#content",
  html: "<p>The quick brown fox jumps over the lazy dog.</p><p>Another paragraph...</p>...")

When to use which tool:

• patch_html — edit a small element you can target by CSS id (selector token cost < content token cost)

• edit_html_range — edit inside a large element where the changed lines are small vs. the element size

• set_attribute — change a single attribute (attribute+value, fast regex path)

Self-Hosting (SSE)

Run the HTTP/SSE transport for remote MCP clients:

npm run build
TRANSPORT=sse PORT=3000 npm start

Or with Docker:

docker compose up --build

Endpoints: /health, /metrics, /mcp/sse, /mcp/message. Put a reverse proxy (Caddy, nginx, Cloudflare Tunnel) in front for TLS when exposing publicly.

Security

Fast HTML MCP takes security seriously:

• XSS Prevention: Every output passes through DOMPurify, preventing cross-site scripting attacks

• Atomic Writes: Files are written to temporary files first, then renamed atomically — preventing partial/corrupt writes

• No Arbitrary Execution: The server only performs HTML operations — no shell execution, no file reads outside workspace boundaries

• Strict Input Validation: All tool inputs are validated with Zod schemas before processing

When self-hosting over the network, terminate TLS at your reverse proxy and restrict access (firewall, VPN, or your own auth layer).

Development

git clone https://github.com/Aimino-Tech/fast-html-mcp-server.git
cd fast-html-mcp-server
npm install
npm run build
npm run dev    # hot reload via tsx

License

GNU General Public License v3.0 — see LICENSE.