WebMCP Explained: Exposing Browser-Native AI Tools with document.modelContext and Declarative HTML

// src/lib/webmcp/register-codingcat-tools.ts
export interface WebMcpToolDefinition<TArgs = Record<string, unknown>> {
  name: string;
  description: string;
  annotations?: {
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
    idempotentHint?: boolean;
    untrustedContentHint?: boolean;
  };
  inputSchema: {
    type: "object";
    properties: Record<string, unknown>;
    required?: string[];
  };
  execute: (args: TArgs) => Promise<unknown>;
}

interface ModelContextContainer {
  registerTool?: <T>(tool: WebMcpToolDefinition<T>, options?: { signal?: AbortSignal }) => void;
  unregisterTool?: (name: string) => void;
}

export function getBrowserModelContext(): ModelContextContainer | null {
  if (typeof document !== "undefined" && "modelContext" in document) {
    return (document as unknown as { modelContext: ModelContextContainer }).modelContext;
  }
  if (typeof navigator !== "undefined" && "modelContext" in navigator) {
    return (navigator as unknown as { modelContext: ModelContextContainer }).modelContext;
  }
  return null;
}

export function mountCodingCatWebMcpTools(): () => void {
  const mc = getBrowserModelContext();
  const controller = new AbortController();

  if (!mc || typeof mc.registerTool !== "function") {
    return () => controller.abort();
  }

  mc.registerTool<{ query: string; pillar?: "course" | "podcast" | "post" }>(
    {
      name: "search_content",
      description:
        "Search CodingCat.dev Courses, Podcasts, and Blog Posts by technical topic or framework.",
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
        untrustedContentHint: true,
      },
      inputSchema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search keyword (e.g. WebMCP, Gemini Nano, Astro, Sanity, Cloudflare D1)",
          },
          pillar: {
            type: "string",
            enum: ["course", "podcast", "post"],
            description: "Optional CodingCat.dev content pillar filter",
          },
        },
        required: ["query"],
      },
      execute: async ({ query, pillar }) => {
        const params = new URLSearchParams({ q: query });
        if (pillar) params.set("type", pillar);
        const response = await fetch(`/api/search?${params.toString()}`, {
          headers: { Accept: "application/json" },
          credentials: "same-origin",
        });
        if (!response.ok) {
          throw new Error(`Search API returned HTTP ${response.status}`);
        }
        return await response.json();
      },
    },
    { signal: controller.signal }
  );

  return () => controller.abort();
}

<!-- Declarative WebMCP Tool Form (as shipped on alexpatterson.dev & codingcat.dev/demos/web-ai) -->
<form
  action="/speaker-kit.json"
  method="get"
  toolname="get_speaker_kit_json"
  tooldescription="Fetch Alex Patterson's programmatic speaker kit JSON including bios, talk abstracts, Sanity CDN headshots, and speaking ledger"
  toolautosubmit="true"
>
  <label for="speaker-kit-section">Speaker Kit Section</label>
  <select
    id="speaker-kit-section"
    name="section"
    required
    toolparamdescription="Speaker kit section to retrieve (all, bios, talks, headshots, ledger)"
  >
    <option value="all">Full Speaker Kit (JSON)</option>
    <option value="bios">Bios (6 Variants)</option>
    <option value="talks">Talk Abstracts</option>
    <option value="headshots">Press Headshots</option>
    <option value="ledger">Speaking Track Record</option>
  </select>
  <button type="submit">Download JSON</button>
</form>