college-scorecard-mcp-server

---

概述

来自教育部 College Scorecard 的美国高校数据，涵盖约 6,500 所院校的费用、收入、专业和成果。搜索和比较院校，查询各专业领域的收入，并计算债务收入比等投资回报率指标。

工具

工具	描述
scorecard_search_schools	按名称、位置、类型、规模、录取率和单一性别标记搜索院校；按支持的 API 字段排序。返回核心身份信息和费用指标。
scorecard_get_school	院校完整档案——费用、招生、成果、助学金、人口统计信息、单一性别标记和完成率。
scorecard_compare_schools	按指定主题对 2–5 所学校进行标准化并列比较。返回指标值、顺序排名和比较摘要。
scorecard_get_programs	单所学校的专业项目：1 年收入中位数、累计 Stafford/Grad PLUS 债务，以及两个合并债务队列年份中的 IPEDS 授予学位数。
scorecard_search_programs	按 CIP 和学历资格或关键词查找项目，保留学位身份信息，并在每个已获取的学校页面内按收入排名。
scorecard_get_earnings	获得联邦助学金的本科入学者在工作且未注册就读时的收入，无论是否完成学业：6/8/10 年收入中位数、6/10 年 P25/P75，以及非男性/男性 6 年收入中位数。
scorecard_value_analysis	工作流工具：并行获取费用、债务、还款和收入数据，然后计算 ROI 指标——债务收入比和净价格收入比。
scorecard_lookup_cip	按代码、关键词或相关项目名称搜索 186 个经整理的 NCES CIP 2020 四位数类别。离线提供。
scorecard_list_fields	按关键词搜索 Scorecard 字段目录。返回匹配的字段路径、描述、数据类型和排序支持情况。传入自定义 fields 参数前请使用此工具。

资源

资源	描述
scorecard://school/{id}	按单位 ID 获取院校档案——可注入与特定学校相关对话的上下文
scorecard://programs/{id}	学校的项目级成果

所有资源数据也可通过工具获取。请先使用 scorecard_search_schools 或 scorecard_get_school 查找学校 ID，再构建资源 URI。

提示词

提示词	描述
scorecard_compare_prompt	使用 Scorecard 数据构建多校比较分析

功能参考

scorecard_search_schools _工具

• 按名称、州、所有权、学位级别、规模、录取率、CIP 代码，或 ZIP 和距离（英里或 km）搜索。per_page 上限为 100；page 从 0 开始索引。州列表接受 WA,CA 这种格式。
• 返回核心身份信息和费用指标，便于快速浏览。
• sort 接受 API 表达式，例如 latest.cost.avg_net_price.overall:asc（:desc 可反向排序）。men_only 和 women_only 接受 true 或 false。

---

scorecard_get_school _工具

• 接受一个学校 ID 或最多 1,000 个 ID 的数组。最多获取前 100 个不重复的 ID；missing_ids 列出已获取但没有记录的 ID，unprocessed_ids 列出超出的 ID。
• 默认档案涵盖费用、招生、成果、助学金、人口统计信息和完成率。自定义 fields 会返回包含所请求值的 selected_fields，而 absent_fields 会列出响应中缺失的所请求路径。
• HBCU 和单一性别标记在已知时为 true/false，缺失时则为 unknown。

---

scorecard_compare_schools _工具

• 接受 2–5 个学校单位 ID，以及一个主题：costs、admissions、outcomes 或 aid。
• 通过一次 API 调用返回指标值和排名：相同的值共享排名（1、1、3），不可用的值不参与排名。
• 每个单元格的 availability 用于区分可用、不可用和因隐私保护而被隐藏的值。

---

scorecard_get_programs _工具

• 接受一个学校 ID，可选的 CIP 代码（带点或不带点）、credential_level 和最低收入筛选条件。没有匹配项目的学校会返回空集合；不存在的学校会产生查询错误。
• 返回获得最高级别证书后 1 年的收入中位数和毕业生人数。earnings_availability 的值为 available、unavailable 或 privacy_suppressed，并包含 suppressed_count 和 unavailable_count。
• median_debt 是毕业生累计借贷的 Stafford/Grad PLUS 贷款金额。ipeds_awards_year1 和 ipeds_awards_year2 分别统计合并债务队列中每一年的授予数，而非学生人数。

---

scorecard_search_programs _工具

• 按 CIP 代码或项目名称搜索，可选整数 credential_level（1–8 和 99）、州、所有权、净价格、收入和债务筛选条件。零起始的 page 和 per_page（最高 100）用于分页学校，因此返回的项目行可能超过 per_page。
• 返回包含项目指标、credential_level 和 credential_title 的学校 ID 和名称。收入可用的结果会排在前面；可用性、债务和授予字段与 scorecard_get_programs 一致。
• min_earnings 在本地筛选，因此总数和分页依据的是筛选前上游学校数量。收入和债务阈值包含等于阈值的值，并排除未知值。

---

scorecard_get_earnings _工具

• 接受一个学校 ID，以及可选的数据文件起始 years，范围为 1996–2025（数据文件版本，而非入学年份）。省略 years 或传入 [] 时，仅返回快照。
• 涵盖获得联邦资助的本科入学者中正在工作且未在读的人员，无论其是否完成学业：入学后 6/8/10 年的中位数、6/10 年的 P25/P75，以及非男性/男性 6 年中位数。
• current_availability 和 trend[].availability 用于标明每项指标的分类。current_context 和 trend[].context 提供 data_file_year、entry_cohorts、measurement_years 和 dollar_year；数值沿用数据提供方的美元计值基准，因此跨版本比较前请先检查该基准。

---

scorecard_value_analysis _工具

• 接受一个学校 ID；可选的 family_income 用于选择适用的净价格区间（$0–30k、$30k–48k、$48k–75k、$75k–110k 或 $110k+）。
• 返回比率及其来源数据。effective_net_price 是所用价格，net_price_basis 的值为 income_bracket、overall 或 unavailable。
• 如果缺少相应区间的数据，则使用总体价格，并在 data_notes 中说明。计算比率要求年度收入为正数。

---

scorecard_lookup_cip _工具

• 按非空关键词或部分名称搜索（默认上限为 20，最高为 50）。带点的 11.07 和不带点的 1107 等效。
• 返回 186 个当前 NCES CIP 2020 四位数类别中的精确组名称和分类身份；这些类别是完整分类体系的子集。相关的六位数项目名称也可匹配，并返回其所属类别；没有匹配项时会返回包含使用指引的空集合。

---

scorecard_list_fields _工具

• 按非空查询搜索 78 个精选的离线字段条目（默认上限为 30，最高为 100）。向 scorecard_get_school 传递自定义 fields 前请先使用此工具。
• 返回字段路径、描述、数据类型、类别和 API 排序支持情况；包含不可排序字段的结果会由 tip 标记。

---

scorecard://school/{id} _资源

• 以 application/json 格式提供机构档案——身份信息、费用、招生、结果、资助和完成情况数据
• id 是来自 scorecard_search_schools 的学校单位 ID（以字符串表示的整数）
• list 会返回少量示例学校 URI；使用 scorecard_search_schools 查找其他学校

scorecard://programs/{id} _资源

• 以 application/json 格式提供项目层面的结果数据，包括 CIP 代码、标题、学历层级、1 年收入、累计 Stafford/Grad PLUS 债务，以及含义与项目工具相同的 ipeds_awards_year1 / ipeds_awards_year2；缺失的指标为 null
• id 是来自 scorecard_search_schools 的学校单元 ID
• list 会返回少量示例学校 URI；使用 scorecard_search_schools 发现其他学校

---

scorecard_compare_prompt _提示词

• 参数：school_names（以逗号分隔的名称列表）和 focus（costs | outcomes | programs），均为必填
• costs 和 outcomes 会执行学校发现、scorecard_compare_schools、概况和价值分析。programs 会执行学校发现、CIP 查询，并针对每所学校运行 scorecard_get_programs，然后比较学历相同项目的收入、债务和 IPEDS 获奖人数。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

College Scorecard 专属功能：

• 完整覆盖 College Scorecard API：约 6,500 所 Title IV 院校、约 2,800 个数据字段，涵盖费用、结果、人口统计、经济援助和专业领域收入
• 项目层面收入：按学校 × CIP 代码 × 学历层级，统计获得最高学历后 1 年仍在工作的毕业生收入中位数
• 每个工具均预先选择字段——根据工具用途整理适当的字段集；支持通过可选的 fields 覆盖设置自定义查询
• 内置 CIP 分类体系（186 个类别）和字段目录（78 个字段），可离线使用
• 通过美国邮政编码和距离半径进行地理筛选

便于 Agent 使用的输出：

• 可用性区分数值（包括零）、缺失值以及明确的提供方标记 PS / PrivacySuppressed
• scorecard_value_analysis 中的派生指标与源数据并列显示，scorecard_compare_schools 还会添加顺序排名
• 学校排序使用已编入索引的 API 字段；选择排序表达式前，请查看 scorecard_list_fields。API 不支持按六年收入排序。
• 提供方故障会分别报告验证、身份验证、请求限流、超时和可用性原因；可用性故障使用 api_error，取消操作仍使用 RequestCancelled

开始使用

公共托管实例

公共实例可通过 https://college-scorecard.caseyjhand.com/mcp 使用——无需安装。无需 API 密钥；实例会提供自己的密钥。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "streamable-http",
      "url": "https://college-scorecard.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。免费 API 密钥请访问 api.data.gov/signup。

{
  "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"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

也可以使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• College Scorecard API 密钥——可在 api.data.gov/signup 免费注册。速率限制：每个密钥每小时 1,000 次请求。

安装

1. 克隆仓库：

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

2. 进入目录：

cd college-scorecard-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

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

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 架构进行验证。主要环境变量：

变量	说明	默认值
SCORECARD_API_KEY	必填。 来自 api.data.gov 的 API 密钥（每小时 1,000 次请求）。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于终止 TLS 的反向代理部署的公共源地址覆盖项	无
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的强制 GC 循环间隔，单位为毫秒（仅限 Bun）；如果 HTTP 负载下堆内存持续增长，可尝试设置为 60000	0（已禁用）
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry 检测	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/college-scorecard-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 如需省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 进行构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具、资源和提示词，并初始化服务。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖搜索、院校档案、专业、收入和分析的九个工具。
src/mcp-server/resources	资源定义。院校档案和专业结果资源。
src/mcp-server/prompts	提示词定义。多院校对比提示词。
src/services	ScorecardService — 针对 College Scorecard API 的 fetch 封装，支持重试、字段选择和分页。
tests/	与 src/ 结构相对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概述如下：

• 处理程序抛出异常，框架捕获异常 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围的日志记录，使用 ctx.state 进行租户范围的存储
• 在 src/index.ts 的 createApp() 数组中注册新工具、资源和提示词
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。