Student Loan IDR MCP

Un pequeño servicio de Cloudflare Workers con una interfaz MCP y una calculadora orientada al prestatario para personas cuyos ingresos son irregulares, estacionales, por horas, independientes, por contrato o difíciles de expresar de otro modo como una única cifra anual.

El servicio expone tres herramientas MCP:

1. calculate_alt_income_student_loan — normaliza los ingresos imponibles variables en una estimación anual y calcula estimaciones de planes de pago para RAP, IBR, PAYE e ICR.

2. get_repayment_documentation_template — genera documentos de declaración de respaldo veraces a partir de matrices estructuradas de fuentes de ingresos en Markdown, texto plano o HTML imprimible seguro para la privacidad.

3. policy_status — informa de la instantánea de política inmutable, los planes admitidos, las fechas de caducidad conocidas, el período de vigencia de la tabla de factores ICR integrada y los enlaces a las fuentes oficiales.

Por qué existe esto

Federal Student Aid permite documentación de ingresos actuales en situaciones en las que la información de la declaración de impuestos no refleja los ingresos actuales del prestatario. El formulario actual de solicitud de IDR indica que la documentación suele incluir un recibo de nómina o una carta del empleador, y cuando la documentación no está disponible o el prestatario quiere explicar sus ingresos, se puede adjuntar una declaración firmada que identifique cada fuente de ingresos y su dirección.

Este proyecto no fabrica documentos fiscales, deducciones ni elegibilidad. Produce estimaciones, objetos deterministas de evaluación de elegibilidad y documentos de respaldo editables por el usuario que dejan marcadores de posición explícitos para los datos que quien llama no proporcionó.

Related MCP server: gsa-calc

Instantánea de política

Las constantes deterministas están versionadas explícitamente a 2026-08-27.

• Las pautas de pobreza de HHS de 2026 están integradas para los EE. UU. contiguos/D.C., Alaska y Hawái.

• RAP se incluye porque pasó a estar disponible el 1 de julio de 2026.

• IBR, PAYE e ICR se modelan para préstamos heredados aplicables con objetos explícitos de elegibilidad por tipo de préstamo/desembolso cuando se proporciona loan.eligibilityLoans.

• La tabla oficial de factores de porcentaje de ingresos ICR de 2026 está integrada para el período del 1 de julio de 2026 al 30 de junio de 2027, incluida la interpolación lineal entre las filas de AGI publicadas.

• PAYE e ICR están programados actualmente para finalizar a más tardar el 1 de julio de 2028.

• SAVE no se modela intencionadamente en esta instantánea.

Referencias oficiales:

• 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

Normalización de ingresos

Frecuencias admitidas:

• por horas (hourlyRate × hoursPerWeek × weeksPerYear)

• semanal (amount × 52)

• cada dos semanas (amount × 26)

• dos veces al mes (amount × 24)

• mensual (amount × 12)

• anual

• sumas globales estacionales (suma de los pagos proporcionados)

El servicio no aplica una falsa «deducción estándar» al ingreso bruto. Los cálculos de IDR se basan en el AGI o en documentación de ingresos actuales. Quien llama puede proporcionar un adjustedGrossIncomeOverride o proporcionar ajustes estimados por encima de la línea. De lo contrario, se utiliza el ingreso bruto imponible anualizado como estimación conservadora del AGI.

V0.2 entradas de elegibilidad

loan.eligibilityLoans acepta registros de préstamo explícitos con un loanType y un período de desembolso aproximado (before_2026_07_01 o on_or_after_2026_07_01). La calculadora devuelve un objeto eligibility a nivel de plan con evaluaciones por préstamo y uno de eligible, ineligible, conditional, mixed o unknown.

El objeto de elegibilidad es una ayuda determinista de evaluación, no una determinación oficial. Los datos específicos del prestatario que no se proporcionan permanecen como condicionales o desconocidos en lugar de ser inventados.

Para PAYE, los indicadores opcionales de prestatario/fecha modelan las condiciones publicadas del 1 de octubre de 2007 y del 1 de octubre de 2011. Para ICR, quien llama puede proporcionar taxFilingStatus o loan.icrIncomeFactorCategory; la calculadora selecciona e interpola automáticamente el factor oficial de 2026. loan.icrIncomePercentageFactor sigue disponible únicamente como anulación explícita.

V0.3 flujo de trabajo de documentos

get_repayment_documentation_template acepta una matriz opcional incomeSources. Cada fuente puede incluir un tipo de fuente, pagador/nombre, dirección, importe bruto, frecuencia de pago y notas. Si no se proporciona un dato descriptivo obligatorio, el documento generado mantiene un marcador de posición visible en lugar de inventar un valor.

Establezca outputFormat en markdown (predeterminado), text o html. El renderizador HTML escapa el contenido proporcionado por quien llama, no incluye scripts ni recursos externos, y se entrega con una política de seguridad de contenido restrictiva adecuada para un documento imprimible seguro para la privacidad.

Toda declaración generada incluye una lista de verificación de categorías comunes de evidencia de respaldo. La lista de verificación es solo una guía: indica explícitamente que el administrador del préstamo puede solicitar evidencia diferente o adicional y que ningún elemento por sí solo garantiza la aceptación.

Los campos heredados de fuente única (incomeSourceName, incomeSourceAddress, paymentFrequency y grossAmount) siguen siendo compatibles por compatibilidad. Un no_current_taxable_income_statement rechaza datos contradictorios de fuentes de ingresos actuales en lugar de producir silenciosamente una declaración incoherente.

V0.4 endurecimiento de MCP en producción

El transporte HTTP ahora aplica un límite de 64 KiB en el cuerpo de la solicitud, el tipo de contenido application/json, los tipos de medio Accept de Streamable HTTP, las reglas de ID de solicitudes/notificaciones JSON-RPC, la recepción de lotes, la negociación de versión de inicialización y la validación en tiempo de ejecución contra el esquema de entrada declarado de cada herramienta. Los campos desconocidos de argumentos de herramienta se rechazan en lugar de ignorarse silenciosamente.

Las solicitudes con origen de navegador a /mcp se deniegan a menos que su origen exacto esté presente en la variable de entorno MCP_ALLOWED_ORIGINS separada por comas. Las solicitudes de servidor a servidor sin un encabezado Origin siguen funcionando con normalidad.

La autenticación es opcional hasta que el servicio se utilice con datos reales de prestatarios. Para habilitar la autenticación de portador, almacene el token como un secreto de Cloudflare en lugar de una variable de Wrangler en texto plano:

npx wrangler secret put MCP_BEARER_TOKEN

El Worker también admite el binding nativo de Cloudflare Rate Limiting bajo el nombre de binding opcional MCP_RATE_LIMITER. Cuando la exposición pública justifique la limitación de velocidad, añada una entrada ratelimits a wrangler.jsonc con un ID de espacio de nombres de entero positivo único para la cuenta de Cloudflare y la ventana de límite deseada de 10 o 60 segundos. El tiempo de ejecución falla cerrado con HTTP 503 si un binding configurado produce un error y devuelve HTTP 429 cuando el binding deniega una solicitud. Cloudflare documenta el binding como disponible en Wrangler 4.36.0 y versiones posteriores.

Los registros de solicitudes estructurados contienen únicamente servicio/versión, método JSON-RPC, nombre de la herramienta, estado HTTP, recuento de bytes de la solicitud y duración. Los nombres de los prestatarios, los campos de los documentos, los argumentos de las herramientas, los encabezados/tokens de autorización, los orígenes y las direcciones IP no se registran mediante el código de la aplicación.

V0.5 calculadora orientada al prestatario

El Worker en producción ahora sirve una pequeña calculadora para prestatarios en GET /. Utiliza el mismo motor determinista calculateRepayment() que la herramienta MCP a través de una ruta ligera del mismo origen POST /api/calculate; el contrato endurecido /mcp y el inventario de tres herramientas no cambian.

La interfaz del navegador no tiene analíticas, recursos externos ni almacenamiento del navegador. Las respuestas utilizan Cache-Control: no-store, una política de seguridad de contenido restrictiva, aplicación de API del mismo origen, el límite existente de 64 KiB en la solicitud y la misma validación de esquema de entrada en tiempo de ejecución que usa MCP. Los resultados siguen siendo estimaciones y muestran la elegibilidad como eligible, ineligible, conditional, mixed o unknown en lugar de presentar una decisión del administrador del préstamo.

Calculadora para prestatarios en producción: https://student-loan-idr-mcp.jaredtechfit.workers.dev/

MCP

Endpoint: POST /mcp

Métodos JSON-RPC admitidos:

• initialize

• notifications/initialized

• ping

• tools/list

• tools/call

Para la revisión declarada 2025-03-26 de Streamable HTTP, las solicitudes POST deben enviar tanto Content-Type: application/json como Accept: application/json, text/event-stream. GET /mcp devuelve intencionadamente 405 porque este servidor sin estado no proporciona un flujo de escucha SSE.

Ejemplo de llamada a herramienta

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

Flujo de trabajo de actualización de política

El flujo de trabajo de CI del repositorio también admite un trabajo policy-refresh programado/manual. Toma la huella de las fuentes oficiales de política actuales y utiliza una solicitud de extracción para cualquier instantánea de fuente modificada. No reescribe automáticamente las constantes de pago ni las reglas de elegibilidad; se requiere una revisión humana antes de fusionar los cambios de política.

Desarrollo

npm install
npm run typecheck
npm test
npm run dev

Despliegue con Wrangler:

npm run deploy

Seguridad / alcance

Esto es un estimador y un generador de plantillas de documentos, no un asesoramiento legal, fiscal, financiero ni de presentación de solicitudes. No envía una solicitud de IDR ni determina la elegibilidad oficial. Los prestatarios deben verificar los resultados con StudentAid.gov y con el administrador de su préstamo.