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

Generate 300+ page HTML reports in seconds — no browser, no Docker, just `npx`

Supported Platforms

Fast HTML MCP is available on all major AI coding platforms:

See the individual integration guides for detailed setup instructions.

OpenCode Plugin

Fast HTML MCP also ships as an OpenCode plugin that adds intent routing, context compression, quality gates, and document state management on top of the base server.

Roadmap

See ROADMAP.md for our full public roadmap covering v0.2 (Monetization), v0.3 (Virality & Sharing), v0.4 (Enterprise & AGI), and v0.5 (Ecosystem). Each feature includes a spec with motivation, success criteria, and RICE priority scoring.

Showcase Gallery

See what fast-html-mcp can build → Showcase Gallery

40+ rendered pages demonstrating all 25 templates and 22 components.

Quick Start

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

Or add to your MCP client config:

Claude Desktop

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

Cursor

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

VS Code (via GitHub Copilot MCP extension)

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

Claude Code

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

Use Cases

Every page below was generated by fast-html-mcp — click the title to see the live rendered preview.

#	Template	Use Case	Preview
1	invoice	Pharma Industry Invoice
2	report	SaaS Quarterly Report
3	budget	Department Budget Proposal
4	data-sheet	Enterprise Product Data Sheet
5	financial-summary	P&L and Balance Sheet Summary
6	landing-page	SaaS Landing Page
7	newsletter	Tech Newsletter
8	changelog	Product Changelog
9	faq	FAQ Page with Categories
10	comparison	Product Comparison
11	api-doc	API Documentation
12	error-page	Branded Error Page
13	code-review	Code Review Report
14	meeting-notes	Meeting Notes
15	equity-research	Equity Research Report
16	industry-overview	Market Industry Overview
17	scientific-paper	Academic Scientific Paper
18	dashboard	Campaign Analytics Dashboard
19	pitch-deck	Investor Pitch Deck
20	research-briefing	Executive Research Briefing
21	design	Component Design System
22	prototyping	Wireframe Mockup

Interactive showcase → showcase/use-cases.html with live preview, search, filters, copyable prompts, and MCP tool call details.

REST API Mode

Fast HTML MCP also runs as a standalone REST API — no MCP client required. Call it with curl, fetch, or any HTTP client.

# Start the API server (standalone mode)
TRANSPORT=api npx -y @aimino/fast-html-mcp-server

# Or use the dedicated binary
npx -y @aimino/fast-html-mcp-server api

Build HTML with curl

# Render a page from components
curl -X POST http://localhost:8766/v1/render \
  -H "Content-Type: application/json" \
  -d '{
    "template": "report",
    "sections": [
      {"component": "hero", "props": {"title": "Q3 Report", "badge": "Draft"}},
      {"component": "data-table", "props": {
        "headers": ["Metric","Value"],
        "rows": [["Revenue","$1.2M"],["Users","45K"]]
      }}
    ]
  }'

# Get raw HTML wrapped in a template
curl -X POST http://localhost:8766/v1/render/html \
  -H "Content-Type: application/json" \
  -d '{"template": "minimal", "content": "<h1>Hello World</h1>"}'

# Patch existing HTML by CSS selector
curl -X POST http://localhost:8766/v1/patch \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/tmp/page.html", "selector": "#title", "html": "<h1>New Title</h1>"}'

# List templates and components
curl http://localhost:8766/v1/templates
curl http://localhost:8766/v1/components

Unified mode (MCP + REST on one port)

TRANSPORT=http npx -y @aimino/fast-html-mcp-server
# → http://localhost:3000/mcp       — MCP protocol for AI agents
# → http://localhost:3000/v1/render — REST API for curl/HTTP clients
# → http://localhost:3000/          — Landing page

OpenAPI Spec

curl http://localhost:8766/v1/openapi.json

See the full API reference for all 15+ endpoints, authentication, and pricing.

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

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)

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

Development

git clone https://github.com/Aimino-Tech/fast-html-mcp.git
cd fast-html-mcp
npm install
npm run build
npm run dev              # hot reload via tsx
npm test                 # vitest (108 tests)
bash demo.sh             # run the REST API demo
cp .env.example .env     # configure for production
npm run api              # start REST API server
TRANSPORT=http npm start # unified MCP + REST server

License

MIT License — see LICENSE.