# Underwriting MCP Server

A headless [Model Context Protocol](https://modelcontextprotocol.io) connector that lets you
underwrite commercial and multifamily deals inside a Claude chat. Claude runs the conversation;
this server does the arithmetic that must be **exact** (NOI, valuation, debt sizing, DSCR, returns)
and serves your firm's underwriting methodology so every conversation underwrites the same way.

There is **no web UI**. The interface is Claude with this connector attached.

> This server does deterministic math + methodology only. It does **not** open, fill, or recalculate
> `Commercial_Template.xlsx` — that's the Skills pipeline's job in code-execution. The two share the
> same underwriting constants so they never disagree.

## Stack

- **Next.js** (App Router) + [`mcp-handler`](https://www.npmjs.com/package/mcp-handler) — wraps the
  route as an MCP endpoint over **stateless Streamable HTTP** (no SSE, no Redis; free-tier friendly).
- **TypeScript** + **Zod** for tool input contracts.
- Deploy target: **Vercel** (Hobby/free tier).

## What it exposes

### Tools (`lib/calc/`)
| Group | Tools |
|---|---|
| Common (§4.1) | `calculate_noi`, `value_from_cap_rate`, `implied_cap_rate`, `size_debt`, `debt_metrics`, `cash_on_cash`, `equity_required`, `exit_value`, `run_scenarios`, `deal_summary` |
| Commercial (§4.2) | `summarize_rent_roll`, `market_rent_gap`, `nnn_reimbursement`, `rollover_exposure` |
| Multifamily (§4.3) | `summarize_unit_mix`, `economic_occupancy`, `per_unit_metrics`, `proforma_rent_growth`, `mf_expense_defaults` |

### Resources (`lib/methodology/`)
`underwriting-conventions`, `scenario-definitions`, `commercial-field-map`, `multifamily-field-map`,
`template-version` — served over `underwriting://…` URIs.

### Prompts (`lib/prompts/`)
`underwrite_retail_commercial`, `underwrite_multifamily` — guided openers that collect the right
inputs, call the tools in order, and present the four-scenario grid.

## Conventions (enforced)

- **Four scenarios** always: List / Target / Probable / Conservative. Per-scenario levers are
  **cap rate, LTV, exit cap rate**; everything else is shared.
- **Rates are fractions** — `0.055` = 5.5%. The server rejects rate-like inputs `> 1.0` to catch the
  classic `5`-vs-`0.05` bug.
- **Stabilization year** selector (2/3/4, default 4); any stabilized result states which year it used.
- Every denominator (cap rate, equity, loan, GPR) is guarded — clear error instead of `Infinity`/`NaN`.
- **Multifamily defaults** (overridable): mgmt fee 3% of EGI, replacement reserves $250/unit/yr,
  rent trend 3%/yr.

## Develop

```bash
npm install
npm test          # hand-checked deal per asset class (node:test via tsx)
npm run typecheck # tsc --noEmit
npm run dev       # http://localhost:3000/api/mcp
```

## Deploy (free tier)

1. `npm test` — confirm every formula matches its hand-checked deal.
2. Push to GitHub.
3. Vercel → **New Project → import repo → Deploy** (Node auto-detected).
4. Your endpoint is `https://<project>.vercel.app/api/mcp`.
5. (Optional) set `MCP_API_KEY` in Vercel env to require `Authorization: Bearer <key>`.

## Add the connector in Claude

Requires a **Pro, Max, Team, or Enterprise** plan (custom connectors over remote MCP).

1. Settings → Connectors → **Add custom connector**.
2. Paste the `…/api/mcp` URL; complete auth if you set a key.
3. Start a chat, confirm the tools/prompts appear, run the two walkthroughs.

## Layout

```
app/api/mcp/route.ts   # mcp-handler entry: registers tools, resources, prompts + shared-key auth
lib/calc/finance.ts    # §5 primitives (debt, DSCR, value, exit)
lib/calc/common.ts     # §4.1 common tools incl. run_scenarios
lib/calc/commercial.ts # §4.2 retail/office/net-lease
lib/calc/multifamily.ts# §4.3 multifamily
lib/validate.ts        # fraction-vs-percent + zero-denominator guards
lib/methodology/       # §6 resources (source of truth, one file each)
lib/prompts/           # §7 guided flows
test/                  # one hand-checked deal per asset class
```

## Roadmap

- **Phase 4 — hardening:** OAuth via `withMcpAuth`, rate limiting, multi-year levered cash flow / IRR
  (ARGUS-style) if desired.