@htmlbricks/mcp

Model Context Protocol server for HTML Bricks (hb-* web components). It exposes the agent catalog reference, list.json, CDN helpers, search, and prompts so coding agents can build correct markup (snake_case attributes, Bootstrap 5, Bootstrap Icons). The same list.json schemas support emitting complete TypeScript for all component props and all custom events (CustomEvent detail per event name).

Usage (agentic IDEs)

Run via stdio (example for MCP clients):

{
  "command": "npx",
  "args": ["-y", "@htmlbricks/mcp"]
}

Requires Node.js 18+. The published package embeds AGENT_WEBCOMPONENTS_REFERENCE.md and list.json for the same version as @htmlbricks/hb-bundle. If assets are missing, the server falls back to jsDelivr for that version.

Instructions for coding agents

Treat this server as the source of truth for the public hb-* catalog. Do not invent tags, attributes, or events.

1. Start with resources (server id is usually htmlbricks in the client config):
   • Read htmlbricks://docs/development-guide for conventions and how to interpret list.json.
   • Read htmlbricks://catalog/agent-reference for human-oriented docs and examples (large file — use search_catalog to narrow).
   • Read htmlbricks://catalog/package-list when you need exact JSON Schema for props and CustomEvent detail.
2. Use tools before answering specific API questions:
   • search_catalog — quick lookup by keyword in the reference.
   • get_component_props — definitions.component only (props / Component JSON Schema).
   • get_component_events — definitions.events only (custom events → detail JSON Schema).
   • get_component_schemas — both schemas in one call (use the split tools when you need a smaller payload). From any of these JSON Schemas you can derive full TS: a Component-style interface and CustomEvent<Detail> per event.
   • get_component_description — package description only (what the element does).
   • get_component_css — styleSetup.vars (CSS variables) and styleSetup.parts (::part names).
   • get_component_slots — htmlSlots only (slot names and docs).
   • get_bundle_cdn_urls — correct jsDelivr URLs for this package version.
3. Use the prompt plan_htmlbricks_page when the user wants a multi-section plan or example HTML built from hb-* components.

Local development of this repo: you can point the MCP client at the workspace server instead of npx (for example run node /absolute/path/to/mcp/cli.js as the command) so agents exercise the same version as the working tree.

Resources

| URI | Content | |-----|---------| | htmlbricks://docs/development-guide | Conventions and workflow | | htmlbricks://catalog/agent-reference | Full merged component reference (Markdown) | | htmlbricks://catalog/package-list | list.json: per package, JSON Schemas (definitions.*) plus manifest fields: description, styleSetup (vars + parts), htmlSlots. Same TypeScript shapes as npm for props/events; use get_component_* tools for focused slices. |

Tools

• search_catalog — keyword search in the reference
• get_component_props — definitions.component only (props / TypeScript Component shape as JSON Schema)
• get_component_events — definitions.events only (each event name → event.detail schema)
• get_component_schemas — definitions.events + definitions.component for one hb-* (from bundled list.json); use to derive all TS props and all custom-event detail types
• get_component_description — description string only
• get_component_css — styleSetup.vars + styleSetup.parts only
• get_component_slots — htmlSlots array only
• get_bundle_cdn_urls — jsDelivr URLs for hb-bundle matching this package version

Prompts

• plan_htmlbricks_page — structured task to read resources and plan UI with hb-* elements