# CATALYST/EDGE ![Abstract source-linked evidence ledger](assets/readme/catalyst-edge-social-preview.png) Source-linked market intelligence for AI agents. Catalyst Edge is a local, read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for public-company research. Ask an agent what changed for a ticker, why it matters, what contradicts it, and which sources support the answer. It combines direct SEC filings and ownership records with optional, policy-gated sources into a compact evidence dossier. Every result preserves its source links and missing-data warnings. **Local first.** Evidence and configuration stay on your machine. **Research only.** The deterministic scorer is untrained and unbacktested; Catalyst Edge does not provide investment advice, trading signals, or execution. --- ## Install Catalyst Edge requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). The SEC requires an identifiable `User-Agent`; use your organization and a monitored email address. ### Codex ```bash codex mcp add catalyst-edge \ --env 'CATALYST_EDGE_SEC_USER_AGENT=YOUR_ORGANIZATION YOUR_EMAIL' \ --env 'CATALYST_EDGE_EVIDENCE_STORE=/absolute/local/path/evidence.sqlite3' \ -- uvx --from 'catalyst-edge-mcp==0.1.8' catalyst-edge-mcp ``` Start a fresh task and verify that Codex discovers these two tools: | Tool | Use | | --- | --- | | `catalyst_edge_score` | Return a compact catalyst-evidence dossier for a ticker. | | `catalyst_edge_claim_sources` | Page through the immutable source records behind a claim. | ### Claude Desktop Download [`catalyst-edge-mcp-0.1.8.mcpb`](https://github.com/rm0nroe/catalyst-edge-mcp/releases/download/v0.1.8/catalyst-edge-mcp-0.1.8.mcpb), then choose **Settings → Extensions → Advanced settings → Install Extension…**. Enter the same SEC identity when prompted. The extension is an unsigned custom bundle; review the source and published checksum before accepting Claude Desktop's warning. --- ## Use Ask your agent a focused research question, for example: > What changed for NVDA in the last 14 days? Include sources, missing evidence, and > anything that would weaken the conclusion. The primary tool accepts a ticker, a 1–90 day lookback, source inclusion, and a research context: ```json { "ticker": "NVDA", "lookback_days": 14, "include_sources": true, "include_raw_signals": false, "risk_mode": "research" } ``` `risk_mode` also supports `alert_triage` and `thesis_review`. Ticker validation runs before any provider is composed; invalid inputs fail clearly rather than producing a partial score. ### From a terminal ```bash # Run the local stdio MCP server uvx --from 'catalyst-edge-mcp==0.1.8' catalyst-edge-mcp # Get a dossier directly uvx --from 'catalyst-edge-mcp==0.1.8' catalyst-edge-score NVDA --lookback-days 14 ``` --- ## What it uses | Evidence | Default | Notes | | --- | --- | --- | | SEC filings and ownership records | Enabled with `CATALYST_EDGE_SEC_USER_AGENT` | Primary regulatory evidence. | | GDELT Web NGrams discovery | Enabled | Attributed, cache-only discovery metadata; set `CATALYST_EDGE_GDELT=disabled` to opt out. | | Issuer RSS/Atom feeds | Disabled | Enable explicitly with `CATALYST_EDGE_ISSUER_FEEDS=enabled`. | | Bluesky public attention | Disabled | Enable explicitly with `CATALYST_EDGE_BLUESKY=enabled`; it is incomplete, neutral-only context. | | Options, technicals, and sentiment | Disabled | Not composed without an approved, rights-cleared provider. | The default evidence store is local SQLite at `~/.local/state/catalyst-edge-mcp/evidence.sqlite3`. Set `CATALYST_EDGE_EVIDENCE_STORE` to choose another local path. ### Check local readiness ```bash CATALYST_EDGE_SEC_USER_AGENT='YOUR_ORGANIZATION YOUR_EMAIL' \ uvx --from 'catalyst-edge-mcp==0.1.8' catalyst-edge-smoke NVDA --lookback-days 14 ``` The smoke check reports sanitized configuration, provenance, coverage, and readiness status. It never prints credentials or provider payloads. --- ## How to read a result Each dossier includes a deterministic `score`, `direction`, `confidence`, source-linked evidence, missing or stale families, and next checks. `research.disposition` tells an agent whether to review the evidence now, monitor it, or report insufficient evidence; it prioritizes research only and is not a trade signal. `model_status` is always `not_trained` in this release. A neutral or no-data result is a valid answer: missing evidence is uncertainty, not bearish evidence. Evidence is compact by design. Use `catalyst_edge_claim_sources` with a claim ID to retrieve its paginated source records, including canonical URLs, timestamps, hashes, parsers, and policy decisions. ```json { "ticker": "NVDA", "edge": {"score": 62, "direction": "bullish", "confidence": 0.69, "scoring_method": "deterministic_v1", "model_status": "not_trained"}, "research": {"disposition": "review_now", "primary_claim_id": "clm_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "supporting_claim_ids": [], "contradicting_claim_ids": [], "blocking_gaps": [], "next_action": "Open SEC accession 0001045810-26-000001 and review the filed item text and exhibits."}, "data_quality": {"coverage": "partial", "missing_families": [], "warnings": ["Deterministic v1 scoring is not backtested."]} } ``` ```json { "ticker": "NVDA", "edge": {"score": 50, "direction": "neutral", "confidence": 0, "scoring_method": "deterministic_v1", "model_status": "not_trained"}, "research": {"disposition": "monitor", "primary_claim_id": null, "supporting_claim_ids": [], "contradicting_claim_ids": [], "blocking_gaps": ["options_flow"], "next_action": "Check whether a sector-wide event explains the observation."}, "data_quality": {"coverage": "none", "missing_families": ["options_flow"], "warnings": ["options_flow provider yfinance is private diagnostic only; no production evidence or coverage credit was granted."]} } ``` ```json { "ticker": "NVDA", "edge": {"score": 50, "direction": "neutral", "confidence": 0, "scoring_method": "deterministic_v1", "model_status": "not_trained"}, "research": {"disposition": "insufficient_evidence", "primary_claim_id": null, "supporting_claim_ids": [], "contradicting_claim_ids": [], "blocking_gaps": ["filings_news", "insider_trading", "options_flow", "social", "technical"], "next_action": "Retry with lookback_days=30 to check a wider filing window."}, "data_quality": {"coverage": "none", "missing_families": ["filings_news", "insider_trading", "options_flow", "social", "technical"], "warnings": ["No live evidence adapters are configured."]} } ``` --- ## Privacy Results and SQLite evidence remain on your machine. Ticker and issuer queries may be sent directly to whichever public-source providers you enable. The SEC identity is sent only to `sec.gov` as its required request `User-Agent`. Read the [Catalyst Edge Privacy Policy](https://catalyst.ryanmonroe.ai/privacy.html). --- ## Build from source ```bash uv sync --frozen --extra dev uv run --frozen pytest uv run --frozen ruff check . uv build --no-sources --out-dir dist ``` Default tests are offline and use sanitized fixtures. The release workflow tests Python 3.10 and 3.14, MCP contracts, a clean build, and the packaged artifact. ## License [MIT](LICENSE)