@riskmodels/mcp 1.0.1 → 1.0.4

package/INSTALL.md

@@ -5,8 +5,9 @@ Copy-paste configs for Claude Desktop, Cursor, and Zed. Works with any [MCP](htt
 ## Prerequisites (one time)
 
 ```bash
-# 1. Get an API key (Stripe card on file, $20 free credit before first charge)
-npm install -g riskmodels
+# 0. Node.js LTS (includes npx). macOS/Homebrew: brew install node; others: https://nodejs.org
+# 1. Get an API key: https://riskmodels.app/get-key (or generate from the dashboard after sign-in)
+npm install -g riskmodels@latest
 riskmodels config init      # stores key at ~/.config/riskmodels/config.json
 
 # 2. Build the MCP server (from this repo)

package/NPM_REPUBLISH_CHECKLIST.md

@@ -0,0 +1,221 @@
+# NPM Republish Checklist: @riskmodels/mcp
+
+**Goal:** Re-enable the `npx @riskmodels/mcp` stdio install path by republishing to npm and updating the MCP Registry listing.
+
+**Prerequisites:**
+- [x] PR #124 merged (stdio build fixed — render tool split out)
+- [ ] npm auth as @riskmodels org member
+- [ ] SDK published at ^0.1.2 (or update version accordingly)
+
+---
+
+## Step 1: Pre-flight Checks
+
+```bash
+cd RiskModels_API/mcp
+
+# Verify npm auth
+npm whoami
+# Should show: <your-npm-username> (with @riskmodels org access)
+
+# Check current package.json
+npm pkg get name version mcpName
+# Expected: @riskmodels/mcp, 1.0.4, io.github.BlueWaterCorp/riskmodels
+
+# Verify SDK is published
+npm view @riskmodels/sdk version
+# Should show: 0.1.2 (or higher)
+```
+
+---
+
+## Step 2: Build
+
+```bash
+# Clean build
+cd RiskModels_API/mcp
+rm -rf dist node_modules
+npm install
+
+# Build (this must succeed cleanly)
+npm run build
+
+# Verify dist/ exists and has expected files
+ls -la dist/
+# Should see: index.js, index.d.ts, etc.
+```
+
+**If build fails:** Stop and fix. Do not proceed to publish.
+
+---
+
+## Step 3: Update Dependencies for Publish
+
+```bash
+cd RiskModels_API/mcp
+
+# Temporarily swap file: dependency to published range
+# DO NOT COMMIT THIS CHANGE
+npm pkg set 'dependencies.@riskmodels/sdk=^0.1.2'
+
+# Verify
+npm pkg get dependencies.@riskmodels/sdk
+# Should show: ^0.1.2 (not file:...)
+```
+
+---
+
+## Step 4: Dry Run
+
+```bash
+cd RiskModels_API/mcp
+
+# Verify package contents
+npm publish --dry-run
+
+# Check output for:
+# - Correct version (1.0.4)
+# - Correct name (@riskmodels/mcp)
+# - Correct mcpName in metadata
+# - Files included (dist/, README.md, etc.)
+# - No file: dependencies
+```
+
+---
+
+## Step 5: Publish
+
+```bash
+cd RiskModels_API/mcp
+
+# Publish to npm
+npm publish
+
+# Verify on npm
+npm view @riskmodels/mcp version mcpName dependencies
+# Should show:
+# - version: 1.0.4
+# - mcpName: io.github.BlueWaterCorp/riskmodels
+# - dependencies.@riskmodels/sdk: ^0.1.2
+```
+
+---
+
+## Step 6: Restore Development Dependency
+
+```bash
+cd RiskModels_API/mcp
+
+# Restore file: dependency for local development
+npm pkg set 'dependencies.@riskmodels/sdk=file:../packages/riskmodels-sdk'
+
+# Verify
+npm pkg get dependencies.@riskmodels/sdk
+# Should show: file:../packages/riskmodels-sdk
+
+# Reinstall to restore symlink
+npm install
+```
+
+---
+
+## Step 7: Update MCP Registry Listing
+
+Edit `RiskModels_API/mcp/server.json` to add the `packages` array:
+
+```json
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.BlueWaterCorp/riskmodels",
+  "title": "RiskModels",
+  "description": "US equity risk: decompose any stock into market/sector/subsector/residual bets + ETF hedge ratios.",
+  "websiteUrl": "https://riskmodels.app",
+  "repository": {
+    "url": "https://github.com/BlueWaterCorp/RiskModels_API",
+    "source": "github"
+  },
+  "version": "1.0.4",
+  "packages": [
+    {
+      "name": "@riskmodels/mcp",
+      "registry": "npm"
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://riskmodels.app/api/mcp/sse"
+    }
+  ]
+}
+```
+
+---
+
+## Step 8: Re-publish to MCP Registry
+
+```bash
+cd RiskModels_API/mcp
+
+# Authenticate (if not already)
+mcp-publisher login github
+
+# Publish updated manifest
+mcp-publisher publish
+
+# Verify
+open https://registry.modelcontextprotocol.io/servers/io.github.BlueWaterCorp/riskmodels
+```
+
+---
+
+## Step 9: Test the npx Path
+
+```bash
+# Test that npx works (in a temp directory, no local install)
+cd /tmp
+mkdir mcp-test && cd mcp-test
+
+# This should download and run the MCP server
+npx @riskmodels/mcp
+
+# Expected: Server starts, outputs stdio transport
+# Ctrl+C to exit
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `npm whoami` shows @riskmodels org member
+- [ ] `npm run build` succeeds cleanly
+- [ ] `npm publish --dry-run` shows correct files, no file: deps
+- [ ] `npm publish` succeeds
+- [ ] `npm view @riskmodels/mcp version` shows 1.0.4
+- [ ] `server.json` has `packages[]` block added
+- [ ] `mcp-publisher publish` succeeds
+- [ ] Registry shows both remote and package options
+- [ ] `npx @riskmodels/mcp` works in clean environment
+
+---
+
+## Rollback (if needed)
+
+If something goes wrong:
+
+```bash
+# Unpublish (within 24h of publish)
+npm unpublish @riskmodels/mcp@1.0.4
+
+# Or deprecate
+npm deprecate @riskmodels/mcp@1.0.4 "Deprecated due to issue X, use 1.0.5+"
+```
+
+---
+
+## References
+
+- Original runbook: `RiskModels_API/mcp/PUBLISHING.md`
+- Build fix PR: #124
+- Registry: https://registry.modelcontextprotocol.io
+- npm package: https://www.npmjs.com/package/@riskmodels/mcp

package/PUBLISHING.md

@@ -0,0 +1,83 @@
+# Publishing the RiskModels MCP server to the Official MCP Registry
+
+Namespace: **`io.github.BlueWaterCorp/riskmodels`** (verified via GitHub org
+membership — GitHub namespaces have **no remote-URL restriction**).
+Manifest: [`server.json`](./server.json) (schema `2025-12-11`).
+
+## What we list now: the hosted remote (no npm needed)
+
+`server.json` currently declares **only the hosted `streamable-http` remote**
+(`https://riskmodels.app/api/mcp/sse`). That endpoint already works in
+production, so listing it requires **no npm publish, no build, no `mcpName`** —
+just GitHub auth. The stdio npm package is a fast-follow (see below).
+
+### Steps (require GitHub auth as a BlueWaterCorp org member)
+
+1. **Install the publisher CLI** (`mcp-publisher`):
+   download from https://github.com/modelcontextprotocol/registry/releases
+   (or `brew install mcp-publisher` if available).
+
+2. **Authenticate** as a member of the **BlueWaterCorp** GitHub org (this
+   authorizes the `io.github.BlueWaterCorp/*` namespace):
+   ```bash
+   mcp-publisher login github
+   ```
+
+3. **Publish** from the dir holding `server.json`:
+   ```bash
+   cd mcp
+   mcp-publisher publish
+   ```
+
+4. **Verify:** search https://registry.modelcontextprotocol.io for `riskmodels`.
+
+## Fast-follow: re-add the stdio npm package (`@riskmodels/mcp`)
+
+The `npx @riskmodels/mcp` stdio package was intentionally **left off this
+listing** because its standalone build is broken and needs a small refactor
+first. This is additive — adding `packages[]` back to `server.json` later does
+not disturb the live remote listing.
+
+**Why it's broken (since 2026-05-20, PR #99):** `lib/mcp/tools/riskmodels-tools.ts`
+(compiled into the stdio bundle via `mcp/tsconfig.json`'s
+`include: ["../lib/mcp/tools/**"]`) imports `@/lib/artifacts/render-client`,
+which imports `@/lib/artifacts/gcp-id-token`. The standalone `tsc` build can't
+resolve the `@/` alias, and `tsc` wouldn't rewrite it for runtime anyway.
+
+**Why a tsconfig-paths patch is not enough:** the `riskmodels_render_artifact`
+tool authenticates to **GCP Cloud Run** to render. A public `npx` user has no
+GCP credentials, so that tool cannot function in the stdio context — it is
+**hosted-only**. The fix is to keep the render tool (and its render-client /
+gcp-id-token deps) out of the public stdio bundle, e.g. split the render-tool
+registration into a hosted-only module that `mcp/src/server.ts` does not import.
+
+**When fixed**, to re-enable the npm package:
+1. Refactor so the stdio build (`cd mcp && npm run build`) compiles clean.
+2. Add `"mcpName": "io.github.BlueWaterCorp/riskmodels"` to `mcp/package.json`
+   (already added on this branch — keep it).
+3. Publish npm `@riskmodels/mcp@1.0.4` (latest on npm is `1.0.2`). The `file:`
+   SDK dep must become a published range at publish time:
+   ```bash
+   cd mcp
+   npm whoami                                            # @riskmodels org member
+   npm run build                                         # must succeed first
+   npm pkg set 'dependencies.@riskmodels/sdk=^0.1.2'     # do NOT commit
+   npm publish --dry-run                                 # confirm version/mcpName/^0.1.2/files
+   npm publish
+   npm pkg set 'dependencies.@riskmodels/sdk=file:../packages/riskmodels-sdk'  # restore
+   npm view @riskmodels/mcp version mcpName dependencies
+   ```
+   Build with `cd mcp && npm run build` — **not** the repo-root `npm run build`
+   (that runs `next build` and OOMs; irrelevant to the npm package).
+4. Add the `packages[]` block back to `server.json` and re-run `mcp-publisher publish`.
+
+## Next: aggregators (#2)
+Once on the official registry, PulseMCP / Glama / Smithery / mcp.so largely
+ingest from it. Glama also auto-indexes public GitHub MCP servers; the OSS
+`mcp-submit` tool submits to 10+ directories at once.
+
+## Known cosmetic follow-ups (not blockers)
+- `.well-known/mcp.json` advertises `transport: "sse"` but the server is
+  Streamable HTTP — reconcile to avoid confusing strict clients.
+- `/api/health` reports `version` from `process.env.API_VERSION` (falls back to
+  `2.0.0-agent`); set `API_VERSION=3.0.0-agent` in prod to match the OpenAPI spec.

package/README.md

@@ -2,7 +2,7 @@
 
 NPM package: `@riskmodels/mcp`
 
-Release note: publish `@riskmodels/sdk` first, then add the published SDK version as a runtime dependency before publishing this package.
+Release note: publish **`@riskmodels/sdk`** to npm first, then **`@riskmodels/mcp`**. In this monorepo, `mcp/package.json` uses `"@riskmodels/sdk": "file:../packages/riskmodels-sdk"` so `cd mcp && npm ci && npm run build` works without publishing; **before `npm publish` of `@riskmodels/mcp`**, replace that dependency with a semver range (e.g. `^0.1.1`) after `@riskmodels/sdk` is live on the registry.
 
 **Decompose** a US stock into market, sector, subsector, and residual risk — with SPY / sector / subsector **ETF hedge ratios**. One call, daily history since 2006.
 
@@ -86,6 +86,8 @@ Run `riskmodels config init` once — the CLI's stored key is automatically pick
 
 Base URL resolution: `RISKMODELS_API_BASE` env → `apiBaseUrl` in CLI config → `https://riskmodels.app` default.
 
+**Hosted transport (`POST https://riskmodels.app/api/mcp/sse`):** send header `Accept: application/json, text/event-stream`. Without it, some clients receive **406 Not Acceptable**.
+
 ---
 
 ## Python SDK on PyPI
@@ -107,12 +109,27 @@ This repo includes **`.cursor/mcp.json`** pointing at `node` + `mcp/dist/index.j
 ### 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.
+- **Preferred (deterministic):** pin the CLI package so `npx` does not resolve a stale cache — e.g. `RISKMODELS_API_KEY=... npx -y riskmodels@latest install` (writes MCP configs via `riskmodels install`). Same flow as [Quickstart](https://riskmodels.app/quickstart).
 - **Use one of these:**
-  - **`npx -y @riskmodels/mcp`** — future published stdio package target used by `npx riskmodels install`.
+  - **`npx -y @riskmodels/mcp`** — stdio MCP package merged into configs by `npx -y riskmodels@latest install` / global `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.
 
+### Claude Code (`claude` CLI)
+
+The **`riskmodels install`** command merges MCP into **Claude Desktop** (`claude_desktop_config.json`) and **Cursor** — not into **Claude Code** (the `claude` terminal application), which maintains its own MCP configuration.
+
+After you have run `riskmodels install` and have a key in `~/.config/riskmodels/config.json`, register the stdio server for Claude Code:
+
+```bash
+claude mcp add --scope user --transport stdio riskmodels -- npx -y @riskmodels/mcp
+```
+
+Restart **`claude`**, then run **`claude mcp list`** — `riskmodels` should show as connected. If it does not, use the **hosted** `mcp-remote` transport with `AUTHORIZATION=Bearer <key>` (same JSON pattern as in the “Hosted endpoint” section below).
+
+`@riskmodels/sdk` powers in-tool SDK calls inside `@riskmodels/mcp`; published builds use Node ESM with `.js` import specifiers so `npx -y @riskmodels/mcp` loads under Node 18+.
+
 ### 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`).
@@ -124,7 +141,7 @@ Paste into Claude Desktop / Cursor via the `mcp-remote` proxy:
   "mcpServers": {
     "riskmodels": {
       "command": "npx",
-      "args": ["mcp-remote", "https://riskmodels.app/api/mcp/sse"],
+      "args": ["-y", "mcp-remote", "https://riskmodels.app/api/mcp/sse"],
       "env": { "AUTHORIZATION": "Bearer rm_agent_live_..." }
     }
   }

package/data/benchmark_master.json

@@ -0,0 +1,68 @@
+{
+  "schema_version": "benchmark-master/1.0",
+  "n_contexts": 2,
+  "aliases": {
+    "70-30-large-small": "BW-BENCH-EQ70-30",
+    "70/30": "BW-BENCH-EQ70-30",
+    "eq70-30": "BW-BENCH-EQ70-30",
+    "ivv": "BW-BENCH-SPY",
+    "s&p 500": "BW-BENCH-SPY",
+    "sp500": "BW-BENCH-SPY",
+    "spx": "BW-BENCH-SPY",
+    "spy": "BW-BENCH-SPY",
+    "us-large-small-70-30": "BW-BENCH-EQ70-30"
+  },
+  "contexts": {
+    "BW-BENCH-EQ70-30": {
+      "bw_bench_id": "BW-BENCH-EQ70-30",
+      "name": "70/30 US Large/Small all-equity blend (70% IWB + 30% IWM)",
+      "benchmark_kind": "blend",
+      "aliases": [
+        "70/30",
+        "EQ70-30",
+        "70-30-large-small",
+        "US-LARGE-SMALL-70-30"
+      ],
+      "methodology": "Fixed-weight all-equity blend: 70% iShares Russell 1000 ETF (IWB) + 30% iShares Russell 2000 ETF (IWM). Each component's in-ERM3 weight vector is renormalized to 1, scaled by its notional weight, and the two are summed over the union of symbols at each teo the components share. Illustrative large/small split (IWB \u222a IWM \u2248 Russell 3000).",
+      "rebalance_schedule": "Notional weights fixed at 70/30; the component weight vectors drift with the underlying ETF holdings (no rebalancing of the blend itself in v1).",
+      "observation_mode": "reality",
+      "proxy": null,
+      "components": [
+        {
+          "source_kind": "etf",
+          "ref": "IWB",
+          "weight": 0.7
+        },
+        {
+          "source_kind": "etf",
+          "ref": "IWM",
+          "weight": 0.3
+        }
+      ],
+      "benchmark_context_version": "benchmark-context/1.0",
+      "notes": ""
+    },
+    "BW-BENCH-SPY": {
+      "bw_bench_id": "BW-BENCH-SPY",
+      "name": "S&P 500 (proxy: iShares Core S&P 500 ETF, IVV)",
+      "benchmark_kind": "index_proxy",
+      "aliases": [
+        "SPY",
+        "S&P 500",
+        "SP500",
+        "SPX",
+        "IVV"
+      ],
+      "methodology": "Float-adjusted market-cap-weighted S&P 500 constituents, proxied by iShares Core S&P 500 ETF (IVV)'s published daily holdings. The benchmark surface = IVV's in-ERM3 holdings renormalized to weights summing to 1 (cash / non-ERM3 lines dropped, as for any portfolio surface).",
+      "rebalance_schedule": "S&P 500 reconstitution is quarterly (effective the 3rd Friday of Mar/Jun/Sep/Dec) plus ad-hoc index changes; the surface tracks IVV's daily-published holdings, so per-teo weights move with IVV (which itself tracks the index ~daily).",
+      "observation_mode": "reality",
+      "proxy": {
+        "source_kind": "etf",
+        "ref": "IVV"
+      },
+      "components": [],
+      "benchmark_context_version": "benchmark-context/1.0",
+      "notes": "v1 proxies the index via IVV; a direct S&P-constituent feed would be a follow-on."
+    }
+  }
+}