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: gsa-calc

Снимок политики

Детерминированные константы явно привязаны к версии 2026-08-27.

• Встроены федеральные руководящие принципы бедности HHS на 2026 год для континентальных штатов США/округ Колумбия, Аляски и Гавайев.

• RAP включён, поскольку он стал доступен 1 июля 2026 года.

• IBR, PAYE и ICR моделируются для подходящих устаревших кредитов с явными объектами соответствия по типу кредита/дате выдачи, когда передан loan.eligibilityLoans.

• Встроена официальная таблица коэффициентов дохода ICR на 2026 год на период с 1 июля 2026 года по 30 июня 2027 года, включая линейную интерполяцию между опубликованными строками AGI.

• PAYE и ICR в настоящее время запланированы к завершению не позднее 1 июля 2028 года.

• 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, либо указать оценочные корректировки, производимые до расчёта AGI. В противном случае в качестве консервативной оценки AGI используется годовой налогооблагаемый валовой доход.

Входные данные соответствия V0.2

loan.eligibilityLoans принимает явные записи о кредитах с loanType и укрупнённым периодом выдачи (before_2026_07_01 или on_or_after_2026_07_01). Калькулятор возвращает объект eligibility на уровне плана с оценками по каждому кредиту и одним из значений eligible, ineligible, conditional, mixed или unknown.

Объект соответствия — это детерминированное вспомогательное средство первичной проверки, а не официальное решение. Факты, специфичные для заёмщика и не предоставленные в запросе, остаются условными или неизвестными, а не выдумываются.

Для PAYE необязательные флаги заёмщика/даты моделируют опубликованные условия от 1 октября 2007 года и 1 октября 2011 года. Для ICR вызывающая сторона может указать taxFilingStatus или loan.icrIncomeFactorCategory; калькулятор затем автоматически выбирает и интерполирует официальный коэффициент 2026 года. loan.icrIncomePercentageFactor остаётся доступным только как явное переопределение.

Рабочий процесс документов V0.3

get_repayment_documentation_template принимает необязательный массив incomeSources. Каждый источник может содержать тип источника, плательщика/наименование, адрес, валовую сумму, периодичность выплат и примечания. Если обязательный описательный факт не предоставлен, сформированный документ сохраняет видимый заполнитель вместо выдуманного значения.

Установите outputFormat в markdown (по умолчанию), text или html. HTML-рендерер экранирует содержимое, предоставленное вызывающей стороной, не включает скрипты или внешние ресурсы и поставляется с ограничительной политикой безопасности контента, подходящей для безопасного с точки зрения конфиденциальности печатного документа.

Каждое сформированное заявление включает контрольный список распространённых категорий подтверждающих документов. Этот список носит исключительно рекомендательный характер: в нём явно указано, что обслуживающая организация может запросить иные или дополнительные доказательства и что ни один отдельный пункт не гарантирует принятие.

Устаревшие поля одного источника (incomeSourceName, incomeSourceAddress, paymentFrequency и grossAmount) по-прежнему поддерживаются для совместимости. no_current_taxable_income_statement отвергает противоречивые данные об источниках текущего дохода, а не молча формирует несогласованное заявление.

Усиление MCP для продакшена V0.4

HTTP-транспорт теперь обеспечивает ограничение размера тела запроса 64 КиБ, тип содержимого application/json, типы носителей Accept для Streamable HTTP, правила идентификаторов JSON-RPC для запросов/уведомлений, приём пакетов, согласование версии инициализации и проверку во время выполнения по объявленной схеме входных данных каждого инструмента. Неизвестные поля аргументов инструментов отвергаются, а не молча игнорируются.

Запросы к /mcp из браузерных источников отклоняются, если точный источник отсутствует в переменной окружения MCP_ALLOWED_ORIGINS со списком значений через запятую. Серверные запросы без заголовка Origin продолжают работать в обычном режиме.

Аутентификация необязательна до тех пор, пока сервис не используется с реальными данными заёмщиков. Чтобы включить аутентификацию по токену, храните токен как секрет Cloudflare, а не как переменную Wrangler в открытом виде:

npx wrangler secret put MCP_BEARER_TOKEN

Worker также поддерживает встроенную привязку Cloudflare Rate Limiting под необязательным именем привязки MCP_RATE_LIMITER. Когда публичный доступ требует ограничения частоты запросов, добавьте запись ratelimits в wrangler.jsonc с идентификатором пространства имён в виде положительного целого числа, уникальным для аккаунта Cloudflare, и желаемым окном ограничения 10 или 60 секунд. Среда выполнения закрывается с ошибкой HTTP 503, если настроенная привязка завершается ошибкой, и возвращает HTTP 429, когда привязка отклоняет запрос. Cloudflare документирует доступность этой привязки в Wrangler 4.36.0 и более поздних версиях.

Структурированные журналы запросов содержат только сервис/версию, метод JSON-RPC, имя инструмента, HTTP-статус, размер запроса в байтах и длительность. Имена заёмщиков, поля документов, аргументы инструментов, заголовки/токены авторизации, источники и IP-адреса не записываются в журнал кодом приложения.

Калькулятор для заёмщиков V0.5

Рабочий Worker теперь предоставляет небольшой калькулятор для заёмщиков по адресу GET /. Он использует тот же детерминированный механизм calculateRepayment(), что и MCP-инструмент, через тонкий маршрут POST /api/calculate с тем же источником; ужесточённый контракт /mcp и состав из трёх инструментов не изменились.

Браузерный интерфейс не содержит аналитики, внешних ресурсов или браузерного хранилища. Ответы используют Cache-Control: no-store, ограничительную политику безопасности контента, принудительное использование API с тем же источником, существующее ограничение размера запроса 64 КиБ и ту же проверку схемы входных данных во время выполнения, что и 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 намеренно возвращает 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 и своей обслуживающей организацией.