# 💰 Wealth Engine MCP

> An [MCP](https://modelcontextprotocol.io) server that helps you **make more money and keep more of it** — a complete personal-finance and business-economics toolkit your AI assistant can use to give you real, math-backed answers.

No API keys. No accounts. No network calls. Every answer is computed locally from battle-tested financial formulas, so it works the moment you install it and produces the same numbers every time.

The honest truth: software can't literally print money. But the decisions these tools inform — charging the right freelance rate, pricing a product at the profit-maximizing point, killing the avalanche of interest on your debt, picking the investment with the best risk-adjusted return — are worth a *lot* of money over a lifetime. That's where the leverage is.

---

## Why this exists

Most "money" advice is vibes. This is arithmetic. Each tool implements the actual formula a financial analyst would use, returns a transparent breakdown (not just a single number), and is covered by tests that check it against known-correct values.

- ✅ **11 financial tools**, each a real engine
- ✅ **Zero setup** — no keys, no DB, runs over stdio
- ✅ **58 passing tests** validating the math against closed-form results
- ✅ **Strict TypeScript**, structured JSON output for both humans and agents
- ✅ Works in **Cursor**, **Claude Desktop**, and any MCP client

---

## The tools

| Tool | What it answers |
| --- | --- |
| `compound_growth` | "If I invest $X and add $Y/month at Z%, what will it become?" (with inflation-adjusted real value) |
| `loan_amortization` | "What's my mortgage payment, and how much do extra payments save me?" |
| `debt_payoff` | "What's the fastest, cheapest way out of my debts — avalanche or snowball?" |
| `fire_calculator` | "How big a portfolio do I need to retire, and how many years until I'm financially independent?" |
| `freelance_rate` | "What hourly rate must I actually charge to hit my income goal?" |
| `price_optimizer` | "What price maximizes my profit, given how demand responds?" |
| `roi_compare` | "Which opportunity creates the most value?" (ROI, payback, NPV, IRR) |
| `tax_estimate` | "What's my income tax, effective rate, and marginal rate?" |
| `budget_analyzer` | "Where is my money leaking vs the 50/30/20 rule?" |
| `subscription_audit` | "How much can I recover by cutting low-value subscriptions?" |
| `side_hustle_ranker` | "Which side hustle is worth my time, risk-adjusted?" |

---

## Install

### 1. Build it

```bash
npm install
npm run build
```

This produces `dist/index.js`, the runnable MCP server.

### 2. Register it with your MCP client

#### Cursor

Create or edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global use):

```json
{
  "mcpServers": {
    "wealth-engine": {
      "command": "node",
      "args": ["C:/Users/jejej/OneDrive/Escritorio/github_projects/mcp/dist/index.js"]
    }
  }
}
```

Then open Cursor → Settings → MCP and confirm **wealth-engine** shows 11 tools. Ask the agent something like *"Use the freelance rate tool to tell me what to charge for a $150k target."*

#### Claude Desktop

Edit `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wealth-engine": {
      "command": "node",
      "args": ["C:/Users/jejej/OneDrive/Escritorio/github_projects/mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. The tools appear under the 🔌 menu.

> **Tip:** During development you can skip the build step and run the TypeScript directly with `"command": "npx", "args": ["tsx", "/abs/path/src/index.ts"]`.

---

## Tool reference & examples

Every tool accepts a JSON object and returns both a human-readable text block and machine-readable `structuredContent`. Below are representative inputs and the headline outputs.

### `compound_growth`

```jsonc
{
  "principal": 10000,
  "contribution": 500,
  "annualRatePct": 7,
  "years": 30,
  "periodsPerYear": 12,
  "annualInflationPct": 2.5
}
```

Returns `futureValue`, `totalContributed`, `totalInterest`, `realFutureValue` (today's purchasing power), `growthMultiple`, and a year-by-year `schedule`.

### `loan_amortization`

```jsonc
{ "amount": 400000, "annualRatePct": 6.5, "years": 30, "extraPayment": 300 }
```

Returns the `periodicPayment`, `totalInterest`, `payoffYears`, `interestSavedVsNoExtra`, and a full amortization `schedule`.

### `debt_payoff`

```jsonc
{
  "debts": [
    { "name": "Visa", "balance": 6000, "annualRatePct": 24.99, "minPayment": 150 },
    { "name": "Car",  "balance": 12000, "annualRatePct": 6.5,  "minPayment": 280 }
  ],
  "monthlyBudget": 900,
  "strategy": "compare"
}
```

`compare` (default) runs **avalanche** and **snowball**, reports `monthsToDebtFree` and `totalInterestPaid` for each, and tells you which is cheaper and by how much.

### `fire_calculator`

```jsonc
{ "annualIncome": 120000, "annualExpenses": 48000, "currentInvestments": 80000, "realReturnPct": 5 }
```

Returns your `fireNumber`, `savingsRate`, `yearsToFire`, plus `leanFireNumber` and `fatFireNumber`.

### `freelance_rate`

```jsonc
{
  "targetAnnualIncome": 150000,
  "annualBusinessExpenses": 12000,
  "taxRatePct": 30,
  "workingWeeksPerYear": 46,
  "billableUtilization": 0.6
}
```

Returns the `hourlyRate` and `dayRate` you must charge, the `billableHoursPerYear`, and how that compares to the naive `salary / 2080` mistake (`vsNaiveSalaryRate`).

### `price_optimizer`

```jsonc
{
  "demandPoints": [
    { "price": 29, "quantity": 420 },
    { "price": 39, "quantity": 300 },
    { "price": 49, "quantity": 190 }
  ],
  "unitCost": 8,
  "fixedCost": 2000
}
```

Fits a linear demand curve, then returns the `optimalPrice` (profit-max), `revenueMaximizingPrice`, the fitted `demandModel` with R², and a transparent price `sweep`.

### `roi_compare`

```jsonc
{
  "investments": [
    { "name": "Rental",   "cashFlows": [-50000, 6000, 6000, 6000, 6000, 76000] },
    { "name": "Business", "cashFlows": [-50000, 0, 20000, 30000, 40000] }
  ],
  "discountRatePct": 8
}
```

Returns per-investment `roi`, `paybackPeriod`, `npv`, `irrPct`, and the winners `bestByNpv` / `bestByRoi` / `bestByIrr`.

### `tax_estimate`

```jsonc
{ "income": 95000, "deduction": 14600 }
```

Defaults to US 2024 single-filer federal brackets (override with your own `brackets` for any country/year). Returns `totalTax`, `afterTaxIncome`, `effectiveRatePct`, `marginalRatePct`, and the per-bracket breakdown.

### `budget_analyzer`

```jsonc
{
  "monthlyIncome": 6000,
  "categories": [
    { "name": "Rent", "amount": 2200, "type": "needs" },
    { "name": "Dining", "amount": 800, "type": "wants" },
    { "name": "Index funds", "amount": 1200, "type": "savings" }
  ]
}
```

Compares your split to 50/30/20, finds `unallocated` money and overspending `gaps`, and returns concrete `recommendations`.

### `subscription_audit`

```jsonc
{
  "subscriptions": [
    { "name": "Streaming A", "amount": 15.99, "cycle": "monthly", "usesPerMonth": 12, "valueRating": 4 },
    { "name": "Gym",         "amount": 60,    "cycle": "monthly", "usesPerMonth": 1,  "valueRating": 2 }
  ]
}
```

Annualizes every line, computes `costPerUse`, flags each as `keep` / `review` / `cut`, and totals `potentialAnnualSavings`.

### `side_hustle_ranker`

```jsonc
{
  "hustles": [
    { "name": "Consulting", "monthlyRevenue": 4000, "hoursPerMonth": 30, "successProbability": 0.9 },
    { "name": "Print shop", "monthlyRevenue": 2500, "monthlyCost": 600, "hoursPerMonth": 60, "startupCost": 5000, "rampMonths": 4, "successProbability": 0.6 }
  ]
}
```

Ranks by **risk-adjusted effective hourly value**, with `breakEvenMonths` and `expectedYearOneProfit` for each.

---

## Development

```bash
npm run dev        # run the server from TypeScript (tsx)
npm run typecheck  # strict type checking, no emit
npm test           # run the full vitest suite
npm run test:watch # watch mode
npm run build      # compile to dist/
```

### Project layout

```
src/
  index.ts            # stdio entry point (the MCP process)
  server.ts           # registers all 11 tools with Zod schemas
  finance/            # pure, dependency-free financial engines
    compound.ts  loan.ts  debt.ts  fire.ts  freelance.ts
    pricing.ts   roi.ts   tax.ts   budget.ts  subscriptions.ts
    sideHustle.ts  money.ts
test/                 # one spec per engine + an end-to-end server test
```

The design rule: **all math lives in `src/finance/` as pure functions** with no MCP or I/O dependencies. The server is a thin adapter. That keeps the logic trivially testable and reusable.

---

## How the numbers are validated

The tests don't just check "it runs" — they assert against independently-derived values:

- **Compound growth** is checked against the closed-form annuity future-value formula.
- **Loan amortization** is checked against the standard mortgage payment (a $100k/6%/30yr loan → ~$599.55/mo, ~$115,838 total interest).
- **Tax** is checked bracket-by-bracket against hand-computed US 2024 figures.
- **IRR** is checked against known multi-period rates and the trivial `[-100, 110] → 10%` case.
- **Price optimization** is checked against the analytic optimum of a known linear demand curve.
- An **end-to-end test** spins up the server over an in-memory transport, lists the tools, and calls them through the real MCP protocol.

Run `npm test` to see all 58 pass.

---

## Disclaimer

This is an educational/decision-support tool, not financial, tax, investment, or legal advice. Tax brackets and assumptions are illustrative defaults — verify against current rules for your jurisdiction, and consult a qualified professional before making consequential decisions.

## License

MIT — see [LICENSE](./LICENSE).