@riskmodels/mcp 1.0.1

package/INSTALL.md

@@ -0,0 +1,130 @@
+# RiskModels MCP — Client Install Guide
+
+Copy-paste configs for Claude Desktop, Cursor, and Zed. Works with any [MCP](https://modelcontextprotocol.io) client that supports stdio servers.
+
+## Prerequisites (one time)
+
+```bash
+# 1. Get an API key (Stripe card on file, $20 free credit before first charge)
+npm install -g riskmodels
+riskmodels config init      # stores key at ~/.config/riskmodels/config.json
+
+# 2. Build the MCP server (from this repo)
+cd RiskModels_API/mcp
+npm install && npm run build
+```
+
+The MCP server reads your API key from `~/.config/riskmodels/config.json` automatically — no need to embed the key in every MCP client config.
+
+Replace `/ABSOLUTE/PATH/TO/RiskModels_API` below with the actual absolute path to your clone of this repo.
+
+---
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "riskmodels": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/RiskModels_API/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. In a new conversation you should see the RiskModels tools listed — try "Run `get_l3_decomposition` for NVDA."
+
+---
+
+## Cursor
+
+This repo ships `.cursor/mcp.json` pointing at the built server, so opening `RiskModels_API/` as a workspace folder auto-wires it. For a different layout, edit `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "riskmodels-api": {
+      "command": "node",
+      "args": ["mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Use absolute paths if Cursor's workspace root is not `RiskModels_API/`. Reload MCP (Settings → MCP → Reload) after saving.
+
+---
+
+## Zed
+
+Edit `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "riskmodels": {
+      "command": {
+        "path": "node",
+        "args": ["/ABSOLUTE/PATH/TO/RiskModels_API/mcp/dist/index.js"]
+      }
+    }
+  }
+}
+```
+
+Restart Zed. Use the assistant panel with `@riskmodels` to call tools.
+
+---
+
+## Overriding the API key per-client (optional)
+
+If you want a different key for a specific MCP client (e.g., a scoped `rm_agent_mcp_*` key for Claude Desktop, a broader key for Cursor), set `RISKMODELS_API_KEY` in that client's MCP env block. Env takes precedence over the CLI config file:
+
+```json
+{
+  "mcpServers": {
+    "riskmodels": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/RiskModels_API/mcp/dist/index.js"],
+      "env": {
+        "RISKMODELS_API_KEY": "rm_agent_...",
+        "RISKMODELS_API_BASE": "https://riskmodels.app"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Verifying the install
+
+Once the server is wired up, ask the assistant:
+
+> "List all RiskModels tools."
+
+You should see:
+
+- **Discovery** — `riskmodels_list_endpoints`, `riskmodels_get_capability`, `riskmodels_get_schema`
+- **Data** — `get_metrics`, `get_l3_decomposition`, `get_portfolio_risk_snapshot`
+
+Then:
+
+> "Get the L3 decomposition for NVDA with 1 year of history."
+
+Every data-tool response includes a meter envelope (`_cost_usd`, `_remaining_daily_usd`, `_rate_limit_remaining`, `_data_as_of`) so the agent can see the meter running and self-throttle.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Tools don't appear | Fully quit and relaunch the client (not just reload). Stdio servers spawn at client start. |
+| `RISKMODELS_API_KEY not found` in tool response | Run `riskmodels config init` or set the env var in the MCP client config. |
+| `API 401` in tool response | Key is invalid or revoked. `riskmodels config init` to mint a fresh one. |
+| `API 429` in tool response | Hit the per-minute rate limit. Default is 60/min; scoped MCP keys are tighter. Wait or ask an admin to bump. |
+| `get_l3_decomposition` returns `Symbol not found` | Ticker is not in the RiskModels universe. Try `riskmodels_get_capability { id: "tickers" }` for the universe endpoint. |

package/README.md

@@ -0,0 +1,196 @@
+# RiskModels API MCP Server
+
+NPM package: `@riskmodels/mcp`
+
+Release note: publish `@riskmodels/sdk` first, then add the published SDK version as a runtime dependency before publishing this package.
+
+**Decompose** a US stock into market, sector, subsector, and residual risk — with SPY / sector / subsector **ETF hedge ratios**. One call, daily history since 2006.
+
+MCP server that exposes **RiskModels API** inside [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com), [Zed](https://zed.dev), and any other [MCP](https://modelcontextprotocol.io) client. Two classes of tools:
+
+- **Discovery tools** — list endpoints, read capabilities, fetch response schemas (no API key required).
+- **Data tools** — fetch daily EOD risk decomposition, metrics snapshots, and portfolio risk reports (API key required).
+
+Data tools return the same numbers the REST API and CLI return — GCP zarr for historical time series, Supabase `security_history_latest` for the latest snapshot. Data freshness: daily after US market close.
+
+---
+
+## Resources (read-only, no auth)
+
+| URI | Description |
+|-----|-------------|
+| `riskmodels:///manifest` | Agent Protocol manifest. Fetches from `RISKMODELS_API_BASE` when set; otherwise returns static capabilities. |
+| `riskmodels:///capabilities` | Full list of API capabilities (endpoints, parameters, pricing, examples). |
+| `riskmodels:///schemas/list` | List of available response schema paths. |
+| `riskmodels:///schemas/{path}` | JSON schema for a response (e.g. `ticker-returns-v2.json`). |
+| `riskmodels:///openapi` | OpenAPI 3.x spec (`data/openapi.json`). |
+| `riskmodels://whitepaper/one-position-four-bets` | Live-paper overview for the Medium article. |
+| `riskmodels://whitepaper/chapter/01-core-claim` | Short markdown chapter: one position is four bets. |
+| `riskmodels://whitepaper/chapter/02-aapl-vs-nvda` | Short markdown chapter for the AAPL vs NVDA comparison. |
+| `riskmodels://whitepaper/chapter/03-hedging` | Short markdown chapter for hedge-ratio scaling. |
+| `riskmodels://examples/aapl-nvda-crwd` | Short markdown example for a three-name comparison. |
+
+## Discovery tools (no auth)
+
+| Tool | Description |
+|------|-------------|
+| `riskmodels_list_endpoints` | List all public API capabilities (id, name, method, endpoint, short description). |
+| `riskmodels_get_capability` | Get full capability by id (parameters, pricing, examples). |
+| `riskmodels_get_schema` | Get JSON schema by path (e.g. `ticker-returns-v2.json`). |
+
+## Data tools (API key required)
+
+| Tool | Wraps | What it returns |
+|------|-------|-----------------|
+| `get_l3_decomposition` | `GET /api/l3-decomposition` | Daily EOD hierarchical decomposition (market → sector → subsector → residual) with parallel time-series arrays + L3 hedge ratios. |
+| `get_metrics` | `GET /api/metrics/{ticker}` | Latest snapshot from the `_latest` table: L1/L2/L3 hedge ratios, ER fractions, volatility, close price, market cap. |
+| `get_portfolio_risk_snapshot` | `POST /api/portfolio/risk-snapshot` | Portfolio variance decomposition (up to 100 positions), optional diversification analytics, Redis-cached per user/portfolio for 1h. |
+| `riskmodels_decompose` | `POST /api/decompose` via `@riskmodels/sdk` | Single-stock four-bet decomposition with `chart_data`, `suggested_chart`, `plain_english`, and `api_call`. |
+| `riskmodels_compare` | `POST /api/batch/analyze` via `@riskmodels/sdk` | Multi-ticker four-layer comparison. Clients should prefer grouped bar charts. |
+| `riskmodels_hedge_position` | `POST /api/decompose` via `@riskmodels/sdk` | Scales hedge ratios to ETF notionals for a dollar stock position. |
+| `riskmodels_portfolio_decompose` | `POST /api/portfolio/risk-snapshot` via `@riskmodels/sdk` | Portfolio-level market / sector / subsector / residual decomposition. |
+| `riskmodels_whitepaper_example` | `@riskmodels/sdk.whitepaperExample()` | Chapter text plus the live SDK/API example result. |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `follow_whitepaper` | Reads the short white-paper resources, then runs the live examples in sequence. |
+| `reproduce_aapl_nvda` | Compares AAPL and NVDA and asks the client to render grouped `chart_data`. |
+| `hedge_single_position` | Scales hedge ratios to a chosen ticker and dollar position. |
+| `explain_my_portfolio` | Collects user holdings and calls `riskmodels_portfolio_decompose`. |
+
+Whenever a tool response includes `chart_data`, clients should render the `suggested_chart` and explain the result in plain English.
+
+Every data-tool response includes a meter envelope so agents can self-throttle:
+
+```json
+{
+  ...actual data...,
+  "_cost_usd": 0.003,
+  "_remaining_daily_usd": 4.997,
+  "_rate_limit_remaining": 59,
+  "_data_as_of": "2026-04-15",
+  "_data_source": "zarr"
+}
+```
+
+### Credentials
+
+The server resolves the API key in this order:
+
+1. `RISKMODELS_API_KEY` from the MCP client's env config (explicit override).
+2. `apiKey` field in `~/.config/riskmodels/config.json` (shared with the `riskmodels` CLI).
+
+Run `riskmodels config init` once — the CLI's stored key is automatically picked up by the MCP server. No need to duplicate the key in your `claude_desktop_config.json`.
+
+Base URL resolution: `RISKMODELS_API_BASE` env → `apiBaseUrl` in CLI config → `https://riskmodels.app` default.
+
+---
+
+## Python SDK on PyPI
+
+This MCP server exposes **discovery** (capabilities, schemas, OpenAPI). For live **`/metrics`**, **`/batch/analyze`**, **`/l3-decomposition`**, and other data routes, call the REST API or install **`riskmodels-py`** from [PyPI](https://pypi.org/project/riskmodels-py/) ([`sdk/README.md`](../sdk/README.md)).
+
+---
+
+## Setup
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+This repo includes **`.cursor/mcp.json`** pointing at `node` + `mcp/dist/index.js` (relative to the **RiskModels_API** workspace root). After `cd mcp && npm ci && npm run build`, open **RiskModels_API** as a folder in Cursor (or add it in a multi-root workspace), then **restart Cursor** or reload MCP so **`riskmodels_list_endpoints`** appears.
+
+### Claude Desktop / `npx` (common mistakes)
+
+- **There is no `mcp` subcommand on the npm package.** The CLI binary is **`riskmodels`**. Do **not** run `npx -y riskmodels-cli mcp` — that legacy package does not provide the new installer flow.
+- **Use one of these:**
+  - **`npx -y @riskmodels/mcp`** — future published stdio package target used by `npx riskmodels install`.
+  - **`riskmodels mcp-config`** — prints a ready-to-paste `mcpServers` block for Claude Desktop (`--client claude-desktop`) or Cursor. Use **`riskmodels mcp-config --embed-key`** only if you want the key in the JSON env block.
+  - **`riskmodels mcp`** — runs the stdio MCP server (same as `node mcp/dist/index.js`). Requires `mcp/dist/index.js` to exist (build `mcp/` first), or set **`RISKMODELS_MCP_SERVER_PATH`** to that file.
+  - **`node /absolute/path/to/RiskModels_API/mcp/dist/index.js`** — always works if the build exists.
+
+### Hosted endpoint (`https://riskmodels.app/api/mcp/sse`)
+
+The hosted endpoint implements the **MCP Streamable HTTP** transport (current SDK spec, successor to legacy SSE+companion-POST). Stateless mode: each `POST` carries a JSON-RPC 2.0 message and returns the response synchronously. Auth via `Authorization: Bearer <key>` (primary) or `?api_key=<key>` query param (fallback for clients that can't set headers, e.g. `EventSource`).
+
+Paste into Claude Desktop / Cursor via the `mcp-remote` proxy:
+
+```json
+{
+  "mcpServers": {
+    "riskmodels": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://riskmodels.app/api/mcp/sse"],
+      "env": { "AUTHORIZATION": "Bearer rm_agent_live_..." }
+    }
+  }
+}
+```
+
+Tool calls bill per-invocation at the downstream REST endpoint (e.g. `get_metrics` costs the same as `GET /metrics/{ticker}`). Discovery tools (`riskmodels_list_endpoints`, etc.) are free.
+
+Stdio remains available for local dev or air-gapped use (see below).
+
+If you configure manually instead, add the server under Cursor Settings → MCP, or use a project file:
+
+```json
+{
+  "mcpServers": {
+    "riskmodels-api": {
+      "command": "node",
+      "args": ["/absolute/path/to/RiskModels_API/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+You can also point **`command`** at your `riskmodels` CLI and **`args`** at `["mcp"]` if the CLI is on `PATH` and `mcp/dist/index.js` is discoverable (repo root or `RISKMODELS_MCP_SERVER_PATH`).
+
+If **RiskModels_API** is the workspace root, a relative path is enough:
+
+```json
+"args": ["mcp/dist/index.js"]
+```
+
+Restart Cursor after editing the config.
+
+**Optional:** Set `RISKMODELS_API_BASE=https://riskmodels.app` so the manifest resource fetches the live agent manifest from the API.
+
+---
+
+## Maintenance (for API / repo maintainers)
+
+The MCP server serves static data from `mcp/data/`. When the live RiskModels API gains new endpoints, changes pricing, or updates response schemas, this data should be updated so Cursor and other MCP clients stay in sync.
+
+### What gets updated
+
+- **`data/capabilities.json`** — List of API capabilities (endpoints, methods, parameters, pricing, examples).
+- **`data/schema-paths.json`** — List of response schema paths.
+- **`data/schemas/*.json`** — JSON Schema files for each response type.
+- **`data/openapi.json`** — Optional; can mirror or summarize the repo’s [OPENAPI_SPEC.yaml](../OPENAPI_SPEC.yaml).
+
+### How to update
+
+The **canonical API and capabilities** live in the [Risk_Models](https://github.com/BlueWaterCorp/Risk_Models) platform repo. From that repo you can run `npm run generate-mcp-data` (in `riskmodels_com/`) to regenerate `capabilities.json`, `schema-paths.json`, and `schemas/*.json` from the app’s `lib/agent` registry; then copy the updated files into this repo’s `mcp/data/`. The `openapi.json` here is a subset of the full [OPENAPI_SPEC.yaml](../OPENAPI_SPEC.yaml) and should be updated when new public endpoints are added.
+
+1. **Obtain updated data** from the canonical source (Risk_Models) or by hand from the API application’s capabilities and schema registry.
+2. **Replace** the contents of `mcp/data/`:
+   - `capabilities.json`
+   - `schema-paths.json`
+   - `schemas/*.json`
+   - `openapi.json` (if used)
+3. **If server code changed** (e.g. new resources or tools): update `mcp/src/index.ts` (and any other source files), then run `npm run build` inside `mcp/`.
+4. **Commit and push** so users who clone RiskModels_API get the latest MCP behavior and data.
+
+### When to update
+
+- New public API endpoints or capabilities.
+- Changes to existing endpoints (parameters, pricing, descriptions).
+- New or changed response schemas.
+- OpenAPI spec changes you want reflected in the `riskmodels:///openapi` resource.
+
+Keeping `data/` in sync with the live API after releases or significant API changes ensures the MCP server remains a reliable reference for developers and tools.