degreeroi

degreeroi

在整个职业生涯中，一个学位的实际价值是多少美元？degreeroi 不讲宣传册上的套话，而是用数据给出答案：大学专业的终身投资回报率，以及美国院校 30 年净现值超过正值门槛时的相关数据。它是 LE TEEN College ROI API 的轻量级只读客户端——提供静态 JSON，无需密钥，无需注册——通过同一个 bin 同时以小型 CLI 和 stdio MCP 服务的形式提供。

专业数据涵盖 19 个类别和 115 个 CIP 子领域：终身投资回报率的中位数和均值、从未达到盈亏平衡点的毕业生占比、达到盈亏平衡点的年龄，以及 AI 暴露程度区间；详情视图还提供完整分布。院校数据涵盖通过正 NPV 范围的 500 所四年制院校（美国约有 1,656 所四年制院校）：对本州和外州学生而言，学位 30 年的价值、就读成本、毕业生收入，以及学位何时回本。所有美元金额均为终身 / 30 年总额，单位为 USD。

有一点值得明确说明：不在这 500 所院校之列的学校，不会出现在数据中。查询此类院校会返回未找到，因为缺失本身就是一种信号——对于数据集未收录的学校，degreeroi 绝不会编造记录。

配置

• COLLEGE_ROI_API_URL（可选）— API 基础 URL。 默认值为 https://le-teen.com/api。

仅此而已。无需 API 密钥：上游 API 免费且无需密钥。响应会在进程内缓存 24 小时，与 API 自身的 CDN 缓存时长一致；并且绝不会写回任何内容。

工具

• list_majors — 返回专业类别和子领域的精简投资回报率数据行。可选筛选条件： kind（category 或 subfield）、parent（子领域所属的 类别）、sort （median_roi、mean_roi、break_even_age 或 name）和 limit。只会发送你设置的筛选条件。
• get_major — 某个专业的完整记录： 投资回报率分布（p25、中位数、均值、p75）、 按完成学业情况调整后的投资回报率和辍学者投资回报率、毕业生和 项目数量，以及 AI 暴露程度详情。
• search_colleges — 按 name、state 或 control 搜索 范围内的 500 所院校，并可设置 limit。数据行包含本州和外州 学生的 30 年 NPV、就读成本、收入中位数和达到盈亏平衡点的年龄。
• get_college — 某所院校的完整记录，包括其 IPEDS unitid 和 FREOPP 覆盖情况。范围之外的院校会返回 college not found: <college>。
• best_value_colleges — 按本州学费筛选的最佳性价比四年制院校：指定 state 时，返回每个州排名前 15 的院校（可通过 limit 缩减结果）；未指定时， 则返回全国范围内的精选摘要。
• out_of_state_penalty — 按外州学生相较于本州学生损失的 30 年 NPV 对公立四年制院校排名；可选按 state 和 limit 缩小范围。
• get_api_info — 底层 API 的元数据： 端点、许可、数据集 DOI 和署名信息。 数据直接取自固定的元数据，不会调用上游 API。

值得了解的行为：

• 列表工具会原样传递 API 的精简投影结果；详情工具会原样传递完整的上游记录。
• 上游返回非 2xx 响应时会报错 degreeroi error: HTTP <status>（详情工具的 404 除外，其会返回上述如实的未找到结果）；如果 API 无法访问，则会返回 degreeroi unreachable。

端点来源

原项目的 README 指定了七个工具、 它们的语义、API 基础地址 （https://le-teen.com/api，静态 JSON）、list_majors 上的筛选概念（kind/parent、sort、limit） 以及 search_colleges 上的筛选概念（name/state/control）， 还有数据集信息（19 个类别、115 个子领域、500 所封套大学、DOI 10.5281/zenodo.21351602、 CC BY 4.0、LE TEEN，位于 le-teen.com）。它没有 列出端点路径或参数表，因此在本次重建中将它们 标注为还原内容——每个联网工具在 API 基础地址下 对应一个 GET 请求：

• GET <base>/majors，仅将设定的筛选条件作为 查询参数（供 list_majors 使用）。
• GET <base>/majors/{major}（供 get_major 使用）。
• GET <base>/colleges，仅将设定的筛选条件作为 查询参数（供 search_colleges 使用）。
• GET <base>/colleges/{college}（供 get_college 使用）。
• GET <base>/best-value-colleges，在设定时附带 state / limit（供 best_value_colleges 使用）。
• GET <base>/out-of-state-penalty，在设定时附带 state / limit（供 out_of_state_penalty 使用）。
• get_api_info 使用固定的元数据提供服务， 其中端点与上述实现一致。

major 和 college 路径段会进行 URL 编码。

API 背后的数据来源：FREOPP 专业层级 估算数据、IPEDS 机构数据和 BEA 价格平减指数。数据许可为 CC BY 4.0——请注明 LE TEEN、 le-teen.com。

CLI

每个工具都是一个子命令，接收一个 JSON 参数 字符串：

npx @reneturcios/degreeroi list_majors '{"kind":"subfield","sort":"median_roi","limit":10}'
npx @reneturcios/degreeroi get_major '{"major":"computer-science"}'
npx @reneturcios/degreeroi search_colleges '{"state":"CA","control":"public"}'
npx @reneturcios/degreeroi get_college '{"college":"example-state-university"}'
npx @reneturcios/degreeroi best_value_colleges '{"state":"CA"}'
npx @reneturcios/degreeroi out_of_state_penalty '{"limit":20}'
npx @reneturcios/degreeroi get_api_info '{}'
npx @reneturcios/degreeroi --version

输出为工具的结果文本（成功时为上游响应正文）。退出代码：成功时为 0，运行时错误时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/degreeroi mcp

MCP 客户端配置：

{
  "mcpServers": {
    "degreeroi": {
      "command": "npx",
      "args": ["-y", "@reneturcios/degreeroi", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/degreeroi
docker run --rm ghcr.io/cloudcorprecords/degreeroi get_api_info '{}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios

上游 API 提供的数据采用 CC BY 4.0 许可 （LE TEEN，le-teen.com；数据集 DOI 10.5281/zenodo.21351602）。