@riskmodels/mcp 1.0.1

package/data/schemas/risk-metadata-v1.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Risk Metadata",
+  "description": "Lineage and provenance metadata for all data responses. Included as _metadata in response body and as X-Risk-* headers.",
+  "type": "object",
+  "properties": {
+    "model_version": {
+      "type": "string",
+      "description": "ERM3 model version (e.g. ERM3-L3-v30)"
+    },
+    "data_as_of": {
+      "type": "string",
+      "format": "date",
+      "description": "Latest trading date in security_history"
+    },
+    "factor_set_id": {
+      "type": "string",
+      "description": "Factor set identifier"
+    },
+    "universe_size": {
+      "type": "integer",
+      "description": "Number of stocks in the universe"
+    },
+    "wiki_uri": {
+      "type": "string",
+      "format": "uri",
+      "description": "Methodology documentation URL"
+    },
+    "factors": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "L3 factor ETF tickers (market + 11 sectors)"
+    }
+  }
+}

package/data/schemas/telemetry-v1.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Telemetry Metrics Response",
+  "type": "object",
+  "required": [
+    "capability",
+    "period",
+    "metrics"
+  ],
+  "properties": {
+    "capability": {
+      "type": "string"
+    },
+    "period": {
+      "type": "string"
+    },
+    "metrics": {
+      "type": "object",
+      "properties": {
+        "requests": {
+          "type": "object",
+          "properties": {
+            "total": {
+              "type": "integer"
+            },
+            "successful": {
+              "type": "integer"
+            },
+            "failed": {
+              "type": "integer"
+            },
+            "success_rate": {
+              "type": "number"
+            }
+          }
+        },
+        "latency": {
+          "type": "object",
+          "properties": {
+            "avg_ms": {
+              "type": "integer"
+            },
+            "p50_ms": {
+              "type": "integer"
+            },
+            "p95_ms": {
+              "type": "integer"
+            },
+            "p99_ms": {
+              "type": "integer"
+            },
+            "max_ms": {
+              "type": "integer"
+            }
+          }
+        },
+        "pricing": {
+          "type": "object",
+          "properties": {
+            "avg_cost_per_request_usd": {
+              "type": "number"
+            },
+            "total_revenue_usd": {
+              "type": "number"
+            }
+          }
+        },
+        "data_quality": {
+          "type": "object",
+          "properties": {
+            "freshness_avg_hours": {
+              "type": "number"
+            },
+            "coverage_percent": {
+              "type": "number"
+            },
+            "accuracy_score": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    "uptime": {
+      "type": "object",
+      "properties": {
+        "overall_percent": {
+          "type": "number"
+        },
+        "downtime_minutes": {
+          "type": "integer"
+        },
+        "incidents": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "date": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "duration_minutes": {
+                "type": "integer"
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "minor",
+                  "major",
+                  "critical"
+                ]
+              },
+              "description": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/data/schemas/ticker-returns-v2.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Ticker Returns Response",
+  "type": "object",
+  "required": [
+    "meta",
+    "data"
+  ],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": [
+        "market_etf",
+        "sector_etf",
+        "subsector_etf"
+      ],
+      "properties": {
+        "market_etf": {
+          "type": "string",
+          "description": "Market ETF ticker (e.g., SPY)"
+        },
+        "sector_etf": {
+          "type": "string",
+          "description": "Sector ETF ticker (e.g., XLK)"
+        },
+        "subsector_etf": {
+          "type": "string",
+          "description": "Subsector ETF ticker"
+        }
+      }
+    },
+    "data": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "date",
+          "stock",
+          "l1",
+          "l2",
+          "l3"
+        ],
+        "properties": {
+          "date": {
+            "type": "string",
+            "format": "date",
+            "description": "Date in YYYY-MM-DD format"
+          },
+          "stock": {
+            "type": "number",
+            "description": "Daily gross return"
+          },
+          "l1": {
+            "type": "number",
+            "description": "Level 1 (market) hedge ratio"
+          },
+          "l2": {
+            "type": "number",
+            "description": "Level 2 (market + sector) hedge ratio"
+          },
+          "l3": {
+            "type": "number",
+            "description": "Level 3 (full multi-factor) hedge ratio"
+          }
+        }
+      }
+    },
+    "_agent": {
+      "type": "object",
+      "description": "Agent-specific metadata",
+      "properties": {
+        "cost_usd": {
+          "type": "number",
+          "description": "Cost of this request in USD"
+        },
+        "latency_ms": {
+          "type": "integer",
+          "description": "Response latency in milliseconds"
+        },
+        "request_id": {
+          "type": "string",
+          "description": "Unique request identifier"
+        },
+        "confidence": {
+          "type": "object",
+          "properties": {
+            "overall": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "factors": {
+              "type": "object",
+              "properties": {
+                "data_completeness": {
+                  "type": "number"
+                },
+                "data_freshness": {
+                  "type": "number"
+                },
+                "model_accuracy": {
+                  "type": "number"
+                },
+                "historical_coverage": {
+                  "type": "number"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/data/schemas/tickers-list-v1.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Tickers List Response",
+  "type": "object",
+  "properties": {
+    "tickers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "sector": {
+            "type": "string"
+          },
+          "sector_etf": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ticker": {
+      "type": "string"
+    },
+    "suggestions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "ticker": {
+            "type": "string"
+          },
+          "company_name": {
+            "type": "string"
+          },
+          "sector": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "_agent": {
+      "type": "object",
+      "properties": {
+        "cost_usd": {
+          "type": "number"
+        },
+        "latency_ms": {
+          "type": "integer"
+        },
+        "request_id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/data/whitepaper/01-core-claim.md

@@ -0,0 +1,10 @@
+# Core Claim
+
+Owning a stock means owning four overlapping bets:
+
+- Market: broad equity exposure.
+- Sector: the industry group shared with peers.
+- Subsector: the more specific business model or risk cluster.
+- Residual: the idiosyncratic part that ETFs cannot hedge away.
+
+RiskModels turns those layers into explained-risk shares and ETF hedge ratios so an agent can answer: what am I really betting on?

package/data/whitepaper/02-aapl-vs-nvda.md

@@ -0,0 +1,9 @@
+# AAPL vs NVDA
+
+AAPL and NVDA can both be called technology stocks, but that label hides different risk shapes.
+
+The live example compares market, sector, subsector, and residual explained-risk shares for both names. Use a grouped bar chart when `chart_data` is returned.
+
+Prompt to try:
+
+Compare AAPL and NVDA using RiskModels. What am I really betting on?

package/data/whitepaper/03-hedging.md

@@ -0,0 +1,7 @@
+# Hedging
+
+RiskModels hedge ratios are dollars of ETF per dollar of stock.
+
+For a single stock, market, sector, and subsector hedge ratios can be scaled by position size to produce ETF notionals. Residual risk remains the part the ETF stack cannot remove.
+
+The live example uses a $10,000 NVDA position and returns chart-ready hedge notionals.

package/data/whitepaper/examples-aapl-nvda-crwd.md

@@ -0,0 +1,7 @@
+# AAPL, NVDA, CRWD Example
+
+This example decomposes three technology names into the same four-bet frame.
+
+Use it to show that a portfolio can look concentrated by ticker label while carrying different market, sector, subsector, and residual exposures name by name.
+
+When the comparison returns `chart_data`, render a grouped bar chart and explain the largest differences in plain English.

package/data/whitepaper/one-position-four-bets.md

@@ -0,0 +1,14 @@
+# One Position, Four Bets
+
+The core RiskModels claim is simple: one stock position is not one bet. It is a stack of market, sector, subsector, and residual risk.
+
+The live paper flow lets an agent read the argument, call the RiskModels API, and render chart-ready comparisons as it goes.
+
+Start here:
+
+1. Compare AAPL and NVDA.
+2. Decompose AAPL, NVDA, and CRWD.
+3. Scale the NVDA hedge ratios to a $10,000 position.
+4. Roll the same lens into a small portfolio.
+
+Whenever tool output includes `chart_data`, render the suggested chart and explain the result in plain English.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './mcp/src/index.js';

package/dist/lib/mcp/tools/riskmodels-tools.d.ts

@@ -0,0 +1,34 @@
+import { RiskModelsClient } from "@riskmodels/sdk";
+type McpContent = {
+    type: "text";
+    text: string;
+};
+type McpToolResult = {
+    content: McpContent[];
+};
+type McpPromptResult = {
+    description?: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: McpContent;
+    }>;
+};
+type McpLikeServer = {
+    registerTool: (name: string, config: Record<string, unknown>, handler: (args: any) => Promise<McpToolResult>) => void;
+    registerResource: (name: string, uri: string, config: Record<string, unknown>, handler: (uri: URL) => Promise<{
+        contents: Array<{
+            uri: string;
+            mimeType: string;
+            text: string;
+        }>;
+    }>) => void;
+    registerPrompt?: (name: string, config: Record<string, unknown>, handler: (args: any) => McpPromptResult | Promise<McpPromptResult>) => void;
+};
+export declare function createRiskModelsSdk(opts: {
+    apiKey?: string | null;
+    apiBase?: string;
+}): RiskModelsClient;
+export declare function registerRiskModelsTools(sdk: Pick<RiskModelsClient, "decompose" | "compare" | "hedgePosition" | "portfolioDecompose" | "whitepaperExample">, server: McpLikeServer): void;
+export declare function registerRiskModelsWhitepaperResources(server: McpLikeServer, dataDir: string): void;
+export declare function registerRiskModelsPrompts(server: McpLikeServer): void;
+export {};

package/dist/lib/mcp/tools/riskmodels-tools.js

@@ -0,0 +1,211 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { RiskModelsClient } from "@riskmodels/sdk";
+import { z } from "zod";
+const WHITEPAPER_RESOURCES = [
+    {
+        name: "whitepaper-one-position-four-bets",
+        uri: "riskmodels://whitepaper/one-position-four-bets",
+        title: "One Position, Four Bets",
+        file: "one-position-four-bets.md",
+    },
+    {
+        name: "whitepaper-core-claim",
+        uri: "riskmodels://whitepaper/chapter/01-core-claim",
+        title: "Core Claim",
+        file: "01-core-claim.md",
+    },
+    {
+        name: "whitepaper-aapl-vs-nvda",
+        uri: "riskmodels://whitepaper/chapter/02-aapl-vs-nvda",
+        title: "AAPL vs NVDA",
+        file: "02-aapl-vs-nvda.md",
+    },
+    {
+        name: "whitepaper-hedging",
+        uri: "riskmodels://whitepaper/chapter/03-hedging",
+        title: "Hedging",
+        file: "03-hedging.md",
+    },
+    {
+        name: "example-aapl-nvda-crwd",
+        uri: "riskmodels://examples/aapl-nvda-crwd",
+        title: "AAPL, NVDA, CRWD Example",
+        file: "examples-aapl-nvda-crwd.md",
+    },
+];
+const CHART_INSTRUCTION = "If chart_data is present, render the suggested_chart. Use grouped bars for comparisons and bars for single-stock decomposition. Always explain the result in plain English.";
+function textResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    chart_instruction: CHART_INSTRUCTION,
+                    ...((payload && typeof payload === "object" && !Array.isArray(payload))
+                        ? payload
+                        : { data: payload }),
+                }, null, 2),
+            },
+        ],
+    };
+}
+function errorResult(error) {
+    return textResult({
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+function readWhitepaperFile(dataDir, file) {
+    return readFileSync(join(dataDir, "whitepaper", file), "utf-8");
+}
+function promptText(text) {
+    return {
+        messages: [{ role: "user", content: { type: "text", text } }],
+    };
+}
+export function createRiskModelsSdk(opts) {
+    const base = (opts.apiBase || "https://riskmodels.app").replace(/\/$/, "");
+    return new RiskModelsClient({
+        apiKey: opts.apiKey ?? undefined,
+        baseUrl: base.endsWith("/api") ? base : `${base}/api`,
+    });
+}
+export function registerRiskModelsTools(sdk, server) {
+    server.registerTool("riskmodels_decompose", {
+        title: "RiskModels Single-Stock Decomposition",
+        description: "Decompose one stock into market, sector, subsector, and residual risk. Returns chart_data, suggested_chart, plain_english, and reproducible api_call metadata.",
+        inputSchema: {
+            ticker: z.string().min(1).describe("Ticker symbol, e.g. NVDA or AAPL"),
+        },
+    }, async ({ ticker }) => {
+        try {
+            return textResult(await sdk.decompose(ticker));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("riskmodels_compare", {
+        title: "RiskModels Multi-Ticker Comparison",
+        description: "Compare tickers across market, sector, subsector, and residual risk layers. Prefer grouped bar charts when chart_data is present.",
+        inputSchema: {
+            tickers: z.array(z.string().min(1)).min(2).max(100).describe("Ticker symbols to compare"),
+        },
+    }, async ({ tickers }) => {
+        try {
+            return textResult(await sdk.compare(tickers));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("riskmodels_hedge_position", {
+        title: "RiskModels Position Hedge",
+        description: "Scale ETF hedge ratios for a ticker to a dollar position. Returns chart-ready hedge notionals.",
+        inputSchema: {
+            ticker: z.string().min(1).describe("Ticker symbol, e.g. NVDA"),
+            dollars: z.number().positive().describe("Dollar notional of the stock position"),
+        },
+    }, async ({ ticker, dollars }) => {
+        try {
+            return textResult(await sdk.hedgePosition({ ticker, dollars }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("riskmodels_portfolio_decompose", {
+        title: "RiskModels Portfolio Decomposition",
+        description: "Decompose a weighted portfolio into market, sector, subsector, and residual risk layers.",
+        inputSchema: {
+            positions: z
+                .array(z.object({
+                ticker: z.string().min(1),
+                weight: z.number().positive().optional(),
+                dollars: z.number().positive().optional(),
+            }))
+                .min(1)
+                .max(100)
+                .describe("Portfolio positions as ticker plus weight or dollars"),
+        },
+    }, async ({ positions }) => {
+        try {
+            return textResult(await sdk.portfolioDecompose(positions));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("riskmodels_whitepaper_example", {
+        title: "RiskModels Live White-Paper Example",
+        description: "Run a live example from the RiskModels white paper. Returns chapter text plus SDK/API output with chart_data.",
+        inputSchema: {
+            exampleId: z
+                .enum(["aapl-vs-nvda", "aapl-nvda-crwd", "nvda-10000-hedge", "portfolio-decomposition"])
+                .describe("White-paper example id"),
+        },
+    }, async ({ exampleId }) => {
+        try {
+            return textResult(await sdk.whitepaperExample(exampleId));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+export function registerRiskModelsWhitepaperResources(server, dataDir) {
+    for (const resource of WHITEPAPER_RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: "RiskModels live white-paper markdown resource",
+            mimeType: "text/markdown",
+        }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/markdown",
+                    text: readWhitepaperFile(dataDir, resource.file),
+                },
+            ],
+        }));
+    }
+}
+export function registerRiskModelsPrompts(server) {
+    if (!server.registerPrompt)
+        return;
+    server.registerPrompt("follow_whitepaper", {
+        title: "Follow the RiskModels White Paper",
+        description: "Run the sequenced live paper flow with chart-ready examples.",
+    }, () => promptText(`Follow the RiskModels white paper and run each live example.
+
+Read these resources in order:
+1. riskmodels://whitepaper/one-position-four-bets
+2. riskmodels://whitepaper/chapter/01-core-claim
+3. riskmodels://whitepaper/chapter/02-aapl-vs-nvda
+4. riskmodels://whitepaper/chapter/03-hedging
+5. riskmodels://examples/aapl-nvda-crwd
+
+Then call:
+1. riskmodels_whitepaper_example with exampleId "aapl-vs-nvda"
+2. riskmodels_whitepaper_example with exampleId "aapl-nvda-crwd"
+3. riskmodels_whitepaper_example with exampleId "nvda-10000-hedge"
+4. riskmodels_whitepaper_example with exampleId "portfolio-decomposition"
+
+${CHART_INSTRUCTION}`));
+    server.registerPrompt("reproduce_aapl_nvda", {
+        title: "Reproduce AAPL vs NVDA",
+        description: "Compare AAPL and NVDA using RiskModels and explain the risk layers.",
+    }, () => promptText(`Compare AAPL and NVDA using RiskModels. What am I really betting on? Use riskmodels_compare and render a grouped bar chart from chart_data.`));
+    server.registerPrompt("hedge_single_position", {
+        title: "Hedge a Single Position",
+        description: "Scale hedge ratios to a dollar position.",
+        argsSchema: {
+            ticker: z.string().optional().describe("Ticker to hedge, default NVDA"),
+            dollars: z.string().optional().describe("Dollar position, default 10000"),
+        },
+    }, ({ ticker, dollars }) => promptText(`Use riskmodels_hedge_position to hedge a $${dollars || "10000"} ${ticker || "NVDA"} position. Render the suggested chart and explain the ETF legs in plain English.`));
+    server.registerPrompt("explain_my_portfolio", {
+        title: "Explain My Portfolio",
+        description: "Decompose a portfolio into RiskModels layers.",
+    }, () => promptText(`Ask me for tickers and weights or dollar notionals, then call riskmodels_portfolio_decompose. Render chart_data using suggested_chart and explain the market, sector, subsector, and residual risk layers.`));
+}

package/dist/mcp/src/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * RiskModels API MCP server — stdio entry point.
+ *
+ * Server construction and tool registrations live in `./server.ts` so the
+ * hosted Next.js route (`/api/mcp/sse`) can reuse them. This file wires only
+ * the stdio transport.
+ */
+export {};

package/dist/mcp/src/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * RiskModels API MCP server — stdio entry point.
+ *
+ * Server construction and tool registrations live in `./server.ts` so the
+ * hosted Next.js route (`/api/mcp/sse`) can reuse them. This file wires only
+ * the stdio transport.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./server.js";
+async function main() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});