statetakehome-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { calculate, selfEmploymentTax, capitalGains } from "./lib/tax-calc.js";
+import { FEDERAL, STATE_ENTRIES } from "./lib/state-data.js";
+const STATE_CODES = STATE_ENTRIES.map((s) => s.abbr);
+const FILING_STATUS = z
+    .enum([
+    "single",
+    "married_filing_jointly",
+    "married_filing_separately",
+    "head_of_household",
+])
+    .describe("IRS filing status.");
+const SOURCE_NOTE = {
+    tax_year: FEDERAL.year,
+    federal_source: FEDERAL.source,
+    federal_verify_url: FEDERAL.verify_url,
+    state_source: "Tax Foundation — State Individual Income Tax Rates and Brackets, as of January 1, 2026, cross-checked against state DOR publications.",
+    disclaimer: "2026 tax year — these are estimates for planning purposes, not tax advice. Consult a licensed tax professional for your specific situation.",
+};
+const server = new McpServer({
+    name: "statetakehome-mcp",
+    version: "0.1.0",
+});
+server.registerTool("us_take_home_pay", {
+    title: "US Take-Home Pay Calculator",
+    description: "Computes net take-home pay for a US W-2 employee: federal income tax, state income tax (all 50 states + DC), FICA (Social Security + Medicare + Additional Medicare), and state-specific extras (e.g. CA SDI, OR transit tax). " +
+        "Supports pre-tax 401(k) and health-insurance deductions and per-paycheck breakdowns. " +
+        'Example input: { "gross": 75000, "state": "CA", "filingStatus": "single" }. ' +
+        "2026 tax year — estimates, not tax advice; brackets from Tax Foundation (Jan 1, 2026) & IRS.",
+    inputSchema: {
+        gross: z.number().positive().describe("Annual gross income in USD, e.g. 75000."),
+        state: z
+            .enum(STATE_CODES)
+            .describe("Two-letter US state or DC postal code, e.g. \"CA\", \"TX\", \"NY\"."),
+        filingStatus: FILING_STATUS,
+        dependents: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Number of dependents claimed (informational; not currently used in the federal/state bracket math)."),
+        pretax401kPct: z
+            .number()
+            .min(0)
+            .max(100)
+            .optional()
+            .describe("Pre-tax 401(k) contribution as a percent of gross pay (0-100), capped at the 2026 employee deferral limit ($23,500)."),
+        pretaxHealthAnnual: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Annual pre-tax health insurance / HSA premiums in USD, excluded from both income tax and FICA wages."),
+        payFrequency: z
+            .enum(["weekly", "biweekly", "semimonthly", "monthly", "annual"])
+            .optional()
+            .describe("Pay frequency; the result always includes a full per-paycheck breakdown for all frequencies regardless of this value."),
+    },
+}, async (input) => {
+    const result = calculate({
+        grossIncome: input.gross,
+        state: input.state,
+        filingStatus: input.filingStatus,
+        dependents: input.dependents,
+        pretax401kPct: input.pretax401kPct,
+        pretaxHealthAnnual: input.pretaxHealthAnnual,
+        payFrequency: input.payFrequency,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    input,
+                    result,
+                    source: SOURCE_NOTE,
+                    reference_url: "https://statetakehome.com/",
+                }, null, 2),
+            },
+        ],
+    };
+});
+server.registerTool("self_employment_tax", {
+    title: "Self-Employment (1099) Tax Calculator",
+    description: "Computes Schedule SE self-employment tax (15.3% = 12.4% Social Security up to the wage base + 2.9% Medicare on 92.35% of net profit), the Additional Medicare surtax, federal income tax, and an optional state income tax, plus a quarterly estimated-payment figure. " +
+        'Example input: { "netProfit": 90000, "filingStatus": "single", "state": "TX" }. ' +
+        "2026 tax year — estimates, not tax advice; brackets from Tax Foundation (Jan 1, 2026) & IRS.",
+    inputSchema: {
+        netProfit: z
+            .number()
+            .positive()
+            .describe("Schedule C net profit in USD (1099 income minus business expenses), e.g. 90000."),
+        filingStatus: FILING_STATUS,
+        state: z
+            .enum(STATE_CODES)
+            .optional()
+            .describe("Optional two-letter US state or DC postal code to also estimate state income tax."),
+        otherIncome: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Other ordinary income (e.g. a W-2 job) that stacks on top for bracket and wage-base purposes."),
+    },
+}, async (input) => {
+    const result = selfEmploymentTax({
+        netProfit: input.netProfit,
+        filingStatus: input.filingStatus,
+        state: input.state,
+        otherIncome: input.otherIncome,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    input,
+                    result,
+                    source: SOURCE_NOTE,
+                    reference_url: "https://statetakehome.com/self-employment-tax-calculator",
+                }, null, 2),
+            },
+        ],
+    };
+});
+server.registerTool("capital_gains_tax", {
+    title: "Capital Gains Tax Calculator",
+    description: "Computes federal capital gains tax (long-term 0%/15%/20% stacked bands or short-term ordinary rates), the 3.8% Net Investment Income Tax (NIIT) above the MAGI threshold, and an optional state income tax on the gain (states generally tax capital gains as ordinary income). " +
+        'Example input: { "gain": 50000, "ordinaryTaxableIncome": 80000, "filingStatus": "single", "term": "long" }. ' +
+        "2026 tax year — estimates, not tax advice; thresholds from Rev. Proc. 2025-32, cross-checked against Tax Foundation & Schwab.",
+    inputSchema: {
+        gain: z.number().positive().describe("Gross capital gain in USD (sale price minus cost basis), e.g. 50000."),
+        ordinaryTaxableIncome: z
+            .number()
+            .min(0)
+            .describe("Other taxable income (excluding the gain), which sets the long-term capital gains bracket and NIIT threshold."),
+        filingStatus: FILING_STATUS,
+        term: z.enum(["long", "short"]).describe("\"long\" for assets held > 1 year (preferential rates), \"short\" for ordinary rates."),
+        state: z
+            .enum(STATE_CODES)
+            .optional()
+            .describe("Optional two-letter US state or DC postal code; most states tax the gain as ordinary income."),
+        exclusion: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Amount excluded from the gain before tax (e.g. the §121 primary-residence sale exclusion)."),
+    },
+}, async (input) => {
+    const result = capitalGains({
+        gain: input.gain,
+        ordinaryTaxableIncome: input.ordinaryTaxableIncome,
+        filingStatus: input.filingStatus,
+        term: input.term,
+        state: input.state,
+        exclusion: input.exclusion,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    input,
+                    result,
+                    source: SOURCE_NOTE,
+                    reference_url: "https://statetakehome.com/capital-gains-tax-calculator",
+                }, null, 2),
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("statetakehome-mcp fatal error:", err);
+    process.exit(1);
+});

package/dist/lib/ca-data.js

@@ -0,0 +1,18 @@
+import { createRequire } from "module";
+// See state-data.ts for why createRequire is used instead of a static ESM
+// JSON import (Node >=18 compatibility, no import-attribute version gate).
+const require = createRequire(import.meta.url);
+const raw = require("../data/ca-tax-data.json");
+export const caData = raw;
+export const CA_FEDERAL = caData.federal;
+export const PROVINCES = caData.provinces;
+// Display order for the calculator dropdown: by population/relevance, not alphabetical.
+export const PROVINCE_ORDER = [
+    "ON", "QC", "BC", "AB", "MB", "SK", "NS", "NB", "NL", "PE", "NT", "YT", "NU",
+];
+export const PROVINCE_ENTRIES = PROVINCE_ORDER
+    .map((code) => caData.provinces[code])
+    .filter(Boolean);
+export function getProvince(abbr) {
+    return caData.provinces[abbr.toUpperCase()];
+}

package/dist/lib/state-data.js

@@ -0,0 +1,22 @@
+import { createRequire } from "module";
+// Loaded via createRequire (not a static ESM JSON import) so this works
+// unmodified on Node >=18 without relying on version-gated `with { type: "json" }`
+// import-attribute support (only stable since Node 20.10 / 18.20).
+const require = createRequire(import.meta.url);
+const raw = require("../data/state-tax-data.json");
+export const data = raw;
+export const FEDERAL = data.federal;
+export const STATES = data.states;
+export const STATE_ENTRIES = Object.values(data.states).sort((a, b) => a.name.localeCompare(b.name));
+export const REGIONS = {
+    Northeast: ["CT", "ME", "MA", "NH", "NJ", "NY", "PA", "RI", "VT"],
+    South: [
+        "AL", "AR", "DE", "DC", "FL", "GA", "KY", "LA", "MD", "MS",
+        "NC", "OK", "SC", "TN", "TX", "VA", "WV",
+    ],
+    Midwest: ["IL", "IN", "IA", "KS", "MI", "MN", "MO", "NE", "ND", "OH", "SD", "WI"],
+    West: ["AK", "AZ", "CA", "CO", "HI", "ID", "MT", "NV", "NM", "OR", "UT", "WA", "WY"],
+};
+export function getState(abbr) {
+    return data.states[abbr.toUpperCase()];
+}