@kainoa/5c-mcp 0.4.0

package/README.md

@@ -0,0 +1,33 @@
+# @kainoa/5c-mcp
+
+MCP server for the Claremont Colleges (5C) course catalog — 5 read-only tools
+over the shared 5c-core engine: `search_classes` · `get_classes` ·
+`check_schedule` · `list_terms` · `get_course_history`.
+
+Every tool declares an input **and** an output schema, so the documented shape
+is the validated shape. Input schemas are strict (`additionalProperties:
+false`): unknown parameters are rejected with -32602 naming the key.
+Logs go to stderr only; stdout carries MCP messages.
+
+## Install
+
+Point your MCP host (Claude Code, Codex, Cursor, Desktop) at npm — no clone, no
+build:
+
+```json
+{
+  "mcpServers": {
+    "5c-index": { "command": "npx", "args": ["-y", "@kainoa/5c-mcp"] }
+  }
+}
+```
+
+Requires Node 20 or newer. Experimental stateless Streamable HTTP on localhost:
+`npx -y @kainoa/5c-mcp --http --port 3000`.
+
+Data comes from [HyperSchedule](https://hyperschedule.io) (the 5C registrars'
+catalogs) through a local snapshot cache; seats are snapshots, always quoted
+with `fetched_at` and a `stale` flag.
+
+The CLI twin ([`@kainoa/5c-cli`](https://www.npmjs.com/package/@kainoa/5c-cli)) and docs:
+[notkainoa/5C-Index](https://github.com/notkainoa/5C-Index).

package/dist/chunk-3PCAZ5XS.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+// ../core/dist/chunk-M5LVN3BK.js
+import { z } from "zod";
+var rawDateSchema = z.object({
+	year: z.number(),
+	month: z.number().min(1).max(12),
+	day: z.number().min(1).max(31),
+});
+var rawCourseCodeSchema = z.object({
+	department: z.string(),
+	courseNumber: z.number(),
+	suffix: z.string(),
+	affiliation: z.string(),
+});
+var rawScheduleSchema = z.object({
+	startTime: z.number(),
+	// seconds since midnight
+	endTime: z.number(),
+	days: z.array(z.string()),
+	locations: z.array(z.string()),
+});
+var rawSectionSchema = z.object({
+	courseAreas: z.array(z.string()),
+	credits: z.number(),
+	permCount: z.number().default(0),
+	seatsTotal: z.number(),
+	seatsFilled: z.number(),
+	status: z.string(),
+	// O | C | R | U (keep raw; map to labels downstream)
+	startDate: rawDateSchema,
+	endDate: rawDateSchema,
+	instructors: z.array(z.object({ name: z.string() })),
+	course: z.object({
+		code: rawCourseCodeSchema,
+		title: z.string(),
+		description: z.string(),
+		primaryAssociation: z.string(),
+		potentialError: z.boolean().default(false),
+	}),
+	schedules: z.array(rawScheduleSchema),
+	potentialError: z.boolean().default(false),
+	identifier: z.object({
+		department: z.string(),
+		courseNumber: z.number(),
+		suffix: z.string(),
+		affiliation: z.string(),
+		sectionNumber: z.number(),
+		year: z.number(),
+		term: z.string(),
+		// FA | SP | SU
+		half: z.nullable(z.object({ prefix: z.string(), number: z.number() })),
+	}),
+});
+var rawSectionsSchema = z.array(rawSectionSchema);
+var rawHistoryEntrySchema = z.object({
+	code: rawCourseCodeSchema,
+	terms: z.array(z.object({ year: z.number(), term: z.string() })),
+});
+var rawHistorySchema = z.array(rawHistoryEntrySchema);
+var rawTermSchema = z.object({ year: z.number(), term: z.string() });
+var rawCourseAreaSchema = z.object({
+	area: z.string(),
+	description: z.string(),
+});
+var termSchema = z
+	.string()
+	.regex(/^(FA|SP|SU)\d{4}$/, "Term must look like FA2026");
+var daySchema = z.enum(["M", "T", "W", "R", "F", "S", "U"]);
+var statusSchema = z.enum(["O", "C", "R", "U"]);
+var meetingSchema = z.object({
+	days: z.array(daySchema),
+	startMin: z.number(),
+	// minutes since midnight (math)
+	endMin: z.number(),
+	startStr: z.string(),
+	// "13:15" (quote)
+	endStr: z.string(),
+	start12: z.string(),
+	// "1:15 PM" (display)
+	end12: z.string(),
+	locations: z.array(z.string()),
+});
+var sectionSchema = z.object({
+	id: z.string(),
+	// "CSCI 051 PO-01 FA2026" (canonical, frozen v1)
+	term: termSchema,
+	year: z.number(),
+	termCode: z.enum(["FA", "SP", "SU"]),
+	half: z.nullable(z.object({ prefix: z.string(), number: z.number() })),
+	dept: z.string(),
+	number: z.number(),
+	suffix: z.string(),
+	school: z.string(),
+	// affiliation, uppercase (PO/CM/HM/SC/PZ + KS/JP/…)
+	sectionNo: z.number(),
+	code: z.string(),
+	// "CSCI 051" (dept + zero-padded + suffix, no school)
+	title: z.string(),
+	description: z.string(),
+	areas: z.array(z.string()),
+	instructors: z.array(z.string()),
+	meetings: z.array(meetingSchema),
+	credits: z.number(),
+	status: statusSchema,
+	statusLabel: z.string(),
+	// Open | Closed | Reopened | Unknown
+	seats: z.object({
+		filled: z.number(),
+		total: z.number(),
+		available: z.number(),
+		permCount: z.number(),
+	}),
+	startDate: z.string(),
+	// ISO
+	endDate: z.string(),
+	potentialError: z.boolean(),
+	primaryAssociation: z.string(),
+	affiliation: z.string(),
+});
+var cacheMetaSchema = z.object({
+	term: z.string(),
+	fetched_at: z.string(),
+	etag: z.string().nullable(),
+	hash: z.string(),
+	count: z.number(),
+	source_url: z.string(),
+	ttl_kind: z.string(),
+	stale: z.boolean(),
+	source: z.enum(["live", "stale-cache", "offline-file"]),
+});
+var BANANA_BASE = "https://banana.hyperschedule.io/v4";
+var USER_AGENT = "5C-Index/0.1 (+research/edu; cache 60s)";
+async function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+async function fetchJson(url, validate, opts = {}, fetchFn = globalThis.fetch) {
+	const { etag, timeoutMs = 15e3, retries = 3 } = opts;
+	let lastErr = null;
+	for (let attempt = 0; attempt <= retries; attempt++) {
+		const ctrl = new AbortController();
+		const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+		try {
+			const res = await fetchFn(url, {
+				signal: ctrl.signal,
+				headers: {
+					Accept: "application/json",
+					"User-Agent": USER_AGENT,
+					...(etag ? { "If-None-Match": etag } : {}),
+				},
+			});
+			clearTimeout(timer);
+			if (res.status === 304) {
+				return { data: void 0, etag: etag ?? null, notModified: true };
+			}
+			if (res.status === 404) {
+				const err = new Error(`Not found: ${url}`);
+				err.code = "E_NOT_FOUND_UPSTREAM";
+				throw err;
+			}
+			if (res.status === 429 || res.status >= 500) {
+				const retryAfter = res.headers.get("Retry-After");
+				const wait = retryAfter
+					? Math.min(Number.parseInt(retryAfter, 10) * 1e3 || 2e3, 15e3)
+					: Math.min(500 * 2 ** attempt + Math.random() * 250, 8e3);
+				lastErr = new Error(`Upstream ${res.status} for ${url}`);
+				if (attempt < retries) {
+					await sleep(wait);
+					continue;
+				}
+				throw lastErr;
+			}
+			if (!res.ok) {
+				const err = new Error(`Upstream ${res.status} for ${url}`);
+				err.code = "E_FETCH";
+				throw err;
+			}
+			const json = await res.json();
+			return {
+				data: validate(json),
+				etag: res.headers.get("ETag"),
+				notModified: false,
+			};
+		} catch (err) {
+			clearTimeout(timer);
+			if (err.code === "E_NOT_FOUND_UPSTREAM") throw err;
+			if (err.name === "AbortError") {
+				lastErr = new Error(`Timeout fetching ${url}`);
+			} else {
+				lastErr = err;
+			}
+			if (attempt < retries && (!err.code || err.code === "E_FETCH")) {
+				if (err.code === "E_FETCH") throw err;
+				await sleep(Math.min(500 * 2 ** attempt + Math.random() * 250, 8e3));
+				continue;
+			}
+			throw lastErr;
+		}
+	}
+	throw lastErr;
+}
+function fetchAllTerms(opts, fetchFn) {
+	return fetchJson(
+		`${BANANA_BASE}/term/all`,
+		(u) => rawTermSchema.array().parse(u),
+		opts,
+		fetchFn,
+	);
+}
+function fetchCurrentTerm(opts, fetchFn) {
+	return fetchJson(
+		`${BANANA_BASE}/term/current`,
+		(u) => rawTermSchema.parse(u),
+		opts,
+		fetchFn,
+	);
+}
+function fetchSections(term, opts, fetchFn) {
+	return fetchJson(
+		`${BANANA_BASE}/sections/${term}`,
+		(u) => rawSectionsSchema.parse(u),
+		opts,
+		fetchFn,
+	);
+}
+function fetchOfferingHistory(term, opts, fetchFn) {
+	return fetchJson(
+		`${BANANA_BASE}/offering-history/${term}`,
+		(u) => rawHistorySchema.parse(u),
+		opts,
+		fetchFn,
+	);
+}
+function fetchCourseAreas(opts, fetchFn) {
+	return fetchJson(
+		`${BANANA_BASE}/course-areas`,
+		(u) =>
+			u.map((x) => ({
+				area: String(x.area),
+				description: String(x.description),
+			})),
+		opts,
+		fetchFn,
+	);
+}
+
+export {
+	rawSectionsSchema,
+	rawHistorySchema,
+	BANANA_BASE,
+	USER_AGENT,
+	fetchJson,
+	fetchAllTerms,
+	fetchCurrentTerm,
+	fetchSections,
+	fetchOfferingHistory,
+	fetchCourseAreas,
+};

package/dist/chunk-B3TGUWJT.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+// ../core/dist/chunk-BUUEIEGG.js
+import { z } from "zod";
+var rawDateSchema = z.object({
+  year: z.number(),
+  month: z.number().min(1).max(12),
+  day: z.number().min(1).max(31)
+});
+var rawCourseCodeSchema = z.object({
+  department: z.string(),
+  courseNumber: z.number(),
+  suffix: z.string(),
+  affiliation: z.string()
+});
+var rawScheduleSchema = z.object({
+  startTime: z.number(),
+  // seconds since midnight
+  endTime: z.number(),
+  days: z.array(z.string()),
+  locations: z.array(z.string())
+});
+var rawSectionSchema = z.object({
+  courseAreas: z.array(z.string()),
+  credits: z.number(),
+  permCount: z.number().default(0),
+  seatsTotal: z.number(),
+  seatsFilled: z.number(),
+  status: z.string(),
+  // O | C | R | U (keep raw; map to labels downstream)
+  startDate: rawDateSchema,
+  endDate: rawDateSchema,
+  instructors: z.array(z.object({ name: z.string() })),
+  course: z.object({
+    code: rawCourseCodeSchema,
+    title: z.string(),
+    description: z.string(),
+    primaryAssociation: z.string(),
+    potentialError: z.boolean().default(false)
+  }),
+  schedules: z.array(rawScheduleSchema),
+  potentialError: z.boolean().default(false),
+  identifier: z.object({
+    department: z.string(),
+    courseNumber: z.number(),
+    suffix: z.string(),
+    affiliation: z.string(),
+    sectionNumber: z.number(),
+    year: z.number(),
+    term: z.string(),
+    // FA | SP | SU
+    half: z.nullable(z.object({ prefix: z.string(), number: z.number() }))
+  })
+});
+var rawSectionsSchema = z.array(rawSectionSchema);
+var rawHistoryEntrySchema = z.object({
+  code: rawCourseCodeSchema,
+  terms: z.array(z.object({ year: z.number(), term: z.string() }))
+});
+var rawHistorySchema = z.array(rawHistoryEntrySchema);
+var rawTermSchema = z.object({ year: z.number(), term: z.string() });
+var rawCourseAreaSchema = z.object({
+  area: z.string(),
+  description: z.string()
+});
+var termSchema = z.string().regex(/^(FA|SP|SU)\d{4}$/, "Term must look like FA2026");
+var daySchema = z.enum(["M", "T", "W", "R", "F", "S", "U"]);
+var statusSchema = z.enum(["O", "C", "R", "U"]);
+var meetingSchema = z.object({
+  days: z.array(daySchema),
+  startMin: z.number(),
+  // minutes since midnight (math)
+  endMin: z.number(),
+  startStr: z.string(),
+  // "13:15" (quote)
+  endStr: z.string(),
+  start12: z.string(),
+  // "1:15 PM" (display)
+  end12: z.string(),
+  locations: z.array(z.string())
+});
+var sectionSchema = z.object({
+  id: z.string(),
+  // "CSCI 051 PO-01 FA2026" (canonical, frozen v1)
+  term: termSchema,
+  year: z.number(),
+  termCode: z.enum(["FA", "SP", "SU"]),
+  half: z.nullable(z.object({ prefix: z.string(), number: z.number() })),
+  dept: z.string(),
+  number: z.number(),
+  suffix: z.string(),
+  school: z.string(),
+  // affiliation, uppercase (PO/CM/HM/SC/PZ + KS/JP/…)
+  sectionNo: z.number(),
+  code: z.string(),
+  // "CSCI 051" (dept + zero-padded + suffix, no school)
+  title: z.string(),
+  description: z.string(),
+  areas: z.array(z.string()),
+  instructors: z.array(z.string()),
+  meetings: z.array(meetingSchema),
+  credits: z.number(),
+  status: statusSchema,
+  statusLabel: z.string(),
+  // Open | Closed | Reopened | Unknown
+  seats: z.object({
+    filled: z.number(),
+    total: z.number(),
+    available: z.number(),
+    permCount: z.number()
+  }),
+  startDate: z.string(),
+  // ISO
+  endDate: z.string(),
+  potentialError: z.boolean(),
+  primaryAssociation: z.string(),
+  affiliation: z.string()
+});
+var cacheMetaSchema = z.object({
+  term: z.string(),
+  fetched_at: z.string(),
+  etag: z.string().nullable(),
+  hash: z.string(),
+  count: z.number(),
+  source_url: z.string(),
+  ttl_kind: z.string(),
+  stale: z.boolean(),
+  source: z.enum(["live", "stale-cache", "offline-file"])
+});
+var BANANA_BASE = "https://banana.hyperschedule.io/v4";
+var USER_AGENT = "5C-Index/0.1 (+research/edu; cache 60s)";
+async function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function fetchJson(url, validate, opts = {}, fetchFn = globalThis.fetch) {
+  const { etag, timeoutMs = 15e3, retries = 3 } = opts;
+  let lastErr = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetchFn(url, {
+        signal: ctrl.signal,
+        headers: {
+          Accept: "application/json",
+          "User-Agent": USER_AGENT,
+          ...etag ? { "If-None-Match": etag } : {}
+        }
+      });
+      clearTimeout(timer);
+      if (res.status === 304) {
+        return { data: void 0, etag: etag ?? null, notModified: true };
+      }
+      if (res.status === 404) {
+        const err = new Error(`Not found: ${url}`);
+        err.code = "E_NOT_FOUND_UPSTREAM";
+        throw err;
+      }
+      if (res.status === 429 || res.status >= 500) {
+        const retryAfter = res.headers.get("Retry-After");
+        const wait = retryAfter ? Math.min(Number.parseInt(retryAfter, 10) * 1e3 || 2e3, 15e3) : Math.min(500 * 2 ** attempt + Math.random() * 250, 8e3);
+        lastErr = new Error(`Upstream ${res.status} for ${url}`);
+        if (attempt < retries) {
+          await sleep(wait);
+          continue;
+        }
+        throw lastErr;
+      }
+      if (!res.ok) {
+        const err = new Error(`Upstream ${res.status} for ${url}`);
+        err.code = "E_FETCH";
+        throw err;
+      }
+      const json = await res.json();
+      return {
+        data: validate(json),
+        etag: res.headers.get("ETag"),
+        notModified: false
+      };
+    } catch (err) {
+      clearTimeout(timer);
+      if (err.code === "E_NOT_FOUND_UPSTREAM") throw err;
+      if (err.name === "AbortError") {
+        lastErr = new Error(`Timeout fetching ${url}`);
+      } else {
+        lastErr = err;
+      }
+      if (attempt < retries && (!err.code || err.code === "E_FETCH")) {
+        if (err.code === "E_FETCH") throw err;
+        await sleep(Math.min(500 * 2 ** attempt + Math.random() * 250, 8e3));
+        continue;
+      }
+      throw lastErr;
+    }
+  }
+  throw lastErr;
+}
+function fetchAllTerms(opts, fetchFn) {
+  return fetchJson(
+    `${BANANA_BASE}/term/all`,
+    (u) => rawTermSchema.array().parse(u),
+    opts,
+    fetchFn
+  );
+}
+function fetchCurrentTerm(opts, fetchFn) {
+  return fetchJson(
+    `${BANANA_BASE}/term/current`,
+    (u) => rawTermSchema.parse(u),
+    opts,
+    fetchFn
+  );
+}
+function fetchSections(term, opts, fetchFn) {
+  return fetchJson(
+    `${BANANA_BASE}/sections/${term}`,
+    (u) => rawSectionsSchema.parse(u),
+    opts,
+    fetchFn
+  );
+}
+function fetchOfferingHistory(term, opts, fetchFn) {
+  return fetchJson(
+    `${BANANA_BASE}/offering-history/${term}`,
+    (u) => rawHistorySchema.parse(u),
+    opts,
+    fetchFn
+  );
+}
+function fetchCourseAreas(opts, fetchFn) {
+  return fetchJson(
+    `${BANANA_BASE}/course-areas`,
+    (u) => u.map((x) => ({
+      area: String(x.area),
+      description: String(x.description)
+    })),
+    opts,
+    fetchFn
+  );
+}
+
+export {
+  rawSectionsSchema,
+  rawHistorySchema,
+  BANANA_BASE,
+  USER_AGENT,
+  fetchJson,
+  fetchAllTerms,
+  fetchCurrentTerm,
+  fetchSections,
+  fetchOfferingHistory,
+  fetchCourseAreas
+};