RiskModels

Descomposición de riesgo de acciones y carteras de EE. UU. (mercado, sector, subsector y específico de acciones), ratios de cobertura de ETF y fundamentos puntuales del modelo de factores RiskModels. MCP alojado con OAuth, o el paquete npm stdio.

GitHub

Servidor MCP alojado

npx add-mcp 'https://riskmodels.app/api/mcp/sse'

Se instala en Claude Code, Codex, Cursor y más

Documentación

RiskModels proporciona retornos totales ajustados por dividendos y divisiones de acciones, descomposición de riesgo por factores, atribución de retornos y ratios de cobertura ejecutables mediante ETFs para acciones estadounidenses, todo a través de REST, un SDK tipado y un servidor MCP integrado. El conjunto de datos es de grado de simulación: cubre alrededor de 16,000 acciones estadounidenses en todo el panel histórico, mientras que al final de cada mes, el universo principal del modelo es el de las ~3,000 más grandes por capitalización de mercado, que es el conjunto que la API expone para retornos, riesgo y cobertura en el uso diario.

Los resultados posteriores a la regresión (ratios de cobertura, descomposiciones de riesgo explicado y series L1–L3 relacionadas) se sirven desde la primera fecha cuya ventana de estimación completa está cubierta: ratios de cobertura desde 2010-12-08, participaciones de riesgo explicado y varianza de acciones desde 2011-12-07, niveles residuales L* desde 2013-01-01. Los retornos ajustados por divisiones y dividendos (los insumos para las regresiones móviles) comienzan 2006-01-04. La API está lista para agentes de IA, incluido un servidor integrado de Protocolo de Contexto de Modelo (MCP) para una integración perfecta con LLMs.

Portal para Desarrolladores de la API RiskModels

CI Live Docs OpenAPI PyPI smithery badge

Este repositorio es la referencia pública autoritativa de la API para la API del modelo de riesgo de acciones RiskModels, que incluye:

  • 📖 Metodología del modelo — Descripción general de ERM3 (canónica; también reflejada en riskmodels.net)
  • 📚 Documentación integral de la API — Especificación OpenAPI 3.0.3, guías y ejemplos
  • 🌐 Portal para desarrolladores — Sitio Next.js (este repositorio) desplegado en riskmodels.app
  • 🐍 Ejemplos en Python y TypeScript — Código listo para producción en examples/
  • 🤖 Integración con agentes de IA — Servidor MCP, OAuth2 y manifiesto de agente

Uso en Cursor (Complemento de Agente)

Este repositorio es un paquete de Complementos de Agente: plugin.json y mcp.json en la raíz del repositorio. El complemento conecta Cursor al servidor MCP alojado de RiskModels. No contiene código que se ejecute en tu máquina ni credenciales.

ArchivoQué declara
plugin.jsonComplemento riskmodels 1.0.0, Apache-2.0
mcp.jsonUn servidor, riskmodels: HTTP Streamable en https://riskmodels.app/api/mcp/openai

Instalación

  1. En Cursor, abre el Marketplace y busca RiskModels.
  2. Instálalo para tu usuario o para el proyecto actual.
  3. Cursor agrega el servidor MCP riskmodels. Sus herramientas aparecen una vez que inicias sesión.

Iniciar sesión

El servidor usa OAuth 2.1 con PKCE. Cursor maneja el flujo y nada se guarda en los archivos del complemento:

  1. Cuando Cursor se conecta por primera vez al servidor riskmodels, el servidor solicita el inicio de sesión y Cursor abre un navegador en riskmodels.app.
  2. Inicia sesión con Google o un enlace de correo electrónico, o elige Iniciar sesión con una contraseña en su lugar.
  3. La pantalla de consentimiento muestra Sesión iniciada como <email>. Si esa no es la cuenta correcta, haz clic en Usar una cuenta diferente primero y luego en Permitir.
  4. Cursor almacena el token. Las herramientas son de solo lectura: devuelven datos y nunca realizan órdenes ni cambian tu cuenta.

Precios y cuenta

  • Se requiere una cuenta de RiskModels. Las cuentas nuevas comienzan con $20 de crédito prepagado. Se solicita un método de pago al registrarse para verificación y no se cobra hasta que recargues.
  • El uso es de pago por uso y se factura por llamada a herramienta contra ese saldo. La mayoría de las llamadas de una sola acción cuestan $0.005; los fundamentales cuestan $0.02 y un informe completo de exposición de cartera cuesta $0.25. Tarifas y planes: riskmodels.app/pricing.
  • Opcional: vincula una cuenta de corretaje (Alpaca, Connect Trade o Plaid) en riskmodels.net Configuración, y riskmodels_get_my_positions lee ese libro.

Ejemplo: NVDA

Pregunta en el chat de agente de Cursor:

Descompón el riesgo de NVDA con RiskModels y dame la cobertura con ETF para una posición de $100,000.

El agente llama a riskmodels_decompose para la división de mercado / sector / subsector / acción específica de la varianza de NVDA y el ratio de cobertura en cada nivel. Luego llama a riskmodels_hedge_position para convertir esos ratios en operaciones en dólares en SPY y los ETFs de sector y subsector. Los números son salida del modelo en vivo hasta el último día de negociación.

El complemento de Claude (claude-plugin/) y el servidor MCP local para desarrolladores (.cursor/mcp.json, mcp/) son separados y no han cambiado.

🚀 Enlaces rápidos

URLs canónicas (REST, OpenAPI y documentación)

Usa estas solo para integraciones y herramientas:

QuéURL
Base REST (OpenAPI servers)https://riskmodels.app/api
JSON de OpenAPI desplegado (misma especificación que OPENAPI_SPEC.yaml)https://riskmodels.app/openapi.json
Referencia de API interactiva (este portal)/api-reference

Importante: El nombre de host api.riskmodels.app no se usa para la API pública ni para la documentación legible por máquina. Los enlaces o documentos antiguos que lo mencionen deben tratarse como obsoletos; usa riskmodels.app (apex) como se indica arriba.

📖 Descripción general de la API

La API de RiskModels proporciona análisis de riesgo de acciones de grado institucional:

  • Descomposiciones de factores diarias — fracciones de riesgo explicado de mercado, sector y subsector para las ~3,000 acciones estadounidenses más grandes por capitalización de mercado (universo de fin de mes)
  • Ratios de cobertura — montos de cobertura con ETF denominados en dólares (L1/L2/L3) diseñados para seguir siendo ejecutables con ETFs líquidos sin procesar
  • Series de tiempo históricas — retornos ajustados por divisiones y dividendos (2006-01-04–presente) más ratios de cobertura móviles (2010-12-08–presente) y riesgo explicado (2011-12-07–presente; los resultados de factores necesitan una ventana de regresión completa)
  • Listo para agentes de IA — OAuth2, facturación por solicitud, manifiestos legibles por máquina

Cobertura de datos: ~16,000 acciones estadounidenses en el panel histórico; ~3,000 más grandes por capitalización de mercado en cada fin de mes para los resultados principales. Actualizado diariamente. Ratios de cobertura: 2010-12-08 hasta el presente. Riesgo explicado: 2011-12-07 hasta el presente. Niveles L*: 2013-01-01 hasta el presente. Series de retornos ajustados: 2006-01-04 hasta el presente.

Por qué el motor importa

RiskModels está diseñado para ser útil en el trabajo real de carteras, no solo para análisis descriptivos:

  • Construido para ser seguro en el tiempo — el motor está diseñado para evitar fuentes comunes de contaminación hacia adelante, como tickers reciclados, acciones instantáneas y contracción retroactiva del universo
  • Fundamentado en un Maestro de Valores real — los resultados a nivel de ticker se apoyan en una capa de identidad puntual construida para la continuidad de identificadores, cambios de símbolos y datos de acciones históricamente defendibles
  • Jerárquico por diseño — el modelo separa la estructura de mercado, sector y subsector en lugar de colapsar todo en una visión plana de beta
  • Comerciable en la práctica — los ratios de cobertura publicados están diseñados para funcionar con ETFs líquidos en el momento de la ejecución, no solo con factores sintéticos u ortogonalizados
  • Construido sobre series de retornos ajustados — los retornos ajustados por divisiones y dividendos hacen que la descomposición y los ratios de cobertura sean más consistentes económicamente en horizontes largos

Para una explicación más profunda de las decisiones de diseño del motor detrás de estas afirmaciones, consulta la documentación de metodología y la referencia de la API.

🐍 SDK de Python (riskmodels-py)

Prefiere el SDK de Python sobre REST sin procesar para flujos de trabajo nativos de agentes: la resolución de tickers, la normalización semántica de campos, la validación con errores instructivos y el formato de contexto listo para LLMs están integrados.

Instalación (PyPI):

PyPI version

pip install riskmodels-py
# Optional — xarray cube from batch Parquet/CSV:
# pip install riskmodels-py[xarray]
# Optional — snapshot PDF rendering:
# pip install riskmodels-py[pdf]

Inicio rápido:

from riskmodels import RiskModelsClient, to_llm_context

client = RiskModelsClient.from_env()
pa = client.analyze({"NVDA": 0.4, "AAPL": 0.6})
print(to_llm_context(pa))

Generación de instantáneas (informes PDF institucionales):

from riskmodels.snapshots import get_data_for_r1, render_r1_to_pdf

client = RiskModelsClient.from_env()
data = get_data_for_r1("NVDA", client)       # fetch → R1Data (caches to JSON)
render_r1_to_pdf(data, "NVDA_R1_Risk.pdf")   # render → PDF (~0.3s, no API)

Documentación:

Inteligencia de riesgo

Los gráficos a continuación se generan a partir de datos de API en vivo (get_rankings + métricas de lote L3 de MAG7) mediante scripts/generate_readme_assets.py. Establece RISKMODELS_API_KEY (el nivel gratuito es suficiente), ejecuta el script desde la raíz del repositorio y luego confirma ./assets/ y ./public/docs/readme/.

MAG7 — Descomposición L3 escalada por σ

MAG7 L3 sigma-scaled risk ratios and residual HR share
Misma etiqueta de “tecnología”, diferente ADN de subsector — la longitud de la barra ∝ σ anualizado; los segmentos = σ × ratios de riesgo L3 de mercado/sector/subsector + residual (participación de HR). POST /batch/analyze mediante SDK save_mag7_l3_sigma_rr_png

Clasificaciones transversales

Ranking by cohort
Desglose del percentil de clasificación de universo / sector / subsector

🤖 Servidor MCP (v3.0.0-agent)

RiskModels incluye un servidor MCP (Protocolo de Contexto de Modelo) de primera clase, que permite a los agentes de IA consultar directamente datos de riesgo y realizar análisis de factores.

Conexión MCP (API alojada):

  • Endpoint (HTTP Streamable, POST): https://riskmodels.app/api/mcp/sse
  • Autenticación: Token Bearer (clave de API o JWT OAuth2)
  • Descubrimiento: https://riskmodels.app/.well-known/mcp.json (consulta OPENAPI_SPEC.yaml)

Servidor MCP local (mcp/ en este repositorio) — transporte stdio para Cursor / Claude Desktop / Zed: descubre capacidades, esquemas, OpenAPI y herramientas de riesgo en papel respaldadas por SDK. Las herramientas incluidas aquí son:

  • riskmodels_list_endpoints — Lista las capacidades de la API (id, método, endpoint, descripción breve)
  • riskmodels_get_capability — Registro completo de capacidad por id (parámetros, precios, ejemplos)
  • riskmodels_get_schema — Esquema JSON para un tipo de respuesta (por ejemplo, ticker-returns-v2.json)
  • riskmodels_decompose, riskmodels_compare, riskmodels_hedge_position, riskmodels_portfolio_decompose, riskmodels_whitepaper_example — Salidas de SDK listas para agentes con chart_data, suggested_chart y resúmenes en lenguaje sencillo

Para datos de riesgo en vivo y matemáticas de cartera, llama a la API REST (por ejemplo, GET /api/metrics/{ticker}, POST /api/batch/analyze, GET /api/l3-decomposition), al SDK de Python (riskmodels-py) o a las herramientas MCP listadas.

Consulta mcp/README.md para instalación y configuración.

Anthropic Claude (Agentes administrados vs API de Mensajes): diseño de ingeniería interno para agentes alojados en la nube opcionales, facturación y cumplimiento — consulta docs/ANTHROPIC_CLOUD_AGENTS.md.

⌨️ CLI de línea de comandos (riskmodels)

El paquete npm en cli/ instala el binario riskmodels: configuración, consulta SQL (API facturada o Supabase directo), introspección de esquema, saldo y manifiestos de agente estáticos.

Instalación desde npm:

npm install -g riskmodels
riskmodels --help

Desarrollo desde este repositorio:

cd cli
npm ci
npm run build
npm run install:global   # optional: npm link for local testing

Publicar en npm (mantenedores): el procedimiento está documentado en el monorepo privado BWMACRO (docs/RISKMODELS_CLI_NPM_PUBLISHING.md), no aquí. Solo publica desde el directorio cli/ — la aplicación Next.js de la raíz del repositorio no se publica en npm.

💻 Portal para desarrolladores (Este repositorio)

Este repositorio ahora incluye un portal para desarrolladores en Next.js con:

  • ✨ Página de inicio hero con aspectos destacados de funciones
  • 📚 Documentación impulsada por MDX (README_API.md, AUTHENTICATION_GUIDE.md)
  • 🔍 Referencia de API interactiva (visor OpenAPI de Redoc)
  • 💡 Ejemplos de código con resaltado de sintaxis y botones de copiar
  • 🎯 Guía de inicio rápido paso a paso

Desarrollo local

# Install dependencies
npm install

# Option A: Copy env template and fill in Supabase/Stripe keys manually
cp .env.example .env.local

# Option B: Use Doppler (recommended for team consistency)
# Ensure `doppler login` is done, then:
doppler secrets download --no-file --format env > .env.local

# Generate OpenAPI JSON for Redoc
npm run build:openapi

# Run dev server
npm run dev

Higiene de capturas de pantalla:

Al capturar capturas de pantalla del sitio para auditoría o documentación:

  1. Asegúrate de que la compilación pase primero: npm run build debe completarse sin errores
  2. Verifica que el servidor de desarrollo responda HTTP 200: Visita http://localhost:3000 y confirma que las páginas se renderizan (no "Internal Server Error")
  3. Ejecuta el script de captura: python3 capture_site.py (requiere Playwright)

El script omitirá páginas que devuelvan HTTP 500 o que contengan contenido "Internal Server Error". Las capturas de pantalla con errores del servidor nunca deben enviarse al repositorio.

Gestión de entorno con Doppler:

Este repositorio usa Doppler para la gestión de secretos. El doppler.yaml está preconfigurado para el proyecto erm3:

# Verify setup (should show project: erm3, config: dev)
doppler setup

# List all secrets
doppler secrets

# Get a specific secret
doppler secrets get STRIPE_SECRET_KEY

# Export dev secrets to .env.local for curl testing and local dev
npm run doppler:env

# Push production secrets to Vercel (requires vercel login + project link)
npm run vercel:sync-env:doppler

Para pruebas con curl/API usando secretos de Doppler:

# 1. Export secrets to .env.local
npm run doppler:env

# 2. Source them for your shell session
source .env.local

# 3. Use in curl commands
curl -H "Authorization: Bearer $RISKMODELS_API_SERVICE_KEY" \
  https://riskmodels.app/api/health

Consulta DEPLOYMENT.md para la integración detallada de Vercel/Doppler.

Visita http://localhost:3000

Compilación y despliegue

# Build for production
npm run build

# Start production server
npm start

Despliegue: Consulta DEPLOYMENT.md para la configuración de Vercel, variables de entorno y configuración de Supabase/Stripe.

📂 Estructura del repositorio

RiskModels_API/
├── app/                      # Next.js app
│   ├── api/                  # API routes (REST)
│   ├── page.tsx              # Hero landing page
│   ├── layout.tsx            # Root layout with Navbar/Footer
│   ├── docs/[[...slug]]/     # MDX docs renderer
│   ├── api-reference/        # Redoc OpenAPI viewer
│   ├── examples/             # Code examples showcase
│   └── quickstart/           # Quickstart guide
├── components/               # React components (new)
│   ├── Navbar.tsx
│   ├── Footer.tsx
│   ├── Hero.tsx
│   ├── CodeBlock.tsx
│   └── Logo.tsx
├── content/docs/             # MDX content (new)
│   ├── api.mdx
│   └── authentication.mdx
├── cli/                      # Command-line CLI (`riskmodels`)
├── sdk/                      # Python SDK (`riskmodels-py`) source
│   └── riskmodels/snapshots/ # Snapshot PDF pipeline (R1 shipped, R2–P4 planned)
├── examples/                 # Runnable examples
│   ├── python/
│   └── typescript/
├── mcp/                      # MCP (Model Context Protocol) server
├── public/                   # Static assets (new)
│   ├── transparent_logo.svg
│   └── openapi.json          # Generated from OPENAPI_SPEC.yaml
├── styles/                   # Global styles (new)
├── lib/                      # Utilities (new)
├── OPENAPI_SPEC.yaml         # Canonical OpenAPI spec
├── README_API.md             # API reference (source for content/docs/api.mdx)
├── AUTHENTICATION_GUIDE.md   # Auth guide (source for content/docs/authentication.mdx)
├── SEMANTIC_ALIASES.md       # Field definitions
└── package.json              # Next.js deps (new)

🛠️ Stack tecnológico (Portal de desarrolladores)

  • Framework: Next.js 15 (App Router)
  • Estilos: Tailwind CSS 3.4, modo oscuro por defecto
  • MDX: @next/mdx para documentación
  • Referencia de API: Redoc (visor OpenAPI 3.0)
  • Resaltado de código: CodeBlock personalizado con botón de copiar
  • Fuentes: Inter (respaldo system-ui)
  • Colores: Azul primario (hsl(217, 91%, 60%)), paleta oscura zinc/slate

📄 Archivos de documentación

DocumentoDescripción
README_API.mdDescripción general completa de la API, endpoints, conceptos clave
API_TERMS.mdTérminos de servicio de la API (riskmodels.net/terms/api)
PLAID_HOLDINGS_UX.mdFlujo de conexión de Plaid y experiencia de usuario de la API de tenencias
AUTHENTICATION_GUIDE.mdToken Bearer, OAuth2, Supabase JWT, límites de tasa
DOCS_PROCESS.mdProceso para agregar nueva documentación
SEMANTIC_ALIASES.mdDefiniciones de campos, unidades, fórmulas
RESPONSE_METADATA.mdBloque _agent, encabezados de respuesta, precios
ERROR_SCHEMA.mdCódigos de error y patrones de recuperación
OPENAPI_SPEC.yamlEspecificación OpenAPI 3.0.3 (v3.0.0-agent)
docs/SNAPSHOT_ROADMAP.mdHoja de ruta del conjunto de snapshots, ADRs y fases de implementación
docs/SNAPSHOT_CONTENT_MAP.mdEspecificación de contenido de 8 páginas con wireframes y esquemas JSON
docs/SNAPSHOT_FRONTEND_ARCH.mdArquitectura de canalización de renderizado con Matplotlib puro

🔗 Relacionados

  • ERM3 — Motor de cálculo de modelos de riesgo en Python (código abierto)

🤝 Contribuciones

Agradecemos las solicitudes de extracción, especialmente para mejorar la especificación OpenAPI — descripciones más claras, mejores esquemas y más ejemplos ayudan a todos.

  1. Especificación OpenAPI: CONTRIBUTING.md — Se recomiendan PRs a OPENAPI_SPEC.yaml
  2. Problemas: Abrir un problema para errores o solicitudes de funciones
  3. Ejemplos: Envía nuevos ejemplos mediante PR a examples/
  4. Documentación: Mejora la documentación editando archivos MDX en content/docs/

📧 Soporte

📜 Licencia

Consulta LICENSE para más detalles.

© 2026 Blue Water Macro Corp. Todos los derechos reservados.

Disparador de despliegue: Mar Jun 9 16:13:22 PDT 2026