Student Loan IDR MCP

소득이 불규칙하거나, 계절적이거나, 시간제, 프리랜서, 계약직, 또는 단일 연간 금액으로 표현하기 어려운 사람들을 위해 MCP 인터페이스와 차주용 계산기를 함께 제공하는 소규모 Cloudflare Workers 서비스입니다.

이 서비스는 세 가지 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로 버전이 고정됩니다.

• 미국 본토/워싱턴 D.C., 알래스카, 하와이에 대한 2026 HHS 빈곤 가이드라인이 포함되어 있습니다.

• RAP는 2026년 7월 1일부터 이용 가능해졌으므로 포함됩니다.

• loan.eligibilityLoans가 제공되면 IBR, PAYE, ICR은 명시적 대출 유형/지급 자격 객체와 함께 적용 가능한 기존 대출에 대해 모델링됩니다.

• 공식 2026 ICR 소득 백분율 팩터 테이블이 2026년 7월 1일부터 2027년 6월 30일까지 포함되며, 게시된 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)

• 월 2회 (amount × 24)

• 월급 (amount × 12)

• 연간

• 계절성 일시금 (제공된 지급액의 합계)

이 서비스는 총소득에 가짜 “표준 공제”를 적용하지 않습니다. IDR 계산은 AGI 또는 현재 소득 증빙을 기반으로 합니다. 호출자는 adjustedGrossIncomeOverride를 제공하거나 추정된 AGI 산출 전 조정액을 제공할 수 있습니다. 그렇지 않으면 연환산 과세 총소득이 보수적인 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는 명시적 재정의(override)로만 계속 사용할 수 있습니다.

V0.3 문서 워크플로

get_repayment_documentation_template는 선택적 incomeSources 배열을 받습니다. 각 소득원은 소득 유형, 지급자/이름, 주소, 총액, 지급 빈도, 메모를 담을 수 있습니다. 필수 설명 사실이 제공되지 않으면 생성된 문서는 값을 임의로 만들지 않고 보이는 자리 표시자를 유지합니다.

outputFormat을 markdown(기본값), text 또는 html로 설정합니다. HTML 렌더러는 호출자가 제공한 콘텐츠를 이스케이프하고, 스크립트나 외부 리소스를 포함하지 않으며, 프라이버시 안전 인쇄용 문서에 적합한 제한적인 Content Security Policy를 제공합니다.

생성되는 모든 진술서에는 일반적인 증빙 자료 범주 체크리스트가 포함됩니다. 체크리스트는 참고용일 뿐이며, 서비스 제공자(servicer)가 다른 또는 추가 증빙을 요청할 수 있고 어떤 항목도 승인을 보장하지 않는다고 명시합니다.

이전 버전과의 호환성을 위해 레거시 단일 소스 필드(incomeSourceName, incomeSourceAddress, paymentFrequency, grossAmount)가 계속 지원됩니다. no_current_taxable_income_statement는 모순된 현재 소득원 데이터를 조용히 일관성 없는 진술서로 생성하는 대신 거부합니다.

V0.4 프로덕션 MCP 강화

HTTP 전송은 이제 64 KiB 요청 본문 상한, application/json 콘텐츠 유형, Streamable HTTP Accept 미디어 유형, JSON-RPC 요청/알림 ID 규칙, 배치 수신, 초기화 버전 협상, 그리고 각 도구의 선언된 입력 스키마에 대한 런타임 검증을 적용합니다. 알 수 없는 도구 인자 필드는 조용히 무시되지 않고 거부됩니다.

/mcp에 대한 브라우저 출처 요청은 해당 정확한 출처가 쉼표로 구분된 MCP_ALLOWED_ORIGINS 환경 변수에 있는 경우에만 허용됩니다. Origin 헤더가 없는 서버 간 요청은 정상적으로 계속 작동합니다.

실제 차주 데이터와 함께 서비스를 사용하기 전까지 인증은 선택 사항입니다. Bearer 인증을 활성화하려면 토큰을 일반 텍스트 Wrangler 변수가 아닌 Cloudflare 비밀로 저장하세요:

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에서 사용하는 것과 동일한 런타임 입력 스키마 검증을 사용합니다. 결과는 추정치로 남으며, 서비스 제공자의 결정을 제시하는 대신 자격을 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는 이 무상태(stateless) 서버가 SSE 수신 스트림을 제공하지 않으므로 의도적으로 405를 반환합니다.

예제 도구 호출

{
  "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 작업도 지원합니다. 현재 공식 정책 소스의 지문(fingerprint)을 생성하고 변경된 소스 스냅샷에 대해 pull request를 사용합니다. 상환 상수나 자격 규칙을 자동으로 다시 작성하지 않으며, 정책 변경 사항이 병합되기 전에 사람의 검토가 필요합니다.

개발

npm install
npm run typecheck
npm test
npm run dev

Wrangler로 배포:

npm run deploy

안전 / 범위

이것은 추정기이자 문서 템플릿 생성기이며, 법률, 세무, 재무 또는 신고 조언이 아닙니다. IDR 신청을 제출하지 않으며 공식 자격을 결정하지 않습니다. 차주는 StudentAid.gov와 자신의 대출 서비스 제공자(servicer)를 통해 결과를 확인해야 합니다.