nixamp 0.68.2 → 0.70.0

package/src/school-cli.ts

@@ -0,0 +1,131 @@
+/**
+ * `nixamp school`: classes on backtoschool.help from the terminal.
+ *
+ * A class is a live event on nixamp's accounts, so `nixamp login` is the
+ * sign-in here too. `teach` is the short path: a station link in, a class on
+ * the air out. `check` and `prune` exist because a class stays live after
+ * its broadcast is gone, and the page then shows a player that never plays.
+ */
+import {
+  broadcastHealth, checkClasses, classUrl, createClass, deleteClass, getClass, listClasses, moveClass, teach, updateClass,
+  type SchoolClass,
+} from "./school-client.ts";
+
+export const SCHOOL_USAGE = `nixamp school: classes on backtoschool.help (sign in with \`nixamp login\`)
+
+  nixamp school [list] [--status live|scheduled|draft|ended] [--mine]
+  nixamp school show SLUG                 one class, and whether its broadcast plays
+  nixamp school teach LINK --title T [--description D] [--topic T] [--unlisted|--private]
+                                          make a class of a broadcast and start it now
+  nixamp school create --title T [LINK] [--starts 2026-11-01T17:00:00Z] [--description D] [--topic T]
+  nixamp school update SLUG [--title T] [--description D] [--topic T] [--link URL] [--public|--unlisted|--private]
+  nixamp school start SLUG
+  nixamp school end SLUG
+  nixamp school delete SLUG
+  nixamp school check                     your live classes, and which ones no longer play
+  nixamp school prune [--end|--delete]    end or delete the ones that no longer play (prints them without a flag)
+
+LINK is what plays: a station link (\`nixamp station show ID\`), a nixamp.com share link, a
+Pairux room, or an https .m3u8/.mp4/.mp3. SLUG is the class's slug or its /live/ link.
+  --json   machine-readable      NIXAMP_SCHOOL_URL   another site (backtoschool.help by default)
+`;
+
+function flag(argv: string[], name: string): string | undefined {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+}
+
+/** The first argument after the command that is not a flag or a flag's value. */
+function positional(argv: string[]): string | undefined {
+  const valued = new Set(["--title", "--description", "--topic", "--starts", "--link", "--status"]);
+  for (let at = 1; at < argv.length; at += 1) {
+    const one = argv[at]!;
+    if (valued.has(one)) { at += 1; continue; }
+    if (!one.startsWith("--")) return one;
+  }
+  return undefined;
+}
+
+function fields(argv: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, key] of [["--title", "title"], ["--description", "description"], ["--topic", "topic"], ["--starts", "startsAt"], ["--link", "broadcastUrl"]] as const) {
+    const value = flag(argv, name);
+    if (value !== undefined) out[key] = value;
+  }
+  for (const visibility of ["public", "unlisted", "private"]) if (argv.includes(`--${visibility}`)) out["visibility"] = visibility;
+  return out;
+}
+
+function print(item: SchoolClass): void {
+  console.log(`${item.status.padEnd(9)} ${item.title}\n          ${classUrl(item)}${item.broadcastUrl ? `\n          plays ${item.broadcastUrl}` : ""}`);
+}
+
+export async function school(argv: string[]): Promise<number> {
+  const [sub = "list"] = argv;
+  const json = argv.includes("--json");
+  const slug = positional(argv);
+  const out = (value: unknown, human: () => void): void => { if (json) console.log(JSON.stringify(value, null, 2)); else human(); };
+  try {
+    if (sub === "help" || argv.includes("--help")) {
+      console.log(SCHOOL_USAGE);
+      return 0;
+    }
+    if (sub === "list") {
+      const status = flag(argv, "--status");
+      const items = await listClasses({ ...(status ? { status } : {}), mine: argv.includes("--mine") });
+      out(items, () => { if (items.length === 0) console.log("No classes match."); for (const one of items) print(one); });
+      return 0;
+    }
+    if (sub === "check" || sub === "prune") {
+      const checked = await checkClasses();
+      const broken = checked.filter((one) => one.health.ok === false);
+      const act = sub === "prune" ? (argv.includes("--delete") ? "delete" : argv.includes("--end") ? "end" : "") : "";
+      for (const { item } of act ? broken : []) {
+        if (act === "delete") await deleteClass(item.id);
+        else await moveClass(item.id, "end");
+      }
+      out(checked.map(({ item, health }) => ({ slug: item.slug, ok: health.ok, reason: health.reason, ...(act && health.ok === false ? { done: act } : {}) })), () => {
+        if (checked.length === 0) console.log("You have no live classes.");
+        for (const { item, health } of checked) console.log(`${health.ok === true ? "plays " : health.ok === false ? "BROKEN" : "  ?   "}  ${item.slug}  (${health.reason})`);
+        if (sub === "prune" && broken.length > 0) console.log(act ? `\n${act === "delete" ? "Deleted" : "Ended"} ${broken.length}.` : `\n${broken.length} no longer play. --end or --delete them.`);
+      });
+      return 0;
+    }
+    if (sub === "teach" || sub === "create") {
+      const input = fields(argv);
+      if (slug) input["broadcastUrl"] = slug;
+      if (!input["title"]) { console.error(`nixamp school ${sub} needs --title`); return 2; }
+      if (sub === "teach" && !input["broadcastUrl"]) { console.error("nixamp school teach needs the LINK that plays"); return 2; }
+      const item = sub === "teach" ? await teach(input) : await createClass(input);
+      out(item, () => { print(item); if (sub === "create") console.log(`\nnixamp school start ${item.slug} puts it on the air.`); });
+      return 0;
+    }
+    if (!slug) { console.error(`nixamp school ${sub} needs a class (its slug or /live/ link)\n\n${SCHOOL_USAGE}`); return 2; }
+    if (sub === "show") {
+      const item = await getClass(slug);
+      const health = await broadcastHealth(item.broadcastUrl);
+      out({ ...item, broadcast: health }, () => { print(item); console.log(`          broadcast: ${health.ok === true ? "playing" : health.ok === false ? "NOT playing" : "unknown"} (${health.reason})`); });
+      return 0;
+    }
+    if (sub === "update") {
+      const item = await updateClass(slug, fields(argv));
+      out(item, () => print(item));
+      return 0;
+    }
+    if (sub === "start" || sub === "end") {
+      const item = await moveClass(slug, sub);
+      out(item, () => print(item));
+      return 0;
+    }
+    if (sub === "delete" || sub === "rm") {
+      await deleteClass(slug);
+      out({ ok: true, slug }, () => console.log(`Deleted ${slug}.`));
+      return 0;
+    }
+    console.error(`nixamp school: no command "${sub}".\n\n${SCHOOL_USAGE}`);
+    return 2;
+  } catch (error) {
+    console.error(`nixamp school: ${(error as Error).message}`);
+    return 1;
+  }
+}

package/src/school-client.ts

@@ -0,0 +1,180 @@
+/**
+ * backtoschool.help as a client: its classes are nixamp's live events, served
+ * by the same process on another host, so one nixamp token signs in to both.
+ *
+ * The CLI (school-cli.ts) and the MCP tools (school-mcp.ts) are both this
+ * file; neither talks HTTP itself.
+ *
+ * `broadcastHealth` is the reason this exists as much as the CRUD: a class
+ * stays "live" until somebody ends it, long after the channel it points at
+ * was stopped, and the page then shows a player that never plays. It asks the
+ * broadcast itself, with only what the public link already carries.
+ */
+import { readSession } from "./session.ts";
+
+export const SCHOOL_SITE = "https://backtoschool.help";
+
+type Fetcher = typeof fetch;
+
+export interface SchoolOptions {
+  /** backtoschool.help unless NIXAMP_SCHOOL_URL says otherwise; the tests hand in a local server. */
+  site?: string;
+  /** The session on disk (or NIXAMP_TOKEN) unless given; null means signed out. */
+  token?: string | null;
+  fetcher?: Fetcher;
+}
+
+export interface SchoolClass {
+  id: string;
+  slug: string;
+  title: string;
+  status: string;
+  visibility: string;
+  kind: string;
+  version: number;
+  ownerId: string;
+  broadcastUrl?: string | null;
+  description?: string;
+  topic?: string;
+  hostName?: string;
+  startsAt?: string | null;
+  [key: string]: unknown;
+}
+
+export class SchoolError extends Error {
+  constructor(message: string, readonly status = 0) {
+    super(message);
+  }
+}
+
+export function schoolSite(options: SchoolOptions = {}): string {
+  return (options.site ?? process.env["NIXAMP_SCHOOL_URL"] ?? SCHOOL_SITE).replace(/\/+$/, "");
+}
+
+export function classUrl(item: Pick<SchoolClass, "slug">, options: SchoolOptions = {}): string {
+  return `${schoolSite(options)}/live/${item.slug}`;
+}
+
+function tokenOf(options: SchoolOptions): string | null {
+  if (options.token !== undefined) return options.token;
+  return readSession()?.token ?? null;
+}
+
+async function call(path: string, init: { method?: string; body?: unknown; auth?: boolean } = {}, options: SchoolOptions = {}): Promise<Record<string, unknown>> {
+  const token = tokenOf(options);
+  if (init.auth && !token) throw new SchoolError("Not signed in. Run `nixamp login`, or set NIXAMP_TOKEN.", 401);
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (token) headers["authorization"] = `Bearer ${token}`;
+  if (init.body !== undefined) headers["content-type"] = "application/json";
+  const response = await (options.fetcher ?? fetch)(`${schoolSite(options)}${path}`, {
+    method: init.method ?? "GET",
+    headers,
+    ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+  });
+  const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!response.ok) throw new SchoolError(String(body["error"] ?? `backtoschool.help answered ${response.status}`), response.status);
+  return body;
+}
+
+const eventOf = (body: Record<string, unknown>): SchoolClass => (body["event"] ?? body) as SchoolClass;
+const ref = (value: string): string => encodeURIComponent(value.replace(/^.*\/live\//, "").replace(/[?#].*$/, ""));
+
+export async function listClasses(query: { status?: string; kind?: string; mine?: boolean; limit?: number } = {}, options: SchoolOptions = {}): Promise<SchoolClass[]> {
+  const params = new URLSearchParams();
+  if (query.status) params.set("status", query.status);
+  if (query.kind) params.set("kind", query.kind);
+  if (query.mine) params.set("mine", "true");
+  params.set("limit", String(query.limit ?? 60));
+  const body = await call(`/api/v1/events?${params}`, { auth: query.mine === true }, options);
+  return (body["events"] as SchoolClass[]) ?? [];
+}
+
+/** A class by its slug, id, or the /live/<slug> link. */
+export async function getClass(slug: string, options: SchoolOptions = {}): Promise<SchoolClass> {
+  return eventOf(await call(`/api/v1/events/${ref(slug)}`, {}, options));
+}
+
+export async function createClass(input: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  return eventOf(await call("/api/v1/events", { method: "POST", body: { kind: "class", visibility: "public", ...input }, auth: true }, options));
+}
+
+export async function updateClass(slug: string, patch: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  const current = await getClass(slug, options);
+  return eventOf(await call(`/api/v1/events/${ref(current.id)}`, { method: "PATCH", body: { ...patch, version: current.version }, auth: true }, options));
+}
+
+/** start, end, doors, encore, cancel or archive. Each wants the version it saw, so it is read first. */
+export async function moveClass(slug: string, action: "start" | "end" | "doors" | "encore" | "cancel" | "archive", options: SchoolOptions = {}): Promise<SchoolClass> {
+  const current = await getClass(slug, options);
+  return eventOf(await call(`/api/v1/events/${ref(current.id)}/${action}`, { method: "POST", body: { version: current.version }, auth: true }, options));
+}
+
+export async function deleteClass(slug: string, options: SchoolOptions = {}): Promise<void> {
+  await call(`/api/v1/events/${ref(slug)}`, { method: "DELETE", auth: true }, options);
+}
+
+/** Make a class of a broadcast and put it on the air in one go. */
+export async function teach(input: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  const made = await createClass(input, options);
+  return moveClass(made.slug, "start", options);
+}
+
+export interface Health {
+  ok: boolean | null;
+  reason: string;
+}
+
+/**
+ * Does this broadcast play? true and false are answers; null is "cannot tell
+ * from here" (a Pairux room), which a prune must leave alone.
+ */
+export async function broadcastHealth(link: string | null | undefined, fetcher: Fetcher = fetch, timeoutMs = 8000): Promise<Health> {
+  if (!link) return { ok: false, reason: "no broadcast link" };
+  let url: URL;
+  try {
+    url = new URL(link);
+  } catch {
+    return { ok: false, reason: "not a link" };
+  }
+  const get = (target: string, headers: Record<string, string> = {}): Promise<Response> =>
+    fetcher(target, { headers, signal: AbortSignal.timeout(timeoutMs) });
+  try {
+    // A station page: its own token opens its state.
+    const station = /^\/station\/([a-z0-9]{10})\/?$/.exec(url.pathname)?.[1];
+    if (station && url.hostname.endsWith(".nixamp.com")) {
+      const response = await get(`${url.origin}/api/v1/stations/${station}/state?t=${encodeURIComponent(url.searchParams.get("t") ?? "")}`);
+      if (!response.ok) return { ok: false, reason: `station ${station} answered ${response.status}` };
+      const state = (await response.json()) as { state?: string };
+      return state.state === "live" ? { ok: true, reason: `station ${station} is live` } : { ok: false, reason: `station ${station} is ${state.state ?? "not live"}` };
+    }
+    // nixamp.com/?url=<server>/view/<listen key>&play=channel:<id>: the listen key reads the server's channels.
+    if ((url.hostname === "nixamp.com" || url.hostname === "www.nixamp.com") && url.searchParams.get("url")) {
+      const server = new URL(url.searchParams.get("url")!);
+      const key = /\/view\/([^/?#]+)/.exec(server.pathname)?.[1] ?? "";
+      const play = url.searchParams.get("play") ?? "live";
+      const response = await get(`${server.origin}/api/streams?k=${encodeURIComponent(key)}`);
+      if (!response.ok) return { ok: false, reason: `${server.host} answered ${response.status}` };
+      const streams = (await response.json()) as { server?: { live?: boolean }; channels?: Array<{ id: string }> };
+      if (play.startsWith("channel:")) {
+        const id = play.slice("channel:".length);
+        return (streams.channels ?? []).some((one) => one.id === id)
+          ? { ok: true, reason: `channel ${id} is on ${server.hostname}` }
+          : { ok: false, reason: `channel ${id} is no longer on ${server.hostname}` };
+      }
+      if (play === "live") return streams.server?.live ? { ok: true, reason: `${server.hostname} is live` } : { ok: false, reason: `${server.hostname} is not live` };
+      return { ok: true, reason: `${server.hostname} is up` };
+    }
+    if (url.hostname === "pairux.com" || url.hostname === "www.pairux.com") return { ok: null, reason: "a Pairux room; cannot tell from here" };
+    // Direct media: one byte is enough to know it is there.
+    const response = await get(url.href, { range: "bytes=0-0" });
+    return response.ok ? { ok: true, reason: `${url.hostname} serves it` } : { ok: false, reason: `${url.hostname} answered ${response.status}` };
+  } catch (error) {
+    return { ok: false, reason: `unreachable: ${(error as Error).message}` };
+  }
+}
+
+/** Your live classes, each with whether its broadcast plays. */
+export async function checkClasses(options: SchoolOptions = {}, status = "live"): Promise<Array<{ item: SchoolClass; health: Health }>> {
+  const items = await listClasses({ mine: true, status }, options);
+  return Promise.all(items.map(async (item) => ({ item, health: await broadcastHealth(item.broadcastUrl, options.fetcher ?? fetch) })));
+}

package/src/school-discovery.ts

@@ -0,0 +1,212 @@
+/**
+ * backtoschool.help's own front door for agents: llms.txt, an OpenAPI
+ * document of the class API, and MCP at /mcp/public (reading) and /mcp
+ * (teaching, as the bearer).
+ *
+ * The school is served by the nixamp process under another Host, so before
+ * this its /llms.txt and /mcp answered as nixamp.com: an agent landing on
+ * the school was told about radio stations and handed no class tools. The
+ * routes here run only for the school's host, ahead of nixamp's.
+ *
+ * The tools are school-mcp.ts, called over HTTP against the school's own
+ * origin with the caller's token, exactly as from a CLI. Sign-in is nixamp's:
+ * one account, one token, and nixamp.com is the authorization server.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { SCHOOL_PUBLIC_TOOLS, SCHOOL_TOOLS, callSchoolTool, isSchoolPublicTool, isSchoolTool } from "./school-mcp.ts";
+import { SCHOOL_SITE } from "./school-client.ts";
+
+export interface SchoolDiscoveryContext {
+  /** This school's origin, e.g. https://backtoschool.help. */
+  site: string;
+  /** nixamp.com: where tokens come from and where OAuth is. */
+  accountSite: string;
+  version: string;
+  whoIs: (token: string) => Promise<unknown>;
+  token: string;
+  readBody: (request: IncomingMessage, limit: number) => Promise<string>;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  fetcher?: typeof fetch;
+}
+
+const CORS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+  "access-control-allow-headers": "authorization, content-type, mcp-session-id, mcp-protocol-version",
+};
+
+const PATHS = new Set(["/llms.txt", "/openapi.json", "/mcp", "/mcp/public", "/.well-known/oauth-protected-resource"]);
+
+/** Is this host the school? backtoschool.help (or NIXAMP_SCHOOL_URL), with or without www. */
+export function isSchoolSite(site: string | undefined, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (!site) return false;
+  const bare = (value: string): string => new URL(value).hostname.replace(/^www\./, "");
+  try {
+    return bare(site) === bare(env["NIXAMP_SCHOOL_URL"] ?? SCHOOL_SITE);
+  } catch {
+    return false;
+  }
+}
+
+export function schoolLlmsTxt(site: string, accountSite: string): string {
+  return `# BackToSchool.help
+
+> Live classes anybody can teach and anybody can join: a broadcast (a nixamp station, a screen share, a video link) with chat and raised hands around it. Free to watch. Accounts are nixamp accounts.
+
+## Web
+- ${site}/ : classes live now and coming up
+- ${site}/live/<slug> : one class
+
+## MCP
+- Public, no account (what is on, one class): ${site}/mcp/public
+- Signed in (teach, start, end, delete, check your classes): ${site}/mcp , a nixamp token as the bearer (\`nixamp token create\`) or OAuth via ${accountSite}
+- Local over stdio: npx -y nixamp mcp (the class tools are among nixamp's)
+
+Tools: classes_list, class_get, class_teach (a broadcast link in, a live class out), class_create, class_update, class_start, class_end, class_delete, classes_check (which of your live classes no longer play).
+
+## CLI
+- Install: curl -fsSL ${accountSite}/install.sh | sh   (or npx -y nixamp)
+- Sign in: nixamp login
+- nixamp school list --status live
+- nixamp school teach <station link> --title "..."   make a class and start it
+- nixamp school check | prune --end                 find and end classes whose broadcast stopped
+- nixamp school help
+
+## API
+- OpenAPI: ${site}/openapi.json
+- GET ${site}/api/v1/events?status=live : classes (public ones; ?mine=true with a token)
+- GET ${site}/api/v1/events/<slug> : one class
+- POST ${site}/api/v1/events : make one {title, broadcastUrl, description, topic, visibility, startsAt}
+- POST ${site}/api/v1/events/<slug>/start|end {version} : the version you last read
+- PATCH ${site}/api/v1/events/<slug> {..., version}, DELETE ${site}/api/v1/events/<slug>
+- Auth: Authorization: Bearer <nixamp token>
+
+## What a broadcast can be
+A nixamp station link (https://<server>.nixamp.com:4321/station/<id>?t=<token>), a nixamp.com share link, a Pairux room, or a direct https .m3u8/.mp4/.mp3. Only broadcast what you have the right to: your own teaching, or openly licensed courses (MIT OpenCourseWare is CC BY-NC-SA: free, credited, no ads).
+`;
+}
+
+export function schoolOpenapi(site: string, accountSite: string, version: string): Record<string, unknown> {
+  const ok = { description: "OK", content: { "application/json": { schema: { type: "object" } } } };
+  const auth = { security: [{ bearer: [] }] };
+  const slug = [{ name: "slug", in: "path", required: true, schema: { type: "string" }, description: "The class's slug or id." }];
+  const versioned = { content: { "application/json": { schema: { type: "object", properties: { version: { type: "integer" } }, required: ["version"] } } } };
+  const fields = {
+    title: { type: "string", maxLength: 160 }, description: { type: "string", maxLength: 5000 }, topic: { type: "string", maxLength: 100 },
+    broadcastUrl: { type: "string", format: "uri" }, visibility: { type: "string", enum: ["public", "unlisted", "private"] },
+    startsAt: { type: "string", format: "date-time" }, chatEnabled: { type: "boolean" }, handRaiseEnabled: { type: "boolean" },
+  };
+  return {
+    openapi: "3.1.0",
+    info: { title: "BackToSchool.help", version, description: "Live classes. Reading is open; teaching wants a nixamp token as the bearer.", license: { name: "MIT", identifier: "MIT" } },
+    servers: [{ url: site }],
+    externalDocs: { description: "llms.txt: MCP, CLI and API in one place", url: `${site}/llms.txt` },
+    components: { securitySchemes: { bearer: { type: "http", scheme: "bearer", description: `A nixamp token (\`nixamp token create\`) or an OAuth access token from ${accountSite}.` } } },
+    paths: {
+      "/api/v1/events": {
+        get: {
+          summary: "Classes", tags: ["classes"], responses: { 200: ok },
+          parameters: [
+            { name: "status", in: "query", schema: { type: "string", enum: ["draft", "scheduled", "starting", "live", "encore", "ended", "cancelled", "archived"] } },
+            { name: "mine", in: "query", schema: { type: "boolean" }, description: "Only yours (needs the bearer)." },
+            { name: "limit", in: "query", schema: { type: "integer", maximum: 100 } },
+          ],
+        },
+        post: { summary: "Make a class (a draft; start it to go live)", tags: ["classes"], ...auth, requestBody: { content: { "application/json": { schema: { type: "object", properties: { kind: { type: "string", enum: ["class", "talk", "concert"] }, ...fields }, required: ["title"] } } } }, responses: { 200: ok } },
+      },
+      "/api/v1/events/{slug}": {
+        parameters: slug,
+        get: { summary: "One class", tags: ["classes"], responses: { 200: ok } },
+        patch: { summary: "Change a class you host", tags: ["classes"], ...auth, requestBody: { content: { "application/json": { schema: { type: "object", properties: { ...fields, version: { type: "integer" } }, required: ["version"] } } } }, responses: { 200: ok } },
+        delete: { summary: "Delete a class you host", tags: ["classes"], ...auth, responses: { 200: ok } },
+      },
+      "/api/v1/events/{slug}/start": { parameters: slug, post: { summary: "Go live", tags: ["classes"], ...auth, requestBody: versioned, responses: { 200: ok } } },
+      "/api/v1/events/{slug}/end": { parameters: slug, post: { summary: "End it", tags: ["classes"], ...auth, requestBody: versioned, responses: { 200: ok } } },
+      "/api/v1/events/{slug}/chat": { parameters: slug, get: { summary: "The class chat", tags: ["chat"], responses: { 200: ok } }, post: { summary: "Say something", tags: ["chat"], ...auth, responses: { 200: ok } } },
+      "/api/v1/auth/me": { get: { summary: "Who the bearer is", tags: ["auth"], ...auth, responses: { 200: ok } } },
+      "/mcp/public": { post: { summary: "MCP (streamable HTTP, JSON-RPC): classes_list, class_get", tags: ["mcp"], responses: { 200: ok } } },
+      "/mcp": { post: { summary: "MCP (streamable HTTP, JSON-RPC): every class tool, as the bearer", tags: ["mcp"], ...auth, responses: { 200: ok } } },
+    },
+  };
+}
+
+type Message = { id?: unknown; method?: unknown; params?: Record<string, unknown> };
+
+export async function handleSchoolDiscovery(request: IncomingMessage, response: ServerResponse, path: string, ctx: SchoolDiscoveryContext): Promise<boolean> {
+  if (!PATHS.has(path)) return false;
+  const method = request.method ?? "GET";
+  const site = ctx.site.replace(/\/+$/, "");
+  if (method === "OPTIONS") {
+    response.writeHead(204, CORS);
+    response.end();
+    return true;
+  }
+  if (path === "/llms.txt" || path === "/openapi.json" || path === "/.well-known/oauth-protected-resource") {
+    if (method !== "GET" && method !== "HEAD") { ctx.json(response, 405, { error: "GET only" }); return true; }
+    const [type, body] = path === "/llms.txt"
+      ? ["text/plain; charset=utf-8", schoolLlmsTxt(site, ctx.accountSite)]
+      : ["application/json; charset=utf-8", JSON.stringify(path === "/openapi.json"
+        ? schoolOpenapi(site, ctx.accountSite, ctx.version)
+        : { resource: site, authorization_servers: [ctx.accountSite], bearer_methods_supported: ["header"], resource_name: "BackToSchool.help" }, null, 2)];
+    response.writeHead(200, { ...CORS, "content-type": type, "cache-control": "public, max-age=300" });
+    response.end(method === "HEAD" ? undefined : body);
+    return true;
+  }
+  // MCP. GET has nothing to push; DELETE ends a session nobody keeps.
+  if (method === "GET") { response.writeHead(405, { ...CORS, allow: "POST, DELETE" }); response.end(); return true; }
+  if (method === "DELETE") { response.writeHead(204, CORS); response.end(); return true; }
+  if (method !== "POST") { ctx.json(response, 405, { error: "POST a JSON-RPC message" }); return true; }
+  const signed = path === "/mcp";
+  if (signed && (await ctx.whoIs(ctx.token)) === null) {
+    const error = JSON.stringify({ error: "sign in: a nixamp token as the bearer (`nixamp token create`), or OAuth" });
+    response.writeHead(401, {
+      ...CORS,
+      "content-type": "application/json; charset=utf-8",
+      "www-authenticate": `Bearer resource_metadata="${site}/.well-known/oauth-protected-resource"`,
+    });
+    response.end(error);
+    return true;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await ctx.readBody(request, 256 * 1024));
+  } catch {
+    ctx.json(response, 400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+    return true;
+  }
+  const tools = signed ? SCHOOL_TOOLS : SCHOOL_PUBLIC_TOOLS;
+  const allowed = signed ? isSchoolTool : isSchoolPublicTool;
+  const answers: unknown[] = [];
+  for (const message of (Array.isArray(parsed) ? parsed : [parsed]) as Message[]) {
+    const id = message?.id ?? null;
+    const name = typeof message?.method === "string" ? message.method : "";
+    if (name.startsWith("notifications/")) continue;
+    if (name === "initialize") {
+      answers.push({ jsonrpc: "2.0", id, result: {
+        protocolVersion: (message.params?.["protocolVersion"] as string | undefined) ?? "2025-06-18",
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "backtoschool", title: "BackToSchool.help: live classes", version: "1" },
+        instructions: signed
+          ? "Live classes on BackToSchool.help. classes_list / class_get to see what is on; class_teach puts a broadcast (a nixamp station link, a Pairux room, an https video) on the air as a class in one call; classes_check finds your live classes whose broadcast stopped, and class_end / class_delete clear them. Only broadcast what you have the right to."
+          : "Live classes on BackToSchool.help: classes_list and class_get. To teach, use /mcp with a nixamp token as the bearer.",
+      } });
+    } else if (name === "ping") {
+      answers.push({ jsonrpc: "2.0", id, result: {} });
+    } else if (name === "tools/list") {
+      answers.push({ jsonrpc: "2.0", id, result: { tools } });
+    } else if (name === "tools/call" && allowed(String(message.params?.["name"] ?? ""))) {
+      const result = await callSchoolTool(String(message.params!["name"]), (message.params?.["arguments"] ?? {}) as Record<string, unknown>, {
+        site, token: ctx.token || null, ...(ctx.fetcher ? { fetcher: ctx.fetcher } : {}),
+      });
+      answers.push({ jsonrpc: "2.0", id, result });
+    } else if (name === "tools/call") {
+      answers.push({ jsonrpc: "2.0", id, error: { code: -32001, message: "only classes_list and class_get are public; for the rest use /mcp with a nixamp token as the bearer (`nixamp token create`), or OAuth" } });
+    } else {
+      answers.push({ jsonrpc: "2.0", id, error: { code: -32601, message: `no method ${name}` } });
+    }
+  }
+  if (answers.length === 0) { response.writeHead(202, CORS); response.end(); return true; }
+  response.writeHead(200, { ...CORS, "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(Array.isArray(parsed) ? answers : answers[0]));
+  return true;
+}