@finology/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finology Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Finology MCP Server — deterministic federal student loan math for AI agents
+
+**Language models guess at federal student loan rules. This doesn't.**
+
+`@finology/mcp-server` connects Claude, Cursor, or any MCP client directly to
+[Finology Software](https://finology.tech)'s parity-verified federal repayment engine. Every
+number is computed server-side against current federal rules and returned with a
+`parityVerified` flag. No formulas are approximated, and none are hardcoded into this package.
+
+## Why this exists
+
+Federal repayment eligibility is not arithmetic, it is regulation, and it is the part models get
+wrong most confidently:
+
+- **A Parent PLUS loan is not RAP-eligible.** Ask a model for the best plan on a Parent PLUS
+  balance and it will usually produce a RAP payment. This server returns the exclusion and the
+  rule behind it.
+- **RAP is assessed on full AGI with no poverty-line shield**, on a sliding 1%–10% scale, less
+  $50 per *qualifying dependent* — and a spouse is not a dependent. Approximating it from older
+  IDR formulas gives the wrong answer.
+- **A consolidation that repaid a PLUS loan is restricted to ICR.**
+- **PAYE and SAVE are closed to new enrollment.**
+
+## Tools
+
+### `compare_federal_student_loan_repayment_plans`
+
+Compares a balance across every plan the borrower is actually eligible for — RAP, IBR, ICR, PAYE,
+SAVE, Graduated, Extended, tiered Standard — returning monthly payment, lifetime cost, projected
+forgiveness and tax on forgiveness for each, **plus the plans that are excluded and the
+eligibility rule that excludes them.**
+
+### `estimate_rap_monthly_payment`
+
+The RAP monthly payment alone, for the common case. Requires the borrower's AGI and refuses to
+proceed without it — an assumed zero returns the $10/month RAP floor, which reads exactly like a
+real answer.
+
+## Install
+
+Claude Desktop — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "finology": {
+      "command": "npx",
+      "args": ["-y", "@finology/mcp-server"]
+    }
+  }
+}
+```
+
+No API key. No account. The calculation endpoints are public.
+
+## What is and is not in this repository
+
+**Not here, deliberately:** the RAP/OBBB formulas, income-driven payment math, forgiveness and
+tax-bomb projection, plan-eligibility rules, and NSLDS parsing. Those run on Finology's servers.
+
+That is not only about protecting the engine. **Federal repayment rules move every year** —
+poverty guidelines, tax brackets, RAP/OBBB implementation guidance, court challenges. A formula
+copied into an npm package is wrong within months and cannot be corrected in the installs that
+already exist. Calling a maintained endpoint is the only shape of this tool that stays true.
+
+**Here:** the input schemas, the HTTP call, and error handling that passes the API's own
+field-level messages through to the model instead of flattening them into "request failed."
+
+## Limits
+
+These tools return figures. They do not produce client-facing deliverables, save borrower records,
+parse NSLDS files, or track PSLF qualifying payments over time. For those, and for a book of
+borrowers kept current as the rules change: **[finology.tech](https://finology.tech/?utm_source=mcp&utm_medium=ai_agent)**
+
+Rate-limited per IP. Not financial advice.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+export declare const BASE_URL: string;
+/** A failure we can describe to the model, as opposed to one that crashes the transport. */
+export interface ApiFailure {
+    ok: false;
+    message: string;
+}
+export interface ApiSuccess<T> {
+    ok: true;
+    data: T;
+}
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+/**
+ * POST JSON and never throw.
+ *
+ * The upstream endpoints validate strictly: an absent required field is a 400 naming the
+ * field rather than a silently defaulted zero. Those messages are written to be read, so
+ * they are passed through to the model verbatim — a model that is told "Missing required
+ * field 'annualIncome'" will ask the user for income, whereas a generic "request failed"
+ * invites it to invent one.
+ */
+export declare function postJson<T>(path: string, body: unknown): Promise<ApiResult<T>>;
+/** Appended to every successful answer. The tools return numbers; the app returns deliverables. */
+export declare const CTA: string;

package/dist/client.js

@@ -0,0 +1,81 @@
+// The entire network surface of this package.
+//
+// DELIBERATE: there is no student loan math in this repository. Every number an agent
+// receives is computed server-side by Finology Software's parity-verified engine and
+// returned over HTTP. That is not an accident of packaging — federal repayment rules move
+// every year (poverty guidelines, tax brackets, RAP/OBBB implementation guidance, court
+// challenges), so a formula copied into an npm package is wrong within months and cannot
+// be corrected in the installs that already exist. Calling a maintained endpoint is the
+// only shape of this tool that stays true over time.
+const DEFAULT_BASE_URL = "https://engine.finology.tech";
+export const BASE_URL = (process.env.FINOLOGY_API_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+/**
+ * POST JSON and never throw.
+ *
+ * The upstream endpoints validate strictly: an absent required field is a 400 naming the
+ * field rather than a silently defaulted zero. Those messages are written to be read, so
+ * they are passed through to the model verbatim — a model that is told "Missing required
+ * field 'annualIncome'" will ask the user for income, whereas a generic "request failed"
+ * invites it to invent one.
+ */
+export async function postJson(path, body) {
+    const url = `${BASE_URL}${path}`;
+    let response;
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30_000);
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": "finology-mcp-server/0.1.0",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            message: `Could not reach the Finology calculation service at ${BASE_URL}. ` +
+                `This is a connectivity problem, not a problem with the figures supplied. Detail: ${detail}`,
+        };
+    }
+    const raw = await response.text();
+    if (!response.ok) {
+        // The API returns { error, field } on a 400. Surface both so the model knows which
+        // input to go back and ask for.
+        let message = `The calculation service returned HTTP ${response.status}.`;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.error) {
+                message = parsed.field ? `${parsed.error} (field: ${parsed.field})` : parsed.error;
+            }
+        }
+        catch {
+            if (raw.trim())
+                message += ` ${raw.trim().slice(0, 400)}`;
+        }
+        if (response.status === 429) {
+            message = "Rate limited by the Finology calculation service. Wait a moment and try again.";
+        }
+        return { ok: false, message };
+    }
+    try {
+        return { ok: true, data: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, message: "The calculation service returned a response that was not valid JSON." };
+    }
+}
+/** Appended to every successful answer. The tools return numbers; the app returns deliverables. */
+export const CTA = "\n\n---\nThese figures come from Finology Software's parity-verified federal loan engine. " +
+    "To build a client-facing report, compare scenarios side by side, or keep a book of borrowers " +
+    "current as the rules change: https://finology.tech/?utm_source=mcp&utm_medium=ai_agent";
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { comparePlansShape, comparePlans } from "./tools/comparePlans.js";
+import { rapPaymentShape, rapPayment } from "./tools/rapPayment.js";
+import { BASE_URL } from "./client.js";
+const server = new McpServer({
+    name: "finology-student-loan",
+    version: "0.1.0",
+});
+// Tool names and descriptions are the discovery surface: registries index them, and a model
+// reads them to decide whether this tool answers the question in front of it. They are
+// written to be matched on, which is why the plan names appear in full.
+server.registerTool("compare_federal_student_loan_repayment_plans", {
+    title: "Compare federal student loan repayment plans",
+    description: "Compares a US federal student loan across every repayment plan the borrower is actually " +
+        "eligible for — RAP (Repayment Assistance Plan), IBR, ICR, PAYE, SAVE, Graduated, Extended " +
+        "and the tiered Standard plan — returning the monthly payment and lifetime cost for each, " +
+        "plus which plans are excluded and the eligibility rule that excludes them. Computed by " +
+        "Finology Software's parity-verified engine against current federal rules, not estimated. " +
+        "Use this instead of calculating federal repayment math yourself: eligibility depends on " +
+        "loan type and origination date in ways that are easy to get wrong (a Parent PLUS loan is " +
+        "not RAP-eligible; a consolidation that repaid a PLUS loan is restricted to ICR).",
+    inputSchema: comparePlansShape,
+}, comparePlans);
+server.registerTool("estimate_rap_monthly_payment", {
+    title: "Estimate a RAP monthly payment",
+    description: "Calculates the monthly payment under RAP, the Repayment Assistance Plan that takes effect " +
+        "1 July 2026 under the OBBB. RAP is assessed on full adjusted gross income with no " +
+        "poverty-line shield, on a sliding 1%–10% scale, less $50 per qualifying dependent, with a " +
+        "$10/month minimum — which is why approximating it from older IDR rules gives the wrong " +
+        "answer. Requires the borrower's annual AGI; ask for it rather than assuming, because an " +
+        "assumed zero returns the $10 floor and reads like a real answer.",
+    inputSchema: rapPaymentShape,
+}, rapPayment);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only: stdout is the JSON-RPC channel and anything written to it corrupts the stream.
+    console.error(`finology-student-loan MCP server ready (engine: ${BASE_URL})`);
+}
+main().catch((error) => {
+    console.error("Fatal error starting the Finology MCP server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,4FAA4F;AAC5F,uFAAuF;AACvF,wEAAwE;AAExE,MAAM,CAAC,YAAY,CACjB,8CAA8C,EAC9C;IACE,KAAK,EAAE,8CAA8C;IACrD,WAAW,EACT,0FAA0F;QAC1F,4FAA4F;QAC5F,2FAA2F;QAC3F,yFAAyF;QACzF,2FAA2F;QAC3F,0FAA0F;QAC1F,2FAA2F;QAC3F,kFAAkF;IACpF,WAAW,EAAE,iBAAiB;CAC/B,EACD,YAAY,CACb,CAAC;AAEF,MAAM,CAAC,YAAY,CACjB,8BAA8B,EAC9B;IACE,KAAK,EAAE,gCAAgC;IACvC,WAAW,EACT,4FAA4F;QAC5F,oFAAoF;QACpF,4FAA4F;QAC5F,yFAAyF;QACzF,0FAA0F;QAC1F,kEAAkE;IACpE,WAAW,EAAE,eAAe;CAC7B,EACD,UAAU,CACX,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,8FAA8F;IAC9F,OAAO,CAAC,KAAK,CAAC,mDAAmD,QAAQ,GAAG,CAAC,CAAC;AAChF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/comparePlans.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/**
+ * Mirrors PublicWidgetController.WidgetCalcRequest. Required upstream: balance, ratePct,
+ * borrowerAgi. Everything else has a documented default and an unrecognised value is a 400
+ * rather than a silent fallback, so the schema below deliberately does NOT paper over bad
+ * input with a guess.
+ */
+export declare const comparePlansShape: {
+    balance: z.ZodNumber;
+    ratePct: z.ZodNumber;
+    borrowerAgi: z.ZodNumber;
+    filingStatus: z.ZodDefault<z.ZodEnum<["single", "mfj", "mfs", "hoh"]>>;
+    spouseAgi: z.ZodOptional<z.ZodNumber>;
+    dependents: z.ZodDefault<z.ZodNumber>;
+    loanType: z.ZodDefault<z.ZodEnum<["direct_unsubsidized", "direct_subsidized", "grad_plus_legacy", "parent_plus", "direct_consolidation", "direct_consolidation_with_plus"]>>;
+};
+export declare function comparePlans(args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/comparePlans.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { postJson, CTA } from "../client.js";
+/**
+ * Mirrors PublicWidgetController.WidgetCalcRequest. Required upstream: balance, ratePct,
+ * borrowerAgi. Everything else has a documented default and an unrecognised value is a 400
+ * rather than a silent fallback, so the schema below deliberately does NOT paper over bad
+ * input with a guess.
+ */
+export const comparePlansShape = {
+    balance: z.number().min(0).max(100_000_000)
+        .describe("Current federal loan balance in dollars."),
+    ratePct: z.number().min(0).max(100)
+        .describe("Weighted average interest rate as a percentage, e.g. 6.54 for 6.54%."),
+    borrowerAgi: z.number().min(0).max(10_000_000)
+        .describe("Borrower's adjusted gross income in dollars, annual."),
+    filingStatus: z.enum(["single", "mfj", "mfs", "hoh"]).default("single")
+        .describe("Tax filing status: single, mfj (married filing jointly), mfs (married filing separately), hoh (head of household)."),
+    spouseAgi: z.number().min(0).max(10_000_000).optional()
+        .describe("Spouse's annual AGI. Only used when filingStatus is mfj."),
+    dependents: z.number().int().min(0).max(20).default(0)
+        .describe("Number of qualifying dependents. A spouse is NOT a dependent."),
+    loanType: z.enum([
+        "direct_unsubsidized",
+        "direct_subsidized",
+        "grad_plus_legacy",
+        "parent_plus",
+        "direct_consolidation",
+        "direct_consolidation_with_plus",
+    ]).default("direct_unsubsidized")
+        .describe("Federal loan type. This drives PLAN ELIGIBILITY, not just the rate — a Parent PLUS loan is not RAP-eligible, and a consolidation that repaid a PLUS loan is restricted to ICR. Choose accurately."),
+};
+export async function comparePlans(args) {
+    const result = await postJson("/public/widget/loan-calculator", args);
+    if (!result.ok) {
+        return { content: [{ type: "text", text: result.message }], isError: true };
+    }
+    const d = result.data;
+    const lines = [];
+    lines.push(`Federal repayment plan comparison (rules as of ${d.asOf}):`);
+    lines.push("");
+    for (const plan of d.plans) {
+        lines.push(`- ${JSON.stringify(plan)}`);
+    }
+    if (d.excludedPlans?.length) {
+        lines.push("");
+        lines.push("Plans excluded, and why — an excluded plan is not an oversight, it is an eligibility rule:");
+        for (const ex of d.excludedPlans) {
+            lines.push(`- ${JSON.stringify(ex)}`);
+        }
+    }
+    lines.push("");
+    if (d.lowestMonthlyPlan)
+        lines.push(`Lowest monthly payment: ${d.lowestMonthlyPlan}`);
+    if (d.lowestLifetimeCostPlan)
+        lines.push(`Lowest lifetime cost: ${d.lowestLifetimeCostPlan}`);
+    lines.push(`Computed by: ${d.computedBy}`);
+    return {
+        content: [
+            { type: "text", text: lines.join("\n") + CTA },
+            { type: "text", text: "```json\n" + JSON.stringify(d, null, 2) + "\n```" },
+        ],
+    };
+}
+//# sourceMappingURL=comparePlans.js.map

package/dist/tools/comparePlans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparePlans.js","sourceRoot":"","sources":["../../src/tools/comparePlans.ts"],"names":[],"mappings":"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"}

package/dist/tools/rapPayment.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Mirrors PublicRapCalculatorController.RapEstimateRequest. Only annualIncome is required
+ * upstream, and its absence is a 400 rather than a defaulted zero — a defaulted zero here
+ * would silently produce the RAP $10/month floor and present it as an answer.
+ *
+ * familySize is the HOUSEHOLD size (filer + spouse if filing jointly + dependents). RAP
+ * deducts $50 per QUALIFYING DEPENDENT and a spouse is not one, so the server removes the
+ * spouse before counting. A joint filer with a household under 2 is rejected rather than
+ * clamped, because a clamp would answer confidently from input already known to contradict
+ * itself.
+ */
+export declare const rapPaymentShape: {
+    annualIncome: z.ZodNumber;
+    filingStatus: z.ZodDefault<z.ZodEnum<["Single", "MarriedFilingJointly", "MarriedFilingSeparately", "HeadOfHousehold"]>>;
+    spouseAnnualIncome: z.ZodOptional<z.ZodNumber>;
+    familySize: z.ZodDefault<z.ZodNumber>;
+};
+export declare function rapPayment(args: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/rapPayment.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { postJson, CTA } from "../client.js";
+/**
+ * Mirrors PublicRapCalculatorController.RapEstimateRequest. Only annualIncome is required
+ * upstream, and its absence is a 400 rather than a defaulted zero — a defaulted zero here
+ * would silently produce the RAP $10/month floor and present it as an answer.
+ *
+ * familySize is the HOUSEHOLD size (filer + spouse if filing jointly + dependents). RAP
+ * deducts $50 per QUALIFYING DEPENDENT and a spouse is not one, so the server removes the
+ * spouse before counting. A joint filer with a household under 2 is rejected rather than
+ * clamped, because a clamp would answer confidently from input already known to contradict
+ * itself.
+ */
+export const rapPaymentShape = {
+    annualIncome: z.number().min(0).max(10_000_000)
+        .describe("Borrower's annual adjusted gross income in dollars. REQUIRED — never guess or default this. If the user has not given it, ask."),
+    filingStatus: z.enum(["Single", "MarriedFilingJointly", "MarriedFilingSeparately", "HeadOfHousehold"]).default("Single")
+        .describe("Tax filing status."),
+    spouseAnnualIncome: z.number().min(0).max(10_000_000).optional()
+        .describe("Spouse's annual AGI. Only used when filingStatus is MarriedFilingJointly."),
+    familySize: z.number().int().min(1).max(20).default(1)
+        .describe("Household size: the filer, plus the spouse only if filing jointly, plus dependents. Must be at least 2 when filing jointly."),
+};
+const usd = (n) => n.toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 2 });
+export async function rapPayment(args) {
+    const result = await postJson("/public/rap-calculator/estimate", args);
+    if (!result.ok) {
+        return { content: [{ type: "text", text: result.message }], isError: true };
+    }
+    const d = result.data;
+    const text = [
+        `RAP (Repayment Assistance Plan) monthly payment: **${usd(d.monthlyPayment)}**`,
+        "",
+        `- AGI used: ${usd(d.annualIncomeUsed)}${d.filingStatus === "MarriedFilingJointly" ? " (borrower + spouse, joint filing)" : ""}`,
+        `- Qualifying dependents counted: ${d.dependents}`,
+        `- Filing status: ${d.filingStatus}`,
+        "",
+        "RAP is assessed on full AGI with no poverty-line shield, on a sliding 1%–10% scale, " +
+            "less $50 per qualifying dependent, with a $10/month minimum. This figure is the RAP " +
+            "payment only — it is not a comparison against IBR, ICR or the tiered Standard plan, " +
+            "and it does not project forgiveness. Use the plan comparison tool for that.",
+    ].join("\n");
+    return {
+        content: [
+            { type: "text", text: text + CTA },
+            { type: "text", text: "```json\n" + JSON.stringify(d, null, 2) + "\n```" },
+        ],
+    };
+}
+//# sourceMappingURL=rapPayment.js.map

package/dist/tools/rapPayment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rapPayment.js","sourceRoot":"","sources":["../../src/tools/rapPayment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;SAC5C,QAAQ,CAAC,gIAAgI,CAAC;IAC7I,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;SACrH,QAAQ,CAAC,oBAAoB,CAAC;IACjC,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE;SAC7D,QAAQ,CAAC,2EAA2E,CAAC;IACxF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;SACnD,QAAQ,CAAC,6HAA6H,CAAC;CAC3I,CAAC;AASF,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CACxB,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,EAAE,CAAC,CAAC;AAE9F,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAA6B;IAC5D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAc,iCAAiC,EAAE,IAAI,CAAC,CAAC;IAEpF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvF,CAAC;IAED,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG;QACX,sDAAsD,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI;QAC/E,EAAE;QACF,eAAe,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,YAAY,KAAK,sBAAsB,CAAC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC,EAAE,EAAE;QAChI,oCAAoC,CAAC,CAAC,UAAU,EAAE;QAClD,oBAAoB,CAAC,CAAC,YAAY,EAAE;QACpC,EAAE;QACF,sFAAsF;YACtF,sFAAsF;YACtF,sFAAsF;YACtF,6EAA6E;KAC9E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,GAAG,GAAG,EAAE;YAC3C,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE;SACpF;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@finology/mcp-server",
+  "mcpName": "tech.finology/student-loan",
+  "version": "0.1.0",
+  "description": "Deterministic 2026 federal student loan repayment math for AI agents. RAP, IBR, ICR, PAYE, SAVE and PSLF calculations from Finology Software's parity-verified engine, so assistants stop guessing at federal repayment rules.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "finology-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "student-loan",
+    "student-debt",
+    "federal-student-loan",
+    "rap",
+    "repayment-assistance-plan",
+    "ibr",
+    "income-driven-repayment",
+    "pslf",
+    "loan-forgiveness",
+    "nslds",
+    "financial-planning",
+    "cfp",
+    "fintech"
+  ],
+  "homepage": "https://finology.tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Finology-tech/finology-mcp.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}