Counterparty Credit

Un servidor MCP abierto y transparente que puntúa la salud crediticia de empresas energéticas públicas a partir de datos públicos. Pregunte a un agente cuán sólida es una empresa de servicios públicos, un generador, un operador de midstream o un comercializador de energía/gas; Counterparty Credit responde con una puntuación de 0 a 100, un desglose factor por factor y la fuente pública detrás de cada número.

Es soporte para la toma de decisiones, no una calificación crediticia — cada resultado tiene fuente, es explicable y está pensado para revisión humana. La idea es una puntuación con la que se pueda discutir, no una caja negra.

Desarrollado por ComtechAI. Versión de metodología: ccr-ref-1.3.

Estado: v1, deliberadamente estable

Este repositorio es una implementación de referencia con alcance congelado. Permanece publicado y funcional; se aceptan correcciones de errores y parches por roturas aguas arriba, pero las nuevas capacidades están fuera de alcance aquí. Consulte DEVELOPMENT.md para configuración, pruebas y reglas de contribución.

Related MCP server: Pulse MCP Server

Cómo funciona

Una herramienta MCP, counterparty.health, toma un nombre de empresa o ticker. Resuelve el declarante de la SEC, obtiene datos financieros públicos y de mercado, puntúa cuatro factores y los combina en un compuesto con una banda descriptiva (Fuerte / Estable / Vigilancia / Estresado / En dificultades).

El compuesto es una mezcla ponderada renormalizada sobre los factores que realmente se calculan en esta ejecución. Los pesos de referencia son F1 0.20 · F3 0.15 · F4 0.25 · F5 0.15. Cuando faltan los insumos de un factor — sin feed de mercado para F3, un nombre no clasificado para F4 — ese factor se elimina y su peso se redistribuye entre el resto. Nada se imputa; un factor se calcula con datos reales o está ausente.

Cada resultado lleva una methodology_version y una fecha as_of, y cada factor nombra la declaración o el feed detrás de él. Cuando una cifra es un proxy (ver limitaciones), la línea de fuente lo indica.

Instalación

Requiere Python 3.10–3.14.

python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

Uso

Desde la línea de comandos

export SEC_USER_AGENT="Your Name you@example.com"   # SEC requires a contact User-Agent
export TIINGO_TOKEN="your_tiingo_key"               # optional; F3 is skipped without it
python3 -m counterparty_credit.cli "NextEra Energy"
python3 -m counterparty_credit.cli DUK

La SEC devuelve HTTP 403 sin un User-Agent descriptivo. Un token gratuito de Tiingo habilita F3; omítalo y la herramienta puntúa con F1/F4/F5 y lo indica. Las declaraciones y el mapa de tickers se almacenan en caché en ~/.cache/counterparty-credit durante 24 horas.

Desde Claude Desktop

Copie claude_desktop_config.example.json en la configuración de Claude Desktop, establezca el command al Python del venv de este repositorio (ruta absoluta) y sus claves en env, luego reinicie Claude y pregunte "¿Cuán sólida financieramente es NextEra como contraparte?" Claude llama a la herramienta y lee la puntuación, el desglose y las fuentes.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Si la empresa no se puede resolver o sus datos no se pueden recuperar, la herramienta devuelve un error en lugar de un número. Una puntuación solo se devuelve cuando realmente se calculó.

Metodología

La puntuación se lee de un objeto de configuración Methodology, no de constantes codificadas. Methodology.default() es la referencia abierta, fijada en ccr-ref-1.3. El registro confirmado:

• src/counterparty_credit/methodology.py — fuente de verdad para todas las curvas, pesos y umbrales

• docs/methodology-c0.md — metodología legible de registro

• docs/methodology-c0.json — especificación de máquina (una prueba protege contra la deriva)

Una metodología personalizada solo indica sus anulaciones y hereda el resto de la referencia:

CCR_METHODOLOGY=/path/to/methodology.json python3 -m counterparty_credit.cli "NextEra Energy"

Debido a que cada resultado está sellado con su versión, una configuración personalizada es visiblemente no la referencia. Los números fijados son una hipótesis inicial, refinada contra nombres reales; una recalibración es una nueva versión, nunca una reescritura silenciosa.

Limitaciones

Estas son deliberadas y se declaran claramente. Un alcance honesto es el punto de una herramienta de referencia.

• No es una calificación crediticia. Soporte para la toma de decisiones a partir de datos públicos. Sin participación del emisor, sin información no pública, sin metodología de agencia de calificación.

• F2 (liquidez / garantía) se excluye de la mezcla en vivo. Su proxy de caja v0 devolvía puntuaciones casi idénticas independientemente de la calidad crediticia, por lo que no añade discriminación. Está definido en la metodología pero excluido hasta que un modelo real de estrés de garantías reemplace al proxy.

• F3 necesita un feed de mercado. Sin un token de Tiingo, o para un nombre sin datos de precios limpios, F3 se elimina y su peso se redistribuye.

• F4 cubre un universo fijo de 27 nombres de emisores energéticos de América del Norte. Los nombres fuera de él se puntúan sin el factor de mezcla de negocio en lugar de adivinarse.

• F5 se basa en un vocabulario fijo. Detecta acciones de calificación expresadas como upgrade / downgrade (restringidas para requerir contexto de agencia de calificación) y un conjunto de eventos crediticios; pasará por alto acciones de calificación expresadas con otros verbos, y el sentimiento de los titulares es grueso.

• La cobertura puede usar un proxy de caja pagada. Algunos grandes declarantes no etiquetan el concepto de gastos por intereses; para ellos, la cobertura se calcula a partir de intereses en efectivo pagados, lo que excluye los intereses capitalizados. La línea de fuente lo indica por nombre.

• Datos públicos puntuales. Las cifras son al cierre de la última declaración; una declaración desactualizada se señala, no se usa silenciosamente.

Estructura

src/counterparty_credit/
  schema.py          # locked I/O contract (HealthResult)
  methodology.py     # config object — reference default + worksheet loader
  resolve.py         # name/ticker → CIK + ticker (SEC company_tickers.json)
  edgar.py           # XBRL companyfacts → financials (recency-aware tag selection)
  ratios.py          # leverage / coverage / liquidity
  market.py          # daily prices → price + annualized vol (Tiingo)
  dtd.py             # naive-Merton distance-to-default
  news.py            # recent headlines (Google News RSS)
  scoring.py         # F1, F3, F5 scorers
  f4_business_mix.py # F4 business-mix lookup over the universe
  universe.json      # 27-name classification universe
  score.py           # orchestration → weighted composite → HealthResult
  server.py          # MCP tool
  cli.py             # one-command live scoring
tests/

Aviso legal

Counterparty Credit produce soporte para la toma de decisiones a partir de datos públicos. No es una calificación crediticia, no es asesoramiento de inversión y no está afiliado con ninguna agencia de calificación ni con los emisores que puntúa. Los resultados tienen fuente y están destinados a revisión humana.