Student Loan IDR MCP

Ein kleiner Cloudflare-Workers-Dienst mit sowohl einer MCP-Schnittstelle als auch einem Rechner für Kreditnehmer, deren Einkommen unregelmäßig, saisonal, stundenbasiert, freiberuflich, auftragsbasiert oder anderweitig schwer als eine einzige jährliche Zahl auszudrücken ist.

Der Dienst stellt drei MCP-Tools bereit:

1. calculate_alt_income_student_loan — normalisiert variables steuerpflichtiges Einkommen in eine Jahresschätzung und berechnet Rückzahlungsplan-Schätzungen für RAP, IBR, PAYE und ICR.

2. get_repayment_documentation_template — erzeugt wahrheitsgemäße unterstützende Erklärungsdokumente aus strukturierten Einkommensquellen-Arrays in Markdown, Klartext oder datenschutzsicherem druckbarem HTML.

3. policy_status — meldet den unveränderlichen Policy-Snapshot, unterstützte Pläne, bekannte Auslaufdaten, den Gültigkeitszeitraum der integrierten ICR-Faktorentabelle und offizielle Quellenlinks.

Warum es das gibt

Federal Student Aid erlaubt eine Dokumentation des aktuellen Einkommens in Situationen, in denen die Steuererklärungsdaten nicht das aktuelle Einkommen eines Kreditnehmers widerspiegeln. Das aktuelle IDR-Antragsformular besagt, dass die Dokumentation in der Regel eine Lohnabrechnung oder ein Arbeitgeberschreiben umfasst, und wenn keine Dokumentation verfügbar ist oder der Kreditnehmer sein Einkommen erläutern möchte, kann eine unterschriebene Erklärung beigefügt werden, die jede Einkommensquelle und deren Adresse angibt.

Dieses Projekt erfindet keine Steuerdokumente, Abzüge oder Berechtigungen. Es erzeugt Schätzungen, deterministische Berechtigungsprüfungsobjekte und vom Benutzer bearbeitbare unterstützende Dokumente, die explizite Platzhalter für Fakten enthalten, die der Aufrufer nicht angegeben hat.

Related MCP server: lenderwiki

Policy-Snapshot

Die deterministischen Konstanten sind explizit auf 2026-08-27 versioniert.

• Die HHS-Armutsrichtlinien von 2026 sind für die zusammenhängenden USA/D.C., Alaska und Hawaii eingebettet.

• RAP ist enthalten, weil es am 1. Juli 2026 verfügbar wurde.

• IBR, PAYE und ICR werden für anwendbare Altkredite mit expliziten Darlehensart-/Auszahlungs-Berechtigungsobjekten modelliert, wenn loan.eligibilityLoans angegeben wird.

• Die offizielle ICR-Einkommensprozentsatz-Faktorentabelle von 2026 ist für den Zeitraum vom 1. Juli 2026 bis zum 30. Juni 2027 eingebettet, einschließlich linearer Interpolation zwischen den veröffentlichten AGI-Zeilen.

• PAYE und ICR laufen derzeit planmäßig spätestens am 1. Juli 2028 aus.

• SAVE ist in diesem Snapshot bewusst nicht modelliert.

Offizielle Referenzen:

• 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

Einkommensnormalisierung

Unterstützte Rhythmen:

• stündlich (hourlyRate × hoursPerWeek × weeksPerYear)

• wöchentlich (amount × 52)

• zweiwöchentlich (amount × 26)

• halbmonatlich (amount × 24)

• monatlich (amount × 12)

• jährlich

• saisonale Einmalbeträge (Summe der angegebenen Zahlungen)

Der Dienst wendet keinen künstlichen „Standardabzug“ auf das Bruttoeinkommen an. IDR-Berechnungen basieren auf dem AGI oder auf einer Dokumentation des aktuellen Einkommens. Der Aufrufer kann entweder einen adjustedGrossIncomeOverride angeben oder geschätzte Above-the-Line-Anpassungen liefern. Andernfalls wird das annualisierte steuerpflichtige Bruttoeinkommen als konservative AGI-Schätzung verwendet.

V0.2-Berechtigungseingaben

loan.eligibilityLoans akzeptiert explizite Darlehensdatensätze mit einem loanType und einem groben Auszahlungszeitraum (before_2026_07_01 oder on_or_after_2026_07_01). Der Rechner gibt ein eligibility-Objekt auf Planebene mit Bewertungen pro Darlehen und einem der Werte eligible, ineligible, conditional, mixed oder unknown zurück.

Das Berechtigungsobjekt ist eine deterministische Prüfhilfe, keine offizielle Feststellung. Kreditnehmerspezifische Fakten, die nicht angegeben werden, bleiben konditional oder unbekannt, statt erfunden zu werden.

Für PAYE modellieren optionale Kreditnehmer-/Datumsflags die veröffentlichten Bedingungen vom 1. Okt. 2007 und 1. Okt. 2011. Für ICR können Aufrufer taxFilingStatus oder loan.icrIncomeFactorCategory angeben; der Rechner wählt und interpoliert dann automatisch den offiziellen Faktor von 2026. loan.icrIncomePercentageFactor bleibt nur als expliziter Override verfügbar.

V0.3-Dokumentenworkflow

get_repayment_documentation_template akzeptiert ein optionales incomeSources-Array. Jede Quelle kann einen Quellentyp, Zahler/Name, Adresse, Bruttobetrag, Zahlungshäufigkeit und Notizen enthalten. Wenn eine erforderliche beschreibende Tatsache nicht angegeben wird, behält das erzeugte Dokument einen sichtbaren Platzhalter bei, statt einen Wert zu erfinden.

Setzen Sie outputFormat auf markdown (Standard), text oder html. Der HTML-Renderer escaped vom Aufrufer gelieferte Inhalte, enthält keine Skripte oder externen Ressourcen und wird mit einer restriktiven Content Security Policy ausgeliefert, die für ein datenschutzsicheres druckbares Dokument geeignet ist.

Jede erzeugte Erklärung enthält eine Checkliste gängiger Belegkategorien. Die Checkliste dient nur als Orientierung: Sie besagt ausdrücklich, dass ein Servicer andere oder zusätzliche Nachweise anfordern kann und dass kein einzelner Punkt die Annahme garantiert.

Die bisherigen Einzelquellen-Felder (incomeSourceName, incomeSourceAddress, paymentFrequency und grossAmount) bleiben aus Kompatibilitätsgründen unterstützt. Eine no_current_taxable_income_statement lehnt widersprüchliche Daten zu aktuellen Einkommensquellen ab, statt stillschweigend eine inkonsistente Erklärung zu erzeugen.

V0.4-Produktionshärtung für MCP

Der HTTP-Transport erzwingt nun eine Obergrenze von 64 KiB für den Request-Body, den Inhaltstyp application/json, die Streamable-HTTP-Accept-Medientypen, die JSON-RPC-Regeln für Anforderungs-/Benachrichtigungs-IDs, den Empfang von Batches, die Aushandlung der Initialisierungsversion und eine Laufzeitvalidierung gegen das deklarierte Eingabeschema jedes Tools. Unbekannte Felder in Tool-Argumenten werden abgelehnt, statt stillschweigend ignoriert zu werden.

Browser-Origin-Anfragen an /mcp werden abgelehnt, sofern ihre exakte Origin nicht in der durch Kommas getrennten Umgebungsvariablen MCP_ALLOWED_ORIGINS enthalten ist. Server-zu-Server-Anfragen ohne Origin-Header funktionieren weiterhin normal.

Die Authentifizierung ist optional, bis der Dienst mit echten Kreditnehmerdaten verwendet wird. Um die Bearer-Authentifizierung zu aktivieren, speichern Sie das Token als Cloudflare-Secret und nicht als Klartext-Wrangler-Variable:

npx wrangler secret put MCP_BEARER_TOKEN

Der Worker unterstützt außerdem das native Cloudflare-Rate-Limiting-Binding unter dem optionalen Binding-Namen MCP_RATE_LIMITER. Wenn die öffentliche Exposition ein Rate Limiting rechtfertigt, fügen Sie einen ratelimits-Eintrag zu wrangler.jsonc hinzu, mit einer positiven ganzzahligen Namespace-ID, die für das Cloudflare-Konto eindeutig ist, und dem gewünschten 10- oder 60-Sekunden-Limitfenster. Die Laufzeit fällt bei einem Fehler des konfigurierten Bindings geschlossen mit HTTP 503 aus und gibt HTTP 429 zurück, wenn das Binding eine Anfrage ablehnt. Cloudflare dokumentiert das Binding als verfügbar in Wrangler 4.36.0 und später.

Strukturierte Anforderungsprotokolle enthalten nur Dienst/Version, JSON-RPC-Methode, Tool-Name, HTTP-Status, Byteanzahl der Anfrage und Dauer. Kreditnehmernamen, Dokumentfelder, Tool-Argumente, Autorisierungsheader/-tokens, Origins und IP-Adressen werden vom Anwendungscode nicht protokolliert.

V0.5-Rechner für Kreditnehmer

Der Live-Worker stellt nun unter GET / einen kleinen Kreditnehmerrechner bereit. Er verwendet über eine schlanke Same-Origin-Route POST /api/calculate dieselbe deterministische calculateRepayment()-Engine wie das MCP-Tool; der gehärtete /mcp-Vertrag und der Bestand von drei Tools bleiben unverändert.

Die Browseroberfläche enthält keine Analytics, externen Ressourcen oder Browser-Speicher. Antworten verwenden Cache-Control: no-store, eine restriktive Content Security Policy, die Durchsetzung von Same-Origin-API-Aufrufen, das bestehende 64-KiB-Anforderungslimit und dieselbe Laufzeitvalidierung des Eingabeschemas wie bei MCP. Ergebnisse bleiben Schätzungen und zeigen die Berechtigung als eligible, ineligible, conditional, mixed oder unknown, statt eine Servicer-Entscheidung darzustellen.

Live-Rechner für Kreditnehmer: https://student-loan-idr-mcp.jaredtechfit.workers.dev/

MCP

Endpunkt: POST /mcp

Unterstützte JSON-RPC-Methoden:

• initialize

• notifications/initialized

• ping

• tools/list

• tools/call

Für die deklarierte Streamable-HTTP-Revision 2025-03-26 sollten POST-Anfragen sowohl Content-Type: application/json als auch Accept: application/json, text/event-stream senden. GET /mcp gibt absichtlich 405 zurück, da dieser zustandslose Server keinen SSE-Listening-Stream bereitstellt.

Beispiel für einen Tool-Aufruf

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

Policy-Refresh-Workflow

Der CI-Workflow des Repositorys unterstützt außerdem einen geplanten/manuellen policy-refresh-Job. Er erstellt Fingerprints der aktuellen offiziellen Policy-Quellen und nutzt für jede geänderte Quellen-Snapshot einen Pull Request. Er schreibt nicht automatisch Rückzahlungskonstanten oder Berechtigungsregeln um; vor dem Zusammenführen von Policy-Änderungen ist eine menschliche Überprüfung erforderlich.

Entwicklung

npm install
npm run typecheck
npm test
npm run dev

Mit Wrangler bereitstellen:

npm run deploy

Sicherheit / Umfang

Dies ist ein Schätzer und Generator für Dokumentvorlagen, keine Rechts-, Steuer-, Finanz- oder Antragsberatung. Er reicht keinen IDR-Antrag ein und trifft keine offizielle Berechtigungsentscheidung. Kreditnehmer sollten Ergebnisse mit StudentAid.gov und ihrem Kredit-Servicer überprüfen.