Architecting the Agent-Ready Web: Combining Client-Side WebMCP, Streamable HTTP MCP, and RFC 9727 Discovery

// src/lib/mcp/shared-search-tool.ts
export const SEARCH_CONTENT_TOOL_SCHEMA = {
  name: "search_content",
  description:
    "Search CodingCat.dev Courses, Podcasts, and Blog Posts by keyword or topic",
  annotations: {
    readOnlyHint: true,
    untrustedContentHint: true,
  },
  inputSchema: {
    type: "object" as const,
    properties: {
      query: {
        type: "string",
        description: "Search keyword (e.g. WebMCP, Gemini Nano, WebGPU, Astro, Sanity)",
      },
    },
    required: ["query"],
  },
};

// 1. Client-side binding for Browser WebMCP (document.modelContext)
export function registerClientWebMcpSearch(origin = "") {
  const mc =
    (typeof document !== "undefined" && (document as any).modelContext) ||
    (typeof navigator !== "undefined" && (navigator as any).modelContext);
  if (!mc || typeof mc.registerTool !== "function") return;

  mc.registerTool({
    ...SEARCH_CONTENT_TOOL_SCHEMA,
    execute: async ({ query }: { query: string }) => {
      const res = await fetch(`${origin}/api/search?q=${encodeURIComponent(query)}`);
      return await res.json();
    },
  });
}

// 2. Edge-side binding for Streamable HTTP MCP (POST /api/mcp)
export async function handleEdgeMcpToolCall(
  toolName: string,
  args: Record<string, unknown>,
  siteOrigin: string
) {
  if (toolName === SEARCH_CONTENT_TOOL_SCHEMA.name) {
    const query = String(args.query || "");
    const res = await fetch(`${siteOrigin}/api/search?q=${encodeURIComponent(query)}`);
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      isError: false,
    };
  }
  throw new Error(`Unknown MCP tool: ${toolName}`);
}

// src/middleware.ts (Excerpt from CodingCat.dev production middleware)
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  const origin = context.url.origin;
  const accept = context.request.headers.get("accept") || "";

  // If an AI agent sends Accept: text/markdown, rewrite transparently to the .md route
  if (
    accept.includes("text/markdown") &&
    !context.url.pathname.endsWith(".md") &&
    !context.url.pathname.startsWith("/api/")
  ) {
    const mdPath =
      context.url.pathname === "/" ? "/index.md" : `${context.url.pathname}/index.md`;
    return context.rewrite(mdPath);
  }

  const response = await next();
  response.headers.append(
    "Link",
    [
      `<${origin}/.well-known/api-catalog>; rel="api-catalog"`,
      `<${origin}/.well-known/mcp/server-card.json>; rel="mcp-server-card"`,
      `<${origin}/llms.txt>; rel="llms-txt"`,
      `<${origin}/AGENTS.md>; rel="agent-guide"`,
    ].join(", ")
  );
  return response;
});