@markcolabs/mcp 0.3.0 → 0.4.1

package/README.md

@@ -1,186 +1,126 @@
-# @markcolabs/mcp
-
-> 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).
-
----
-
-## Install
-
-```bash
-npm install -g @markcolabs/mcp
-```
-
-Or run without installing:
-
-```bash
-npx @markcolabs/mcp
-```
-
-The package ships a `digitalcalculator-mcp` binary that speaks MCP over stdio.
-
-## Quickstart — Claude Desktop
-
-Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
-Windows: `%APPDATA%\Claude\`):
-
-```json
-{
-  "mcpServers": {
-    "digitalcalculator": {
-      "command": "node",
-      "args": ["/absolute/path/to/global/node_modules/@markcolabs/mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-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/).
-
-## Tools (v0.3.0)
-
-| 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 |
-
-| Resource | Purpose |
-|---|---|
-| `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
-
-Every response carries the same envelope:
-
-```json
-{
-  "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"
-}
-```
-
-Failures use a single-envelope `ToolError` (HTTP 400 / 429 / 500):
-
-```json
-{ "error": { "code": "INPUT_VALIDATION", "message": "...", "field": "...", "retriable": false } }
-```
-
-Error codes: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT`
-(only `RATE_LIMIT` is retriable).
-
-Full input schemas, output payload shapes, and error codes:
-[www.digitalcalculator.info/mcp/api-reference/](https://www.digitalcalculator.info/mcp/api-reference/).
-
-## Hosted endpoint (no install needed)
-
-If you don't have an MCP client, POST JSON to the hosted REST companion:
-
-```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.
-
-## Licensing
-
-Two distinct surfaces, two distinct license documents:
-
-- **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).
-
-## Local development
-
-```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
-```
-
-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
-
-| 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` |
-
-`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
-
-- [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)
-
-## 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 for the package source ([LICENSE](./LICENSE)). Hosted API terms in
-[LICENSE-API.md](./LICENSE-API.md). Markco Labs LLC.
+# @markcolabs/mcp
+
+> Thin stdio-HTTPS shim that gives AI agents (Claude Desktop, MCP Inspector, any MCP client) access to financial calculator tools hosted at [digitalcalculator.info](https://www.digitalcalculator.info/mcp/). New tools are added server-side without a package update — call `tools/list` on the hosted endpoint for the current list.
+
+**v0.4.1** — stdio-HTTPS shim (S142/ADR-0044a). Engine source is private and runs in AWS Lambda; this package is a transport adapter only (~60 lines, zero engine code, MIT-licensed).
+
+---
+
+## Install
+
+```bash
+npm install -g @markcolabs/mcp
+```
+
+Or run without installing (recommended):
+
+```bash
+npx -y @markcolabs/mcp
+```
+
+## Quickstart - Claude Desktop
+
+Add to `claude_desktop_config.json`:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "digitalcalculator": {
+      "command": "npx",
+      "args": ["-y", "@markcolabs/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask "what tools do you have?" and Claude should list the available financial calculator tools.
+
+Full setup instructions: [www.digitalcalculator.info/mcp/quickstart/](https://www.digitalcalculator.info/mcp/quickstart/)
+
+---
+
+## Tools
+
+Tools are served by the hosted endpoint at `mcp.digitalcalculator.info/mcp`. New tools are added server-side — the package does not need to be updated when the tool set grows. Call `tools/list` for the authoritative current list.
+
+Tools currently available (as of v0.4.1):
+
+| Tool | Input (summary) | Returns (summary) |
+|---|---|---|
+| `mortgage_monthly_payment` | `principal`, `annualRatePercent`, `termYears` | Monthly P&I, total interest, total paid |
+| `compound_interest_future_value` | `principal`, `annualRatePercent`, `years`, `compoundingFrequency`, optional `monthlyContribution` | Future value, contributions, interest earned |
+| `retirement_401k_projection` | balance, salary, contribution %, employer match, return %, ages | Year-by-year balance, IRS 2026 limits applied |
+| `social_security_estimated_benefit` | `birthYear`, `currentEarnings`, `claimAge`, optional `yearsWorked`, `lifeExpectancy` | Monthly benefit at FRA, adjusted for claim age, lifetime projection |
+| `paycheck_net_pay` | `grossAnnualSalary`, `payFrequency`, `federalFilingStatus`, `state`, pre-/post-tax deductions | Per-paycheck gross/federal/FICA/state/net, annualized totals |
+| `ira_contribution_limit` | `age`, `filingStatus`, `magi`, `type` ('traditional' or 'roth') | Eligible contribution, Roth phase-out, catch-up, 2026 IRS limits |
+| `roth_conversion_tax_impact` | `conversionAmount`, `age`, `filingStatus`, `currentTaxableIncome`, optional retirement rate | Federal tax owed, marginal/effective rate, 5-year-rule flag |
+| `rmd_distribution_amount` | `accountBalance`, `ownerAge` (>= 73) | Required minimum distribution, Uniform Lifetime Table factor |
+| `hsa_contribution_limit` | `age`, `coverageTier` ('self-only' or 'family'), optional `employerContribution` | Total annual limit, employee max remaining, 2026 IRS limits |
+| `inflation_adjusted_value` | `amount`, `inflationRate`, `years`, optional `mode` | Future value or purchasing power after N years of inflation |
+| `savings_future_balance` | `initialDeposit`, `monthlyContribution`, `annualInterestRate`, `years` | Future balance, total contributions, interest earned |
+
+| Resource | Purpose |
+|---|---|
+| `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
+| `dc://methodologies/manifest` | Methodology URLs for all available calculator tools. |
+
+Every tool response includes a `disclaimer` field ("Estimates only - for educational purposes...") and an `engineVersion` field. Failures return:
+
+```json
+{ "error": { "code": "INPUT_VALIDATION", "message": "...", "field": "...", "retriable": false } }
+```
+
+Error codes: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT` (only `RATE_LIMIT` is retriable).
+
+Full input schemas and output shapes: [www.digitalcalculator.info/mcp/api-reference/](https://www.digitalcalculator.info/mcp/api-reference/)
+
+---
+
+## Hosted endpoint
+
+The MCP endpoint accepts JSON-RPC directly:
+
+```bash
+curl -X POST https://mcp.digitalcalculator.info/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+Rate-limited to 100 req / 5 min per IP.
+
+---
+
+## Architecture
+
+v0.4.x is a thin transport adapter with no calculation logic. Because engines run server-side, new tools appear automatically to any connected MCP client without a package update:
+
+```
+Claude Desktop -> stdin -> @markcolabs/mcp (shim) -> HTTPS -> mcp.digitalcalculator.info/mcp -> Lambda engine
+```
+
+The shim adds a 30-second request timeout (matching the AWS API Gateway integration ceiling) and a `User-Agent` header for diagnostics.
+
+---
+
+## Licensing
+
+MIT - see [LICENSE](./LICENSE). The calculator engines at the hosted endpoint are proprietary; the MIT license does not apply to them.
+
+---
+
+## Links
+
+- [Quickstart](https://www.digitalcalculator.info/mcp/quickstart/) - install and 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
+- [GitHub repo](https://github.com/mark57-ux/digitalcalculator/tree/main/packages/mcp)
+
+## Support
+
+Open an issue at [github.com/mark57-ux/digitalcalculator/issues](https://github.com/mark57-ux/digitalcalculator/issues). Include the tool name, the input that reproduces the issue, and the expected vs. actual output.
+
+## License
+
+MIT - see [LICENSE](./LICENSE). Markcolabs LLC.

package/dist/index.d.ts

@@ -1,42 +1,16 @@
 #!/usr/bin/env node
 /**
- * @markcolabs/mcp — MCP server entrypoint.
+ * @markcolabs/mcp v0.4.1 — stdio↔HTTPS shim.
  *
- * v0.3.0 (per ADR-0039 + ADR-0041 reconciliation; S141 Wave 1A + 1B).
- * Registers:
- *   - 9 tools:
- *       dc.calculator.mortgage.monthlyPayment           (S135 Item 5)
- *       dc.calculator.compoundInterest.futureValue      (S135 Item 5)
- *       dc.calculator.retirement401k.projection         (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
- *       dc.calculator.socialSecurity.estimatedBenefit   (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
- *       dc.calculator.paycheck.netPay                   (S136 Item 3)
- *       dc.calculator.ira.contributionLimit             (S141 Wave 1A)
- *       dc.calculator.rothConversion.taxImpact          (S141 Wave 1A)
- *       dc.calculator.rmd.distributionAmount            (S141 Wave 1B — new)
- *       dc.calculator.hsa.contributionLimit             (S141 Wave 1B — new)
- *   - 1 resource: dc://disclaimers/ymyl (canonical YMYL disclaimer)
+ * Proxies MCP JSON-RPC messages from stdin to the hosted MCP server at
+ * mcp.digitalcalculator.info/mcp and writes responses back to stdout.
  *
- * Transport: stdio (default for local MCP clients).
+ * Per ADR-0044a (ACCEPTED 2026-05-28): engine source lives in the private
+ * monorepo at infra/mcp/. This shim contains no calculation logic — it is
+ * a thin transport adapter only. MIT-licensed.
  *
- * S141 Wave 1A took tool coverage 5 → 7; Wave 1B finalizes 7 → 9 (v0.3.0).
+ * Claude Desktop config:
+ *   { "mcpServers": { "digitalcalculator": { "command": "npx", "args": ["-y", "@markcolabs/mcp"] } } }
  */
-export { execute as executeMortgageTool } from "./tools/mortgage.js";
-export { execute as executeCompoundInterestTool } from "./tools/compoundInterest.js";
-export { execute as executeRetirement401kTool } from "./tools/retirement401k.js";
-export { execute as executeSocialSecurityTool } from "./tools/socialSecurity.js";
-export { execute as executePaycheckTool } from "./tools/paycheck.js";
-export { execute as executeIraTool } from "./tools/ira.js";
-export { execute as executeRothConversionTool } from "./tools/rothConversion.js";
-export { execute as executeRmdTool } from "./tools/rmd.js";
-export { execute as executeHsaTool } from "./tools/hsa.js";
-export * as mortgageEngine from "./engines/mortgage.js";
-export * as compoundInterestEngine from "./engines/compoundInterest.js";
-export * as retirement401kEngine from "./engines/retirement401k.js";
-export * as socialSecurityEngine from "./engines/socialSecurity.js";
-export * as paycheckEngine from "./engines/paycheck.js";
-export * as iraEngine from "./engines/ira.js";
-export * as rothConversionEngine from "./engines/rothConversion.js";
-export * as rmdEngine from "./engines/rmd.js";
-export * as hsaEngine from "./engines/hsa.js";
-export * from "./envelope.js";
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AA4BH,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,sBAAsB,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}