@cyanheads/college-scorecard-mcp-server 0.1.9 → 0.2.0

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** college-scorecard-mcp-server
-**Version:** 0.1.9
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.2.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
 **Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -54,7 +54,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -188,13 +188,14 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
-| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
+| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
+| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
 | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
-| `ctx.requestId` | Unique request ID. |
+| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
 | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
@@ -203,7 +204,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -215,7 +216,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** college-scorecard-mcp-server
-**Version:** 0.1.9
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.2.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
 **Zod:** ^4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -54,7 +54,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -188,13 +188,14 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
-| `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
+| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
+| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
 | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
-| `ctx.requestId` | Unique request ID. |
+| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
 | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
@@ -203,7 +204,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`). Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -215,7 +216,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
   return item;
 }
 ```

package/Dockerfile

@@ -5,8 +5,8 @@
 # source code into JavaScript, and prepares the production assets.
 #
 # Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
-# JavaScript, and only `dist/` crosses into the production stage, which runs its
-# own target-arch install. Built for the target instead, the non-native leg of a
+# JavaScript, and only `dist/` crosses into the production stage.
+# Built for the target instead, the non-native leg of a
 # `--platform linux/amd64,linux/arm64` build runs under QEMU, where bun >= 1.4
 # aborts with a JavaScriptCore allocator assertion and fails the multi-arch push.
 #
@@ -14,7 +14,7 @@
 # output. A stage that compiles a native addon needs the target-arch toolchain
 # and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
 
 WORKDIR /usr/src/app
 
@@ -36,59 +36,74 @@ RUN bun run build
 
 
 # ==============================================================================
-# Production Stage
+# Production Dependencies Stage
 #
-# This stage creates a minimal, optimized, and secure image for running the
-# application. It uses a slim base image and only includes production
-# dependencies and build artifacts.
+# Run the scanner and OTel installer natively, cross-installing production
+# dependencies for the target architecture. Only node_modules leaves this stage.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
 
 WORKDIR /usr/src/app
 
-# Set the environment to production for performance and to ensure only
-# production dependencies are installed.
-ENV NODE_ENV=production
+# Keep the release-age gate and security scanner on every production install.
+COPY package.json bun.lock bunfig.toml ./
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
 
-# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-ARG APP_VERSION=unknown
-LABEL org.opencontainers.image.title="college-scorecard-mcp-server"
-LABEL org.opencontainers.image.description="Search, compare, and analyze U.S. college data — costs, earnings, programs, and outcomes — via MCP."
-LABEL org.opencontainers.image.licenses="Apache-2.0"
-LABEL org.opencontainers.image.source="https://github.com/cyanheads/college-scorecard-mcp-server"
-LABEL org.opencontainers.image.version="${APP_VERSION}"
-
-# Copy dependency manifests
-COPY package.json bun.lock ./
+# Docker uses amd64; Bun uses x64. Both support arm64 unchanged.
+ARG TARGETOS
+ARG TARGETARCH
+RUN case "$TARGETARCH" in \
+      amd64) echo x64 ;; \
+      arm64) echo arm64 ;; \
+      *) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
+    esac > .bun-cpu
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
 # `--omit=peer` drops the framework's optional peer tiers (test runner, service
 # SDKs, parsers) that Bun would otherwise auto-install. Anything this server
 # actually imports belongs in its own `dependencies`, so nothing needed at
-# runtime is lost. The OTEL step below carries the same flag — without it, that
-# install re-resolves the graph and pulls every optional peer back in.
+# runtime is lost.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
+      --os="$TARGETOS" --cpu="$(cat .bun-cpu)"
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # Installed by default. Omit them for a leaner image at build time
 # with: docker build --build-arg OTEL_ENABLED=false
+COPY scripts/install-otel.ts ./scripts/
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
-        @opentelemetry/exporter-metrics-otlp-http \
-        @opentelemetry/exporter-trace-otlp-http \
-        @opentelemetry/instrumentation-pino \
-        @opentelemetry/resources \
-        @opentelemetry/sdk-metrics \
-        @opentelemetry/sdk-node \
-        @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
+      bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
     fi
 
+# The scanner is only needed during installation.
+RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
+
+
+# ==============================================================================
+# Production Stage
+#
+# Runtime-only stage: Bun runs on the target architecture at container start.
+# ==============================================================================
+FROM oven/bun:1.4.2-slim AS production
+
+WORKDIR /usr/src/app
+ENV NODE_ENV=production
+
+# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+ARG APP_VERSION=unknown
+LABEL org.opencontainers.image.title="college-scorecard-mcp-server"
+LABEL org.opencontainers.image.description="Search, compare, and analyze U.S. college data — costs, earnings, programs, and outcomes — via MCP."
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.source="https://github.com/cyanheads/college-scorecard-mcp-server"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+
+# Keep the original manifest; the OTel installer rewrites the deps-stage copy.
+COPY package.json ./
+COPY --from=deps /usr/src/app/node_modules ./node_modules
+
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
 
@@ -113,7 +128,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/college-scorecard-mcp-server"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/college-scorecard-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/college-scorecard-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/college-scorecard-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/college-scorecard-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/college-scorecard-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/college-scorecard-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -29,14 +29,14 @@ U.S. college data from the Department of Education College Scorecard API — cos
 
 | Tool | Description |
 |:---|:---|
-| `scorecard_search_schools` | Search and filter institutions by name, location, type, size, and acceptance rate range. Returns core identity and cost metrics. |
-| `scorecard_get_school` | Full institutional profile for one or more school IDs — costs, admissions, outcomes, aid, demographics, and completion rates. |
+| `scorecard_search_schools` | Search institutions by name, location, type, size, acceptance rate, and single-sex flags; sort by supported API fields. Returns core identity and cost metrics. |
+| `scorecard_get_school` | Full institutional profiles — costs, admissions, outcomes, aid, demographics, single-sex flags, and completion rates. |
 | `scorecard_compare_schools` | Normalized side-by-side comparison of 2–5 schools on a named topic. Returns percentile-ranked rows and relative deltas within the result set. |
-| `scorecard_get_programs` | All field-of-study programs at one school: median 1-year post-graduation earnings, debt at graduation, and enrollment figures. |
-| `scorecard_search_programs` | Find programs by CIP code or keyword across all institutions, ranked by median earnings. Accepts school-side filters (state, ownership, max cost). |
+| `scorecard_get_programs` | Field-of-study programs at one school: median 1-year earnings, cumulative Stafford/Grad PLUS debt, and IPEDS awards in the two pooled debt-cohort years. |
+| `scorecard_search_programs` | Find programs by CIP code or keyword, with school, earnings, and debt filters; rank by earnings within each fetched school page. |
 | `scorecard_get_earnings` | Institution-level post-graduation earnings for one school — median at 6, 8, and 10 years after entry (P25/P75 at 6 and 10 years), with optional gender breakdown. |
 | `scorecard_value_analysis` | Workflow tool: parallel-fetches cost, debt, repayment, and earnings data, then computes ROI metrics — debt-to-earnings ratio and net price to earnings ratio. |
-| `scorecard_lookup_cip` | Search a curated ~160-code Classification of Instructional Programs (CIP) taxonomy by keyword or partial name. Served from embedded static data — no API call or rate-limit impact. |
+| `scorecard_lookup_cip` | Search 202 curated Classification of Instructional Programs (CIP) codes by keyword or partial name. Served from embedded static data — no API call or rate-limit impact. |
 | `scorecard_list_fields` | Search the Scorecard field catalog by keyword. Returns matching field paths, descriptions, data types, and sort support. Use before passing custom `fields` parameters. |
 
 ### Resources
@@ -58,89 +58,68 @@ All resource data is also reachable via tools. Use `scorecard_search_schools` or
 
 ### `scorecard_search_schools` <sub>tool</sub>
 
-- Free-text name search plus typed filters: state, ownership (public/private nonprofit/private for-profit), degree level, size range, acceptance rate range
-- Geographic proximity filtering by U.S. zip code and distance (miles or km)
-- CIP code filter to find schools offering a specific program family
-- Pagination (`per_page` up to 100, zero-indexed `page`)
-- Returns core identity and cost metrics for quick scanning
+- Search by name, state, ownership, degree level, size, acceptance rate, CIP code, or zip code and distance; `per_page` is capped at 100 with zero-indexed `page`.
+- Returns core identity and cost metrics for quick scanning.
+- `sort` forwards a supported API expression such as `latest.cost.avg_net_price.overall:asc` (`:desc` reverses it). `men_only` and `women_only` accept true or false; omission includes unknown flags, while false selects only explicit zero values.
 
 ---
 
 ### `scorecard_get_school` <sub>tool</sub>
 
-- Accepts a single ID or an array of IDs (batch fetch up to 100 per call)
-- Covers costs, admissions, outcomes, financial aid, demographics, and completion rates
-- Optional `fields` override for callers who need a narrower or broader field set
-- For side-by-side comparison on a specific dimension, use `scorecard_compare_schools`
+- Accepts a single school ID or an array of up to 100 IDs per call.
+- Returns institutional profiles covering costs, admissions, outcomes, financial aid, demographics, and completion rates; `fields` overrides the default selection. `men_only` and `women_only` preserve true/false when known and are absent when unknown.
 
 ---
 
 ### `scorecard_compare_schools` <sub>tool</sub>
 
-- 2–5 school unit IDs per call; four topics — `costs`, `admissions`, `outcomes`, `aid` — each pulls a curated topic-specific field set
-- Computes within-set percentile ranks and relative deltas — structured output an agent cannot reconstruct from raw profiles
-- Single API call for all schools; normalization applied post-fetch
-- Distinct from `scorecard_get_school` with multiple IDs: output shape is rows, not profiles
+- Accepts 2–5 school unit IDs and one topic: `costs`, `admissions`, `outcomes`, or `aid`.
+- Returns comparison rows with within-set percentile ranks and relative deltas from a single API call.
 
 ---
 
 ### `scorecard_get_programs` <sub>tool</sub>
 
-- Returns median 1-year post-graduation earnings, median debt at graduation, and enrollment figures per program
-- Filter by CIP code to return only matching programs
-- Filter by `credential_level` (certificate through doctoral/professional) and minimum earnings threshold
-- Primary source for program-level earnings — institution-level earnings at 6/8/10 years are available via `scorecard_get_earnings`
-- FERPA suppression surfaced as a structured `suppressed: true` flag with `suppression_note`, not bare null
+- Accepts one school ID, with optional CIP code, `credential_level`, and minimum earnings filters.
+- Returns median earnings and the matching count of graduates working and not enrolled 1 year after their highest credential, with `suppressed` and `suppression_note` for unavailable earnings.
+- `median_debt` is completers' cumulative Stafford/Grad PLUS borrowing across attended institutions at the same academic level. `ipeds_awards_year1` and `ipeds_awards_year2` count awards in each year of the pooled debt cohort, not enrollment or unique students.
 
 ---
 
 ### `scorecard_search_programs` <sub>tool</sub>
 
-- Program-centric: "which schools in Washington have CS programs with median earnings over $80k?"
-- School-side filters: state, ownership, max net price; program-side filters: min earnings, max debt
-- Pagination (`per_page` up to 100, zero-indexed `page`) is at the school level — a school with multiple matching programs can return more rows than `per_page`
-- Returns school ID (unit ID) and name alongside program metrics for chaining to `scorecard_get_school` or `scorecard_get_programs`
-- Sorting applied post-fetch since earnings fields aren't API-indexed
+- Search by CIP code or program name, with state, ownership, net price, earnings, and debt filters; zero-indexed `page` and `per_page` (up to 100) paginate schools, so returned program rows may exceed `per_page`.
+- Returns school IDs and names alongside program metrics, sorted by earnings within the fetched page.
+- `min_earnings` filters locally; totals and pagination remain upstream school counts before local filtering. Earnings/debt thresholds are inclusive and exclude unknown values. Debt and award fields have the same meanings as in `scorecard_get_programs`.
 
 ---
 
 ### `scorecard_get_earnings` <sub>tool</sub>
 
-- Median earnings at 6, 8, and 10 years after entry, with P25/P75 percentiles at 6 and 10 years
-- Optional 6-year gender breakdown (`earnings_6yr_female_median` / `earnings_6yr_male_median`) when reported
-- Optional `years` array of cohort entry years returns a per-year trend row (6yr and 10yr median) alongside the current snapshot
-- Institution-wide across all graduates — for program-specific earnings use `scorecard_get_programs`, for ROI analysis use `scorecard_value_analysis`
-- Top-level `suppressed` / `suppression_note` flags when earnings are unavailable at every time point
+- Accepts one school ID and optional `years` for cohort trends and a gender-breakdown option.
+- Returns median earnings at 6, 8, and 10 years after entry, P25/P75 at 6 and 10 years, and optional 6-year female/male medians; `suppressed` and `suppression_note` flag earnings unavailable at every time point.
+- Each requested trend year adds its 6-year and 10-year median alongside the current snapshot.
 
 ---
 
 ### `scorecard_value_analysis` <sub>tool</sub>
 
-- Parallel-fetches cost/debt/repayment and earnings data in two concurrent requests
-- Computes ROI metrics the API doesn't pre-calculate: debt-to-earnings ratio (median debt / 6-year earnings) and net price to annualized 6-year earnings ratio
-- `family_income` parameter selects the applicable net price bracket ($0–30k, $30k–48k, $48k–75k, $75k–110k, $110k+)
-- Returns all source figures alongside derived metrics — callers can audit the arithmetic
-- `data_notes` array flags any suppressed or missing fields with plain-language explanations
+- Accepts one school ID; optional `family_income` selects the applicable net price bracket ($0–30k, $30k–48k, $48k–75k, $75k–110k, or $110k+).
+- Returns debt-to-earnings and net-price-to-earnings ratios alongside the source figures; `data_notes` explains suppressed or missing fields.
 
 ---
 
 ### `scorecard_lookup_cip` <sub>tool</sub>
 
-- Curated set of ~160 common 4-digit CIP codes embedded as static data — not the full NCES taxonomy
-- No API call required — zero rate-limit impact, works offline
-- Required before using CIP-based filters when the caller knows a program by name but not code
-- Up to 50 results per call (`limit`, default 20)
-- Returns matching codes with standard titles and CIP family
+- Search by keyword or partial name with `limit` up to 50 (default 20); use before CIP filters when the code is unknown.
+- Returns codes, standard titles, and CIP families from a curated offline set of 202 common 4-digit codes, rather than the full NCES taxonomy.
 
 ---
 
 ### `scorecard_list_fields` <sub>tool</sub>
 
-- ~79 field entries curated from the Scorecard data dictionary, embedded as static data
-- No API call required — zero rate-limit impact
-- Returns field path, description, data type, category, and whether it supports API-side sorting
-- Up to 100 results per call (`limit`, default 30)
-- Use before passing custom `fields` parameters to `scorecard_search_schools` or `scorecard_get_school`; a `tip` field flags when results include unsortable fields
+- Search 80 curated offline field entries with `limit` up to 100 (default 30); use before passing custom `fields` to `scorecard_get_school`.
+- Returns field paths, descriptions, data types, categories, and API sorting support; `tip` flags results containing unsortable fields.
 
 ---
 
@@ -154,7 +133,7 @@ All resource data is also reachable via tools. Use `scorecard_search_schools` or
 
 ### `scorecard://programs/{id}` <sub>resource</sub>
 
-- Program-level outcomes as `application/json` — CIP code, title, credential level, 1-year earnings, debt, and enrollment per program
+- Program-level outcomes as `application/json` — CIP code, title, credential level, 1-year earnings, cumulative Stafford/Grad PLUS debt, and `ipeds_awards_year1` / `ipeds_awards_year2` with the same meanings as the program tools; missing metrics are null
 - `id` is the school unit ID from `scorecard_search_schools`
 - `list` returns a handful of example school URIs; use `scorecard_search_schools` to discover others
 
@@ -172,9 +151,9 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 College Scorecard-specific:
 
 - Full College Scorecard API coverage: ~6,500 Title IV institutions, ~2,800 data fields spanning costs, outcomes, demographics, financial aid, and field-of-study earnings
-- Program-level post-graduation earnings: median earnings 1 year after graduation per school × CIP code combination
+- Program-level earnings: median earnings of graduates working and not enrolled 1 year after their highest credential, per school × CIP code × credential level
 - Field pre-selection per tool — curated field sets appropriate to each tool's purpose; optional `fields` override for custom queries
-- Embedded CIP code taxonomy (~160 codes) and field catalog (~79 fields) served as static data — zero API calls, zero rate-limit impact
+- Embedded CIP code taxonomy (202 codes) and field catalog (80 fields) served as static data — zero API calls, zero rate-limit impact
 - Geographic filtering via U.S. zip code + distance radius
 
 Agent-friendly output:
@@ -182,7 +161,7 @@ Agent-friendly output:
 - FERPA suppression surfaced as structured `suppressed: true` flag with `suppression_note` — prevents hallucination of missing earnings data at selective schools with small cohorts
 - Derived metrics alongside source figures in `scorecard_value_analysis` — agents can verify arithmetic and branch on computed values, not raw numbers
 - Percentile ranks and relative deltas in `scorecard_compare_schools` — structured output an agent cannot reconstruct from raw profiles without knowing the full comparison set
-- Post-fetch sorting documented and handled transparently — callers never hit API errors on non-indexed sort fields
+- School sorting uses indexed API fields; check `scorecard_list_fields` before choosing a sort expression. Six-year earnings does not support API sorting. Program earnings ordering applies within each fetched school page.
 
 ## Getting started
 

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,47 @@
+---
+summary: "Program enrollment output is removed in favor of ipeds_awards_year1 and ipeds_awards_year2, with program debt and earnings counts read from the correct Scorecard fields. School search gains sort and single-sex filters, and the value-analysis net-price ratio is no longer inflated sixfold."
+breaking: true
+security: false
+---
+
+# 0.2.0 — 2026-09-30
+
+**Breaking:** program `enrollment` is gone from `scorecard_get_programs`, `scorecard_search_programs`, and `scorecard://programs/{id}`. Read `ipeds_awards_year1` and `ipeds_awards_year2` instead — IPEDS awards conferred in each of the two pooled debt-cohort years. They count awards, not enrollment or unique students, and no program-level enrollment figure replaces the old field.
+
+## Added
+
+- **`scorecard_search_schools` `sort`, `men_only`, `women_only`** ([#8](https://github.com/cyanheads/college-scorecard-mcp-server/issues/8)) — `sort` forwards an API sort expression such as `latest.cost.avg_net_price.overall:asc`. Each flag sends `1` for true and `0` for false; omitting it applies no filter and keeps schools with an unknown flag.
+- **`scorecard_get_school` `men_only` / `women_only`** ([#8](https://github.com/cyanheads/college-scorecard-mcp-server/issues/8)) — booleans when the API reports the flag, absent when it does not; rendered as Yes/No.
+- **`ipeds_awards_year1` / `ipeds_awards_year2`** ([#16](https://github.com/cyanheads/college-scorecard-mcp-server/issues/16)) on both program tools and the programs resource, read from `counts.ipeds_awards1` / `counts.ipeds_awards2`. Tools omit an unknown count; the resource returns `null`.
+
+## Changed
+
+- **Program `median_debt`** ([#16](https://github.com/cyanheads/college-scorecard-mcp-server/issues/16)) now reads `debt.staff_grad_plus.all.all_inst.median` — completers' median cumulative Stafford/Grad PLUS borrowing across institutions at the same academic level. `max_debt` filters on the same path, is inclusive, and now excludes programs with unknown debt.
+- **`scorecard_get_programs` `earnings_count`** ([#16](https://github.com/cyanheads/college-scorecard-mcp-server/issues/16)) now reads `earnings.highest.1_yr.working_not_enrolled.overall_count`, the population behind the 1-year median.
+- **`scorecard_search_programs` `min_earnings`** ([#18](https://github.com/cyanheads/college-scorecard-mcp-server/issues/18)) filters the fetched school page locally instead of being sent upstream, where the earnings field is not indexed. It is inclusive and now excludes programs with unavailable earnings; `total` and pagination stay school counts before local filtering.
+- **`scorecard_list_fields` catalog** ([#8](https://github.com/cyanheads/college-scorecard-mcp-server/issues/8), [#16](https://github.com/cyanheads/college-scorecard-mcp-server/issues/16)) — `sortable` flags follow the data dictionary's INDEX column (`latest.earnings.6_yrs_after_entry.median` is no longer marked sortable), and the program entries use the paths above plus `credential.level`.
+- **Docker image** — production dependencies and the OpenTelemetry peers (`scripts/install-otel.ts`) now install in a `$BUILDPLATFORM` stage, cross-installed for the target OS and CPU. Base images move to `oven/bun:1.4.2`; the image no longer sets `MCP_FORCE_CONSOLE_LOGGING`.
+- **Packaging** — the npm `files` allowlist excludes `dist/*.mcpb`, and the `.mcpb` bundle leaves out `docs/idea.md` and `logs/`.
+- **Framework scripts and skills** synced to `@cyanheads/mcp-ts-core` 0.13.10 — `lint-packaging` adds checks 13–15 (npm bundle exclusion, `manifest.json` version parity, Dockerfile build platform) and `release-github` gains `--check`. 31 skill directories and `CLAUDE.md` / `AGENTS.md` follow.
+- **README and `docs/design.md`** describe the corrected program fields, school sorting, and page-local program ranking; embedded data counts are corrected to 202 CIP codes and 80 catalog fields.
+- **Contract tests** ([#10](https://github.com/cyanheads/college-scorecard-mcp-server/issues/10)) — `tests/services/scorecard-contract.test.ts` drives the tools through the real `ScorecardService` over a fetch fake, including the empty-ID `ValidationError` that fails before any request.
+
+## Removed
+
+- **Program `enrollment`** ([#16](https://github.com/cyanheads/college-scorecard-mcp-server/issues/16)) from `scorecard_get_programs`, `scorecard_search_programs`, and `scorecard://programs/{id}` — see the migration note above.
+
+## Fixed
+
+- **`scorecard_value_analysis` `net_price_to_annual_earnings`** ([#20](https://github.com/cyanheads/college-scorecard-mcp-server/issues/20)) — the ratio divided `earnings_6yr_median`, already an annual figure, by six; it is now net price / `earnings_6yr_median`, so values are one sixth of what earlier versions returned. The description no longer claims a Carnegie peer-group comparison.
+- **Full final pages no longer report `truncated: true`** ([#19](https://github.com/cyanheads/college-scorecard-mcp-server/issues/19)) — `scorecard_search_schools` and `scorecard_search_programs` derive continuation from the API's page metadata, so next-page guidance appears only when a later page exists.
+- **`scorecard_search_programs` notices compose** ([#9](https://github.com/cyanheads/college-scorecard-mcp-server/issues/9)) — suppressed-earnings or no-match guidance and next-page guidance share one `notice` instead of the pagination text replacing the other.
+- **A rejected API key fails after one attempt** ([#13](https://github.com/cyanheads/college-scorecard-mcp-server/issues/13)) — HTTP 401/403 and `API_KEY_MISSING` / `API_KEY_INVALID` responses carry `data.retryable: false`. HTTP 429 and 5xx responses still retry.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.13.6` → `^0.13.10` — resolves `@modelcontextprotocol/server` 2.1.0. Error envelopes now carry `data.requestId`, and error text closes with `(reason … · request <id>)`.
+- `@socketsecurity/bun-security-scanner` `^1.1.2` → `^1.1.3` (dev)
+- `@types/node` `^26.6.2` → `^26.6.3` (dev)
+- `ignore` `^7.0.9` → `^7.0.10` (dev)
+- `vitest` `^5.0.1` → `^5.0.2` (dev)
+- `packageManager` `bun@1.4.0` → `bun@1.4.2`

package/dist/data/field-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-catalog.d.ts","sourceRoot":"","sources":["../../src/data/field-catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB;IAChB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClD;AAED,mFAAmF;AACnF,eAAO,MAAM,aAAa,EAAE,UAAU,EAmkBrC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,UAAU,EAAE,CAsB1E"}
+{"version":3,"file":"field-catalog.d.ts","sourceRoot":"","sources":["../../src/data/field-catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB;IAChB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClD;AAED,mFAAmF;AACnF,eAAO,MAAM,aAAa,EAAE,UAAU,EA+kBrC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,UAAU,EAAE,CAsB1E"}