diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ea64cfec7..1149ba85e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -118,6 +118,12 @@ "source": "./plugins/partner-built/spglobal", "description": "S&P Global - Financial data and analytics skills including company tearsheets, earnings previews, and transaction summaries" }, + { + "name": "riskmodels", + "displayName": "RiskModels", + "source": "./plugins/partner-built/riskmodels", + "description": "Decompose US equity and portfolio risk into market, sector, subsector, and stock-specific components with tradeable ETF hedge ratios, pull point-in-time fundamentals with a CAPM cost-of-capital layer, and rank names on residual risk using the hosted RiskModels MCP." + }, { "name": "claude-for-msft-365-install", "displayName": "Claude for Microsoft 365 Install", diff --git a/plugins/partner-built/riskmodels/.claude-plugin/plugin.json b/plugins/partner-built/riskmodels/.claude-plugin/plugin.json new file mode 100644 index 000000000..6e038fbc0 --- /dev/null +++ b/plugins/partner-built/riskmodels/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "riskmodels", + "version": "1.0.0", + "description": "Decompose US equity and portfolio risk into market, sector, subsector, and stock-specific components with tradeable ETF hedge ratios, pull point-in-time quarterly fundamentals with a CAPM cost-of-capital layer, and rank names on residual risk — via the hosted RiskModels MCP. Realized/historical analytics; not investment advice.", + "author": { + "name": "RiskModels (Blue Water Macro Corp.)" + } +} diff --git a/plugins/partner-built/riskmodels/.mcp.json b/plugins/partner-built/riskmodels/.mcp.json new file mode 100644 index 000000000..286de3f15 --- /dev/null +++ b/plugins/partner-built/riskmodels/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "riskmodels": { + "type": "http", + "url": "https://riskmodels.app/api/mcp/sse", + "headers": { + "Authorization": "Bearer ${RISKMODELS_API_KEY}" + } + } + } +} diff --git a/plugins/partner-built/riskmodels/CONNECTORS.md b/plugins/partner-built/riskmodels/CONNECTORS.md new file mode 100644 index 000000000..6dc9ded51 --- /dev/null +++ b/plugins/partner-built/riskmodels/CONNECTORS.md @@ -0,0 +1,59 @@ +# Connectors + +This plugin connects to the **RiskModels MCP Server** (`https://riskmodels.app/api/mcp/sse`), +a single hosted MCP that serves US equity factor-risk, point-in-time fundamentals, +cost of capital, and hedging tools — no additional connectors are needed. Unlike the +licensed-terminal connectors elsewhere in this repo, RiskModels is a hosted service +billed per call (free tier available); a key is set via `RISKMODELS_API_KEY`. + +## How Skills Reference Tools + +Skills reference MCP tools by their exact tool name (e.g. `riskmodels_decompose`, +`riskmodels_get_fundamentals`). The tools are grouped into categories below. + +## Tool Categories + +| Category | Tools | Description | +|----------|-------|-------------| +| Risk Decomposition | `riskmodels_get_hedge_levels`, `riskmodels_decompose`, `get_metrics`, `riskmodels_portfolio_decompose` | L1/L2/L3 market/sector/subsector/residual decomposition with ETF hedge ratios | +| Fundamentals | `riskmodels_get_fundamentals` | Point-in-time quarterly fundamentals, ratios, CAPM cost-of-capital layer, SEC-sourced raw line items | +| Hedging | `riskmodels_hedge_position`, `riskmodels_hedge_portfolio`, `riskmodels_analyze_portfolio`, `riskmodels_get_lstar`, `riskmodels_batch_lstar` | Scale ETF hedge legs to notionals; Lstar residual isolation | +| Rankings & Signals | `riskmodels_get_rankings`, `riskmodels_screen_rankings`, `riskmodels_get_residual_signal` | Cross-sectional percentile ranks; residual mean-reversion signal | +| Return Attribution | `riskmodels_get_return_attribution`, `riskmodels_get_returns` | Daily return split into L1/L2/L3 factor + residual components | +| Discovery | `riskmodels_search_tickers`, `riskmodels_search_etfs`, `riskmodels_get_etf_holdings`, `riskmodels_search_filers`, `riskmodels_get_filer_holdings` | Resolve names/symbols; fetch real ETF and 13F-filer holdings | +| Capabilities | `riskmodels_list_endpoints`, `riskmodels_get_capability` | Enumerate the live capability surface (free) | + +## Complete Tool Reference + +### Risk Decomposition +- **`riskmodels_get_hedge_levels`** — L1/L2/L3 hedge snapshots side by side: hedge ratios (`*_hr`), explained-risk fractions (`*_er`), and the ETF legs (market/sector/subsector) at each depth. +- **`riskmodels_decompose`** — L3 four-bet decomposition (market / sector / subsector / residual) for one name. +- **`get_metrics`** — latest snapshot: hedge ratios, ER fractions, volatility, close, market cap. +- **`riskmodels_portfolio_decompose`** — decompose a weighted portfolio into the four layers. + +### Fundamentals +- **`riskmodels_get_fundamentals`** — point-in-time quarterly fundamentals: rows visible only where `filed_date <= as_of`. Returns TTM profitability and capital-return ratios, leverage, ERM3 cascade betas, a CAPM cost-of-capital layer (`cost_of_equity`, `wacc`, `economic_profit`; caller `erp` / `rf_tenor`, `grid=true` for sensitivity), an equity-bridge decomposition, and `sec_facts` — raw line items per cell where the serving value is SEC XBRL. + +### Hedging +- **`riskmodels_hedge_position`** — scale one ticker's ETF hedge ratios to a dollar position. +- **`riskmodels_hedge_portfolio`** — hedge ratios at L1/L2/L3, scaled by notionals, aggregated into ETF USD legs for a book. +- **`riskmodels_analyze_portfolio`** — holdings-weighted L1/L2/L3 hedge-level aggregate. +- **`riskmodels_get_lstar`** / **`riskmodels_batch_lstar`** — dispatch the simplest cascade level clearing the marginal-ER threshold; return residual-return series (single / up to 100 tickers). + +### Rankings & Signals +- **`riskmodels_get_rankings`** — where a name sits in its sector/universe percentile for a metric. +- **`riskmodels_screen_rankings`** — full cross-section percentile/decile rank screen, server-side. +- **`riskmodels_get_residual_signal`** — aggregate L3 residual mean-reversion signal across a basket. + +### Return Attribution +- **`riskmodels_get_return_attribution`** — daily gross return split into additive L1/L2/L3 factor, combined-factor, and residual return series. +- **`riskmodels_get_returns`** — daily returns with L1/L2/L3 hedge ratios and risk decomposition. + +### Discovery +- **`riskmodels_search_tickers`** — search tickers by symbol or company name. +- **`riskmodels_search_etfs`** / **`riskmodels_get_etf_holdings`** — resolve an ETF and fetch its holdings. +- **`riskmodels_search_filers`** / **`riskmodels_get_filer_holdings`** — resolve a 13F filer (by name / CIK / LEI) and fetch its top holdings. + +### Capabilities +- **`riskmodels_list_endpoints`** — enumerate the live public capability surface (free). +- **`riskmodels_get_capability`** — full details for one capability by id (free). diff --git a/plugins/partner-built/riskmodels/README.md b/plugins/partner-built/riskmodels/README.md new file mode 100644 index 000000000..f095ffe55 --- /dev/null +++ b/plugins/partner-built/riskmodels/README.md @@ -0,0 +1,68 @@ +# RiskModels Equity Risk Plugin + +Decompose US equity and portfolio risk, pull point-in-time fundamentals, and compute a +CAPM cost of capital using the hosted **RiskModels** MCP — a subscription-light data +source that can stand in for a licensed-terminal connector in equity-risk and valuation +workflows. + +## What This Plugin Does + +This plugin packages the RiskModels MCP tools into equity-analysis skills that stitch +together multiple tool calls: decompose a name or book into market / sector / subsector / +stock-specific risk with tradeable ETF hedge ratios, build hedge legs scaled to +notionals, and compute cost of equity / WACC / economic profit from point-in-time +fundamentals. It is the equity-risk analog of this repo's fixed-income partner analytics. + +## The swap thesis + +Every data MCP elsewhere in this repo points at a licensed terminal +(`${FACTSET_MCP_URL}`, `${CAPIQ_MCP_URL}`, and peers). RiskModels is a single hosted +MCP — point a `.mcp.json` server entry (or a `data-puller` env var) at +`https://riskmodels.app/api/mcp/sse` to source equity risk decomposition, PIT +fundamentals, and cost of capital without an enterprise data license. Install is free; +usage is billed per call, from $0.005. + +## Skills + +| Skill | Domain knowledge | +|-------|-----------------| +| `equity-risk-decomposition` | ERM3 L1/L2/L3 cascade, explained-risk attribution, ETF hedge-ratio framing, residual (idiosyncratic) risk | +| `cost-of-capital` | CAPM cost of equity, book-weight WACC, economic profit, caller-supplied ERP and rf-tenor sensitivity | +| `portfolio-hedge` | ETF hedge-leg construction scaled to notionals, Lstar residual isolation, real-holdings resolution | + +## Integrations + +This plugin connects to the **RiskModels MCP Server**, which serves US equity +factor-risk, fundamentals, cost-of-capital, and hedging tools across these domains: + +- **Risk Decomposition** — L1/L2/L3 market / sector / subsector / residual with ETF hedge ratios +- **Fundamentals** — point-in-time quarterly ratios, CAPM cost-of-capital layer, SEC-sourced raw line items +- **Hedging** — position and portfolio ETF hedge legs; Lstar residual isolation +- **Rankings & Signals** — cross-sectional ranks and the residual mean-reversion signal +- **Return Attribution** — daily return split into L1/L2/L3 factor + residual components + +See [CONNECTORS.md](CONNECTORS.md) for the complete tool reference. + +## Requirements + +- A RiskModels API key (free tier available; usage billed per call). Get one at + **https://riskmodels.app/get-key**. +- Set it in your environment before use: + + ```bash + export RISKMODELS_API_KEY="rm_agent_live_..." + ``` + + The bundled `.mcp.json` reads `${RISKMODELS_API_KEY}` as a Bearer token. + +## Data scope and disclaimers + +- **PIT-normalized fundamentals derived from SEC filings and licensed sources.** Raw + line items are exposed per cell only where the serving value is SEC XBRL (`sec_facts`); + other cells are derived. The panel is not a full raw-fundamentals feed. +- **Cost of capital is CAPM** (risk-free at the chosen tenor + conditional market beta × + caller-supplied ERP); the ERP is never assumed. WACC uses book-value weights. +- **Realized/historical analytics only.** These skills report model outputs — + decomposition, hedge ratios, ranks, cost of capital — as analyst work product staged + for human sign-off. RiskModels is an analytical tool, **not an investment adviser**: + nothing here is a recommendation, price target, or suitability assessment. diff --git a/plugins/partner-built/riskmodels/skills/cost-of-capital/SKILL.md b/plugins/partner-built/riskmodels/skills/cost-of-capital/SKILL.md new file mode 100644 index 000000000..9ba3e49c2 --- /dev/null +++ b/plugins/partner-built/riskmodels/skills/cost-of-capital/SKILL.md @@ -0,0 +1,71 @@ +--- +name: cost-of-capital +description: Compute a CAPM cost of equity, cost of debt, book-weight WACC, and economic profit for a US equity from its point-in-time fundamentals, with the equity risk premium and risk-free tenor supplied by the caller and an ERP × rf-tenor sensitivity grid. Use when a model or analysis needs a name's WACC, cost of equity, hurdle rate, or economic profit instead of a licensed-terminal input. +--- + +# Cost of Capital (CAPM) + +You are a valuation analyst. Use the RiskModels MCP to produce a name's cost of capital +from its point-in-time fundamentals — a hosted, subscription-light substitute for a +licensed-terminal WACC input in a DCF or comps build. Cost of equity is CAPM: the +risk-free rate at the chosen tenor plus the ERM3 conditional market beta times the +caller-supplied equity risk premium. Let the tool compute; you supply the assumptions +and interpret. + +## Core Principles + +Cost of capital is only as meaningful as its assumptions, so surface them every time. +The equity risk premium is **always caller-supplied** — never assume or hardcode one; +if the caller has not fixed an ERP, report across the sensitivity grid. WACC here uses +book-value weights; the textbook convention is market-value weights, so say which you +are reporting. This is a CAPM cost of capital — do not describe any layered or +factor-decomposed cost-of-capital methodology. + +## Available MCP Tools + +- **`riskmodels_get_fundamentals`** — the cost-of-capital layer rides on this tool. + Parameters that matter here: + - **`erp`** — equity risk premium. Caller-supplied; state it in every answer. + - **`rf_tenor`** — Treasury constant-maturity tenor (`3m|1y|2y|5y|10y|30y`, default + `10y`, the long-duration valuation convention). + - **`tax_rate`** — applied to the WACC debt shield (default 0.21). + - **`grid=true`** with `erp_grid` / `rf_tenor_grid` — returns the sensitivity table of + `cost_of_equity` / `wacc` / `economic_profit` across every ERP × tenor cell. +- **`riskmodels_search_tickers`** — resolve a company name to a ticker first. + +## Tool Chaining Workflow + +1. **Resolve the symbol** if a name was given (`riskmodels_search_tickers`). +2. **Fix the assumptions:** get the ERP and tenor from the caller. If no ERP is given, + plan to use `grid=true` and report the range. +3. **Call `riskmodels_get_fundamentals`** with `erp`, `rf_tenor`, `tax_rate` (and + `grid=true` for the sensitivity table). Extract `cost_of_equity`, `cost_of_debt`, + `wacc`, `economic_profit`, and the `rf_rate` used. +4. **Interpret:** report the scalar (or grid), always naming the ERP, tenor, and tax rate. + +## Output Format + +### Cost of Capital (state ERP, rf_tenor, tax_rate used) +| Metric | Value | +|--------|-------| +| Risk-free rate (tenor) | ... | +| Cost of equity (CAPM) | ... | +| Cost of debt | ... | +| WACC (book weights) | ... | +| Economic profit | ... | + +### Sensitivity (when `grid=true`) +A table of WACC / cost of equity across the `erp_grid` × `rf_tenor_grid` cells. + +### Notes +Because `beta_market` is a short-half-life conditional beta, a defensive name's cost of +equity can sit below the risk-free rate — a property of the beta, not an error; state it +plainly. Flag that WACC uses book-value weights (recompute with market weights if you +have market caps), and that a short `rf_tenor` should be paired with a bill-basis ERP. + +## Boundary + +These are model outputs from realized fundamentals and caller-supplied assumptions — +not a valuation opinion, price target, or recommendation. RiskModels is an analytical +tool, not an investment adviser. Always state the assumptions behind any number and call +the tool before quoting figures. diff --git a/plugins/partner-built/riskmodels/skills/equity-risk-decomposition/SKILL.md b/plugins/partner-built/riskmodels/skills/equity-risk-decomposition/SKILL.md new file mode 100644 index 000000000..cb11b88fc --- /dev/null +++ b/plugins/partner-built/riskmodels/skills/equity-risk-decomposition/SKILL.md @@ -0,0 +1,77 @@ +--- +name: equity-risk-decomposition +description: Decompose a US equity's or portfolio's risk into market, sector, subsector, and stock-specific (residual) components with the tradeable ETF hedge ratios each layer implies, using the RiskModels ERM3 cascade. Use when analyzing what is driving a name's risk, how idiosyncratic it is, what an ETF hedge of a given leg would neutralize, or how a book's risk aggregates. +--- + +# Equity Risk Decomposition (ERM3 cascade) + +You are an equity risk analyst. Combine the RiskModels MCP tools to decompose a US +stock or portfolio into a nested factor cascade — market → +sector → +subsector → +residual — and report the ETF hedge ratios each layer implies. Let the tools compute; +you route their outputs into the decomposition table and synthesize the read. This is +the equity analog of a fixed-income spread decomposition: the residual (what's left +after market, sector, and subsector) is the stock-specific component. + +## Core Principles + +Risk decomposition is about *where a name's variance lives* and *what would +mechanically neutralize each layer*. Always read the explained-risk fractions (`*_er`, +which sum to ~1.0 at L3), not the signs of the hedge ratios, to attribute variance. A +high residual fraction means most of the risk is idiosyncratic and not hedgeable with +sector/market ETFs. Hedge ratios are model outputs (dollars of an ETF leg that +neutralize $1 of a layer), like a beta — report them as math, never as a trade. + +## Available MCP Tools + +- **`riskmodels_get_hedge_levels`** — L1/L2/L3 hedge snapshots side by side: hedge + ratios (`*_hr`), explained-risk fractions (`*_er`), and the ETF legs at each depth. +- **`riskmodels_decompose`** — the L3 four-bet decomposition (market / sector / + subsector / residual) for a single name. +- **`get_metrics`** — latest snapshot (hedge ratios, ER fractions, vol, close, market cap). +- **`riskmodels_portfolio_decompose`** — decompose a weighted portfolio into the four layers. +- **`riskmodels_search_tickers`** — resolve a company name to a ticker first. +- **`riskmodels_get_return_attribution`** — daily return split into additive L1/L2/L3 + factor + residual components (optional, for return- rather than risk-attribution). + +## Tool Chaining Workflow + +1. **Resolve the symbol:** if given a company name, call `riskmodels_search_tickers`. +2. **Pull the cascade:** call `riskmodels_get_hedge_levels` (single name) or + `riskmodels_portfolio_decompose` (weighted book). Extract `*_er` and `*_hr` at L1/L2/L3 + and the ETF legs (`hedge_etfs`: market/sector/subsector). +3. **Read where variance lives:** at L3, use `l3_mkt_er`, `l3_sec_er`, `l3_sub_er`, + `l3_res_er` (they sum to ~1.0). The residual fraction is the idiosyncratic share. +4. **Frame the hedge legs:** scale each ETF leg's hedge ratio into "what $1 of position + would need" — e.g. "$0.94 of SPY neutralizes the market leg." +5. **Synthesize:** state where the risk sits and what each leg would neutralize. + +## Output Format + +### Risk Decomposition (explained-risk fractions) +| Level | Market ER | Sector ER | Subsector ER | Residual ER | ETF legs | +|-------|-----------|-----------|--------------|-------------|----------| +| L1 | ... | — | — | ... | SPY | +| L2 | ... | ... | — | ... | SPY, sector | +| L3 | ... | ... | ... | ... | SPY, sector, subsector | + +### Hedge Legs (L3) +| Leg | ETF | Hedge ratio | Neutralizes | +|-----|-----|-------------|-------------| +| Market | SPY | ... | $X of SPY per $1 of position | +| Sector | (e.g. XLK) | ... | ... | +| Subsector | (e.g. SMH) | ... | ... | + +### Read +State where the variance sits (market vs sector vs stock-specific), how idiosyncratic +the name is (residual ER), and what each ETF leg would mechanically neutralize. A +negative market hedge ratio is **not** "negative market exposure": at L2/L3 the sector +and subsector legs already carry market beta, and the SPY leg offsets what is embedded +in them (orthogonalization) — never infer market stance from the sign of `l3_market_hr`. + +## Boundary + +RiskModels is an analytical tool, not an investment adviser. Report the decomposition, +ranks, and what each hedge leg would neutralize — never a recommendation to buy, sell, +hedge, trim, or rebalance, and never a suitability assessment. No options, swaps, or +derivatives — ETF legs only. Always call the tools before quoting any figure; never +invent numbers. diff --git a/plugins/partner-built/riskmodels/skills/portfolio-hedge/SKILL.md b/plugins/partner-built/riskmodels/skills/portfolio-hedge/SKILL.md new file mode 100644 index 000000000..4b80da689 --- /dev/null +++ b/plugins/partner-built/riskmodels/skills/portfolio-hedge/SKILL.md @@ -0,0 +1,65 @@ +--- +name: portfolio-hedge +description: Build ETF hedge legs for a single position or a multi-name US equity portfolio from the ERM3 cascade — scale the market / sector / subsector hedge ratios to dollar notionals and aggregate the ETF legs, or dispatch the Lstar level that isolates a position's residual return. Use when analyzing what would neutralize a book's market or sector exposure, or how to isolate idiosyncratic return, staged for human sign-off. +--- + +# Portfolio & Position Hedging (ERM3 cascade + Lstar) + +You are a portfolio risk analyst. Use the RiskModels MCP to report the ETF hedge legs +the cascade decomposition implies for a position or book, scaled to dollar notionals. +Let the tools compute the ratios; you aggregate and present. Hedge construction here is +analytical work product staged for human sign-off — not an instruction to trade. + +## Core Principles + +A hedge ratio is a model output, like a beta: the dollars of an ETF leg that +mechanically neutralize $1 of a given layer of risk. Present the aggregate ETF legs for +the book and what each would neutralize; the decision to act is the user's. Negative +hedge ratios are valid (orthogonalization) — a negative market leg usually offsets beta +already embedded in the sector/subsector legs, not a short-macro bet. + +## Available MCP Tools + +- **`riskmodels_hedge_position`** — one ticker: scale the L-level ETF hedge ratios to a + dollar position. +- **`riskmodels_hedge_portfolio`** — a weighted book: hedge ratios at the chosen cascade + level (L1/L2/L3), scaled by notionals and aggregated into ETF USD hedge legs. +- **`riskmodels_analyze_portfolio`** — holdings-weighted L1/L2/L3 hedge-level aggregate. +- **`riskmodels_get_lstar`** / **`riskmodels_batch_lstar`** — dispatch the simplest + cascade level that clears the marginal-ER threshold and return the residual-return + series after that hedge. +- **Real holdings** (if an entity is named instead of pasted tickers): + `riskmodels_search_etfs` → `riskmodels_get_etf_holdings`, or `riskmodels_search_filers` + → `riskmodels_get_filer_holdings`. Never fabricate or approximate holdings — if no tool + covers the portfolio, say so and ask for the positions. + +## Tool Chaining Workflow + +1. **Assemble the book:** take pasted `TICKER:WEIGHT` positions, or resolve real + holdings for a named ETF/filer with the tools above. +2. **Choose the cascade level** (L1 market-only, L2 +sector, L3 +subsector). +3. **Scale the legs:** call `riskmodels_hedge_portfolio` (or `riskmodels_hedge_position` + for one name) with notionals; aggregate each ETF leg into a single USD figure. +4. **Isolate residual (optional):** call `riskmodels_get_lstar` for a name to get the + dispatched level and the residual-return series. +5. **Present** the aggregate legs and what each neutralizes. + +## Output Format + +### Aggregate Hedge Legs (level Lx, $ notional) +| ETF leg | Role | USD hedge | Neutralizes | +|---------|------|-----------|-------------| +| SPY | Market | ... | market layer of the book | +| (sector ETFs) | Sector | ... | ... | +| (subsector ETFs) | Subsector | ... | ... | + +### Residual note +If residual ER is high, state that the leftover is stock-specific and not hedgeable with +sector/market ETFs. + +## Boundary + +RiskModels is an analytical tool, not an investment adviser. Report what each hedge leg +would mechanically neutralize — never tell the user to place, trim, or rebalance a trade, +and never assess whether the book is suitable for them. ETF legs only; no options, swaps, +or derivatives. Always call the tools before quoting figures; never invent numbers.