# marketgenius.app

Professional stock market analysis and visualization tools for everyday investors and traders. Heatmaps re-invented!

## Markdown for Agents & Crawlers

Every page on marketgenius.app is available as clean Markdown via HTTP content
negotiation — no separate API, no scraping HTML. Send an `Accept: text/markdown`
request header to any URL and you get the agent-friendly Markdown rendering of
that exact page; omit it (or send `text/html`) for the normal web page.

- Works on **every** route — heatmaps, index pages, stock pages, calculators,
  validators, articles, everything.
- Includes the page's **JSON-LD structured data** (schema.org) inline, so
  agents get the same machine-readable metadata the HTML carries — breadcrumbs,
  FAQ, WebApplication/WebSite entities, etc.
- Same URLs, same query params (`?lang=`, calculator params, etc.) — only the
  `Accept` header changes.
- Built for LLM agents and crawlers: token-efficient, structured, no UI chrome.

Example: `curl -H "Accept: text/markdown" https://marketgenius.app/stocks/indices/nasdaq-100`

## Dynamic Metric Heatmaps - Core Feature

Interactive heatmaps where tile size is driven by any supported metric, not just market cap.

### URL Pattern

`/heatmaps/{category}/{scope}/{metric}?lang={lang}`

- `{category}` — see Supported Categories
- `{scope}` — an index or portfolio slug; must belong to `{category}` (e.g. `indices/nasdaq-100`, `portfolios/warren-buffett`)
- `{metric}` — see Supported Metrics
- `{lang}` — optional: `es` (Spanish), `nl` (Dutch). Omit for English (default).

Example: `/heatmaps/indices/nasdaq-100/percent-change?lang=es`

### Supported Categories

| Slug | Description |
|------|-------------|
| indices | Stock market indices |
| portfolios | Super investor portfolios |

### Supported Indices

| Slug | Moniker | Full Name | Country |
|------|---------|-----------|---------|
| aex | AEX | AEX-Index | NL |
| amx | AMX | AMX-Index | NL |
| ams-next-20 | AMS Next 20 | AMS Next 20 | NL |
| bel-20 | BEL 20 | BEL 20 | BE |
| bel-mid | BEL Mid | BEL Mid | BE |
| ibex-35 | IBEX 35 | IBEX 35 | ES |
| ibex-medium-cap | IBEX Medium Cap | IBEX Medium Cap | ES |
| ibex-small-cap | IBEX Small Cap | IBEX Small Cap | ES |
| dow-30 | Dow 30 | Dow Jones Industrial Average | US |
| nasdaq-100 | NASDAQ 100 | NASDAQ-100 | US |
| sp-500 | S&P 500 | S&P 500 | US |
| sp-bmv-inmex | BMV INMEX | S&P/BMV Índice México | MX |
| sp-bmv-ipc | BMV IPC | S&P/BMV Índice de Precios y Cotizaciones | MX |
| sp-bmv-ipc-compmx | BMV CompMx | S&P/BMV IPC CompMx | MX |
| psi | PSI | PSI | PT |
| psi-all-share | PSI All-Share | PSI All-Share | PT |
| iseq-20 | ISEQ 20 | ISEQ 20 | IE |
| iseq-all-share | ISEQ All-Share | ISEQ All-Share | IE |
| cac-40 | CAC 40 | CAC 40 | FR |
| cac-next-20 | CAC Next 20 | CAC Next 20 | FR |
| sbf-120 | SBF 120 | SBF 120 | FR |
| smi | SMI | SMI | CH |
| smi-mid | SMI MID | SMI MID | CH |
| wig-20 | WIG20 | WIG20 | PL |
| mwig-40 | mWIG40 | mWIG40 | PL |
| dax | DAX | DAX | DE |
| mdax | MDAX | MDAX | DE |
| px | PX | PX | CZ |
| ftse-mib | FTSE MIB | FTSE MIB | IT |
| ftse-italia-mid-cap | FTSE Italia Mid Cap | FTSE Italia Mid Cap | IT |
| ftse-100 | FTSE 100 | FTSE 100 | GB |
| ftse-250 | FTSE 250 | FTSE 250 | GB |

### Supported Portfolios

| Slug | Moniker | Full Name | Country |
|------|---------|-----------|---------|
| bill-ackman | Bill Ackman | Pershing Square Capital Management | US |
| bill-melinda | Bill & Melinda | Bill & Melinda Gates Foundation Trust | US |
| carl-icahn | Carl Icahn | Icahn Enterprises | US |
| cathie-wood | Cathie Wood | ARK Investment Management | US |
| michael-burry | Michael Burry | Scion Asset Management | US |
| warren-buffett | Warren Buffett | Berkshire Hathaway | US |

### Supported Metrics

| Slug | Name |
|------|------|
| 52w-high-drawdown | 52W High (Drawdown) |
| 52w-low-gain | 52W Low (Gain) |
| beta | Beta |
| current-ratio-mrq | Current Ratio (MRQ) |
| debt-to-equity-mrq | Debt-to-Equity (MRQ) |
| dividend-yield-forward | Dividend Yield Forward |
| earnings-growth-yoy | Earnings Growth (YOY) |
| enterprise-value-to-ebitda | EV/EBITDA |
| eps-yield | EPS Yield |
| market-cap | Market Cap |
| payout-ratio | Payout Ratio |
| pe-ratio-forward | P/E Ratio Forward |
| pe-ratio-trailing | P/E Ratio Trailing |
| peg-ratio | PEG Ratio |
| percent-change | Percent Change |
| percentage-short-interest | Short Interest |
| price-to-book-mrq | Price-to-Book (MRQ) |
| price-to-sales-ttm | Price-to-Sales (TTM) |
| profit-margin-gross-mrq | Profit Margin Gross (MRQ) |
| profit-margin-net-ttm | Profit Margin Net (TTM) |
| return-on-equity-ttm | Return on Equity (TTM) |
| revenue-growth-mrq | Revenue Growth (MRQ) |

### Time Range Controls

Flexible time period analysis: 1D, 5D, 1M, 3M, 6M, YTD, 1Y, 5Y, MAX.

### Multilingual Support

All UI, metric names, and explanations are translated. URLs stay consistent across languages — only the `?lang=` query parameter changes.

## Index Pages — Constituents & Metric Rankings

Browsable, SSR-indexed pages for every supported index: the full constituent
list plus per-metric rankings. Complements the heatmaps (a visualization)
with crawlable, sortable tabular data. Uses the same index and metric
vocabulary as the heatmaps — see Supported Indices and Supported Metrics above.

### URL Patterns

| URL | Page |
|-----|------|
| `/stocks/indices` | Directory of all indices, grouped by country, searchable |
| `/stocks/indices/{slug}` | Index overview: header, top-10 winners/losers today, full constituent list, sector breakdown, FAQ |
| `/stocks/indices/{slug}/metrics/{metric}` | Full constituent list ranked by `{metric}`, best first; client-sortable and searchable |

- `{slug}` — any index from Supported Indices (e.g. `nasdaq-100`, `ibex-35`)
- `{metric}` — any metric from Supported Metrics (e.g. `pe-ratio-forward`)
- `/stocks/indices/{slug}/metrics` (no metric) redirects to `.../metrics/percent-change` (the default ranking)
- One canonical URL per index×metric ranking

Example: `/stocks/indices/ibex-35/metrics/dividend-yield-forward?lang=es`

### Notes
- Only the `metrics` category is live; `sectors`, `industry-groups` and `industries` return 404 by design.
- Prices and percent-change update live.
- Multilingual via `?lang=es|nl` (omit for English), same as the heatmaps.

## Stock Code Validators - Professional Tools Suite

### Overview
Six specialized validators for global financial instrument identifiers, designed for investors, analysts, and financial professionals. Each validator provides instant validation, detailed structural breakdown, and automatic stock matching when available in our database.

### Supported Identifier Types
1. **CFI** (Classification of Financial Instruments) - `/tools/stock-code-validators/cfi`
2. **CUSIP** (Committee on Uniform Securities Identification Procedures) - `/tools/stock-code-validators/cusip`
3. **ISIN** (International Securities Identification Number) - `/tools/stock-code-validators/isin`
4. **LEI** (Legal Entity Identifier) - `/tools/stock-code-validators/lei`
5. **SEDOL** (Stock Exchange Daily Official List) - `/tools/stock-code-validators/sedol`
6. **WKN** (Wertpapierkennnummer) - `/tools/stock-code-validators/wkn`

### URL Structure & Pre-filled Validation
- Base pattern: `/tools/stock-code-validators/{type}`
- Pre-fill validation: Add `?code={identifier}` query parameter
- Example: `/tools/stock-code-validators/lei?code=HWUPKR0MPOU8FGXBT394`
- Benefit: Share specific validation results, deep-link from other tools, bookmark common lookups

### Unique Features

#### Visual Naming Convention Breakdown
Unlike basic validators that only show pass/fail, our validators educate users by:
- **Structural dissection**: Visual breakdown of each code segment
- **Color-coded components**: Each part of the identifier highlighted separately
- **Component explanations**: Clear descriptions of what each segment represents
- **Example** (LEI structure):
  - First 4 characters: LOU (Local Operating Unit) identifier - `HWUP`
  - Next 14 characters: Legal Entity identifier - `KR0MPOU8FGXBT3`
  - Last 2 characters: Check digits (MOD 97-10 algorithm) - `94`

#### Automatic Stock Matching
When a valid code is entered:
- Searches internal database for matching securities
- Displays company name, ticker, and relevant metadata
- Links to detailed stock profile pages
- Example: LEI `HWUPKR0MPOU8FGXBT394` → Apple (US) (AAPL)

#### Educational Explainers
Each validator includes:
- **What it is**: Clear definition of the identifier type
- **Character specifications**: Length, format requirements, allowed characters
- **Global vs regional**: Scope of usage (global, US-only, UK-only, etc.)
- **Issuing authority**: Who manages and assigns these codes
- **Common use cases**: When you'd encounter this identifier type

### Validation Feedback
Clear, actionable results:
- ✅ **Valid codes**: Green success message with entity details
- ❌ **Invalid codes**: Specific error explanation (wrong length, invalid characters, failed checksum)
- **Structural display**: Always shows the naming convention breakdown for educational context

### Technical Implementation Details
Each validator implements:
- Algorithm-specific checksum validation (Luhn, MOD 10, MOD 97-10, etc.)
- Format verification (alphanumeric patterns, position-specific rules)
- Real-time validation as user submits
- Database lookup for recognized securities

### Use Cases
- **Investors**: Verify identifiers before trades, look up company details
- **Analysts**: Quick validation during research, educational reference
- **Compliance officers**: Verify LEI codes for regulatory requirements
- **Traders**: Convert between identifier types, validate counterparty LEIs
- **Students/educators**: Learn about global financial identifier systems

## Investment Calculators - Free Planning Tools

### Overview
Free, interactive investment calculators at `/tools/calculators/`. Every
calculator is built around three principles: instant shareability, clear
visualizations, and plain-language explanations that build genuine
understanding rather than just producing a number.

### What Makes Our Calculators Different

#### Fully Shareable via Stateful URLs
Every calculator input is encoded directly in the URL as a query param, so any
configuration produces a stateful, shareable deep link. Bookmarks preserve
inputs exactly, back/forward navigation works naturally, and a built-in Share
button is always present.

**Each calculator section below includes a `Supported URL Parameters` table —
use it to construct deep links directly.**

Example: `/tools/calculators/dividend?mode=amount&baInitialInvestment=50000&baDivYield=4.0&baProjectionPeriod=20&currency=$`

#### Stock-Prefill URLs (DCF, Reverse DCF, WACC)
The DCF, Reverse DCF, and WACC calculators expose a `stockSlug` URL param
(format: `TICKER:EXCHANGE`, e.g. `AAPL:US`). It is a stateful-URL marker only
— it preserves which ticker the snapshot came from so the stock-search input
shows it as selected on reload. It does **not** trigger any data fetch.

The snapshot values in the URL (`sharePrice`, `sharesOutstanding`,
`freeCashFlow`, `netDebt`, or for WACC `stMarketCap`/`stTotalDebt`/`stBeta`)
are a frozen point-in-time and remain the source of truth for the
calculation. Include `stockSlug` only when the snapshot genuinely came from
that ticker; omit it for hypothetical scenarios.

#### Multiple Visualization Types
Three switchable chart views per calculator with consistent color semantics:
**line** (year-by-year compounding curve), **bar** (annual values side-by-side),
**pie** (final earned-vs-invested breakdown). Switching never loses data.

#### Clear Mental Models and Explanations
Each page pairs results with plain-language labels (e.g. "You invest",
"You earn"), an inline explainer card defining the core concept, and FAQ
structured data for AI/search surfacing.

### Multilingual Support
Calculators are fully translated to Dutch (NL) and Spanish (ES) via the
optional `?lang=nl` or `?lang=es` query param (omit for English, the default).
Input labels, result labels, chart tooltips, explainer text, and FAQ answers
are all localized. URLs are otherwise identical across languages — only
`?lang=` changes.

---

### Dividend Calculator — `/tools/calculators/dividend`

**Purpose**: Project dividend income, portfolio growth, and total return over
a chosen horizon, with or without monthly deposits and dividend growth.

Two modes selected by `mode`: `amount` (model a cash investment, `ba*`
params) or `shares` (model an existing holding, `bs*` params). Inputs from
the inactive mode are preserved in the URL but ignored.

#### Supported URL Parameters

**Shared:**

| Param | Type | Default | Description |
|---|---|---|---|
| `mode` | `amount` \| `shares` | `amount` | Entry mode |
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

**By Amount (`mode=amount`):**

| Param | Type | Default | Description |
|---|---|---|---|
| `baInitialInvestment` | number | (empty) | Initial investment amount |
| `baDepositAmount` | number | (empty) | Recurring deposit amount |
| `baDepositMonths` | int (1–12) | `1` | Number of deposit months per year |
| `baDivYield` | number | (empty) | Dividend yield in % |
| `baDivGrowthRate` | number | `0` | Annual dividend growth rate in % |
| `baSharePriceGrowthRate` | number | `0` | Annual share-price growth rate in % |
| `baProjectionPeriod` | int | `0` | Projection period in years |
| `baReinvest` | boolean | `true` | Reinvest dividends |
| `baInflationRate` | number | `0` | Inflation rate in % (for real returns) |

**By Shares (`mode=shares`):**

| Param | Type | Default | Description |
|---|---|---|---|
| `bsShares` | number | (empty) | Number of shares held |
| `bsSharePrice` | number | (empty) | Share price |
| `bsSharePriceGrowthRate` | number | `0` | Annual share-price growth rate in % |
| `bsDivYield` | number | (empty) | Dividend yield in % |
| `bsDivGrowthRate` | number | `0` | Annual dividend growth rate in % |
| `bsProjectionPeriod` | int | `0` | Projection period in years |
| `bsReinvest` | boolean | `true` | Reinvest dividends |
| `bsInflationRate` | number | `0` | Inflation rate in % (for real returns) |

Example: `/tools/calculators/dividend?mode=amount&baInitialInvestment=50000&baDivYield=4.0&baProjectionPeriod=20&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| You invest | Total capital deployed (initial + all deposits, or portfolio value for shares mode) |
| You end up with | Total portfolio value at end of projection (invested + all dividends earned) |
| You earn | Total cumulative dividend income over the full period |
| Yearly income | Projected annual dividend income in the final year |

#### Live Stock Matching
When the yield is set, a live table appears below the calculator showing
real dividend-paying stocks within ±0.5% of the target yield (top 10 by
yield), each linking to its stock quote page.

#### MCP App
Available as `mg_calculator_dividend`. Prefillable fields: every URL param
above, with `currencySymbol` instead of the URL param `currency`.

---

### CAGR Calculator — `/tools/calculators/cagr`

**Purpose**: Calculate the Compound Annual Growth Rate between a beginning and
ending value over a number of years. Also shows equivalent monthly, weekly, and
daily rates.

#### Supported URL Parameters
| Param | Type | Default | Description |
|---|---|---|---|
| `beginningValue` | number | (empty) | Starting investment value |
| `endingValue` | number | (empty) | Final investment value |
| `years` | int | `0` | Number of years over which growth is measured |
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

Example: `/tools/calculators/cagr?beginningValue=10000&endingValue=15000&years=3&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| Total gain | Absolute gain (ending − beginning) |
| Yearly growth | Year-by-year growth amount in the final year |

#### MCP App
Available as `mg_calculator_cagr`. Prefillable fields: `beginningValue`,
`endingValue`, `years`, `currencySymbol` (URL param name is `currency`).

---

### Profit Margin Calculator — `/tools/calculators/profit-margin`

**Purpose**: Calculate profit margin from any two of four interlinked inputs
(`revenue`, `cost`, `profit`, `margin`). The remaining two are derived
automatically. Optionally project forward with growth and inflation
assumptions.

#### Supported URL Parameters

| Param | Type | Default | Description |
|---|---|---|---|
| `revenue` | number | (empty) | Annual revenue |
| `cost` | number | (empty) | Cost of goods sold |
| `profit` | number | (empty) | Profit (revenue − cost) |
| `margin` | number | (empty) | Profit margin in % |
| `revenueGrowthRate` | number | `0` | Annual revenue growth rate in % |
| `costGrowthRate` | number | `0` | Annual cost growth rate in % |
| `inflationRate` | number | `0` | Inflation rate in % (for real returns) |
| `projectionPeriod` | int | `0` | Projection period in years |
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

The four interlinked inputs are mathematically dependent — prefill exactly
two (any combination) and the calculator derives the remaining two.

Example: `/tools/calculators/profit-margin?revenue=1000000&cost=750000&projectionPeriod=5&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| Revenue | Total projected revenue |
| Cost | Total projected cost |
| Profit | Total projected profit |
| Margin % | Final-year profit margin |

#### MCP App
Available as `mg_calculator_profit_margin`. Prefillable fields: `revenue`,
`cost`, `currencySymbol` (URL param name is `currency`). The solver derives
profit and margin automatically.

---

### Market Cap Calculator — `/tools/calculators/market-cap`

**Purpose**: Calculate market capitalization from share price and shares
outstanding, or derive any one of the three from the other two
(`market cap = share price × shares outstanding`). Classifies the result
into a market cap tier instantly. No projection, no chart — instant lookup.

#### Supported URL Parameters

| Param | Type | Default | Description |
|---|---|---|---|
| `sharePrice` | number | (empty) | Price per share |
| `sharesOutstanding` | number | (empty) | Total shares outstanding |
| `marketCap` | number | (empty) | Market capitalization |
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

The three numeric inputs are mathematically linked — prefill exactly two
and the calculator derives the third.

Example: `/tools/calculators/market-cap?sharePrice=180&sharesOutstanding=15500000000&currency=$`

#### Result
Market cap value plus tier classification: Nano Cap / Micro Cap / Small Cap /
Mid Cap / Large Cap / Mega Cap.

#### MCP App
Available as `mg_calculator_market_cap`. Prefillable fields: `sharePrice`,
`sharesOutstanding`, `marketCap`, `currencySymbol` (URL param name is
`currency`). The solver derives the third field from whichever two are
provided.

---

### DCF Calculator — `/tools/calculators/dcf`

**Purpose**: Estimate the intrinsic (fair) value of a stock with a discounted
cash flow model. Project free cash flows, discount them to today's value, and
compare to the current price to see whether the stock may be under- or
overvalued.

#### Supported URL Parameters

**Stock snapshot** (source of truth for the calculation):

| Param | Type | Default | Description |
|---|---|---|---|
| `sharePrice` | number | (empty) | Current share price |
| `sharesOutstanding` | number | (empty) | Total shares outstanding |
| `freeCashFlow` | number | (empty) | Current annual free cash flow (TTM, levered) |
| `netDebt` | number | (empty) | Net debt (total debt − cash); can be negative |
| `stockSlug` | string | (none) | Stateful-URL marker (no fetch). See "Stock-Prefill URLs" note above |

**Assumptions:**

| Param | Type | Default | Description |
|---|---|---|---|
| `fcfGrowthRate` | number | `10` | Expected annual FCF growth rate in % |
| `discountRate` | number | `10` | Discount rate / WACC in % |
| `terminalGrowthRate` | number | `3` | Terminal (perpetual) growth rate in % |
| `projectionPeriod` | int | `10` | Number of years to project |
| `marginOfSafety` | number | `25` | Margin of safety in % |

**Other:**

| Param | Type | Default | Description |
|---|---|---|---|
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

Example: `/tools/calculators/dcf?sharePrice=180&sharesOutstanding=15500000000&freeCashFlow=100000000000&netDebt=50000000000&fcfGrowthRate=8&discountRate=10&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| Fair value per share | Intrinsic value per share based on the DCF model |
| Valuation tier | Significantly Undervalued (fair value 50%+ above price), Undervalued (15–50%), Fairly Valued (±15%), Overvalued (15–50% below), Significantly Overvalued (50%+ below) |
| Current price | The share price input |
| Upside / Downside | % difference between fair value and current price |
| Buy below | Fair value adjusted down by the margin of safety |
| PV of cash flows (1–Ny) | Present value of projected FCFs over the projection period |
| PV of terminal value (N+1y+) | Present value of the terminal value (Gordon Growth perpetuity) |
| Enterprise value | Sum of PV of cash flows and PV of terminal value |

The page also renders a sensitivity matrix showing fair value across a range
of FCF growth rates × discount rates, with the current assumption highlighted.

#### No MCP App
The DCF calculator has no MCP app — the stock-prefill UI is the designed
entry point. Shareable URLs work as documented above.

---

### Reverse DCF Calculator — `/tools/calculators/reverse-dcf`

**Purpose**: Work backwards from a stock's current price to find the FCF growth
rate the market is implicitly pricing in. Tells investors whether embedded
expectations are realistic compared to historical performance.

#### Supported URL Parameters

**Stock snapshot** (source of truth for the calculation):

| Param | Type | Default | Description |
|---|---|---|---|
| `sharePrice` | number | (empty) | Current share price |
| `sharesOutstanding` | number | (empty) | Total shares outstanding |
| `freeCashFlow` | number | (empty) | Current annual free cash flow (TTM, levered) |
| `netDebt` | number | (empty) | Net debt (total debt − cash); can be negative |
| `stockSlug` | string | (none) | Stateful-URL marker (no fetch). See "Stock-Prefill URLs" note above |

**Assumptions:**

| Param | Type | Default | Description |
|---|---|---|---|
| `discountRate` | number | `10` | Discount rate / WACC in % |
| `terminalGrowthRate` | number | `3` | Terminal (perpetual) growth rate in % |
| `projectionPeriod` | int | `10` | Number of years to project |

**Other:**

| Param | Type | Default | Description |
|---|---|---|---|
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

Example: `/tools/calculators/reverse-dcf?sharePrice=180&sharesOutstanding=15500000000&freeCashFlow=100000000000&netDebt=50000000000&discountRate=10&projectionPeriod=10&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| Implied FCF growth (Ny) | Annual FCF growth rate the market is pricing in over the projection period |
| PV of cash flows (1–Ny) | Present value of the projected FCF stream |
| PV of terminal value (N+1y+) | Present value of the terminal value (Gordon Growth model) |

#### No MCP App
The Reverse DCF calculator has no MCP app — the stock-prefill UI is the
designed entry point. Shareable URLs work as documented above.

---

### WACC Calculator — `/tools/calculators/wacc`

**Purpose**: Calculate the Weighted Average Cost of Capital for a company,
either from a stock snapshot (CAPM-derived cost of equity) or from manual
equity/debt values.

Two modes selected by `mode`: `stock` (use snapshot + CAPM, `st*` params) or
`custom` (enter equity/debt directly, `cu*` params). Inputs from the inactive
mode are preserved in the URL but ignored. In `stock` mode, cost of equity is
derived automatically: `Re = riskFreeRate + beta × marketRiskPremium`.

#### Supported URL Parameters

**Shared:**

| Param | Type | Default | Description |
|---|---|---|---|
| `mode` | `stock` \| `custom` | `stock` | Entry mode |
| `currency` | string | `$` | Currency symbol shown in the UI (e.g. `$`, `€`, `£`, `¥`) |

**By Stock (`mode=stock`):**

| Param | Type | Default | Description |
|---|---|---|---|
| `stMarketCap` | number | (empty) | Market capitalization |
| `stTotalDebt` | number | (empty) | Total debt (book value) |
| `stBeta` | number | `1` | Equity beta |
| `stRiskFreeRate` | number | `4.5` | Risk-free rate in % |
| `stMarketRiskPremium` | number | `5.5` | Equity market risk premium in % |
| `stCostOfDebt` | number | `5` | Pre-tax cost of debt in % |
| `stTaxRate` | number | `21` | Corporate tax rate in % |
| `stockSlug` | string | (none) | Stateful-URL marker (no fetch, ignored in `custom` mode). See "Stock-Prefill URLs" note above |

**Custom (`mode=custom`):**

| Param | Type | Default | Description |
|---|---|---|---|
| `cuEquityValue` | number | (empty) | Market value of equity |
| `cuDebtValue` | number | (empty) | Market value of debt |
| `cuCostOfEquity` | number | `0` | Cost of equity in % |
| `cuCostOfDebt` | number | `0` | Pre-tax cost of debt in % |
| `cuTaxRate` | number | `0` | Corporate tax rate in % |

Example: `/tools/calculators/wacc?mode=stock&stMarketCap=2800000000000&stTotalDebt=110000000000&stBeta=1.2&currency=$`

#### Result Metrics
| Label | Meaning |
|---|---|
| WACC | The weighted average cost of capital (%) |
| Cost of Equity | Return investors expect (CAPM-derived in stock mode) |
| Cost of Debt (after tax) | Interest rate on borrowing adjusted for tax shield |
| Equity weight | Equity as a share of total financing (E/V) |
| Debt weight | Debt as a share of total financing (D/V) |

#### No MCP App
The WACC calculator has no MCP app — the stock-prefill UI is the designed
entry point. Shareable URLs work as documented above.

---

## MCP Integration — Interactive Calculator Apps for AI Agents

### Overview
Marketgenius exposes an MCP server that gives AI agents access to fully
interactive versions of our investment calculators. These are not
read-only tools — they render a live React UI inside the agent's host
(e.g. Claude Desktop) and support two-way communication: the agent can
read and update calculator fields in real time while the user interacts
with the same UI.

### Discovery
- Well-known endpoint: `/.well-known/mcp`
- MCP server: `/mcp` (Streamable HTTP, no authentication required)

### Available Calculator Apps

#### Dividend Calculator MCP App
Exposes the full dividend calculator as an embedded interactive UI.
The agent opens the app, optionally prefills fields, and can update or
read values at any point — including values the user has changed manually
in the UI.

**Tools** (all prefixed `mg_calculator_dividend`):

| Tool | Visible to | Purpose |
|---|---|---|
| `mg_calculator_dividend` | model | Open the calculator. Returns a `sessionId`. Accepts any calculator field as optional prefill arguments. |
| `mg_calculator_dividend_update` | model | Update one or more fields in an already-open calculator. Pass the `sessionId` and only the fields to change. Send all changes in a single call. |
| `mg_calculator_dividend_state` | model + app | Read the current field values of the open calculator, including any the user has changed manually in the UI. Call this before answering questions about current values. |

**Recommended workflow:**
1. Call `mg_calculator_dividend` to open the calculator (prefill if helpful)
2. Note the `sessionId` returned in the text response
3. When the user asks to change values, call `mg_calculator_dividend_update` — do not re-open the calculator
4. Before answering questions about current state, call `mg_calculator_dividend_state` to get the latest values (the user may have changed fields manually)

#### CAGR Calculator MCP App
Exposes the full CAGR calculator as an embedded interactive UI.

**Tools** (all prefixed `mg_calculator_cagr`):

| Tool | Visible to | Purpose |
|---|---|---|
| `mg_calculator_cagr` | model | Open the calculator. Returns a `sessionId`. Accepts `beginningValue`, `endingValue`, `years`, `currencySymbol` as optional prefill arguments. |
| `mg_calculator_cagr_update` | model | Update one or more fields in an already-open calculator. Pass the `sessionId` and only the fields to change. |
| `mg_calculator_cagr_state` | model + app | Read the current field values of the open calculator, including any the user has changed manually. Call this before answering questions about current values. |

#### Profit Margin Calculator MCP App
Exposes the full profit margin calculator as an embedded interactive UI.
Prefilling `revenue` and `cost` is enough — the solver derives profit and
margin automatically.

**Tools** (all prefixed `mg_calculator_profit_margin`):

| Tool | Visible to | Purpose |
|---|---|---|
| `mg_calculator_profit_margin` | model | Open the calculator. Returns a `sessionId`. Accepts `revenue`, `cost`, `currencySymbol` as optional prefill arguments. |
| `mg_calculator_profit_margin_update` | model | Update one or more fields in an already-open calculator. Pass the `sessionId` and only the fields to change. |
| `mg_calculator_profit_margin_state` | model + app | Read the current field values of the open calculator, including any the user has changed manually. Call this before answering questions about current values. |

#### Market Cap Calculator MCP App
Exposes the full market cap calculator as an embedded interactive UI.
Prefill any two of the three linked fields and the third is derived
automatically.

**Tools** (all prefixed `mg_calculator_market_cap`):

| Tool | Visible to | Purpose |
|---|---|---|
| `mg_calculator_market_cap` | model | Open the calculator. Returns a `sessionId`. Accepts `sharePrice`, `sharesOutstanding`, `marketCap`, `currencySymbol` as optional prefill arguments. |
| `mg_calculator_market_cap_update` | model | Update one or more fields in an already-open calculator. Pass the `sessionId` and only the fields to change. |
| `mg_calculator_market_cap_state` | model + app | Read the current field values of the open calculator, including any the user has changed manually. Call this before answering questions about current values. |

**The recommended workflow is the same for all calculator MCP apps:**
1. Call the open tool to launch the calculator (prefill if helpful)
2. Note the `sessionId` returned in the text response
3. When the user asks to change values, call the `_update` tool — do not re-open the calculator
4. Before answering questions about current state, call the `_state` tool to get the latest values (the user may have changed fields manually)