.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/college-scorecard-mcp-server</h1> <p><b>Search, compare, and analyze U.S. college data — costs, earnings, programs, and outcomes — via MCP. STDIO or Streamable HTTP.</b> <div>9 Tools • 2 Resources • 1 Prompt</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

Tools

9 tools for working with U.S. Department of Education College Scorecard data — institution search, program-level earnings, cost and outcomes analysis, and structured comparison:

scorecard_search_schools

Search for institutions using name, location, and institutional filters.

• 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

scorecard_get_school

Fetch a full institutional profile by school ID.

• Accepts a single ID or an array of IDs (batch fetch up to 100 per page)
• 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

scorecard_compare_schools

Normalized comparison across 2–5 institutions on a named topic.

• 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 multi-ID: output shape is rows, not profiles

scorecard_get_programs

List all field-of-study programs at one school with earnings and debt data.

• Returns P25/median/P75 earnings 1 year after graduation, median debt at graduation, and enrollment figures per program
• Filter by CIP code to return only matching programs
• Filter by credential_level (certificate, associate's, bachelor's) 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 structured suppressed: true flag with suppression_note, not bare null

scorecard_search_programs

Find programs by CIP code or name across all institutions, ranked by median earnings.

• Program-centric: "which schools in Washington have CS programs with median earnings over $80k?"
• Accepts school-side filters: state, ownership, max net price
• Earnings and debt thresholds for filtering results
• Returns school name, school ID, and unit ID alongside program metrics for follow-up chaining
• Sorting applied post-fetch where earnings fields are not API-indexed

scorecard_get_earnings

Institution-level post-graduation earnings for one school.

• Median and P25/P75 earnings at 6, 8, and 10 years after entry
• Optional gender breakdown when available
• years parameter for time-series analysis; defaults to latest.* for current-state queries
• Reflects outcomes across all graduates, not broken down by program

scorecard_value_analysis

Workflow tool: "Is this school worth it?"

• Parallel-fetches cost/debt/repayment and earnings data in two concurrent requests
• Computes ROI metrics the API does not pre-calculate: debt-to-earnings ratio (median debt / 6-year earnings), net price to first-year earnings ratio, and 3-year loan repayment rate
• family_income parameter selects the applicable net price bracket
• Fetches peer school identifiers (same Carnegie category and ownership) for comparative median values
• Returns all source figures alongside derived metrics — callers can audit the arithmetic
• data_notes flags any suppressed or null fields with structured explanations

scorecard_lookup_cip

Search CIP codes by keyword or partial name.

• Covers the full ~2,400-code CIP taxonomy embedded as static data
• 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
• Returns matching codes with standard titles

scorecard_list_fields

Search the Scorecard field catalog by keyword.

• ~2,800 field entries from the data dictionary, embedded as static data
• Returns field paths, descriptions, data types, and whether the field supports API-side sorting
• No API call required — zero rate-limit impact
• Use before passing custom fields parameters to search/get tools

Resources and prompts

All resource data is also reachable via tools. Use scorecard_search_schools or scorecard_get_school to discover school IDs before constructing resource URIs.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

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: actual median earnings 1 year after graduation for ~6,500 school × CIP code combinations
• Field pre-selection per tool — curated ~10–20 field sets appropriate to each tool's purpose; optional fields override for custom queries
• Embedded CIP code taxonomy and field catalog: both served as static data with zero API calls and zero rate-limit impact
• Geographic filtering via U.S. zip code + distance radius
• scorecard_value_analysis workflow tool computes ROI metrics (debt-to-earnings ratio, net price to first-year earnings) that require multiple API round-trips and post-processing arithmetic

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

Getting started

Add the following to your MCP client configuration file. See api.data.gov/signup for a free API key.

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SCORECARD_API_KEY=your-api-key",
        "ghcr.io/cyanheads/college-scorecard-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SCORECARD_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• A College Scorecard API key — free registration at api.data.gov/signup. Rate limit: 1,000 requests/hour per key.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/college-scorecard-mcp-server.git

1. Navigate into the directory:

cd college-scorecard-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set SCORECARD_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t college-scorecard-mcp-server .
docker run --rm -e SCORECARD_API_KEY=your-key -p 3010:3010 college-scorecard-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/college-scorecard-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.