@cyanheads/college-scorecard-mcp-server 0.3.0 → 0.4.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** college-scorecard-mcp-server
-**Version:** 0.3.0
+**Version:** 0.4.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
@@ -179,6 +179,12 @@ await createApp({
 
 This server declares `sessionMode: 'stateless'` in `src/index.ts`: no tool calls `ctx.requestInput`, so no request depends on a live session.
 
+### Scorecard metric semantics
+
+Institution earnings cover federally aided undergraduate entrants working and not enrolled, regardless of completion. Earnings `years` is the published API data-file start-year domain 1996–2025, not an entry-year selector. `src/data/earnings-context.ts` holds official per-metric cohort/measurement/dollar provenance; refresh it from the dictionary when coverage changes, never infer vintage by arithmetic or sample equality.
+
+`readMetric` distinguishes numbers (including zero), unknown-cause null/absence, and explicit `PS` / `PrivacySuppressed` markers. Suppression flags/counts require the latter; unexpected values are provider contract failures. CIP lookup remains a curated set of current NCES four-digit groups, with exact group/family titles and verified descendant aliases. Program search applies CIP × credential together upstream before school pagination; totals remain school-level.
+
 ---
 
 ## Context

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** college-scorecard-mcp-server
-**Version:** 0.3.0
+**Version:** 0.4.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
@@ -179,6 +179,12 @@ await createApp({
 
 This server declares `sessionMode: 'stateless'` in `src/index.ts`: no tool calls `ctx.requestInput`, so no request depends on a live session.
 
+### Scorecard metric semantics
+
+Institution earnings cover federally aided undergraduate entrants working and not enrolled, regardless of completion. Earnings `years` is the published API data-file start-year domain 1996–2025, not an entry-year selector. `src/data/earnings-context.ts` holds official per-metric cohort/measurement/dollar provenance; refresh it from the dictionary when coverage changes, never infer vintage by arithmetic or sample equality.
+
+`readMetric` distinguishes numbers (including zero), unknown-cause null/absence, and explicit `PS` / `PrivacySuppressed` markers. Suppression flags/counts require the latter; unexpected values are provider contract failures. CIP lookup remains a curated set of current NCES four-digit groups, with exact group/family titles and verified descendant aliases. Program search applies CIP × credential together upstream before school pagination; totals remain school-level.
+
 ---
 
 ## Context

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.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.3.1-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.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.4.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.3.1-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.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -39,10 +39,10 @@ U.S. college data from the Department of Education College Scorecard API — cos
 | `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 metric values, ordinal ranks, and a comparison summary. |
 | `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_search_programs` | Find programs by CIP and credential or keyword, retain degree identity, and rank earnings within each fetched school page. |
+| `scorecard_get_earnings` | Earnings of federally aided undergraduate entrants working and not enrolled, regardless of completion: 6/8/10-year medians, 6/10-year P25/P75, and non-male/male 6-year medians. |
 | `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 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_lookup_cip` | Search 186 curated NCES CIP 2020 four-digit groups by code, keyword, or verified descendant alias. Served offline. |
 | `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
@@ -81,7 +81,7 @@ All resource data is also reachable via tools. Use `scorecard_search_schools` or
 ### `scorecard_compare_schools` <sub>tool</sub>
 
 - Accepts 2–5 school unit IDs and one topic: `costs`, `admissions`, `outcomes`, or `aid`.
-- Returns comparison rows with metric values, within-set ordinal ranks, and a comparison summary from a single API call.
+- Returns metric values and competition ranks from one API call: equal values share a rank (1, 1, 3), unavailable values are unranked, and summaries name tied leaders. Each cell's `availability` distinguishes available, unavailable with unknown cause, and confirmed privacy suppression.
 
 ---
 
@@ -89,44 +89,45 @@ All resource data is also reachable via tools. Use `scorecard_search_schools` or
 
 - Accepts one school ID, with optional CIP code, `credential_level`, and minimum earnings filters.
 - Existing schools with no reported or matching programs return a successful empty collection; a nonexistent school remains a lookup error. Dotted and undotted four-digit CIP codes are equivalent.
-- 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.
+- Returns median earnings and the matching count of graduates working and not enrolled 1 year after their highest credential. `earnings_availability` is `available`, `unavailable`, or `privacy_suppressed`; zero is available, null/absence has unknown cause, and only explicit provider privacy markers set `suppressed`. `suppressed_count` and `unavailable_count` distinguish those populations.
 - `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>
 
-- 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.
+- Search by CIP code or program name, with optional integer `credential_level`, 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`. CIP and credential selectors apply together upstream before pagination; credential codes are 1–8 and 99, and unknown integer selectors may return no matches.
+- Returns school IDs and names alongside program metrics and provider `credential_level` / `credential_title`, retaining separate credentials and future numeric credential levels; missing identity fields stay absent. Available earnings sort first; availability states and counts have the same meaning as in `scorecard_get_programs`.
 - `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>
 
-- 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.
+- Accepts one school ID and optional API data-file start `years` from 1996–2025. These are file vintages, not entry years; valid files without observations succeed. Omit `years` or pass `[]` for snapshot only.
+- Institution earnings cover federally aided undergraduate entrants working and not enrolled, regardless of completion. Returns medians at 6/8/10 years after entry, 6/10-year P25/P75, and non-male/male 6-year medians.
+- `current_availability` and `trend[].availability` classify each supported metric; aggregate `suppressed` requires every current metric to carry an explicit privacy marker. Null and omitted values do not prove suppression.
+- `current_context` and `trend[].context` give per-metric `data_file_year`, verified academic `entry_cohorts`, calendar `measurement_years`, and inflation `dollar_year`. Metadata comes from the official cohort maps; unknown parts are omitted. Values retain the provider's dollar basis, so cross-vintage comparisons require checking it. Each requested file adds six- and ten-year medians without extra requests.
 
 ---
 
 ### `scorecard_value_analysis` <sub>tool</sub>
 
 - 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.
+- Returns ratios alongside their source figures. `effective_net_price` discloses the price used, and `net_price_basis` is `income_bracket`, `overall`, or `unavailable`. A missing bracket preserves requested `family_income` / `applicable_income_bracket` and explains the established overall-price fallback in `data_notes`. Zero estimates remain valid; ratios require positive annual earnings.
 
 ---
 
 ### `scorecard_lookup_cip` <sub>tool</sub>
 
 - Search by nonblank keyword or partial name (default limit 20); requests up to 1,000 are accepted and served at a cap of 50. Totals count before slicing; exact-cap results are not truncated, and no matches return an empty collection with guidance.
-- Returns codes, standard titles, and CIP families from a curated offline set of 202 common 4-digit codes, rather than the full NCES taxonomy.
+- Dotted `11.07` and undotted `1107` queries are equivalent. Returns exact group titles and family identities from 186 current NCES CIP 2020 four-digit groups; verified six-digit descendant names act as keyword aliases, returning their canonical group. This curated set is a subset of the full taxonomy.
 
 ---
 
 ### `scorecard_list_fields` <sub>tool</sub>
 
-- Search 80 curated offline field entries by nonblank query (default limit 30); requests up to 1,000 are accepted and served at a cap of 100. Totals count before slicing; no matches return an empty collection with guidance. Use before passing custom `fields` to `scorecard_get_school`.
+- Search 78 curated offline field entries by nonblank query (default limit 30); requests up to 1,000 are accepted and served at a cap of 100. Totals count before slicing; no matches return an empty collection with guidance. 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.
 
 ---
@@ -150,7 +151,7 @@ All resource data is also reachable via tools. Use `scorecard_search_schools` or
 ### `scorecard_compare_prompt` <sub>prompt</sub>
 
 - Arguments: `school_names` (comma-separated list) and `focus` (`costs` | `outcomes` | `programs`), both required
-- Returns one user message sequencing `scorecard_search_schools` → `scorecard_compare_schools` → `scorecard_get_school`, plus `scorecard_get_programs`/`scorecard_lookup_cip` when focus is `programs` or `scorecard_value_analysis` otherwise
+- Costs/outcomes sequence school discovery, `scorecard_compare_schools`, profiles, and value analysis. Programs sequence school discovery, CIP lookup, and `scorecard_get_programs` per school; compare matching credentials using returned earnings, cumulative debt, and IPEDS awards in the two pooled debt-cohort years. Missing values and award-year dates remain unknown.
 
 ## Features
 
@@ -161,12 +162,12 @@ 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 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 (202 codes) and field catalog (80 fields) served as static data — zero API calls, zero rate-limit impact
+- Embedded CIP taxonomy (186 groups) and field catalog (78 fields) served offline
 - Geographic filtering via U.S. zip code + distance radius
 
 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
+- Availability distinguishes numbers (including zero), unknown-cause missing values, and explicit `PS` / `PrivacySuppressed` provider markers. Confirmed privacy suppression does not identify its particular cause.
 - Derived metrics alongside source figures in `scorecard_value_analysis` — agents can verify arithmetic and branch on computed values, not raw numbers
 - Ordinal ranks in `scorecard_compare_schools` place each school's metric values within the comparison set
 - 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.

package/changelog/0.4.x/0.4.0.md

@@ -0,0 +1,31 @@
+---
+summary: "Correct Scorecard earnings, availability, and program comparisons."
+breaking: true
+security: false
+---
+
+# 0.4.0 — 2026-10-14
+
+## Added
+
+- **`scorecard_search_programs`** accepts integer `credential_level` selectors before school pagination and retains provider credential levels/titles, including future numeric levels; missing identity remains absent. ([#26](https://github.com/cyanheads/college-scorecard-mcp-server/issues/26))
+- **`scorecard_value_analysis`** discloses `effective_net_price`, `net_price_basis`, requested income/bracket, and the overall-price fallback when a bracket estimate is unavailable. ([#35](https://github.com/cyanheads/college-scorecard-mcp-server/issues/35))
+
+## Changed
+
+- **`scorecard_get_earnings.years`** selects API data-file start years, validated to 1996–2025; valid files without observations succeed. Per-metric context supplies verified entry cohorts, measurement years, and dollar basis without re-inflation. ([#25](https://github.com/cyanheads/college-scorecard-mcp-server/issues/25))
+- **Availability** distinguishes available numbers, unknown-cause missing data, and explicit privacy markers. Consumers must use availability fields for missing data; `suppressed` flags/counts now require confirmed privacy suppression, and aggregate earnings suppression requires every current metric explicitly marked. ([#38](https://github.com/cyanheads/college-scorecard-mcp-server/issues/38))
+- **Provider metrics** accept explicit privacy sentinels and reject unexpected values with `ServiceUnavailable` / `api_error` plus recovery guidance.
+
+## Removed
+
+- **`current.earnings_6yr_female_median`** is replaced by `earnings_6yr_non_male_median`; migrate consumers to the provider's non-male population. Unsupported `percent_greater_than_100000` and `mean_annual_increment` catalog entries are removed. ([#24](https://github.com/cyanheads/college-scorecard-mcp-server/issues/24))
+
+## Fixed
+
+- **Earnings projections** use real percentile and non-male/male paths; profiles render available P75 values even when P25 is absent.
+- **Earnings descriptions** identify federally aided undergraduate entrants working and not enrolled, regardless of completion.
+- **`scorecard_compare_prompt`** uses CIP lookup and per-school program retrieval for programs focus, comparing matching credentials with earnings, cumulative debt, and pooled-cohort IPEDS awards. ([#27](https://github.com/cyanheads/college-scorecard-mcp-server/issues/27))
+- **`scorecard_compare_schools`** uses competition ranks (1, 1, 3), leaves unavailable values unranked, and names tied leaders. ([#34](https://github.com/cyanheads/college-scorecard-mcp-server/issues/34))
+- **`scorecard_lookup_cip`** reconciles 186 curated four-digit groups to NCES CIP 2020, resolves verified descendant aliases, and accepts undotted codes. ([#30](https://github.com/cyanheads/college-scorecard-mcp-server/issues/30))
+- **Packaging** declares the required Scorecard API key for HTTP npm installs and excludes development tests/fixtures from desktop bundles.

package/dist/data/cip-codes.d.ts

@@ -13,11 +13,16 @@ export interface CipEntry {
     /** Standard title for the program (e.g. "Computer Science") */
     title: string;
 }
-/** 4-digit CIP code taxonomy — common programs for college/career exploration. */
+/** Curated current four-digit groups, with exact NCES CIP 2020 titles and family names. */
 export declare const CIP_CODES: CipEntry[];
 /**
  * Search CIP codes by keyword — matches against code, title, family title.
  * Returns up to `limit` results (default 20).
  */
 export declare function searchCipCodes(query: string, limit?: number): CipEntry[];
+/** Verified six-digit descendants used only as keyword aliases for their four-digit group. */
+export declare const CIP_ALIASES: Record<string, Array<{
+    code: string;
+    title: string;
+}>>;
 //# sourceMappingURL=cip-codes.d.ts.map

package/dist/data/cip-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cip-codes.d.ts","sourceRoot":"","sources":["../../src/data/cip-codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kFAAkF;AAClF,eAAO,MAAM,SAAS,EAAE,QAAQ,EA4iC/B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,QAAQ,EAAE,CAuBpE"}
+{"version":3,"file":"cip-codes.d.ts","sourceRoot":"","sources":["../../src/data/cip-codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,eAAO,MAAM,SAAS,EAAE,QAAQ,EAimC/B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,QAAQ,EAAE,CAqCpE;AAED,8FAA8F;AAC9F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B9E,CAAC"}