Counterparty Credit

An open, transparent MCP server that scores the credit health of public energy companies from public data. Ask an agent how sound a utility, generator, midstream operator, or power/gas marketer is; Counterparty Credit answers with a 0–100 score, a factor-by-factor breakdown, and the public source behind every number.

It is decision-support, not a credit rating — every output is sourced, explainable, and meant for human review. The point is a score you can argue with, not a black box.

Built by ComtechAI. Methodology version: ccr-ref-1.3.

Status: v1, deliberately stable

This repo is a scope-frozen reference implementation. It stays published and working; bug fixes and upstream-breakage patches are welcome, new capability is out of scope here. See DEVELOPMENT.md for setup, tests, and contribution rules.

Related MCP server: Pulse MCP Server

How it works

One MCP tool, counterparty.health, takes a company name or ticker. It resolves the SEC filer, pulls public financials and market data, scores four factors, and blends them into a composite with a descriptive band (Strong / Stable / Watch / Stressed / Distressed).

The composite is a renormalized weighted blend over whatever factors actually compute this run. Reference weights are F1 0.20 · F3 0.15 · F4 0.25 · F5 0.15. When a factor's inputs are missing — no market feed for F3, an unclassified name for F4 — that factor drops and its weight redistributes across the rest. Nothing is imputed; a factor is either computed from real data or absent.

Every result carries a methodology_version and an as_of date, and each factor names the filing or feed behind it. Where a figure is a proxy (see limitations), the source line says so.

Install

Requires Python 3.10–3.14.

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

Use it

From the command line

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

SEC returns HTTP 403 without a descriptive User-Agent. A free Tiingo token enables F3; omit it and the tool scores on F1/F4/F5 and says so. Filings and the ticker map cache under ~/.cache/counterparty-credit for 24 hours.

From Claude Desktop

Copy claude_desktop_config.example.json into your Claude Desktop config, set the command to this repo's venv Python (absolute path) and your keys in env, then restart Claude and ask "How financially sound is NextEra as a counterparty?" Claude calls the tool and reads back the score, breakdown, and sources.

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

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

If the company can't be resolved or its data can't be retrieved, the tool returns an error rather than a number. A score is only ever returned when it was actually computed.

Methodology

Scoring reads from a Methodology config object, not hardcoded constants. Methodology.default() is the open reference, locked at ccr-ref-1.3. The committed record:

• src/counterparty_credit/methodology.py — source of truth for all curves, weights, thresholds

• docs/methodology-c0.md — human-readable methodology of record

• docs/methodology-c0.json — machine spec (a test guards against drift)

A custom methodology states only its overrides and inherits the rest of the reference:

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

Because every result is stamped with its version, a custom config is visibly not the reference. The locked numbers are a starting hypothesis, refined against real names; a recalibration is a new version, never a silent rewrite.

Limitations

These are deliberate and stated plainly. An honest scope is the point of a reference tool.

• Not a credit rating. Decision-support from public data. No issuer engagement, no non-public information, no rating-agency methodology.

• F2 (liquidity / collateral) is withheld from the live blend. Its v0 cash proxy returned near-identical scores regardless of credit quality, so it adds no discrimination. It is defined in the methodology but excluded until a real collateral-stress model replaces the proxy.

• F3 needs a market feed. Without a Tiingo token, or for a name without clean price data, F3 drops and its weight redistributes.

• F4 covers a fixed 27-name universe of North American energy issuers. Names outside it are scored without the business-mix factor rather than guessed at.

• F5 keys on a fixed vocabulary. It detects rating actions phrased as upgrade / downgrade (gated to require rating-agency context) and a set of credit events; it will miss rating actions phrased with other verbs, and headline sentiment is coarse.

• Coverage may use a cash-paid proxy. Some large filers tag no interest-expense concept; for those, coverage is computed from cash interest paid, which excludes capitalized interest. The source line flags this per name.

• Point-in-time public data. Figures are as-of the latest filing; a stale filing is flagged, not silently used.

Layout

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/

Disclaimer

Counterparty Credit produces decision-support from public data. It is not a credit rating, not investment advice, and not affiliated with any rating agency or the issuers it scores. Outputs are sourced and intended for human review.