@markcolabs/mcp 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +128 -205
  3. package/dist/index.d.ts +9 -23
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.js +51 -186
  6. package/dist/index.js.map +1 -1
  7. package/package.json +21 -12
  8. package/dist/disclaimers/ymyl.d.ts +0 -16
  9. package/dist/disclaimers/ymyl.d.ts.map +0 -1
  10. package/dist/disclaimers/ymyl.js +0 -20
  11. package/dist/disclaimers/ymyl.js.map +0 -1
  12. package/dist/engines/compoundInterest.d.ts +0 -75
  13. package/dist/engines/compoundInterest.d.ts.map +0 -1
  14. package/dist/engines/compoundInterest.js +0 -74
  15. package/dist/engines/compoundInterest.js.map +0 -1
  16. package/dist/engines/data/federalTax.d.ts +0 -47
  17. package/dist/engines/data/federalTax.d.ts.map +0 -1
  18. package/dist/engines/data/federalTax.js +0 -111
  19. package/dist/engines/data/federalTax.js.map +0 -1
  20. package/dist/engines/data/irs2026.d.ts +0 -30
  21. package/dist/engines/data/irs2026.d.ts.map +0 -1
  22. package/dist/engines/data/irs2026.js +0 -30
  23. package/dist/engines/data/irs2026.js.map +0 -1
  24. package/dist/engines/data/ssa.d.ts +0 -39
  25. package/dist/engines/data/ssa.d.ts.map +0 -1
  26. package/dist/engines/data/ssa.js +0 -55
  27. package/dist/engines/data/ssa.js.map +0 -1
  28. package/dist/engines/mortgage.d.ts +0 -70
  29. package/dist/engines/mortgage.d.ts.map +0 -1
  30. package/dist/engines/mortgage.js +0 -60
  31. package/dist/engines/mortgage.js.map +0 -1
  32. package/dist/engines/paycheck.d.ts +0 -93
  33. package/dist/engines/paycheck.d.ts.map +0 -1
  34. package/dist/engines/paycheck.js +0 -113
  35. package/dist/engines/paycheck.js.map +0 -1
  36. package/dist/engines/retirement401k.d.ts +0 -109
  37. package/dist/engines/retirement401k.d.ts.map +0 -1
  38. package/dist/engines/retirement401k.js +0 -130
  39. package/dist/engines/retirement401k.js.map +0 -1
  40. package/dist/engines/socialSecurity.d.ts +0 -63
  41. package/dist/engines/socialSecurity.d.ts.map +0 -1
  42. package/dist/engines/socialSecurity.js +0 -139
  43. package/dist/engines/socialSecurity.js.map +0 -1
  44. package/dist/envelope.d.ts +0 -76
  45. package/dist/envelope.d.ts.map +0 -1
  46. package/dist/envelope.js +0 -34
  47. package/dist/envelope.js.map +0 -1
  48. package/dist/shared/bounds.d.ts +0 -83
  49. package/dist/shared/bounds.d.ts.map +0 -1
  50. package/dist/shared/bounds.js +0 -121
  51. package/dist/shared/bounds.js.map +0 -1
  52. package/dist/tools/compoundInterest.d.ts +0 -48
  53. package/dist/tools/compoundInterest.d.ts.map +0 -1
  54. package/dist/tools/compoundInterest.js +0 -107
  55. package/dist/tools/compoundInterest.js.map +0 -1
  56. package/dist/tools/mortgage.d.ts +0 -51
  57. package/dist/tools/mortgage.d.ts.map +0 -1
  58. package/dist/tools/mortgage.js +0 -112
  59. package/dist/tools/mortgage.js.map +0 -1
  60. package/dist/tools/paycheck.d.ts +0 -54
  61. package/dist/tools/paycheck.d.ts.map +0 -1
  62. package/dist/tools/paycheck.js +0 -122
  63. package/dist/tools/paycheck.js.map +0 -1
  64. package/dist/tools/retirement401k.d.ts +0 -85
  65. package/dist/tools/retirement401k.d.ts.map +0 -1
  66. package/dist/tools/retirement401k.js +0 -141
  67. package/dist/tools/retirement401k.js.map +0 -1
  68. package/dist/tools/socialSecurity.d.ts +0 -51
  69. package/dist/tools/socialSecurity.d.ts.map +0 -1
  70. package/dist/tools/socialSecurity.js +0 -117
  71. package/dist/tools/socialSecurity.js.map +0 -1
  72. package/dist/util/zod-to-json-schema.d.ts +0 -28
  73. package/dist/util/zod-to-json-schema.d.ts.map +0 -1
  74. package/dist/util/zod-to-json-schema.js +0 -98
  75. package/dist/util/zod-to-json-schema.js.map +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Markco Labs LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,263 +1,186 @@
1
1
  # @markcolabs/mcp
2
2
 
3
- Model Context Protocol (MCP) server for **digitalcalculator.info** financial calculators.
4
-
5
- **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.
6
-
7
- Locks in the contract from **ADR-0039** (MCP Tool Contract & Calc-Engine Lift), reconciled per **ADR-0041** (post-deploy audit decisions).
3
+ > A free, MIT-licensed Model Context Protocol (MCP) server exposing 9
4
+ > deterministic financial calculator tools for AI agents — mortgage payment,
5
+ > compound interest, 401(k) projection, Social Security benefit, paycheck
6
+ > net pay, IRA contribution limit, Roth conversion tax impact, RMD
7
+ > distribution amount, and HSA contribution limit. Powered by the same
8
+ > engines that run the calculators at
9
+ > [www.digitalcalculator.info](https://www.digitalcalculator.info), parity-tested
10
+ > on every release. Hosted REST companion at
11
+ > [mcp.digitalcalculator.info/mcp](https://mcp.digitalcalculator.info/mcp);
12
+ > self-hostable over MCP stdio with `npx`.
13
+
14
+ **Status**: v0.3.0 (Sprint 141 Wave 1A + 1B). Adds 4 new retirement-cluster
15
+ tools (`dc.calculator.ira.contributionLimit`,
16
+ `dc.calculator.rothConversion.taxImpact`, `dc.calculator.rmd.distributionAmount`,
17
+ `dc.calculator.hsa.contributionLimit`), taking tool coverage 5 → 9.
18
+ See [CHANGELOG.md](./CHANGELOG.md).
19
+
20
+ Contract: **ADR-0039** (Tool Contract), reconciled per **ADR-0041**
21
+ (post-deploy audit decisions).
8
22
 
9
23
  ---
10
24
 
11
- ## What ships in v0.2.0
12
-
13
- | Tool | Purpose |
14
- |---|---|
15
- | `dc.calculator.mortgage.monthlyPayment` | Monthly principal & interest, total interest, total paid for a fixed-rate mortgage. |
16
- | `dc.calculator.compoundInterest.futureValue` | Future value of a principal with optional monthly contributions, at a chosen compounding frequency. |
17
- | `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). |
18
- | `dc.calculator.socialSecurity.estimatedBenefit` | SSA bend-point PIA estimate with early-claim reduction, delayed-credit math, and lifetime projection. |
19
- | `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). |
20
-
21
- | Resource | Purpose |
22
- |---|---|
23
- | `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
24
-
25
- Every tool response carries the `ToolResult<T>` envelope:
26
-
27
- ```jsonc
28
- {
29
- "result": { /* tool-specific structured payload */ },
30
- "disclaimer": "Estimates only — for educational purposes...",
31
- "methodology": {
32
- "url": "https://www.digitalcalculator.info/mortgage-calculator/",
33
- "version": "2026-05-09"
34
- },
35
- "calculatedAt": "2026-05-09T18:32:11.123Z",
36
- "engineVersion": "0.1.0"
37
- }
38
- ```
39
-
40
- Failures funnel through the `ToolError` shape (never thrown to the transport):
25
+ ## Install
41
26
 
42
- ```jsonc
43
- {
44
- "error": {
45
- "code": "INPUT_VALIDATION",
46
- "message": "Number must be greater than or equal to 0",
47
- "field": "principal",
48
- "retriable": false
49
- }
50
- }
27
+ ```bash
28
+ npm install -g @markcolabs/mcp
51
29
  ```
52
30
 
53
- Code namespaces: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT` (only `RATE_LIMIT` is retriable).
54
-
55
- ---
56
-
57
- ## Local install + test
31
+ Or run without installing:
58
32
 
59
33
  ```bash
60
- cd packages/mcp
61
- npm install
62
- npm test # run parity + envelope tests
63
- npm run build # compile TypeScript to dist/
64
- npm start # boot MCP server over stdio
34
+ npx @markcolabs/mcp
65
35
  ```
66
36
 
67
- 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.
68
-
69
- ---
37
+ The package ships a `digitalcalculator-mcp` binary that speaks MCP over stdio.
70
38
 
71
- ## Connecting from a local MCP client
39
+ ## Quickstart Claude Desktop
72
40
 
73
- 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:
41
+ Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
42
+ Windows: `%APPDATA%\Claude\`):
74
43
 
75
- ```jsonc
44
+ ```json
76
45
  {
77
46
  "mcpServers": {
78
47
  "digitalcalculator": {
79
48
  "command": "node",
80
- "args": ["/absolute/path/to/packages/mcp/dist/index.js"]
49
+ "args": ["/absolute/path/to/global/node_modules/@markcolabs/mcp/dist/index.js"]
81
50
  }
82
51
  }
83
52
  }
84
53
  ```
85
54
 
86
- The server emits a single startup line on stderr and then speaks JSON-RPC over stdio per the MCP spec.
55
+ Restart Claude Desktop. In a new conversation, ask "what MCP tools do you
56
+ have access to?" — Claude should list the 9 `dc.calculator.*` tools.
87
57
 
88
- ---
58
+ Full setup instructions (incl. MCP Inspector, agentic CLIs, HTTP REST):
59
+ [www.digitalcalculator.info/mcp/quickstart/](https://www.digitalcalculator.info/mcp/quickstart/).
89
60
 
90
- ## Tool input/output sketches
61
+ ## Tools (v0.3.0)
91
62
 
92
- ### `dc.calculator.retirement401k.projection`
63
+ | Tool | Input (summary) | Returns (summary) |
64
+ |---|---|---|
65
+ | `dc.calculator.mortgage.monthlyPayment` | `principal`, `annualRatePercent`, `termYears` | Monthly P&I payment, total interest, total paid |
66
+ | `dc.calculator.compoundInterest.futureValue` | `principal`, `annualRatePercent`, `years`, `compoundingFrequency`, optional `monthlyContribution` | Future value, total contributions, interest earned |
67
+ | `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 |
68
+ | `dc.calculator.socialSecurity.estimatedBenefit` | `birthYear`, `currentEarnings`, `claimAge`, optional `yearsWorked`, `lifeExpectancy` | Monthly benefit at FRA, adjusted for claim age, lifetime projection, FRA age |
69
+ | `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 |
70
+ | `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 |
71
+ | `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) |
72
+ | `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) |
73
+ | `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 |
93
74
 
94
- ```jsonc
95
- // Input
96
- {
97
- "currentBalance": 25000,
98
- "annualSalary": 80000,
99
- "contributionPercent": 6, // % of salary
100
- "employerMatchPercent": 50, // 50% match...
101
- "employerMatchLimitPercent": 6, // ...up to 6% of salary
102
- "annualSalaryGrowthPercent": 3, // 3%/yr; 0 mirrors site engine
103
- "annualReturnPercent": 7,
104
- "currentAge": 35,
105
- "retirementAge": 65,
106
- "catchUpEnabled": true // optional, default true
107
- }
75
+ | Resource | Purpose |
76
+ |---|---|
77
+ | `dc://disclaimers/ymyl` | Canonical YMYL disclaimer string returned in every tool response. |
78
+
79
+ Every response carries the same envelope:
108
80
 
109
- // Result payload
81
+ ```json
110
82
  {
111
- "futureBalance": 873421.55,
112
- "totalContributions": 228450.12,
113
- "employerContribTotal": 114225.06,
114
- "growthEarned": 530746.37,
115
- "yearByYear": [
116
- { "year": 1, "age": 36, "employeeContribution": 4944.00,
117
- "employerMatch": 2472.00, "growth": 1750.00,
118
- "endingBalance": 34166.00 }
119
- /* ...30 rows */
120
- ]
83
+ "result": { /* tool-specific structured object */ },
84
+ "disclaimer": "Estimates only — for educational purposes...",
85
+ "methodology": {
86
+ "url": "https://www.digitalcalculator.info/<calculator>/",
87
+ "version": "YYYY-MM-DD"
88
+ },
89
+ "calculatedAt": "ISO-8601 UTC",
90
+ "engineVersion": "SemVer of the engine that produced the result"
121
91
  }
122
92
  ```
123
93
 
124
- ### `dc.calculator.socialSecurity.estimatedBenefit`
125
-
126
- ```jsonc
127
- // Input
128
- {
129
- "birthYear": 1965,
130
- "currentEarnings": 80000,
131
- "claimAge": 67, // 62..70
132
- "yearsWorked": 35, // optional, default 35
133
- "lifeExpectancy": 85 // optional, default 85
134
- }
94
+ Failures use a single-envelope `ToolError` (HTTP 400 / 429 / 500):
135
95
 
136
- // Result payload
137
- {
138
- "monthlyBenefitAtFRA": 2104.50,
139
- "adjustedMonthlyBenefit": 2104.50,
140
- "lifetimeBenefitProjection": 454572,
141
- "fraAge": 67.0,
142
- "eligibilityYear": 2027,
143
- "bendPointsEstimated": true
144
- }
96
+ ```json
97
+ { "error": { "code": "INPUT_VALIDATION", "message": "...", "field": "...", "retriable": false } }
145
98
  ```
146
99
 
147
- For an authoritative estimate based on actual 35-year earnings history,
148
- direct callers to <https://www.ssa.gov/myaccount/>.
100
+ Error codes: `INPUT_VALIDATION`, `BUSINESS_RULE`, `INTERNAL`, `RATE_LIMIT`
101
+ (only `RATE_LIMIT` is retriable).
149
102
 
150
- ### `dc.calculator.paycheck.netPay`
103
+ Full input schemas, output payload shapes, and error codes:
104
+ [www.digitalcalculator.info/mcp/api-reference/](https://www.digitalcalculator.info/mcp/api-reference/).
151
105
 
152
- ```jsonc
153
- // Input
154
- {
155
- "grossAnnualSalary": 80000,
156
- "payFrequency": "biweekly", // weekly | biweekly | semimonthly | monthly | quarterly | annual
157
- "federalFilingStatus": "single", // single | married | marriedSeparate | headOfHousehold
158
- "state": "CA",
159
- "dependents": 0,
160
- "preTaxDeductionsAnnual": 4800,
161
- "postTaxDeductionsAnnual": 0
162
- }
106
+ ## Hosted endpoint (no install needed)
163
107
 
164
- // Result payload
165
- {
166
- "grossPerPaycheck": 3076.92,
167
- "federalTax": 320.45,
168
- "ficaTax": 215.61,
169
- "stateTax": 116.91,
170
- "netPay": 2240.43,
171
- "payPeriodsPerYear": 26,
172
- "federalTaxAnnual": 8331.70,
173
- "ficaTaxAnnual": 5605.86,
174
- "stateTaxAnnual": 3039.66,
175
- "netPayAnnual": 58282.78,
176
- "noStateIncomeTax": false
177
- }
178
- ```
108
+ If you don't have an MCP client, POST JSON to the hosted REST companion:
179
109
 
180
- > v0.2.0 limitation: state withholding is `$0` for the 9 no-income-tax states
181
- > (AK, FL, NV, NH, SD, TN, TX, WA, WY) and a flat 5% estimate over taxable
182
- > income elsewhere. Per-state brackets, SDI, and local taxes are NOT modeled.
183
- > See the methodology link for the full site calculator.
110
+ ```bash
111
+ curl -X POST https://mcp.digitalcalculator.info/mcp \
112
+ -H 'Content-Type: application/json' \
113
+ -d '{
114
+ "tool": "dc.calculator.mortgage.monthlyPayment",
115
+ "input": { "principal": 300000, "annualRatePercent": 6.5, "termYears": 30 }
116
+ }'
117
+ ```
184
118
 
185
- ---
119
+ Returns the same envelope shape as the MCP wire protocol. Rate-limited to
120
+ 100 req / 5 min per IP (WAFv2). See [LICENSE-API.md](./LICENSE-API.md) for the
121
+ hosted-API terms.
186
122
 
187
- ## Architecture
123
+ ## Licensing
188
124
 
189
- ```
190
- packages/mcp/
191
- ├── package.json # private:false (v0.1.0)
192
- ├── CHANGELOG.md
193
- ├── tsconfig.json
194
- ├── vitest.config.ts
195
- ├── src/
196
- │ ├── index.ts # MCP server entry; tools/list, tools/call, resources/list
197
- │ ├── envelope.ts # ToolResult<T>, ToolError types + helpers
198
- │ ├── disclaimers/ymyl.ts # Canonical YMYL disclaimer (single source of truth)
199
- │ ├── shared/bounds.ts # Numeric bounds shared by Zod schemas + engines
200
- │ ├── engines/
201
- │ │ ├── mortgage.ts # Pure math + ENGINE_VERSION
202
- │ │ ├── compoundInterest.ts # Pure math + ENGINE_VERSION
203
- │ │ ├── retirement401k.ts # Pure math + ENGINE_VERSION (S136)
204
- │ │ ├── socialSecurity.ts # Pure math + ENGINE_VERSION (S136)
205
- │ │ ├── paycheck.ts # Pure math + ENGINE_VERSION (S136)
206
- │ │ └── data/ # Self-contained data subset (S136)
207
- │ │ ├── ssa.ts # SSA bend points + wage base
208
- │ │ ├── irs2026.ts # IRS 2026 401(k) limits
209
- │ │ └── federalTax.ts # 2026 federal brackets/standard ded/FICA
210
- │ ├── tools/
211
- │ │ ├── mortgage.ts
212
- │ │ ├── compoundInterest.ts
213
- │ │ ├── retirement401k.ts # (S136)
214
- │ │ ├── socialSecurity.ts # (S136)
215
- │ │ └── paycheck.ts # (S136)
216
- │ └── util/zod-to-json-schema.ts
217
- └── test/
218
- ├── envelope.test.ts # Envelope contract tests
219
- └── parity/
220
- ├── mortgage.test.ts # parity + envelope checks
221
- ├── compoundInterest.test.ts # parity + envelope checks
222
- ├── retirement401k.test.ts # 5 parity + envelope checks (S136)
223
- ├── socialSecurity.test.ts # 5 parity + envelope checks (S136)
224
- └── paycheck.test.ts # 5 parity + envelope checks (S136)
225
- ```
125
+ Two distinct surfaces, two distinct license documents:
226
126
 
227
- 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.
127
+ - **Package source** (this npm package + the GitHub repo): [MIT LICENSE](./LICENSE).
128
+ Self-host, modify, redistribute, embed in commercial products — all permitted.
129
+ - **Hosted API** at `mcp.digitalcalculator.info/mcp`: governed by
130
+ [LICENSE-API.md](./LICENSE-API.md) (acceptable use, rate limits, no-warranty,
131
+ contact). These terms apply only when you call the hosted endpoint; they do
132
+ NOT bind self-hosted use of the MIT source.
228
133
 
229
- ---
134
+ If you self-host the MIT source, only the [LICENSE](./LICENSE) applies. If you
135
+ use the hosted endpoint, both apply (MIT for what you read; LICENSE-API for how
136
+ you call the hosted host).
230
137
 
231
- ## Versioning
138
+ ## Local development
232
139
 
233
- - **`@markcolabs/mcp` SemVer**: package version. New tool = minor; renamed tool = major.
234
- - **Per-engine `ENGINE_VERSION`**: independent SemVer per engine module. Bumps when math changes.
235
- - **`methodology.version`**: ISO date of the methodology document's `last-modified` field (per ADR-0035).
140
+ ```bash
141
+ cd packages/mcp
142
+ npm install
143
+ npm test # parity + envelope tests (vitest)
144
+ npm run build # compile TypeScript to dist/
145
+ npm start # boot MCP server over stdio
146
+ ```
236
147
 
237
- `engineVersion` and `methodology.version` are **independent** callers should not assume they move in lockstep.
148
+ Vitest runs `test/parity/*.test.ts` (per-tool parity vs. site source) and
149
+ `test/envelope.test.ts` (envelope contract). Parity tests must pass before any
150
+ engine change is shipped.
238
151
 
239
- ---
152
+ ## Versioning
240
153
 
241
- ## What's next (post-S136)
154
+ | Bump | Trigger | Example |
155
+ |---|---|---|
156
+ | Major package | Tool rename, removed field, breaking envelope change | v0.1.0 → v0.2.0 (tool renames) |
157
+ | 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) |
158
+ | Patch package | Bug fixes, metadata corrections | v0.2.0 → v0.2.1 (LICENSE, README, optional dependents, dead-link audit) |
159
+ | `engineVersion` | Math changes only | 5 prior engines at `1.0.0`; new IRA + Roth + RMD + HSA engines start at `1.0.0` |
160
+ | `methodology.version` | Source methodology document materially updated | ISO date of the canonical methodology page's `last-modified` |
242
161
 
243
- 1. Methodology resources `dc://methodologies/<calculator>` populated from the
244
- `.md` companions (ADR-0033).
245
- 2. The `plan-retirement` prompt template (O5-KR2).
246
- 3. Per-state withholding tables for the paycheck tool (replace v0.2.0's flat
247
- 5% estimate with bracket-accurate state math).
162
+ `engineVersion` and `methodology.version` are independent callers should not
163
+ assume they move in lockstep. See [CHANGELOG.md](./CHANGELOG.md) for the full
164
+ version history.
248
165
 
249
- ---
166
+ ## Links
250
167
 
251
- ## References
168
+ - [Quickstart](https://www.digitalcalculator.info/mcp/quickstart/) — install + first call in under 5 minutes
169
+ - [API Reference](https://www.digitalcalculator.info/mcp/api-reference/) — full schemas, output shapes, error codes
170
+ - [FAQ](https://www.digitalcalculator.info/mcp/faq/) — accuracy, YMYL posture, rate limits, support, change policy
171
+ - [GitHub repo](https://github.com/mark57-ux/digitalcalculator/tree/main/packages/mcp) — open issues, contribute
172
+ - [CHANGELOG](https://github.com/mark57-ux/digitalcalculator/blob/main/packages/mcp/CHANGELOG.md)
173
+ - [ADR-0039 — MCP Tool Contract](https://github.com/mark57-ux/digitalcalculator/blob/main/docs/Claude/Architecture/ADR/ADR-0039-mcp-tool-contract.md)
174
+ - [ADR-0041 — v1 Contract Reconciliation](https://github.com/mark57-ux/digitalcalculator/blob/main/docs/Claude/Architecture/ADR/ADR-0041-mcp-v1-contract-reconciliation.md)
252
175
 
253
- - ADR-0039 — MCP Tool Contract & Calc-Engine Lift
254
- - ADR-0033 — Markdown Companion Strategy (powers `methodology.url`)
255
- - ADR-0035 — JSON-LD `dateModified` Propagation (powers `methodology.version`)
256
- - ADR-0038 — Centralized Shared-Data Architecture (regulatory constants source)
257
- - P12 OKR O5 — AI-Native Distribution
176
+ ## Support
258
177
 
259
- ---
178
+ Open an issue at
179
+ [github.com/mark57-ux/digitalcalculator/issues](https://github.com/mark57-ux/digitalcalculator/issues).
180
+ Best-effort triage, no SLA. Include tool name, input that reproduces, expected
181
+ vs. actual output, and the `engineVersion` from the response envelope.
260
182
 
261
183
  ## License
262
184
 
263
- MIT. Markcolabs LLC.
185
+ MIT for the package source ([LICENSE](./LICENSE)). Hosted API terms in
186
+ [LICENSE-API.md](./LICENSE-API.md). Markco Labs LLC.
package/dist/index.d.ts CHANGED
@@ -1,30 +1,16 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * @markcolabs/mcp — MCP server entrypoint.
3
+ * @markcolabs/mcp v0.4.0 stdio↔HTTPS shim.
4
4
  *
5
- * v0.2.0 (per ADR-0039 + ADR-0041 reconciliation). Registers:
6
- * - 5 tools:
7
- * dc.calculator.mortgage.monthlyPayment (S135 Item 5)
8
- * dc.calculator.compoundInterest.futureValue (S135 Item 5)
9
- * dc.calculator.retirement401k.projection (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
10
- * dc.calculator.socialSecurity.estimatedBenefit (S136 Item 3, renamed v0.2.0 per ADR-0041 D2)
11
- * dc.calculator.paycheck.netPay (S136 Item 3)
12
- * - 1 resource: dc://disclaimers/ymyl (canonical YMYL disclaimer)
5
+ * Proxies MCP JSON-RPC messages from stdin to the hosted MCP server at
6
+ * mcp.digitalcalculator.info/mcp and writes responses back to stdout.
13
7
  *
14
- * Transport: stdio (default for local MCP clients).
8
+ * Per ADR-0044a (ACCEPTED 2026-05-28): engine source lives in the private
9
+ * monorepo at infra/mcp/. This shim contains no calculation logic — it is
10
+ * a thin transport adapter only. MIT-licensed.
15
11
  *
16
- * S136 hits O5-KR1 5-tool target. Post-S136: methodology resources
17
- * (dc://methodologies/*) and the `plan-retirement` prompt template (O5-KR2).
12
+ * Claude Desktop config:
13
+ * { "mcpServers": { "digitalcalculator": { "command": "npx", "args": ["-y", "@markcolabs/mcp"] } } }
18
14
  */
19
- export { execute as executeMortgageTool } from "./tools/mortgage.js";
20
- export { execute as executeCompoundInterestTool } from "./tools/compoundInterest.js";
21
- export { execute as executeRetirement401kTool } from "./tools/retirement401k.js";
22
- export { execute as executeSocialSecurityTool } from "./tools/socialSecurity.js";
23
- export { execute as executePaycheckTool } from "./tools/paycheck.js";
24
- export * as mortgageEngine from "./engines/mortgage.js";
25
- export * as compoundInterestEngine from "./engines/compoundInterest.js";
26
- export * as retirement401kEngine from "./engines/retirement401k.js";
27
- export * as socialSecurityEngine from "./engines/socialSecurity.js";
28
- export * as paycheckEngine from "./engines/paycheck.js";
29
- export * from "./envelope.js";
15
+ export {};
30
16
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AAwBH,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,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,cAAc,eAAe,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}