Student Loan IDR MCP

一个基于 Cloudflare Workers 的小型服务，同时提供 MCP 接口和面向借款人的计算器，适用于收入不稳定、季节性、按小时计酬、自由职业、合同制，或以其他方式难以用单一年度数字表达的人群。

该服务提供三个 MCP 工具：

1. calculate_alt_income_student_loan — 将可变的应税收入归一化为年度估算值，并为 RAP、IBR、PAYE 和 ICR 计算还款计划估算值。

2. get_repayment_documentation_template — 根据结构化的收入来源数组生成真实的辅助陈述文档，支持 Markdown、纯文本或隐私安全的可打印 HTML。

3. policy_status — 报告不可变的政策快照、受支持的还款计划、已知的终止日期、内置 ICR 系数表的有效期限以及官方来源链接。

为什么会有这个项目

Federal Student Aid 允许在纳税申报信息无法反映借款人当前收入的情况下，使用当前收入证明文件。当前的 IDR 申请表格说明，证明文件通常包括工资单或雇主信函；当无法提供证明文件，或借款人希望解释收入情况时，可以附上一份签署的陈述，其中标明每个收入来源及其地址。

本项目不会伪造税务文件、扣除项或资格。它生成估算值、确定性的资格筛选对象，以及用户可编辑的辅助文档，并为调用方未提供的事实保留明确的占位符。

Related MCP server: lenderwiki

政策快照

确定性常量被明确版本化为 2026-08-27。

• 内置了适用于美国本土/哥伦比亚特区、阿拉斯加和夏威夷的 2026 HHS 贫困指南。

• 包含 RAP，因为它于 2026 年 7 月 1 日起可用。

• 当提供 loan.eligibilityLoans 时，会为适用的遗留贷款建模 IBR、PAYE 和 ICR，并带有明确的贷款类型/发放资格对象。

• 内置了 2026 年 7 月 1 日至 2027 年 6 月 30 日期间的官方 2026 ICR 收入百分比系数表，包括已发布 AGI 行之间的线性插值。

• PAYE 和 ICR 目前计划最迟于 2028 年 7 月 1 日终止。

• 本快照有意不对 SAVE 建模。

官方参考：

• https://studentaid.gov/articles/faqs-idr-plan/

• https://studentaid.gov/sites/default/files/IncomeDrivenRepayment-en-us.pdf

• https://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines

• https://www.govinfo.gov/content/pkg/FR-2026-06-09/pdf/2026-11540.pdf

收入归一化

支持的计薪周期：

• 按小时（hourlyRate × hoursPerWeek × weeksPerYear）

• 按周（amount × 52）

• 每两周（amount × 26）

• 每月两次（amount × 24）

• 按月（amount × 12）

• 按年

• 季节性一次性款项（所提供付款的总和）

该服务不会对总收入应用虚假的“标准扣除”。IDR 计算基于 AGI 或当前收入证明文件。调用方可以提供 adjustedGrossIncomeOverride，也可以提供估算的线上调整项（above-the-line adjustments）。否则，将使用年化应税总收入作为保守的 AGI 估算值。

V0.2 资格输入

loan.eligibilityLoans 接受带有 loanType 和粗略发放期间（before_2026_07_01 或 on_or_after_2026_07_01）的明确贷款记录。计算器返回一个计划级别的 eligibility 对象，其中包含逐笔贷款评估，以及 eligible、ineligible、conditional、mixed 或 unknown 之一。

该资格对象是确定性的筛选辅助工具，而非官方裁定。未提供的借款人特定事实将保持为 conditional 或 unknown，而不会被凭空捏造。

对于 PAYE，可选的借款人/日期标志用于模拟已发布的 2007 年 10 月 1 日和 2011 年 10 月 1 日条件。对于 ICR，调用方可以提供 taxFilingStatus 或 loan.icrIncomeFactorCategory；计算器随后会自动选择并插值官方 2026 系数。loan.icrIncomePercentageFactor 仍然仅作为显式覆盖值可用。

V0.3 文档工作流

get_repayment_documentation_template 接受一个可选的 incomeSources 数组。每个来源可以包含来源类型、付款方/名称、地址、总金额、付款频率和备注。如果未提供必需的描述性事实，生成的文档会保留一个可见的占位符，而不是凭空编造一个值。

将 outputFormat 设置为 markdown（默认）、text 或 html。HTML 渲染器会转义调用方提供的内容，不包含脚本或外部资源，并附带严格的 Content Security Policy，适合隐私安全的可打印文档。

每份生成的陈述都包含一份常见辅助证据类别的清单。该清单仅供参考：它明确说明贷款服务机构可能会要求不同或额外的证据，并且没有任何单项能保证被接受。

为保持兼容性，旧的单来源字段（incomeSourceName、incomeSourceAddress、paymentFrequency 和 grossAmount）仍然受支持。no_current_taxable_income_statement 会拒绝相互矛盾的当前收入来源数据，而不是静默生成不一致的陈述。

V0.4 生产环境 MCP 加固

HTTP 传输现在强制执行 64 KiB 请求体上限、application/json 内容类型、Streamable HTTP 的 Accept 媒体类型、JSON-RPC 请求/通知 ID 规则、批量接收、初始化版本协商，以及针对每个工具声明的输入 schema 的运行时验证。未知的工具参数字段会被拒绝，而不是被静默忽略。

除非请求的确切来源出现在逗号分隔的 MCP_ALLOWED_ORIGINS 环境变量中，否则对 /mcp 的浏览器来源请求将被拒绝。没有 Origin 头的服务器到服务器请求继续正常工作。

在服务用于真实借款人数据之前，身份验证是可选的。要启用 Bearer 身份验证，请将令牌存储为 Cloudflare 机密（secret），而不是明文 Wrangler 变量：

npx wrangler secret put MCP_BEARER_TOKEN

Worker 还支持可选的绑定名称 MCP_RATE_LIMITER 下的原生 Cloudflare Rate Limiting 绑定。当公开暴露有必要进行限流时，在 wrangler.jsonc 中添加一个 ratelimits 条目，其中包含对 Cloudflare 账户唯一的正整数命名空间 ID，以及所需的 10 秒或 60 秒限制窗口。如果配置的绑定出错，运行时将以 HTTP 503 失败关闭（fail closed）；当绑定拒绝请求时，返回 HTTP 429。Cloudflare 文档说明该绑定自 Wrangler 4.36.0 起可用。

结构化请求日志仅包含服务/版本、JSON-RPC 方法、工具名称、HTTP 状态、请求字节数和持续时间。借款人姓名、文档字段、工具参数、授权头/令牌、来源和 IP 地址不会被应用程序代码记录。

V0.5 面向借款人的计算器

线上 Worker 现在在 GET / 提供一个面向借款人的小型计算器。它通过一个轻量的同源 POST /api/calculate 路由，使用与 MCP 工具相同的确定性 calculateRepayment() 引擎；加固后的 /mcp 契约和三个工具清单保持不变。

浏览器界面没有分析功能、外部资源或浏览器存储。响应使用 Cache-Control: no-store、严格的 Content Security Policy、同源 API 强制、现有的 64 KiB 请求上限，以及 MCP 使用的相同运行时输入 schema 验证。结果仍然是估算值，并将资格显示为 eligible、ineligible、conditional、mixed 或 unknown，而不是呈现贷款服务机构裁定。

在线借款人计算器：https://student-loan-idr-mcp.jaredtechfit.workers.dev/

MCP

端点：POST /mcp

支持的 JSON-RPC 方法：

• initialize

• notifications/initialized

• ping

• tools/list

• tools/call

对于声明的 2025-03-26 Streamable HTTP 修订版，POST 请求应同时发送 Content-Type: application/json 和 Accept: application/json, text/event-stream。GET /mcp 有意返回 405，因为这个无状态服务器不提供 SSE 监听流。

示例工具调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculate_alt_income_student_loan",
    "arguments": {
      "income": [
        { "cadence": "hourly", "hourlyRate": 28, "hoursPerWeek": 25, "weeksPerYear": 48 },
        { "cadence": "seasonal_lump_sum", "seasonalPayments": [3500, 4200] }
      ],
      "region": "contiguous_us",
      "familySize": 2,
      "taxFilingStatus": "single",
      "dependentsClaimedOnFederalTaxReturn": 1,
      "loan": {
        "principal": 42000,
        "annualInterestRatePercent": 5.5,
        "newBorrowerOnOrAfterJuly1_2014": true,
        "eligibilityLoans": [
          { "loanType": "direct_unsubsidized", "disbursementPeriod": "before_2026_07_01" }
        ]
      }
    }
  }
}

政策刷新工作流

仓库的 CI 工作流还支持一个定时/手动的 policy-refresh 任务。它会对当前官方政策来源计算指纹，并为任何发生更改的源快照使用拉取请求（pull request）。它不会自动重写还款常量或资格规则；政策变更合并前需要人工审查。

开发

npm install
npm run typecheck
npm test
npm run dev

使用 Wrangler 部署：

npm run deploy

安全 / 范围

这是一个估算器和文档模板生成器，不是法律、税务、财务或申报建议。它不会提交 IDR 申请，也不会确定官方资格。借款人应通过 StudentAid.gov 及其贷款服务机构核实结果。