handzon-core 0.7.0 → 0.8.1

package/src/lib/ai/stepData.ts

@@ -0,0 +1,74 @@
+import type { AssistantContext } from "./context";
+
+/**
+ * Reads the per-step JSON payload that TutorialLayout emits into
+ * `<script id="tt-step-data" type="application/json">`. Family B
+ * touchpoints (CopyPrompt, deep-link row, copy-step button, …) need
+ * the raw MDX source and tutorial/step titles at click time without
+ * having every island accept them as props.
+ */
+export interface StepData {
+  tutorialSlug: string;
+  tutorialTitle: string;
+  stepSlug: string;
+  stepTitle: string;
+  stepSource: string;
+}
+
+export function readStepData(): StepData | null {
+  if (typeof document === "undefined") return null;
+  const node = document.getElementById("tt-step-data");
+  if (!node?.textContent) return null;
+  try {
+    return JSON.parse(node.textContent) as StepData;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a CopyPrompt template by substituting `{{placeholder}}`
+ * tokens with the values from step data. Unknown placeholders are
+ * left untouched so authors notice typos.
+ */
+export function renderTemplate(template: string, data: StepData): string {
+  const map: Record<string, string> = {
+    tutorialTitle: data.tutorialTitle,
+    tutorialSlug: data.tutorialSlug,
+    stepTitle: data.stepTitle,
+    stepSlug: data.stepSlug,
+    stepSource: data.stepSource,
+  };
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (raw, key) => {
+    return key in map ? map[key] : raw;
+  });
+}
+
+/**
+ * Construct a minimal AssistantContext from client-side step data
+ * for Family B touchpoints that need to call buildAssistantPrompt
+ * without the build-time context that ChatButton holds. Fields we
+ * don't know client-side (difficulty, tags, outline, prior steps,
+ * progress) come back empty; the intents that Family B uses
+ * (explainStep, recap) only read tutorial + currentStep.
+ */
+export function contextFromStepData(data: StepData): AssistantContext {
+  return {
+    tutorial: {
+      slug: data.tutorialSlug,
+      title: data.tutorialTitle,
+      description: "",
+      difficulty: "",
+      tags: [],
+    },
+    outline: [],
+    currentStep: {
+      slug: data.stepSlug,
+      title: data.stepTitle,
+      source: data.stepSource,
+    },
+    priorSteps: [],
+    progress: { completed: [], quizzes: [], checkpoints: [] },
+    references: [],
+  };
+}

package/src/lib/mdx-components.ts

@@ -1,10 +1,12 @@
 import Callout from "../components/mdx/Callout.astro";
 import Checkpoint from "../components/mdx/Checkpoint.astro";
+import CopyPrompt from "../components/mdx/CopyPrompt.astro";
 import Diff from "../components/mdx/Diff.astro";
 import Download from "../components/mdx/Download.astro";
 import Embed from "../components/mdx/Embed.astro";
 import File from "../components/mdx/File.astro";
 import FileTree from "../components/mdx/FileTree.astro";
+import HelpMe from "../components/mdx/HelpMe.astro";
 import Hint from "../components/mdx/Hint.astro";
 import Mermaid from "../components/mdx/Mermaid.astro";
 import Playground from "../components/mdx/Playground.astro";
@@ -43,5 +45,7 @@ export function mdxComponents() {
     Quiz,
     Checkpoint,
     Playground,
+    HelpMe,
+    CopyPrompt,
   };
 }

package/src/lib/progress/remote.ts

@@ -70,6 +70,14 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
   for (const id of Object.keys(prev.checkpoints)) {
     if (!next.checkpoints[id]) {
       out.push({ kind: "checkpoint", scope: "global", key: id, value: null });
+      // Family D: drop the matching kind:"verification" telemetry
+      // row so a re-attempt isn't pre-poisoned by the previous
+      // failure feedback. Scope comes from the feedback entry
+      // populated by SSE.
+      const feedback = prev.verificationFeedback[id];
+      if (feedback) {
+        out.push({ kind: "verification", scope: feedback.scope, key: id, value: null });
+      }
     }
   }
   for (const [k, value] of Object.entries(next.prefs)) {
@@ -95,6 +103,59 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
   return out;
 }
 
+/**
+ * Apply one server-side progress entry to a mutable state object.
+ * Shared by the initial snapshot fetch and the SSE per-event path.
+ * Mutates in place — callers replace the store atom after batching.
+ */
+function applyEntryInto(state: ProgressState, e: ProgressEntry): void {
+  if (e.kind === "step") {
+    state.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
+      | "incomplete"
+      | "complete";
+  } else if (e.kind === "quiz") {
+    state.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
+  } else if (e.kind === "checkpoint") {
+    if (e.value == null) {
+      delete state.checkpoints[e.key];
+      return;
+    }
+    state.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
+  } else if (e.kind === "pref") {
+    (state.prefs as Record<string, unknown>)[e.key] = e.value;
+  } else if (e.kind === "lastVisited") {
+    const v = e.value as unknown;
+    state.lastVisited[e.scope] =
+      typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
+  } else if (e.kind === "tutorial") {
+    const v = (e.value as { ts?: number }) ?? {};
+    const marker = state.tutorials[e.scope] ?? {};
+    if (e.key === "started") marker.started = v.ts;
+    else if (e.key === "completed") marker.completed = v.ts;
+    state.tutorials[e.scope] = marker;
+  } else if (e.kind === "verification") {
+    if (e.value == null) {
+      delete state.verificationFeedback[e.key];
+      return;
+    }
+    const v = e.value as {
+      pass: boolean;
+      failingCheckIndex?: number;
+      reason?: string;
+      hint?: string;
+      ts?: number;
+    };
+    state.verificationFeedback[e.key] = {
+      scope: e.scope as `${string}/${string}`,
+      pass: !!v.pass,
+      failingCheckIndex: v.failingCheckIndex,
+      reason: v.reason,
+      hint: v.hint,
+      ts: v.ts ?? Date.now(),
+    };
+  }
+}
+
 /**
  * Same shape as the local store, but mirrors writes to /api/progress with
  * debounced batching and an offline queue.
@@ -149,31 +210,7 @@ export function createRemoteStore(): ProgressStore {
           entries: Array<{ kind: string; scope: string; key: string; value: unknown }>;
         };
         const merged: ProgressState = { ...emptyState(), ...state };
-        for (const e of entries) {
-          if (e.kind === "step") {
-            merged.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
-              | "incomplete"
-              | "complete";
-          } else if (e.kind === "quiz") {
-            merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
-          } else if (e.kind === "checkpoint") {
-            if (e.value == null) continue;
-            merged.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
-          } else if (e.kind === "pref") {
-            (merged.prefs as Record<string, unknown>)[e.key] = e.value;
-          } else if (e.kind === "lastVisited") {
-            // Tolerate both new ({step, ts}) and legacy (string) shapes.
-            const v = e.value as unknown;
-            merged.lastVisited[e.scope] =
-              typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
-          } else if (e.kind === "tutorial") {
-            const v = (e.value as { ts?: number }) ?? {};
-            const marker = merged.tutorials[e.scope] ?? {};
-            if (e.key === "started") marker.started = v.ts;
-            else if (e.key === "completed") marker.completed = v.ts;
-            merged.tutorials[e.scope] = marker;
-          }
-        }
+        for (const e of entries) applyEntryInto(merged, e);
         state = merged;
         writeStorage(state);
         for (const fn of subscribers) fn(state);
@@ -181,6 +218,30 @@ export function createRemoteStore(): ProgressStore {
         // ignore — local data still drives the UI
       }
     })();
+
+    // Live sync: subscribe to per-learner SSE so MCP-driven writes
+    // (or another tab via the cookie POST) show up immediately. The
+    // standard EventSource auto-reconnects on transient drops.
+    if (typeof EventSource !== "undefined") {
+      try {
+        const es = new EventSource("/api/progress/events", { withCredentials: true });
+        es.addEventListener("message", (ev) => {
+          try {
+            const entry = JSON.parse(ev.data) as ProgressEntry;
+            const next: ProgressState = { ...state };
+            applyEntryInto(next, entry);
+            state = next;
+            writeStorage(state);
+            for (const fn of subscribers) fn(state);
+            channel?.postMessage({ type: "set", state });
+          } catch (e) {
+            console.warn("[handzon] sse parse failed:", e);
+          }
+        });
+      } catch {
+        // ignore — polling-via-mount still keeps things eventually consistent
+      }
+    }
   }
 
   return {

package/src/lib/progress/types.ts

@@ -16,10 +16,32 @@ export interface TutorialMarker {
   completed?: number;
 }
 
+/**
+ * Family D verification feedback delivered via SSE from
+ * `submit_verification` failures. Keyed by the checkpoint id (which
+ * equals `verify.id`). Carries the step scope so the diff can emit
+ * a tombstone with the right scope when the learner unchecks.
+ */
+export interface VerificationFeedbackEntry {
+  scope: StepKey;
+  pass: boolean;
+  failingCheckIndex?: number;
+  reason?: string;
+  hint?: string;
+  ts: number;
+}
+
 export type ProgressState = {
   steps: Record<StepKey, "incomplete" | "complete">;
   quizzes: Record<string, { chosen: number[]; correct: boolean; ts: number }>;
   checkpoints: Record<string, { ts: number }>;
+  /**
+   * Latest verification verdict per checkpoint id. `pass: true`
+   * entries hang around as evidence; the Family D UI only renders
+   * the inline hint block on `pass: false`. Cleared when the
+   * learner unchecks the matching checkpoint.
+   */
+  verificationFeedback: Record<string, VerificationFeedbackEntry>;
   prefs: {
     packageManager?: "npm" | "pnpm" | "yarn" | "bun";
     os?: "macos" | "linux" | "windows";
@@ -50,6 +72,7 @@ export const emptyState = (): ProgressState => ({
   steps: {},
   quizzes: {},
   checkpoints: {},
+  verificationFeedback: {},
   prefs: {},
   lastVisited: {},
   tutorials: {},

package/src/lib/progress/useProgress.ts

@@ -59,10 +59,14 @@ export function useProgress(): ProgressApi {
         })),
       removeCheckpoint: (checkpointId: string) =>
         store.set((s) => {
-          if (!s.checkpoints[checkpointId]) return s;
-          const next = { ...s.checkpoints };
-          delete next[checkpointId];
-          return { ...s, checkpoints: next };
+          const hadCheckpoint = !!s.checkpoints[checkpointId];
+          const hadFeedback = !!s.verificationFeedback[checkpointId];
+          if (!hadCheckpoint && !hadFeedback) return s;
+          const nextCheckpoints = { ...s.checkpoints };
+          delete nextCheckpoints[checkpointId];
+          const nextFeedback = { ...s.verificationFeedback };
+          delete nextFeedback[checkpointId];
+          return { ...s, checkpoints: nextCheckpoints, verificationFeedback: nextFeedback };
         }),
       setPref: <K extends keyof ProgressState["prefs"]>(key: K, value: ProgressState["prefs"][K]) =>
         store.set((s) => ({ ...s, prefs: { ...s.prefs, [key]: value } })),

package/src/pages/Home.astro

@@ -60,6 +60,7 @@ for (const t of tutorials) {
   repoUrl={repoUrl}
   nav="userMenu"
 >
+  <slot name="head" slot="head" />
   <div class="home">
     <Hero title={hero?.title} subtitle={hero?.subtitle} logoUrl={logoUrl} />
 
@@ -238,7 +239,12 @@ for (const t of tutorials) {
   }
   .grid {
     display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    /* Cap at 3 columns max: the lower-bound of each track is the larger
+     * of 280px or one-third of the row (minus the two 1rem gaps). On
+     * wide viewports the (100% - 2rem)/3 term wins and forces exactly
+     * 3 columns; on narrow viewports 280px wins and the grid wraps to
+     * 2 or 1 columns as usual. */
+    grid-template-columns: repeat(auto-fill, minmax(max(280px, (100% - 2rem) / 3), 1fr));
     gap: 1rem;
     margin-top: 0.75rem;
   }

package/src/pages/TutorialLanding.astro

@@ -26,6 +26,7 @@ const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >
+  <slot name="head" slot="head" />
   <div class="landing">
     <a class="back" href="/">← All tutorials</a>
 
@@ -58,7 +59,7 @@ const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
 
       {tutorial.data.tags.length > 0 && (
         <div class="hero-tags" aria-label="Topics">
-          {tutorial.data.tags.map((tag) => (
+          {tutorial.data.tags.map((tag: string) => (
             <a class="hero-tag" href={`/?tag=${encodeURIComponent(tag)}`}>#{tag}</a>
           ))}
         </div>
@@ -68,7 +69,7 @@ const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
     {tutorial.data.prerequisites.length > 0 && (
       <section class="block">
         <h2>Prerequisites</h2>
-        <ul class="prereqs">{tutorial.data.prerequisites.map((p) => <li>{p}</li>)}</ul>
+        <ul class="prereqs">{tutorial.data.prerequisites.map((p: string) => <li>{p}</li>)}</ul>
       </section>
     )}
 
@@ -188,10 +189,11 @@ const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
   }
   .hero-tag:hover { color: var(--color-accent); }
   h1 {
+    font-family: var(--font-display, var(--font-sans));
     font-size: clamp(2.1rem, 4.5vw, 3rem);
-    font-weight: 800;
+    font-weight: var(--font-weight-display, 800);
     margin: 0 0 0.75rem;
-    letter-spacing: -0.025em;
+    letter-spacing: var(--tracking-display, -0.025em);
     line-height: 1.05;
   }
   .desc {

package/src/pages/TutorialStep.astro

@@ -2,6 +2,9 @@
 import { render } from "astro:content";
 import TutorialLayout from "../layouts/TutorialLayout.astro";
 import ChatButton from "../components/ai/ChatButton.tsx";
+import OpenInAgent from "../components/ai/OpenInAgent.tsx";
+import SelectionAsk from "../components/ai/SelectionAsk.tsx";
+import StepHelp from "../components/ai/StepHelp.tsx";
 import { parseStepId } from "../lib/content.ts";
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
 import { mdxComponents } from "../lib/mdx-components.ts";
@@ -60,8 +63,17 @@ const initialContext = buildContext({
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >
+  <slot name="head" slot="head" />
   <Content components={components} />
+  {aiConfig.enabled && aiConfig.autoStepHelp && (
+    <StepHelp client:visible stepTitle={currentStep.data.title} />
+  )}
+  <OpenInAgent client:visible />
+
   {aiConfig.enabled && (
-    <ChatButton client:idle config={aiConfig} context={initialContext} />
+    <>
+      <ChatButton client:idle config={aiConfig} context={initialContext} />
+      <SelectionAsk client:idle />
+    </>
   )}
 </TutorialLayout>

package/src/server/auth.ts

@@ -2,7 +2,7 @@ import type { AstroCookieSetOptions, AstroCookies } from "astro";
 import { and, eq, isNull } from "drizzle-orm";
 import { getAuthedUser } from "./auth/session.ts";
 import { getDb } from "./db/client.ts";
-import { learners, progressEntries } from "./db/schema.ts";
+import { learnerApiTokens, learners, progressEntries } from "./db/schema.ts";
 
 const COOKIE = "tt-device";
 const ONE_YEAR = 60 * 60 * 24 * 365;
@@ -121,3 +121,86 @@ async function maybeClaimDeviceProgress(
     await tx.delete(learners).where(eq(learners.id, orphan.id));
   });
 }
+
+const PAT_PREFIX = "hzn_pat_";
+const PAT_RANDOM_BYTES = 32;
+
+/** Hash a raw PAT string to its database form. SHA-256 hex. */
+export async function hashPat(raw: string): Promise<string> {
+  const data = new TextEncoder().encode(raw);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Generate a fresh PAT to show the learner once. The settings page is
+ * the only caller — the API surface never sees the raw token after
+ * mint, and only the hash hits the database.
+ */
+export function generatePat(): string {
+  const bytes = new Uint8Array(PAT_RANDOM_BYTES);
+  crypto.getRandomValues(bytes);
+  // Base64url without padding — agent config files want short, copy/pasteable tokens.
+  const b64 = btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `${PAT_PREFIX}${b64}`;
+}
+
+/**
+ * Resolve a bearer token presented on an incoming request to the
+ * learner that owns it. Returns null when no token, the token is
+ * unknown, or it has expired. `last_used_at` is touched
+ * asynchronously so a slow DB write doesn't add latency to MCP calls.
+ *
+ * Used by the MCP endpoint; the cookie-based progress endpoint stays
+ * on getOrCreateLearner so the same-origin guard remains effective.
+ */
+export async function resolveBearerLearner(
+  request: Request,
+): Promise<{ learnerId: string; scopes: string[] } | null> {
+  const header = request.headers.get("authorization") ?? request.headers.get("Authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  if (!match) return null;
+  const raw = match[1]!;
+  if (!raw.startsWith(PAT_PREFIX)) return null;
+
+  const db = getDb();
+  const hash = await hashPat(raw);
+  const rows = await db
+    .select()
+    .from(learnerApiTokens)
+    .where(eq(learnerApiTokens.tokenHash, hash))
+    .limit(1);
+  const token = rows[0];
+  if (!token) return null;
+  if (token.expiresAt && token.expiresAt.getTime() < Date.now()) return null;
+
+  const learnerRow = await db
+    .select({ id: learners.id })
+    .from(learners)
+    .where(eq(learners.userId, token.userId))
+    .limit(1);
+  const learner = learnerRow[0];
+  if (!learner) return null;
+
+  // Fire-and-forget last-used touch. Failures are logged-but-ignored;
+  // an audit log is more useful than blocking the call.
+  void db
+    .update(learnerApiTokens)
+    .set({ lastUsedAt: new Date() })
+    .where(eq(learnerApiTokens.id, token.id))
+    .catch((e) => {
+      console.warn("[handzon] failed to update PAT last_used_at:", e);
+    });
+
+  const scopes = token.scopes
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return { learnerId: learner.id, scopes };
+}

package/src/server/db/schema.ts

@@ -40,6 +40,59 @@ export const learners = pgTable(
   }),
 );
 
+/**
+ * Personal access tokens for the per-user MCP surface.
+ *
+ * Created by the settings/tokens page in the scaffold template. Stored
+ * as SHA-256 hashes of `hzn_pat_<32 base64url bytes>` strings — the
+ * raw token is shown to the learner once at mint time and never
+ * persisted. The MCP v2 OAuth proxy reuses this table, so the row
+ * shape is forward-compatible with DCR-minted tokens.
+ *
+ * scopes: comma-separated; v1 known values are "progress:read" and
+ * "progress:write". Catalog reads don't require any scope beyond a
+ * valid token.
+ */
+export const learnerApiTokens = pgTable("learner_api_tokens", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  tokenHash: text("token_hash").notNull().unique(),
+  scopes: text("scopes").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+  expiresAt: timestamp("expires_at", { withTimezone: true }),
+});
+
+/**
+ * Help-bridge inbox: pending help requests posted by the agent on
+ * the learner's machine (`request_help` MCP tool). ChatPanel reads
+ * pending rows on open, prepends them as a user turn, and marks
+ * them consumed so the next open doesn't re-replay them.
+ */
+export const helpRequests = pgTable(
+  "help_requests",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    learnerId: uuid("learner_id")
+      .notNull()
+      .references(() => learners.id, { onDelete: "cascade" }),
+    tutorialSlug: text("tutorial_slug").notNull(),
+    stepSlug: text("step_slug").notNull(),
+    query: text("query").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+  },
+  (table) => ({
+    byLearnerPending: index("help_requests_by_learner_pending").on(
+      table.learnerId,
+      table.consumedAt,
+    ),
+  }),
+);
+
 export const progressEntries = pgTable(
   "progress_entries",
   {

package/src/server/handlers/helpInbox.ts

@@ -0,0 +1,45 @@
+import type { APIRoute } from "astro";
+import { and, eq, isNull } from "drizzle-orm";
+import { getOrCreateLearner } from "../auth.ts";
+import { getDb } from "../db/client.ts";
+import { helpRequests } from "../db/schema.ts";
+import { isSameOrigin, json } from "../http.ts";
+
+/**
+ * Returns the learner's pending help-request inbox (rows where
+ * consumed_at IS NULL) and stamps them as consumed in one
+ * round-trip. ChatPanel calls this when it opens; the response
+ * becomes the seed user turns that get auto-streamed.
+ *
+ * Same-origin guarded — only the in-browser ChatPanel reads the
+ * inbox. The MCP-side `request_help` tool produces rows; this
+ * endpoint consumes them.
+ */
+export const GET: APIRoute = async ({ cookies, request }) => {
+  if (!process.env.DATABASE_URL) return json({ requests: [] });
+  if (!isSameOrigin(request)) {
+    return json({ error: "Cross-origin read rejected." }, { status: 403 });
+  }
+  const learner = await getOrCreateLearner(cookies, request);
+  const db = getDb();
+  const rows = await db
+    .select()
+    .from(helpRequests)
+    .where(and(eq(helpRequests.learnerId, learner.id), isNull(helpRequests.consumedAt)));
+  if (rows.length > 0) {
+    const now = new Date();
+    await db
+      .update(helpRequests)
+      .set({ consumedAt: now })
+      .where(and(eq(helpRequests.learnerId, learner.id), isNull(helpRequests.consumedAt)));
+  }
+  return json({
+    requests: rows.map((r) => ({
+      id: r.id,
+      tutorialSlug: r.tutorialSlug,
+      stepSlug: r.stepSlug,
+      query: r.query,
+      createdAt: r.createdAt.toISOString(),
+    })),
+  });
+};

package/src/server/handlers/mcp.ts

@@ -0,0 +1,72 @@
+import type { APIRoute } from "astro";
+import { resolveBearerLearner } from "../auth.ts";
+import type { JsonRpcRequest } from "../mcp/protocol.ts";
+import { type DispatchOptions, dispatchMcp } from "../mcp/server.ts";
+import { defaultTools } from "../mcp/tools.ts";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+/**
+ * Build an Astro POST handler that mounts the MCP JSON-RPC dispatcher
+ * with the given tool set. Scaffold templates re-export this from
+ * `src/pages/api/mcp/index.ts` so updates land for every site
+ * without a code change in the consumer.
+ *
+ * GET /api/mcp returns a tiny capability descriptor that some
+ * clients ping before issuing JSON-RPC.
+ */
+export function createMcpHandler(
+  opts: DispatchOptions = { tools: defaultTools, resolveAuth: resolveBearerLearner },
+): {
+  GET: APIRoute;
+  POST: APIRoute;
+} {
+  const GET: APIRoute = async () =>
+    new Response(
+      JSON.stringify({
+        ok: true,
+        transport: "http+json",
+        message: "POST a JSON-RPC 2.0 request to invoke MCP tools.",
+      }),
+      { headers: { "Content-Type": "application/json" } },
+    );
+
+  const POST: APIRoute = async ({ request }) => {
+    const lengthHeader = request.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_BODY_BYTES) {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Payload too large." },
+      });
+    }
+    const raw = await request.text();
+    if (raw.length > MAX_BODY_BYTES) {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Payload too large." },
+      });
+    }
+    let body: JsonRpcRequest;
+    try {
+      body = JSON.parse(raw) as JsonRpcRequest;
+    } catch {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error." },
+      });
+    }
+    const response = await dispatchMcp(request, body, opts);
+    return jsonRpcHttp(response);
+  };
+
+  return { GET, POST };
+}
+
+function jsonRpcHttp(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "Content-Type": "application/json" },
+  });
+}