@markcolabs/mcp 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markco Labs LLC
+
+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/LICENSE-API.md

@@ -0,0 +1,111 @@
+# Hosted API Terms — `mcp.digitalcalculator.info/mcp`
+
+**Document**: LICENSE-API.md
+**Applies to**: Use of the **hosted** MCP API at `https://mcp.digitalcalculator.info/mcp` operated by Markco Labs LLC.
+**Does NOT apply to**: Self-hosted use of the `@markcolabs/mcp` source code, which is governed by the [MIT LICENSE](./LICENSE) that ships in this package.
+
+These terms are distinct from, and complementary to, the MIT license that
+governs the package source. The MIT license lets you copy, modify, and
+redistribute the source — including running your own copy of the server on
+your own infrastructure. These hosted-API terms govern how you may interact
+with the Markco Labs–operated HTTP endpoint at the URL above.
+
+---
+
+## 1. Scope
+
+These terms apply **only** to HTTP requests made to
+`https://mcp.digitalcalculator.info/mcp` (and any future host-name variants
+operated by Markco Labs LLC for the same service).
+
+If you `npm install @markcolabs/mcp` and run it locally over MCP stdio, or
+deploy it to your own infrastructure, the MIT [LICENSE](./LICENSE) is the only
+license that applies — these hosted-API terms do not bind you in that mode.
+
+## 2. Acceptable Use
+
+The hosted endpoint is free to use, without signup or API key, subject to the
+following acceptable-use constraints:
+
+- **No scraping at scale.** The endpoint is for interactive AI agent calls and
+  developer integrations. Bulk crawling of every input combination to build
+  derivative datasets is not permitted.
+- **No resale of raw API output as a standalone product.** Embedding tool
+  responses inside a larger product (AI agent answers, calculators, dashboards)
+  is fine and encouraged. Selling the raw JSON responses as a paid feed is not.
+- **No sole-authority financial decisions.** The tools return YMYL (Your Money
+  or Your Life) estimates with a canonical disclaimer (see
+  `packages/mcp/src/disclaimers/ymyl.ts`). Downstream products must surface
+  the disclaimer alongside the numbers and must not present the results as
+  professional financial, tax, legal, or investment advice. Verify all
+  outputs against the canonical methodology pages on
+  [www.digitalcalculator.info](https://www.digitalcalculator.info) before
+  acting on them.
+- **No reverse-engineering of throttle behavior** to evade rate limits, and
+  no use of multiple IPs / clients to multiply effective throughput beyond
+  the published thresholds.
+
+## 3. Rate Limits
+
+The hosted endpoint enforces a per-IP rate limit:
+
+- **100 requests per 5 minutes per source IP** (WAFv2-enforced floor).
+- Bursts above this threshold receive HTTP 429 with the
+  `{"error":{"code":"RATE_LIMIT","retriable":true}}` envelope.
+- Markco Labs reserves the right to tighten, loosen, or replace this throttle
+  at any time. Significant changes will be announced in the package CHANGELOG
+  and on the [/mcp/](https://www.digitalcalculator.info/mcp/) landing page.
+
+Markco Labs reserves the right to suspend or block clients (by IP, ASN, or
+other identifier) that materially exceed fair-share usage, generate abuse
+patterns, or violate the acceptable-use terms above. Suspension decisions
+are at Markco Labs' sole discretion.
+
+## 4. No Warranty / Liability Limitation
+
+THE HOSTED API 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, NON-INFRINGEMENT, OR ACCURACY OF THE
+CALCULATIONS RETURNED.
+
+Specifically:
+
+- **No accuracy warranty for hosted output.** Although the engines that power
+  the hosted endpoint are parity-tested against the canonical calculators at
+  www.digitalcalculator.info on every release, the hosted endpoint is a
+  convenience surface. Authoritative results for any consequential financial
+  decision must be verified against the corresponding methodology page on the
+  main site (linked via the `methodology.url` field of every response
+  envelope).
+- **No uptime SLA.** The hosted endpoint is offered free of charge and runs
+  on best-effort infrastructure. No service-level agreement is provided.
+- **No liability for downstream use.** Markco Labs is not liable for any
+  damages — direct, indirect, incidental, special, consequential, or punitive
+  — arising from your use of the hosted endpoint, including but not limited
+  to losses caused by acting on inaccurate or out-of-date calculations.
+
+Self-hosters running the MIT-licensed source independently are governed only
+by the warranty disclaimer in the [LICENSE](./LICENSE) file — not by this
+section.
+
+## 5. Contact
+
+- **Technical issues** (bugs, broken responses, integration questions): open
+  an issue at
+  [github.com/mark57-ux/digitalcalculator/issues](https://github.com/mark57-ux/digitalcalculator/issues).
+  Best-effort triage, no SLA.
+- **Acceptable-use questions or abuse reports**: open a GitHub issue with the
+  `mcp-abuse` label, or use the contact path on
+  [www.digitalcalculator.info](https://www.digitalcalculator.info).
+- **Content / accuracy concerns**: the canonical YMYL disclaimer policy
+  (see `packages/mcp/src/disclaimers/ymyl.ts` and the response envelope)
+  applies. Direct content/accuracy disputes to the corresponding calculator's
+  methodology page on www.digitalcalculator.info.
+
+---
+
+These terms may be updated from time to time. The version that applies to a
+given request is the version that was current at the time the request was
+served. Material changes are noted in `packages/mcp/CHANGELOG.md`.
+
+Last updated: 2026-05-27 (v0.2.1 patch release).

package/README.md

@@ -1,263 +1,186 @@
 # @markcolabs/mcp
 
-Model Context Protocol (MCP) server for **digitalcalculator.info** financial calculators.
-
-**Status:** v0.2.0 — contract reconciliation release. Renames 2 tools to match ADR-0039 § 1 canon (`retirement401k.projection`, `socialSecurity.estimatedBenefit`), resets `ENGINE_VERSION` per ADR-0039 § 5 semantics, fixes Lambda handler error-envelope bug, removes dead config and CORS code. v0.1.0 is deprecated on npm.
-
-Locks in the contract from **ADR-0039** (MCP Tool Contract & Calc-Engine Lift), reconciled per **ADR-0041** (post-deploy audit decisions).
+> A free, MIT-licensed Model Context Protocol (MCP) server exposing 9
+> deterministic financial calculator tools for AI agents — mortgage payment,
+> compound interest, 401(k) projection, Social Security benefit, paycheck
+> net pay, IRA contribution limit, Roth conversion tax impact, RMD
+> distribution amount, and HSA contribution limit. Powered by the same
+> engines that run the calculators at
+> [www.digitalcalculator.info](https://www.digitalcalculator.info), parity-tested
+> on every release. Hosted REST companion at
+> [mcp.digitalcalculator.info/mcp](https://mcp.digitalcalculator.info/mcp);
+> self-hostable over MCP stdio with `npx`.
+
+**Status**: v0.3.0 (Sprint 141 Wave 1A + 1B). Adds 4 new retirement-cluster
+tools (`dc.calculator.ira.contributionLimit`,
+`dc.calculator.rothConversion.taxImpact`, `dc.calculator.rmd.distributionAmount`,
+`dc.calculator.hsa.contributionLimit`), taking tool coverage 5 → 9.
+See [CHANGELOG.md](./CHANGELOG.md).
+
+Contract: **ADR-0039** (Tool Contract), reconciled per **ADR-0041**
+(post-deploy audit decisions).
 
 ---
 
-## What ships in v0.2.0
-
-| Tool | Purpose |
-|---|---|
-| `dc.calculator.mortgage.monthlyPayment` | Monthly principal & interest, total interest, total paid for a fixed-rate mortgage. |
-| `dc.calculator.compoundInterest.futureValue` | Future value of a principal with optional monthly contributions, at a chosen compounding frequency. |
-| `dc.calculator.retirement401k.projection` | Year-by-year 401(k) projection through retirement, honoring IRS 2026 contribution limits (incl. SECURE 2.0 super catch-up for ages 60-63). |
-| `dc.calculator.socialSecurity.estimatedBenefit` | SSA bend-point PIA estimate with early-claim reduction, delayed-credit math, and lifetime projection. |
-| `dc.calculator.paycheck.netPay` | IRS 2026 federal Percentage Method + FICA + simplified state-tax estimate (no state-specific tables, SDI, or local taxes — see methodology link). |
-
-| Resource | Purpose |
-|---|---|
-| `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
-
-Every tool response carries the `ToolResult<T>` envelope:
-
-```jsonc
-{
-  "result": { /* tool-specific structured payload */ },
-  "disclaimer": "Estimates only — for educational purposes...",
-  "methodology": {
-    "url": "https://www.digitalcalculator.info/mortgage-calculator/",
-    "version": "2026-05-09"
-  },
-  "calculatedAt": "2026-05-09T18:32:11.123Z",
-  "engineVersion": "0.1.0"
-}
-```
-
-Failures funnel through the `ToolError` shape (never thrown to the transport):
+## Install
 
-```jsonc
-{
-  "error": {
-    "code": "INPUT_VALIDATION",
-    "message": "Number must be greater than or equal to 0",
-    "field": "principal",
-    "retriable": false
-  }
-}
+```bash
+npm install -g @markcolabs/mcp
 ```
 
-Code namespaces: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT` (only `RATE_LIMIT` is retriable).
-
----
-
-## Local install + test
+Or run without installing:
 
 ```bash
-cd packages/mcp
-npm install
-npm test       # run parity + envelope tests
-npm run build  # compile TypeScript to dist/
-npm start      # boot MCP server over stdio
+npx @markcolabs/mcp
 ```
 
-Vitest runs `test/parity/*.test.ts` (per-tool parity vs site source) and `test/envelope.test.ts` (envelope contract). Parity tests must pass before any engine change is shipped.
-
----
+The package ships a `digitalcalculator-mcp` binary that speaks MCP over stdio.
 
-## Connecting from a local MCP client
+## Quickstart — Claude Desktop
 
-After `npm run build`, point your MCP-compatible client at `node /path/to/packages/mcp/dist/index.js` over stdio. Example Claude Desktop config snippet:
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
+Windows: `%APPDATA%\Claude\`):
 
-```jsonc
+```json
 {
   "mcpServers": {
     "digitalcalculator": {
       "command": "node",
-      "args": ["/absolute/path/to/packages/mcp/dist/index.js"]
+      "args": ["/absolute/path/to/global/node_modules/@markcolabs/mcp/dist/index.js"]
     }
   }
 }
 ```
 
-The server emits a single startup line on stderr and then speaks JSON-RPC over stdio per the MCP spec.
+Restart Claude Desktop. In a new conversation, ask "what MCP tools do you
+have access to?" — Claude should list the 9 `dc.calculator.*` tools.
 
----
+Full setup instructions (incl. MCP Inspector, agentic CLIs, HTTP REST):
+[www.digitalcalculator.info/mcp/quickstart/](https://www.digitalcalculator.info/mcp/quickstart/).
 
-## Tool input/output sketches
+## Tools (v0.3.0)
 
-### `dc.calculator.retirement401k.projection`
+| Tool | Input (summary) | Returns (summary) |
+|---|---|---|
+| `dc.calculator.mortgage.monthlyPayment` | `principal`, `annualRatePercent`, `termYears` | Monthly P&I payment, total interest, total paid |
+| `dc.calculator.compoundInterest.futureValue` | `principal`, `annualRatePercent`, `years`, `compoundingFrequency`, optional `monthlyContribution` | Future value, total contributions, interest earned |
+| `dc.calculator.retirement401k.projection` | current balance, salary, contribution %, employer match, growth %, return %, current/retirement age | Year-by-year balance, employer match total, growth earned, IRS 2026 limits applied |
+| `dc.calculator.socialSecurity.estimatedBenefit` | `birthYear`, `currentEarnings`, `claimAge`, optional `yearsWorked`, `lifeExpectancy` | Monthly benefit at FRA, adjusted for claim age, lifetime projection, FRA age |
+| `dc.calculator.paycheck.netPay` | `grossAnnualSalary`, `payFrequency`, `federalFilingStatus`, `state`, pre-/post-tax deductions, optional `dependents` (default 0) | Per-paycheck gross/federal/FICA/state/net, annualized totals, no-state-income-tax flag |
+| `dc.calculator.ira.contributionLimit` | `age`, `filingStatus`, `magi`, `type` ('traditional' or 'roth') | Eligible contribution (with Roth MAGI phase-out + catch-up), `traditionalDeductionStatus` signal, 2026 IRS limits |
+| `dc.calculator.rothConversion.taxImpact` | `conversionAmount`, `age`, `filingStatus`, `currentTaxableIncome`, optional `retirementMarginalRatePercent` + `expectedReturnPercent` | Federal tax owed on conversion, marginal/effective rate, 5-year-rule flag, optional break-even years. Single-conversion scope (multi-year optimization is a future tool) |
+| `dc.calculator.rmd.distributionAmount` | `accountBalance`, `ownerAge` (>= 73 SECURE 2.0 floor) | Required minimum distribution, distribution period (Uniform Lifetime Table III), `tableUsed`, SECURE 2.0 §302 25% missed-RMD excise tax. `spouseAge` + `isSpouseSoleBeneficiary` accepted but ignored in v1 (Joint Life Expectancy Table is a future minor) |
+| `dc.calculator.hsa.contributionLimit` | `age`, `coverageTier` ('self-only' or 'family'), optional `employerContribution`, optional `estimatedMarginalRatePercent` | Total annual limit (with age-55+ catch-up), employee max remaining after employer reduction, optional payroll-deduction tax savings. 2026 IRS Rev. Proc. 2025-19 limits |
 
-```jsonc
-// Input
-{
-  "currentBalance": 25000,
-  "annualSalary": 80000,
-  "contributionPercent": 6,           // % of salary
-  "employerMatchPercent": 50,         // 50% match...
-  "employerMatchLimitPercent": 6,     // ...up to 6% of salary
-  "annualSalaryGrowthPercent": 3,     // 3%/yr; 0 mirrors site engine
-  "annualReturnPercent": 7,
-  "currentAge": 35,
-  "retirementAge": 65,
-  "catchUpEnabled": true              // optional, default true
-}
+| Resource | Purpose |
+|---|---|
+| `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
+
+Every response carries the same envelope:
 
-// Result payload
+```json
 {
-  "futureBalance": 873421.55,
-  "totalContributions": 228450.12,
-  "employerContribTotal": 114225.06,
-  "growthEarned": 530746.37,
-  "yearByYear": [
-    { "year": 1, "age": 36, "employeeContribution": 4944.00,
-      "employerMatch": 2472.00, "growth": 1750.00,
-      "endingBalance": 34166.00 }
-    /* ...30 rows */
-  ]
+  "result": { /* tool-specific structured object */ },
+  "disclaimer": "Estimates only — for educational purposes...",
+  "methodology": {
+    "url": "https://www.digitalcalculator.info/<calculator>/",
+    "version": "YYYY-MM-DD"
+  },
+  "calculatedAt": "ISO-8601 UTC",
+  "engineVersion": "SemVer of the engine that produced the result"
 }
 ```
 
-### `dc.calculator.socialSecurity.estimatedBenefit`
-
-```jsonc
-// Input
-{
-  "birthYear": 1965,
-  "currentEarnings": 80000,
-  "claimAge": 67,                     // 62..70
-  "yearsWorked": 35,                  // optional, default 35
-  "lifeExpectancy": 85                // optional, default 85
-}
+Failures use a single-envelope `ToolError` (HTTP 400 / 429 / 500):
 
-// Result payload
-{
-  "monthlyBenefitAtFRA": 2104.50,
-  "adjustedMonthlyBenefit": 2104.50,
-  "lifetimeBenefitProjection": 454572,
-  "fraAge": 67.0,
-  "eligibilityYear": 2027,
-  "bendPointsEstimated": true
-}
+```json
+{ "error": { "code": "INPUT_VALIDATION", "message": "...", "field": "...", "retriable": false } }
 ```
 
-For an authoritative estimate based on actual 35-year earnings history,
-direct callers to <https://www.ssa.gov/myaccount/>.
+Error codes: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT`
+(only `RATE_LIMIT` is retriable).
 
-### `dc.calculator.paycheck.netPay`
+Full input schemas, output payload shapes, and error codes:
+[www.digitalcalculator.info/mcp/api-reference/](https://www.digitalcalculator.info/mcp/api-reference/).
 
-```jsonc
-// Input
-{
-  "grossAnnualSalary": 80000,
-  "payFrequency": "biweekly",         // weekly | biweekly | semimonthly | monthly | quarterly | annual
-  "federalFilingStatus": "single",    // single | married | marriedSeparate | headOfHousehold
-  "state": "CA",
-  "dependents": 0,
-  "preTaxDeductionsAnnual": 4800,
-  "postTaxDeductionsAnnual": 0
-}
+## Hosted endpoint (no install needed)
 
-// Result payload
-{
-  "grossPerPaycheck": 3076.92,
-  "federalTax": 320.45,
-  "ficaTax": 215.61,
-  "stateTax": 116.91,
-  "netPay": 2240.43,
-  "payPeriodsPerYear": 26,
-  "federalTaxAnnual": 8331.70,
-  "ficaTaxAnnual": 5605.86,
-  "stateTaxAnnual": 3039.66,
-  "netPayAnnual": 58282.78,
-  "noStateIncomeTax": false
-}
-```
+If you don't have an MCP client, POST JSON to the hosted REST companion:
 
-> v0.2.0 limitation: state withholding is `$0` for the 9 no-income-tax states
-> (AK, FL, NV, NH, SD, TN, TX, WA, WY) and a flat 5% estimate over taxable
-> income elsewhere. Per-state brackets, SDI, and local taxes are NOT modeled.
-> See the methodology link for the full site calculator.
+```bash
+curl -X POST https://mcp.digitalcalculator.info/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool": "dc.calculator.mortgage.monthlyPayment",
+    "input": { "principal": 300000, "annualRatePercent": 6.5, "termYears": 30 }
+  }'
+```
 
----
+Returns the same envelope shape as the MCP wire protocol. Rate-limited to
+100 req / 5 min per IP (WAFv2). See [LICENSE-API.md](./LICENSE-API.md) for the
+hosted-API terms.
 
-## Architecture
+## Licensing
 
-```
-packages/mcp/
-├── package.json                # private:false (v0.1.0)
-├── CHANGELOG.md
-├── tsconfig.json
-├── vitest.config.ts
-├── src/
-│   ├── index.ts                # MCP server entry; tools/list, tools/call, resources/list
-│   ├── envelope.ts             # ToolResult<T>, ToolError types + helpers
-│   ├── disclaimers/ymyl.ts     # Canonical YMYL disclaimer (single source of truth)
-│   ├── shared/bounds.ts        # Numeric bounds shared by Zod schemas + engines
-│   ├── engines/
-│   │   ├── mortgage.ts             # Pure math + ENGINE_VERSION
-│   │   ├── compoundInterest.ts     # Pure math + ENGINE_VERSION
-│   │   ├── retirement401k.ts       # Pure math + ENGINE_VERSION (S136)
-│   │   ├── socialSecurity.ts       # Pure math + ENGINE_VERSION (S136)
-│   │   ├── paycheck.ts             # Pure math + ENGINE_VERSION (S136)
-│   │   └── data/                   # Self-contained data subset (S136)
-│   │       ├── ssa.ts                # SSA bend points + wage base
-│   │       ├── irs2026.ts            # IRS 2026 401(k) limits
-│   │       └── federalTax.ts         # 2026 federal brackets/standard ded/FICA
-│   ├── tools/
-│   │   ├── mortgage.ts
-│   │   ├── compoundInterest.ts
-│   │   ├── retirement401k.ts       # (S136)
-│   │   ├── socialSecurity.ts       # (S136)
-│   │   └── paycheck.ts             # (S136)
-│   └── util/zod-to-json-schema.ts
-└── test/
-    ├── envelope.test.ts        # Envelope contract tests
-    └── parity/
-        ├── mortgage.test.ts            # parity + envelope checks
-        ├── compoundInterest.test.ts    # parity + envelope checks
-        ├── retirement401k.test.ts      # 5 parity + envelope checks (S136)
-        ├── socialSecurity.test.ts      # 5 parity + envelope checks (S136)
-        └── paycheck.test.ts            # 5 parity + envelope checks (S136)
-```
+Two distinct surfaces, two distinct license documents:
 
-Engines are pure synchronous TypeScript ports of the corresponding browser-side calculator JS at `site/src/pages/<calculator>/<calculator>.js` (mortgage, compound-interest, 401k) and `site/src/utils/<x>-engine.js` (Social Security, paycheck). The site files are not imported directly (they mix DOM bindings with math, and npm consumers cannot reach `site/src/`); parity tests guard that the lift remains numerically identical. Where the engines depend on regulatory data (IRS limits, SSA bend points, federal tax brackets), a curated subset is mirrored in `src/engines/data/` and updated in lockstep with the site source.
+- **Package source** (this npm package + the GitHub repo): [MIT LICENSE](./LICENSE).
+  Self-host, modify, redistribute, embed in commercial products — all permitted.
+- **Hosted API** at `mcp.digitalcalculator.info/mcp`: governed by
+  [LICENSE-API.md](./LICENSE-API.md) (acceptable use, rate limits, no-warranty,
+  contact). These terms apply only when you call the hosted endpoint; they do
+  NOT bind self-hosted use of the MIT source.
 
----
+If you self-host the MIT source, only the [LICENSE](./LICENSE) applies. If you
+use the hosted endpoint, both apply (MIT for what you read; LICENSE-API for how
+you call the hosted host).
 
-## Versioning
+## Local development
 
-- **`@markcolabs/mcp` SemVer**: package version. New tool = minor; renamed tool = major.
-- **Per-engine `ENGINE_VERSION`**: independent SemVer per engine module. Bumps when math changes.
-- **`methodology.version`**: ISO date of the methodology document's `last-modified` field (per ADR-0035).
+```bash
+cd packages/mcp
+npm install
+npm test       # parity + envelope tests (vitest)
+npm run build  # compile TypeScript to dist/
+npm start      # boot MCP server over stdio
+```
 
-`engineVersion` and `methodology.version` are **independent** — callers should not assume they move in lockstep.
+Vitest runs `test/parity/*.test.ts` (per-tool parity vs. site source) and
+`test/envelope.test.ts` (envelope contract). Parity tests must pass before any
+engine change is shipped.
 
----
+## Versioning
 
-## What's next (post-S136)
+| Bump | Trigger | Example |
+|---|---|---|
+| Major package | Tool rename, removed field, breaking envelope change | v0.1.0 → v0.2.0 (tool renames) |
+| Minor package | Additive tool, additive output field | v0.2.1 → v0.3.0 (IRA + Roth conversion + RMD + HSA tools, all four shipped together in S141 Wave 1A + 1B) |
+| Patch package | Bug fixes, metadata corrections | v0.2.0 → v0.2.1 (LICENSE, README, optional dependents, dead-link audit) |
+| `engineVersion` | Math changes only | 5 prior engines at `1.0.0`; new IRA + Roth + RMD + HSA engines start at `1.0.0` |
+| `methodology.version` | Source methodology document materially updated | ISO date of the canonical methodology page's `last-modified` |
 
-1. Methodology resources `dc://methodologies/<calculator>` populated from the
-   `.md` companions (ADR-0033).
-2. The `plan-retirement` prompt template (O5-KR2).
-3. Per-state withholding tables for the paycheck tool (replace v0.2.0's flat
-   5% estimate with bracket-accurate state math).
+`engineVersion` and `methodology.version` are independent — callers should not
+assume they move in lockstep. See [CHANGELOG.md](./CHANGELOG.md) for the full
+version history.
 
----
+## Links
 
-## References
+- [Quickstart](https://www.digitalcalculator.info/mcp/quickstart/) — install + first call in under 5 minutes
+- [API Reference](https://www.digitalcalculator.info/mcp/api-reference/) — full schemas, output shapes, error codes
+- [FAQ](https://www.digitalcalculator.info/mcp/faq/) — accuracy, YMYL posture, rate limits, support, change policy
+- [GitHub repo](https://github.com/mark57-ux/digitalcalculator/tree/main/packages/mcp) — open issues, contribute
+- [CHANGELOG](https://github.com/mark57-ux/digitalcalculator/blob/main/packages/mcp/CHANGELOG.md)
+- [ADR-0039 — MCP Tool Contract](https://github.com/mark57-ux/digitalcalculator/blob/main/docs/Claude/Architecture/ADR/ADR-0039-mcp-tool-contract.md)
+- [ADR-0041 — v1 Contract Reconciliation](https://github.com/mark57-ux/digitalcalculator/blob/main/docs/Claude/Architecture/ADR/ADR-0041-mcp-v1-contract-reconciliation.md)
 
-- ADR-0039 — MCP Tool Contract & Calc-Engine Lift
-- ADR-0033 — Markdown Companion Strategy (powers `methodology.url`)
-- ADR-0035 — JSON-LD `dateModified` Propagation (powers `methodology.version`)
-- ADR-0038 — Centralized Shared-Data Architecture (regulatory constants source)
-- P12 OKR O5 — AI-Native Distribution
+## Support
 
----
+Open an issue at
+[github.com/mark57-ux/digitalcalculator/issues](https://github.com/mark57-ux/digitalcalculator/issues).
+Best-effort triage, no SLA. Include tool name, input that reproduces, expected
+vs. actual output, and the `engineVersion` from the response envelope.
 
 ## License
 
-MIT. Markcolabs LLC.
+MIT for the package source ([LICENSE](./LICENSE)). Hosted API terms in
+[LICENSE-API.md](./LICENSE-API.md). Markco Labs LLC.

package/dist/engines/data/irs2026.d.ts

@@ -1,12 +1,14 @@
 /**
  * Self-contained 2026 IRS retirement-plan limits subset for the MCP package's
- * 401(k) projection engine.
+ * retirement engines (401k, IRA, Roth conversion).
  *
- * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026. See
- * engines/data/ssa.ts for full rationale on the mirror pattern.
+ * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026 / LIMITS_IRA_2026
+ * / ROTH_PHASE_OUT_2026 / TRADITIONAL_PHASE_OUT_2026. See engines/data/ssa.ts
+ * for full rationale on the mirror pattern.
  *
  * Source: IRS Notice 2025-67 (2026 retirement-plan limits) +
  *         SECURE 2.0 Act §109 (super catch-up provision for ages 60-63).
+ *         IRA limits re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
  * Last verified: 2026-05-09.
  */
 export declare const LIMITS_401K_2026: {
@@ -27,4 +29,109 @@ export declare const LIMITS_401K_2026: {
     /** End of super catch-up window. */
     readonly superCatchUpAgeEnd: 63;
 };
+/**
+ * 2026 IRA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_IRA_2026`.
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement plan limits); SECURE 2.0 Act §107
+ *         (catch-up indexing). Re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
+ */
+export declare const LIMITS_IRA_2026: {
+    /** Base IRA contribution limit (under age 50). */
+    readonly standard: 7500;
+    /** Catch-up amount for age 50+ (SECURE 2.0 indexed). */
+    readonly catchUp: 1100;
+    /** Total contribution limit for age 50+ (standard + catchUp). */
+    readonly total50Plus: 8600;
+    /** Minimum age for catch-up eligibility. */
+    readonly catchUpAge: 50;
+};
+/**
+ * 2026 Roth IRA Income (MAGI) Phase-Out Thresholds.
+ * Mirrored from site/src/data/annual-limits.js `ROTH_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §408A(c)(3) phase-out methodology.
+ * Filing-status keys are camelCase to match the MCP package's `FilingStatus`
+ * convention; mapping vs. site keys: single=single, mfj=marriedFilingJointly,
+ * mfs=marriedFilingSeparately. (Head-of-household uses the single thresholds
+ * per IRS rules.)
+ */
+export declare const ROTH_PHASE_OUT_2026: {
+    readonly single: {
+        readonly start: 153000;
+        readonly end: 168000;
+    };
+    readonly marriedFilingJointly: {
+        readonly start: 242000;
+        readonly end: 252000;
+    };
+    readonly marriedFilingSeparately: {
+        readonly start: 0;
+        readonly end: 10000;
+    };
+    readonly headOfHousehold: {
+        readonly start: 153000;
+        readonly end: 168000;
+    };
+};
+/**
+ * 2026 Traditional IRA Deduction Phase-Out (contributor covered by workplace plan).
+ * Mirrored from site/src/data/annual-limits.js `TRADITIONAL_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §219(g) deduction phase-out methodology.
+ * NOTE: This phase-out governs the DEDUCTIBILITY of traditional IRA
+ * contributions, not the contribution limit itself. The IRA contributionLimit
+ * tool returns the eligibleContribution (= base limit for Traditional regardless
+ * of MAGI, since non-deductible contributions are always permitted). The
+ * Traditional phase-out is exposed via a separate field for clients that need
+ * the deduction-phase-out signal.
+ */
+export declare const TRADITIONAL_PHASE_OUT_2026: {
+    readonly single: {
+        readonly start: 81000;
+        readonly end: 91000;
+    };
+    readonly marriedFilingJointly: {
+        readonly start: 129000;
+        readonly end: 149000;
+    };
+    readonly marriedFilingSeparately: {
+        readonly start: 0;
+        readonly end: 10000;
+    };
+    readonly headOfHousehold: {
+        readonly start: 81000;
+        readonly end: 91000;
+    };
+};
+/**
+ * 2026 HSA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_HSA_2026`.
+ *
+ * Source: IRS Rev. Proc. 2025-19 (2026 HSA inflation adjustments under IRC §223);
+ *         IRC §223(b)(3)(B) ($1,000 catch-up is statutory and NOT inflation-indexed).
+ *         Last verified: 2026-05-27 (mirrored from site/src/data/annual-limits.js,
+ *         site _meta.last_verified_date: 2026-05-07).
+ *
+ * Notes:
+ *   - `medicareAge`: HSA contributions are prohibited once enrolled in Medicare
+ *     (typically age 65). Surfaced as an informational threshold; the HSA
+ *     contribution-limit tool does not zero out the limit at this age, it just
+ *     reports it (parallel to how the site shows a Medicare warning badge).
+ *   - Employer contributions REDUCE the employee's eligible payroll deduction
+ *     dollar-for-dollar because the IRS limit is a TOTAL annual limit, not a
+ *     per-source limit. See engines/hsa.ts for the clamp.
+ */
+export declare const LIMITS_HSA_2026: {
+    /** Self-only HDHP coverage base limit. */
+    readonly selfOnly: 4400;
+    /** Family HDHP coverage base limit. */
+    readonly family: 8750;
+    /** Catch-up amount for age 55+ (statutory, not indexed). */
+    readonly catchUp: 1000;
+    /** Minimum age for catch-up eligibility. */
+    readonly catchUpAge: 55;
+    /** Age at which Medicare enrollment typically begins (informational only). */
+    readonly medicareAge: 65;
+};
 //# sourceMappingURL=irs2026.d.ts.map

package/dist/engines/data/irs2026.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"irs2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB;IAC3B,oCAAoC;;IAEpC,qDAAqD;;IAErD,yDAAyD;;IAEzD,kDAAkD;;IAElD,gDAAgD;;IAEhD,oCAAoC;;IAEpC,sCAAsC;;IAEtC,oCAAoC;;CAE5B,CAAC"}
+{"version":3,"file":"irs2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,gBAAgB;IAC3B,oCAAoC;;IAEpC,qDAAqD;;IAErD,yDAAyD;;IAEzD,kDAAkD;;IAElD,gDAAgD;;IAEhD,oCAAoC;;IAEpC,sCAAsC;;IAEtC,oCAAoC;;CAE5B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;IAC1B,kDAAkD;;IAElD,wDAAwD;;IAExD,iEAAiE;;IAEjE,4CAA4C;;CAEpC,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;CAKtB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;CAK7B,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe;IAC1B,0CAA0C;;IAE1C,uCAAuC;;IAEvC,4DAA4D;;IAE5D,4CAA4C;;IAE5C,8EAA8E;;CAEtE,CAAC"}