@htmlbricks/mcp 0.66.10 → 0.66.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/mcp",
-  "version": "0.66.10",
+  "version": "0.66.12",
   "private": false,
   "description": "MCP server with HTML Bricks (hb-*) web component catalog resources and tools for agentic IDEs.",
   "type": "module",

package/server.js

@@ -18,7 +18,7 @@ let referenceCache = null;
 
 const DEVELOPMENT_GUIDE = `# HTML Bricks — agent development guide
 
-Use this together with the resource **${RESOURCE_REFERENCE_URI}** (full catalog) and **${RESOURCE_LIST_URI}** (manifest index).
+Use this together with the resource **${RESOURCE_REFERENCE_URI}** (full catalog) and **${RESOURCE_LIST_URI}** (\`list.json\`: one manifest per component).
 
 ## Conventions
 
@@ -32,11 +32,32 @@ Use this together with the resource **${RESOURCE_REFERENCE_URI}** (full catalog)
 - **Per-component** scripts from jsDelivr: \`https://cdn.jsdelivr.net/npm/@htmlbricks/hb-<name>@<version>/main.iife.js\` (see each package for optional \`integrity\` from npm).
 - **Full catalog** IIFE: **@htmlbricks/hb-bundle** provides \`main.iife.js\`, \`list.json\`, \`bundle.json\`, and \`agents/docs/AGENT_WEBCOMPONENTS_REFERENCE.md\` (same content as the MCP resource above when versions match).
 
+## Custom events — read \`list.json\` (\`definitions.events\`)
+
+1. Parse **${RESOURCE_LIST_URI}** (or \`list.json\` from hb-bundle). Use \`packages[]\`.
+2. Find the object whose \`name\` matches the tag (e.g. \`"hb-footer"\`).
+3. Open **\`definitions.events\`**: a **JSON Schema** (draft-07) for the component’s **\`Events\`** TypeScript type.
+4. Navigate to **\`definitions.Events\`** inside that object (path is usually \`definitions.events.definitions.Events\`).
+5. Under **\`properties\`**, **each key is a \`CustomEvent\` type string** — the same name you pass to \`element.addEventListener("<key>", …)\` and that appears as \`event.type\`.
+6. The **schema value** for that key describes **\`event.detail\`**: typically \`type: "object"\` with \`properties\`, \`required\`, and \`$ref\` to nested definitions. Resolve \`$ref\` within the same \`definitions.events\` document.
+
+Prose event lists in the merged Markdown reference are aligned with these schemas; use **list.json** when you need exact **detail** field types and nesting.
+
+## Component props — read \`list.json\` (\`definitions.component\`)
+
+1. Same \`packages[]\` entry as above.
+2. Open **\`definitions.component\`**: JSON Schema for the **\`Component\`** TypeScript interface.
+3. Open **\`definitions.Component\`** (usually \`definitions.component.definitions.Component\`).
+4. **\`properties\`** lists each prop **as in TypeScript** (often camelCase). Types use JSON Schema (\`type\`, \`enum\`, \`items\`, booleans, etc.). Shared shapes (\`ICompany\`, …) appear under the same document’s **\`definitions\`** map; follow **\`$ref\`**.
+
+For **HTML**, attribute names and JSON-string props are documented per component in **${RESOURCE_REFERENCE_URI}** (snake_case on the host). Use **\`definitions.component\`** for the **logical type** of each prop and nested JSON; use the **README section** for the **exact attribute names** and examples.
+
 ## Workflow for agents
 
 1. Read **${RESOURCE_GUIDE_URI}** (this file) and **${RESOURCE_REFERENCE_URI}** before proposing markup or props.
-2. Use the **search_catalog** tool for keyword lookup when the reference is too large to scan manually.
-3. Prefer attributes and events documented in the reference; do not invent props.
+2. For **events** and **prop typings**, use **${RESOURCE_LIST_URI}** (\`definitions.events\` / \`definitions.component\`) or the **get_component_schemas** tool for one component.
+3. Use the **search_catalog** tool for keyword lookup when the Markdown reference is too large to scan manually.
+4. Do not invent props or events; stick to schemas + README.
 
 Version of this MCP package tracks the published **@htmlbricks/hb-bundle** release it was built with.
 `;
@@ -109,6 +130,26 @@ function searchInText(text, query, maxResults) {
   return matches;
 }
 
+/**
+ * Match list.json package by `hb-*` name, folder slug, or loose id (e.g. footer, hb-footer).
+ */
+function findPackageEntry(packages, componentId) {
+  const raw = componentId.trim();
+  if (!raw) return undefined;
+  const slug = raw.replace(/^hb-/i, "").replace(/_/g, "-");
+  return packages.find((p) => {
+    const n = p && typeof p.name === "string" ? p.name : "";
+    if (!n) return false;
+    const pSlug = n.replace(/^hb-/, "");
+    return (
+      n === raw ||
+      n === `hb-${slug}` ||
+      pSlug === slug ||
+      pSlug.replace(/-/g, "_") === raw.replace(/^hb-/i, "")
+    );
+  });
+}
+
 export async function startMcp() {
   const version = await readPackageVersion();
   const server = new McpServer(
@@ -148,7 +189,8 @@ export async function startMcp() {
     RESOURCE_LIST_URI,
     {
       title: "HTML Bricks — package list",
-      description: "list.json from hb-bundle: component metadata, versions, tags, IIFE paths.",
+      description:
+        "list.json: { version, packages[] }. Each package includes definitions.events and definitions.component (JSON Schema). Event names = keys under definitions.events.definitions.Events.properties; each value schemas event.detail. Prop types = definitions.component.definitions.Component.properties (+ $ref). Excludes iifeIntegrity.",
       mimeType: "application/json",
     },
     async () => {
@@ -211,6 +253,54 @@ export async function startMcp() {
     }
   );
 
+  server.registerTool(
+    "get_component_schemas",
+    {
+      title: "JSON Schemas for one component (from list.json)",
+      description:
+        "Returns definitions.events and definitions.component for one package: JSON Schema for CustomEvent detail (event names = keys under definitions.Events.properties) and for Component props. Pass hb-* name or folder slug (e.g. hb-footer or footer).",
+      inputSchema: {
+        component_id: z
+          .string()
+          .min(1)
+          .describe("Component: hb-footer, footer, or hb_footer-style folder slug"),
+      },
+    },
+    async ({ component_id }) => {
+      const raw = await getPackageListJson();
+      const data = JSON.parse(raw);
+      const packages = Array.isArray(data.packages) ? data.packages : [];
+      const found = findPackageEntry(packages, component_id);
+      if (!found) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No package matching ${JSON.stringify(component_id)} in list.json (try hb-<folder> or folder name).`,
+            },
+          ],
+        };
+      }
+      const defs = found.definitions && typeof found.definitions === "object" ? found.definitions : {};
+      const slice = {
+        name: found.name,
+        list_json_guide: {
+          events:
+            "Open definitions.events → definitions.Events.properties: each key is CustomEvent.type; value schemas event.detail.",
+          props:
+            "Open definitions.component → definitions.Component.properties; follow $ref in the same document for nested objects.",
+        },
+        definitions: {
+          events: defs.events ?? null,
+          component: defs.component ?? null,
+        },
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(slice, null, 2) }],
+      };
+    }
+  );
+
   server.registerTool(
     "get_bundle_cdn_urls",
     {
@@ -257,7 +347,7 @@ First, read MCP resources:
 - ${RESOURCE_GUIDE_URI}
 - ${RESOURCE_REFERENCE_URI}
 
-Rules: use **snake_case** attributes with **string** values; follow Bootstrap 5 and Bootstrap Icons; align with the reference for props and events.
+Rules: use **snake_case** attributes with **string** values; follow Bootstrap 5 and Bootstrap Icons. For **event names** and **event.detail** shapes, use **list.json** \`packages[].definitions.events\`; for **prop JSON types**, use \`packages[].definitions.component\`. Cross-check **${RESOURCE_REFERENCE_URI}** for attribute names and examples.
 
 Goal: ${goal}