MCP-HTML-Bridge

Live Demo

These are actual rendered outputs from the engine — zero dependencies, self-contained HTML. Each demo is generated from a single function call.

[
  { "name": "Alice", "role": "Admin", "status": "Active", "email": "alice@example.com" },
  { "name": "Bob", "role": "Editor", "status": "Active", "email": "bob@example.com" },
  { "name": "Charlie", "role": "Viewer", "status": "Inactive", "email": "charlie@example.com" },
  { "name": "Diana", "role": "Admin", "status": "Active", "email": "diana@example.com" }
]

{
  "project": "MCP-HTML-Bridge",
  "version": "0.5.1",
  "totalDownloads": 12483,
  "weeklyGrowth": 23.5,
  "openIssues": 7,
  "stars": 342,
  "license": "MIT",
  "dependencies": 0,
  "status": "stable"
}

{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Search keywords" },
    "category": { "type": "string", "enum": ["Books", "Electronics", "Clothing", "Food"] },
    "maxPrice": { "type": "number", "minimum": 0, "maximum": 10000 },
    "inStock": { "type": "boolean", "default": true }
  },
  "required": ["query"]
}

This is the structural fallback mode (no LLM). With an LLM configured, the output is even richer — the model understands data semantics and renders SVGs, markdown, charts, etc.

Quick Start

# 1. Install
npm install -g @mcp-html-bridge/claude-skill

# 2. Configure your LLM provider once
mcp-html-skill config --api-url http://localhost:11434/v1 --model qwen2

# 3. Render any JSON
echo '{"name":"Alice","scores":[98,85,92]}' > /tmp/data.json
mcp-html-skill render --data /tmp/data.json --open

# Or skip LLM, use structural rendering
mcp-html-skill render --data /tmp/data.json --no-llm --open

Or without installing:

npx @mcp-html-bridge/claude-skill render --data /tmp/data.json --open

LLM Configuration

Configure once, use everywhere. Supports any OpenAI-compatible API.

mcp-html-skill config --api-url <url> --model <model> [--api-key <key>]

Provider Examples

# Local Ollama (no API key needed)
mcp-html-skill config --api-url http://localhost:11434/v1 --model qwen2

# DeepSeek
mcp-html-skill config --api-url https://api.deepseek.com/v1 \
  --api-key sk-xxx --model deepseek-chat

# Baidu ERNIE
mcp-html-skill config \
  --api-url https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop \
  --api-key xxx --model ernie-4.0-8k

Manage Config

mcp-html-skill config --show     # View current config
mcp-html-skill config --clear    # Clear config

Resolution Priority

Env vars: MCP_HTML_LLM_API_URL / MCP_HTML_LLM_API_KEY / MCP_HTML_LLM_MODEL

Config file: ~/.mcp-html-bridge/config.json

Rendering Modes

Library API

Async LLM Rendering

import { renderFromData } from '@mcp-html-bridge/ui-engine';

const html = await renderFromData(data, {
  title: 'API Result',
  llm: {
    apiUrl: 'http://localhost:11434/v1',
    model: 'qwen2',
  },
});

Sync Structural Rendering

import { renderFromDataSync } from '@mcp-html-bridge/ui-engine';

const html = renderFromDataSync(data, { title: 'API Result' });

Form from JSON Schema

import { renderFromSchema } from '@mcp-html-bridge/ui-engine';

const html = renderFromSchema({
  type: 'object',
  properties: {
    query: { type: 'string', description: 'Search query' },
    category: { type: 'string', enum: ['Books', 'Electronics'] },
    maxPrice: { type: 'number', minimum: 0 },
  },
  required: ['query'],
}, {
  toolName: 'search_products',
});

Form Widget Mapping

CLI Usage

# Render with LLM (auto-loads config)
mcp-html-skill render --data result.json --open

# Force structural, no LLM
mcp-html-skill render --data result.json --no-llm --open

# Schema → interactive form
mcp-html-skill render --schema tool-schema.json --open

# Inline JSON
mcp-html-skill render --json '{"users":[{"name":"Alice"}]}' --open

# Stdout
mcp-html-skill render --data result.json --stdout > output.html

All Options

Claude Code Integration

# Install /mcp-render command
mcp-html-skill install

# Then in any Claude Code conversation:
/mcp-render

Tailwind Utility Classes

Every generated page includes Tailwind-compatible atomic classes mapped to the CSS variable theme. Both the LLM and hand-written HTML can use them.

Responsive Prefixes

sm:grid-cols-2  sm:flex-row  sm:text-lg  sm:p-6    /* ≥640px */
md:grid-cols-3  md:flex-row  md:text-2xl  md:p-8    /* ≥768px */

Bridge Protocol

Every generated page includes a bridge script for bidirectional iframe communication.

Inside the HTML

__mcpBridge.callTool('search_products', { query: 'laptop' });
__mcpBridge.onResult(function(data) { console.log(data); });

From the Parent Frame

window.addEventListener('message', (evt) => {
  if (evt.data?.type === 'MCP_TOOL_CALL') {
    iframe.contentWindow.postMessage({ type: 'MCP_RESULT', data: result }, '*');
  }
  if (evt.data?.type === 'MCP_RESIZE') {
    iframe.style.height = evt.data.height + 'px';
  }
});

Architecture

Proxy Mode

Transparently forwards all MCP messages while appending rendered HTML to tool results.

npx @mcp-html-bridge/proxy "npx -y @modelcontextprotocol/server-filesystem /tmp"

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@mcp-html-bridge/proxy",
               "npx -y @modelcontextprotocol/server-filesystem /tmp"]
    }
  }
}

Packages

Recipes

Embed in React (sync)

import { renderFromDataSync } from '@mcp-html-bridge/ui-engine';

function MCPViewer({ data }) {
  const html = useMemo(() => renderFromDataSync(data), [data]);
  return <iframe srcDoc={html} sandbox="allow-scripts"
           style={{ width: '100%', border: 'none' }} />;
}

Embed in React (async LLM)

import { renderFromData } from '@mcp-html-bridge/ui-engine';

function MCPViewer({ data }) {
  const [html, setHtml] = useState('');
  useEffect(() => {
    renderFromData(data, {
      llm: { apiUrl: 'http://localhost:11434/v1', model: 'qwen2' },
    }).then(setHtml);
  }, [data]);
  if (!html) return <div>Rendering...</div>;
  return <iframe srcDoc={html} sandbox="allow-scripts"
           style={{ width: '100%', border: 'none' }} />;
}