{"_id":"@aimino/fast-html-mcp-server","_rev":"3-d104f8dff3eb97d7e571cdef2f9130f5","name":"@aimino/fast-html-mcp-server","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@aimino/fast-html-mcp-server","version":"0.1.1","keywords":["mcp","mcp-server","model-context-protocol","html","html-generation","dom-manipulation","templates","components","ai","typescript"],"license":"GPL-3.0-only","_id":"@aimino/fast-html-mcp-server@0.1.1","maintainers":[{"name":"xdn.aimino","email":"xuan-duc.nguyen@aimino.de"}],"homepage":"https://github.com/Aimino-Tech/fast-html-mcp-server#readme","bugs":{"url":"https://github.com/Aimino-Tech/fast-html-mcp-server/issues"},"bin":{"fast-html-mcp":"dist/index.js"},"dist":{"shasum":"eaba89762fe0b8a1316489193698fc2f68b901b8","tarball":"https://registry.npmjs.org/@aimino/fast-html-mcp-server/-/fast-html-mcp-server-0.1.1.tgz","fileCount":297,"integrity":"sha512-OHKNQ2lJyUeXG+T3rRrOgPyaLhNfQzIhBE/DytLrturBuOhyUeGPCtkOiJmjliQ280/GpUrNJtAsHiQRI2La9Q==","signatures":[{"sig":"MEQCIDpyOa6HYBftxG4k9/rExvDkjLDAzIodorbI/FReaBfmAiAZqeSxmNj91EKw6IDk2Il6B8AzTXJnwMiqNu+ccjOSNw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":708588},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"eaccaa405bc64dd80f99229dd195f1244fe102e7","mcpName":"io.github.Aimino-Tech/fast-html-mcp","scripts":{"dev":"tsx src/index.ts","build":"tsc && cp -r src/templates/*.dot dist/templates/","clean":"rm -rf dist","start":"node dist/index.js","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"xdn.aimino","email":"xuan-duc.nguyen@aimino.de"},"repository":{"url":"git+https://github.com/Aimino-Tech/fast-html-mcp-server.git","type":"git"},"_npmVersion":"11.12.1","description":"Five-tier MCP server for lightning-fast HTML generation from AI agents — assembly, patch, read, raw, and consistency tiers with tools, components, and templates","directories":{},"_nodeVersion":"24.15.0","dependencies":{"dot":"^1.1.3","zod":"^3.24.0","jsdom":"^25.0.0","parse5":"^8.0.1","dompurify":"^3.2.0","js-beautify":"^1.15.0","html-minifier-terser":"^7.2.0","@modelcontextprotocol/sdk":"^1.11.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","@types/dot":"^1.1.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/jsdom":"^28.0.3","@types/parse5":"^6.0.3","@types/dompurify":"^3.0.0","@types/js-beautify":"^1.14.0"},"peerDependencies":{"@opencode-ai/plugin":"^1.15.5"},"_npmOperationalInternal":{"tmp":"tmp/fast-html-mcp-server_0.1.1_1779348371843_0.9531398345939388","host":"s3://npm-registry-packages-npm-production"},"deprecated":"⚠️ Package renamed to @aimino/opentalk2html-notmd. Please update your dependencies."},"0.1.2":{"name":"@aimino/fast-html-mcp-server","version":"0.1.2","keywords":["mcp","mcp-server","model-context-protocol","html","html-generation","dom-manipulation","templates","components","ai","typescript"],"license":"GPL-3.0-only","_id":"@aimino/fast-html-mcp-server@0.1.2","maintainers":[{"name":"xdn.aimino","email":"xuan-duc.nguyen@aimino.de"}],"homepage":"https://github.com/Aimino-Tech/fast-html-mcp-server#readme","bugs":{"url":"https://github.com/Aimino-Tech/fast-html-mcp-server/issues"},"bin":{"fast-html-mcp":"dist/index.js"},"dist":{"shasum":"3712e9703b4cd45df89f07c3a2e6d0a3ec967197","tarball":"https://registry.npmjs.org/@aimino/fast-html-mcp-server/-/fast-html-mcp-server-0.1.2.tgz","fileCount":297,"integrity":"sha512-wtncqW2WTr5/zqpDDtl9nrOqVXq9d3O87l1q2TrTF9/nMpTAkJ7WiLzKyzM75R3oULoPoG34T6bTOQySEfUGPg==","signatures":[{"sig":"MEYCIQCvRHAf+0mmlkex2zpImYZGEudScUcUEMTit0SZeYcRRQIhAOl0eIU9oANFCtQmoMBIHfNso8n6XFTF+HXKBbJ6uld6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":708588},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"09001938899e19bb26d9167b04c5d0297de698e4","mcpName":"io.github.Aimino-Tech/fast-html-mcp","scripts":{"dev":"tsx src/index.ts","build":"tsc && cp -r src/templates/*.dot dist/templates/","clean":"rm -rf dist","start":"node dist/index.js","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"xdn.aimino","email":"xuan-duc.nguyen@aimino.de"},"repository":{"url":"git+https://github.com/Aimino-Tech/fast-html-mcp-server.git","type":"git"},"_npmVersion":"11.12.1","description":"Five-tier MCP server for lightning-fast HTML generation from AI agents — assembly, patch, read, raw, and consistency tiers with tools, components, and templates","directories":{},"_nodeVersion":"24.15.0","dependencies":{"dot":"^1.1.3","zod":"^3.24.0","jsdom":"^25.0.0","parse5":"^8.0.1","dompurify":"^3.2.0","js-beautify":"^1.15.0","html-minifier-terser":"^7.2.0","@modelcontextprotocol/sdk":"^1.11.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","@types/dot":"^1.1.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/jsdom":"^28.0.3","@types/parse5":"^6.0.3","@types/dompurify":"^3.0.0","@types/js-beautify":"^1.14.0"},"peerDependencies":{"@opencode-ai/plugin":"^1.15.5"},"_npmOperationalInternal":{"tmp":"tmp/fast-html-mcp-server_0.1.2_1779349631429_0.6702460657496412","host":"s3://npm-registry-packages-npm-production"},"deprecated":"⚠️ Package renamed to @aimino/opentalk2html-notmd. Please update your dependencies."}},"time":{"created":"2026-05-21T07:26:11.734Z","modified":"2026-05-27T10:54:21.047Z","0.1.1":"2026-05-21T07:26:12.010Z","0.1.2":"2026-05-21T07:47:11.589Z"},"bugs":{"url":"https://github.com/Aimino-Tech/fast-html-mcp-server/issues"},"license":"GPL-3.0-only","homepage":"https://github.com/Aimino-Tech/fast-html-mcp-server#readme","keywords":["mcp","mcp-server","model-context-protocol","html","html-generation","dom-manipulation","templates","components","ai","typescript"],"repository":{"url":"git+https://github.com/Aimino-Tech/fast-html-mcp-server.git","type":"git"},"description":"Five-tier MCP server for lightning-fast HTML generation from AI agents — assembly, patch, read, raw, and consistency tiers with tools, components, and templates","maintainers":[{"name":"xdn.aimino","email":"xuan-duc.nguyen@aimino.de"}],"readme":"# Fast HTML MCP\n\n[![npm version](https://img.shields.io/npm/v/@aimino/fast-html-mcp-server)](https://www.npmjs.com/package/@aimino/fast-html-mcp-server)\n[![License](https://img.shields.io/badge/license-GPL%203.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)\n[![MCP](https://badge.mcpx.dev?type=server 'MCP Server')](https://github.com/modelcontextprotocol/specification)\n**Five-tier MCP server for lightning-fast HTML generation from AI agents.**  \nAssembly-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.\n\nMCP name: `io.github.aimino-tech/fast-html-mcp-server`\n\n## Quick Start\n\n```bash\nnpx -y @aimino/fast-html-mcp-server\n```\n\nOr add to your MCP client config:\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"fast-html-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aimino/fast-html-mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"fast-html-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aimino/fast-html-mcp-server\"]\n    }\n  }\n}\n```\n\n### VS Code (via GitHub Copilot MCP extension)\n\n```json\n{\n  \"inputs\": [],\n  \"servers\": {\n    \"fast-html-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aimino/fast-html-mcp-server\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add fast-html-mcp-server -e npx -a \"-y\" -a \"@aimino/fast-html-mcp-server\"\n```\n\n## Working Example\n\nHere's a complete copy-paste workflow that builds a report page:\n\n```bash\n# 1. List available templates and components\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"list_templates\",\"arguments\":{}}}' | npx -y @aimino/fast-html-mcp-server\n\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"list_components\",\"arguments\":{}}}' | npx -y @aimino/fast-html-mcp-server\n\n# 2. Render a page\necho '{\"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\n\n# 3. Inspect the output\necho '{\"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\n```\n\n## Performance Benchmarks\n\nAll benchmarks measured from cold start (first tool call after server launch). No warmup or pre-initialization.\n\n| Operation | Target | Actual | vs Alternatives |\n|-----------|--------|--------|-----------------|\n| **Cold start → first render** | <3s | **~1.5s** | Playwright/Puppeteer: 5-15s |\n| **Subsequent render_page** (25 templates) | <1s | **~900ms** | Handlebars/EJS render: similar |\n| **patch_html** (typo fix on landing page) | <2s | **~800ms** | Regex replace: 1-3s |\n| **patch_html** (500KB table, 10 rows) | <5s | **~3s** | parse5 full parse: 8-15s |\n| **patch_html** (#id fast-path) | <500ms | **~200ms** | JSoup/Cheerio: 2-5s |\n| **5 sequential patches** (same file) | <4s total | **~2s total** | Re-parsing each time: 10s+ |\n| **set_attribute** on 500KB file | <2s | **~1s** | DOM parser: 3-8s |\n| **Compression:high** (bloated HTML) | >40% reduction | **40-70%** | html-minifier: 10-30% |\n| **Compression:ai** (full report→500 tokens) | <1750 chars | **~1600 chars** | Manual minification: unreliable |\n| **Streaming** (real-time preview) | Valid HTML chunks | **all chunks valid** | No streaming alternative exists |\n| **Equity research report** (10 sections) | <5s | **~3s** | FinRobot (7K★): 15-30s |\n\n**Why is it faster?**\n\n1. **#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\n2. **Pre-compiled doT.js templates** — All 25 templates are compiled at startup, not at render time\n3. **No browser runtime** — Unlike Playwright/Puppeteer-based solutions, Fast HTML MCP operates directly on strings and AST with no headless browser overhead\n4. **Atomic in-place edits** — Read the structure once, edit specific sections, no full DOM re-serialization\n\n## Coherence Benchmarks\n\nThe **Document Consistency Engine** (AIM-797) ensures cross-section coherence via entity-aware dependency graph propagation. All benchmarks measured from cold start.\n\n| Sections | Pattern | Propagation | Stale Detection | File Size |\n|----------|---------|-------------|-----------------|-----------|\n| 5 | Linear chain | **1.26 ms** | 0.50 ms | 0.3 KB |\n| 5 | Star (broadcast) | **2.60 ms** | 0.70 ms | 0.4 KB |\n| 10 | Linear chain | **5.48 ms** | 1.96 ms | 0.7 KB |\n| 25 | Linear chain | **6.82 ms** | 2.23 ms | 1.8 KB |\n| 50 | Linear chain | **7.21 ms** | 2.43 ms | 3.7 KB |\n| **100** | **Linear chain** | **8.71 ms** | 5.22 ms | 7.5 KB |\n| **100** | **Star (broadcast)** | **8.60 ms** | 2.64 ms | 7.9 KB |\n| **100** | **Balanced DAG** | **7.27 ms** | 1.87 ms | 11.4 KB |\n\n**Worst case: 11.47 ms for 100-section propagation.** That's ~200,000× faster than manual search-replace across 100 sections.\n\n- **Linear chain**: Deep A→B→C→... chain (worst case for BFS)\n- **Star**: Single root with 100 dependents (worst case for manifest updates)\n- **Balanced DAG**: Random dependency graph (realistic financial report style)\n- **100% stale detection accuracy** — zero false positives, zero missed\n\n## Tools\n\n| Tier | Tool | Description |\n|------|------|-------------|\n| **Assembly** | `render_page` | Compose pages from structured component specs using doT.js templates |\n| **Patch** | `patch_html` | Replace inner content of matched elements via CSS selectors (parse5 AST) |\n| **Patch** | `set_attribute` | Set an attribute on elements matched by CSS selector |\n| **Read** | `read_html` | Analyze existing HTML in three modes: structure, content, compressed |\n| **Raw** | `write_raw_html` | Write raw HTML string (optionally template-wrapped) to file |\n| **Raw** | `write_html_file` | Alias for `write_raw_html` |\n| **Raw** | `format_html` | Beautify an existing HTML file in-place with js-beautify |\n| **Raw** | `preview_html` | Render HTML string to a preview file without writing to disk |\n| **Consistency** | `propagate_edit` | Propagate entity edit through dependency graph, auto-updating affected sections |\n| **Consistency** | `check_consistency` | Audit document for stale cross-section references |\n| **Utility** | `list_components` | List available components, optionally filtered by category |\n| **Utility** | `list_templates` | List available templates, optionally filtered by category |\n| **Utility** | `get_template_schema` | Get template metadata with available variables and defaults |\n| **Utility** | `get_component_schema` | Get component schema with available props |\n| **Utility** | `register_template` | Register a custom template at runtime for immediate use |\n\n## Components (22)\n\n| Category | Components |\n|----------|------------|\n| Layout | `header`, `footer`, `sidebar`, `card-deck`, `grid` |\n| Interactive | `tabs`, `accordion` |\n| Data | `data-table`, `stats-grid`, `timeline`, `financial-table`, `evidence-grid` |\n| Visual | `risk-matrix`, `valuation-chart`, `prisma-flow` |\n| Media | `figure`, `image-gallery` |\n| Utility | `hero`, `callout`, `code-block`, `citation-block` |\n\n## Templates (25)\n\n### General Purpose\n`report`, `exploration`, `deck`, `code-review`, `design`, `prototyping`, `illustrations`, `research`, `custom-editor`, `minimal`, `documentation`\n\n### Business\n`invoice`, `budget`, `financial-summary`, `data-sheet`, `dashboard`, `financial-dashboard`\n\n### Communication\n`newsletter`, `changelog`, `faq`, `meeting-notes`, `comparison`\n\n### Technical\n`api-doc`, `landing-page`, `error-page`\n\n### Research\n`equity-research`, `lit-review`, `research-briefing`, `scientific-paper`, `journal-club`, `earnings-summary`, `industry-overview`\n\n### Presentation\n`pitch-deck`\n\n## Architecture\n\nAssembly-Patch-Read-Raw (APRR) — four tiers that work together in a feedback loop:\n\n```\nFast HTML MCP\n├── Assembly Tier    — render_page\n├── Patch Tier       — patch_html, set_attribute\n├── Read Tier        — read_html\n├── Raw Tier         — write_raw_html, write_html_file, format_html, preview_html\n├── Consistency Tier — propagate_edit, check_consistency\n└── Utilities        — list_components, list_templates\n```\n\n### Ping-Pong Loop\n\n1. **Discover** → `list_templates` + `list_components` + schema tools\n2. **Build** → `render_page` with template + sections\n3. **Inspect** → `read_html` to verify output\n4. **Refine** → `patch_html` / `set_attribute` → read again\n5. **Consistency** → `check_consistency` / `propagate_edit` to maintain data integrity across interdependent sections\n\n### Key Design Decisions\n\n- **doT.js** for templates (not Handlebars/EJS — 10x faster compile time, critical for AI agent latency)\n- **#id fast-path** — `patch_html`/`set_attribute` detects `#id` selectors for direct string substitution instead of full AST parse (~10x faster for most edits)\n- **parse5** for full HTML patching (AST manipulation, not regex — safe and correct for complex selectors)\n- **js-beautify** for HTML formatting\n- **DOMPurify** for XSS prevention on all output\n- **AI compression** — Token-aware minification that preserves semantic content while fitting agent token budgets\n- **Streaming** — Real-time HTML streaming for preview use cases, each chunk parseable as valid HTML\n- **Consistency Engine** — Dependency-graph-based cross-section propagation for maintaining data integrity across edits\n- **Atomic writes**: tmp file + rename to prevent partial writes\n- **ESM**: TypeScript compiled to ES modules for Node.js 20+\n\n## Token Efficiency\n\nFast HTML MCP is designed from the ground up for AI agent token budgets. All read and edit modes prioritize token efficiency through progressive disclosure.\n\n### Read Modes Comparison (106KB HTML page)\n\n| Mode | Tokens | vs Raw HTML | Best For |\n|------|--------|-------------|----------|\n| Raw HTML (baseline) | 30,553 | — | Full DOM access |\n| Structure | 9,163 | 70% saved | Tree overview |\n| Content | 7,991 | 74% saved | Typed blocks |\n| Compressed | 3,909 | 87% saved | Summary + stats |\n| **Text** | **1,000** | **97% saved** | **Token-minimal reading** |\n\nThe `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:\n\n```\n# Read just the first 1K chars (~250 tokens)\nread_html(path, mode: \"text\", offset: 0, limit: 1000)\n\n# Read more if needed\nread_html(path, mode: \"text\", offset: 1000, limit: 1000)\n```\n\nFor 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.\n\n### Edit Modes Comparison\n\nWhen an AI agent changes one value in a 500-line HTML file:\n\n| Approach | Tokens Sent | Best For |\n|----------|-------------|----------|\n| `patch_html` with CSS selector | ~2,396 tokens | Small, single-line targets (by id) |\n| **`edit_html_range` with line range** | **~48 tokens** | **Large containers, surgical changes** |\n\nFor 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.\n\n```\n# Fix a typo — send just the one changed line\nedit_html_range(file_path: \"report.html\", start_line: 42, end_line: 42, \n  new_content: \"  <p>The quick brown fox jumps over the lazy dog.</p>\")\n\n# vs. patch_html which requires the entire element content\npatch_html(file_path: \"report.html\", selector: \"#content\",\n  html: \"<p>The quick brown fox jumps over the lazy dog.</p><p>Another paragraph...</p>...\")\n```\n\n**When to use which tool:**\n- `patch_html` — edit a small element you can target by CSS id (selector token cost < content token cost)\n- `edit_html_range` — edit inside a large element where the changed lines are small vs. the element size\n- `set_attribute` — change a single attribute (attribute+value, fast regex path)\n\n## Self-Hosting (SSE)\n\nRun the HTTP/SSE transport for remote MCP clients:\n\n```bash\nnpm run build\nTRANSPORT=sse PORT=3000 npm start\n```\n\nOr with Docker:\n\n```bash\ndocker compose up --build\n```\n\nEndpoints: `/health`, `/metrics`, `/mcp/sse`, `/mcp/message`. Put a reverse proxy (Caddy, nginx, Cloudflare Tunnel) in front for TLS when exposing publicly.\n\n## Security\n\nFast HTML MCP takes security seriously:\n\n- **XSS Prevention**: Every output passes through DOMPurify, preventing cross-site scripting attacks\n- **Atomic Writes**: Files are written to temporary files first, then renamed atomically — preventing partial/corrupt writes\n- **No Arbitrary Execution**: The server only performs HTML operations — no shell execution, no file reads outside workspace boundaries\n- **Strict Input Validation**: All tool inputs are validated with Zod schemas before processing\n\nWhen self-hosting over the network, terminate TLS at your reverse proxy and restrict access (firewall, VPN, or your own auth layer).\n\n## Development\n\n```bash\ngit clone https://github.com/Aimino-Tech/fast-html-mcp-server.git\ncd fast-html-mcp-server\nnpm install\nnpm run build\nnpm run dev    # hot reload via tsx\n```\n\n## License\n\nGNU General Public License v3.0 — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}