catalyst-edge-mcp

# CATALYST/EDGE

<!-- mcp-name: io.github.rm0nroe/catalyst-edge-mcp -->

**Catalyst Edge Research** is source-linked market intelligence for AI agents. The
standalone, read-only MCP server returns compact,
source-linked catalyst evidence dossiers for public-company tickers. It collects
independent evidence families concurrently and applies a documented deterministic
score. It does not import the sibling `analysis-api` application or its random-weight
model.

The public surface has two read-only tools: `catalyst_edge_score` returns the
compact dossier, and `catalyst_edge_claim_sources` pages through every immutable
source record counted by a grouped claim.

## Audience and distribution status

Catalyst Edge is for analysts and builders. **Builders includes retail traders and
technically capable individual investors who assemble their own Claude, Codex, Cursor,
or other MCP research workflows.** It is not limited to institutional teams.

The product promise is bounded:

> Ask your AI research agent what changed for a ticker, why it matters, what contradicts
> it, and show every source and missing-data warning.

The scorer is deterministic and unbacktested. Catalyst Edge does not promise alpha,
investment performance, buy/sell signals, personalized advice, or execution.

Version 0.1.4 is the approved free Local Beta for GitHub, PyPI, Codex, and the MCP
Registry. Claude Desktop can use the same PyPI package through a manual stdio
configuration, but the one-click `.mcpb` is intentionally withheld until its publisher
can be verified by a production-trusted signing path. The current direction also includes
a `Hosted Pro — $29/month` paid-intent test. Research does not support building Hosted Pro
now: only recent activation-linked, verified, price-aware signups count toward staged 350
compatibility-spike, 1,350 scoped-review, and 11,100 safeguarded full-build reconsideration
gates. None grants automatic implementation, payment, or deployment authority. Paid
launch remains separately gated in
[`GTM_PLAN.md`](https://github.com/rm0nroe/catalyst-edge-mcp/blob/main/GTM_PLAN.md); the economics are documented in the
[`Hosted Pro architecture research`](https://github.com/rm0nroe/catalyst-edge-mcp/blob/main/thoughts/unknown-ticket/research/2026-08-03-RESEARCH-hosted-pro-architecture.md).

## Current status and completion boundary

As of 2026-07-21, the zero-subscription local runtime has the free dependencies
needed to deliver the revised product: direct SEC filings and insider records plus
implemented GDELT Web NGrams discovery and opt-in issuer-feed and Bluesky capabilities.
The MCP transports, schemas, provenance, typed missingness, event graph, and
deterministic scorer are implemented and tested.

The first product-completion slice landed on 2026-07-15: evidence now carries
event type, materiality, novelty, correction lineage, source-record support, and
factual why-it-matters context. SEC 8-K item codes and insider transaction facts
drive event-specific headlines, invalidation criteria, and next checks. The slice
is covered by fixed real RKLB SEC metadata and was rechecked against live RKLB
Form 144 and 8-K records.

The default local GDELT lifecycle schedules a bounded catch-up when persisted state is
due, while periodic refresh remains outside
the MCP request path, shutdown cancels cleanly, and `catalyst-edge-health` reports
last-success age plus fresh, stale, failed, never-refreshed, or unregistered state.
Every dossier and paginated claim containing GDELT-derived data includes a machine-readable
`The GDELT Project` citation and official link even when detailed sources are suppressed.
Issuer feeds, discovery rules, social aliases, and publisher-domain quality tiers
now load from one strictly validated local JSON registry. Registry v2 applies
reviewed per-alias kind, match mode, required/negative context, validity interval,
canonical CIK, rule version, and review provenance before a GDELT candidate enters
the event graph. Custom registry v1 files remain compatible through deterministic
legacy-rule translation. The packaged reviewed defaults preserve the existing
cohort; a custom path replaces that cohort rather than silently merging unreviewed
aliases.

Grouped issuer-feed and GDELT evidence now carries an immutable `claim_id`, exact
`source_record_count`, and up to 20 `supporting_source_ids`. Call
`catalyst_edge_claim_sources` with the claim ID and its integer cursor to recover
every source ID, accession/record ID, canonical URL, timestamp, hash, parser, and
policy decision in pages of at most 20. `data_quality.reason_records` separately
retains ordered scoped reasons for unsupported or unavailable sources, no
observations, rejected entities, discovery-only evidence, and evaluated
non-material candidates. Display precedence does not discard coexisting reasons,
and truncation is explicit through `reason_record_count` and
`reason_records_truncated`. GDELT rejection disposition is source-scoped and
aggregate in the dossier; individual candidate decisions remain in the bounded
append-only entity audit.

The zero-subscription runtime meets its current local acceptance corpus as of
2026-07-16. A 25-case real SEC evaluation complements the 28 synthetic Phase 6
contract scenarios. It exposed and closed event-priority, merger-delisting, and
recorded Item 8.01 specificity defects; all recorded classification, provenance,
freshness, distinct-event, research-value, and dossier-direction checks pass.

The SEC-backed fund lane is implemented for SPY, QQQ, DIA, IWM, XLE, XLK, GLD,
and GDX. QQQ, IWM, XLE, XLK, and GDX resolve reviewed SEC registrant CIK plus
series/class IDs and produce neutral N-CEN/NPORT context with separate report,
period-end, filing, and acceptance chronology. SPY and DIA have official CIKs
but no SEC mutual-fund series/class mapping; GLD is outside the N-CEN/NPORT
investment-company lane. Those three cases return explicit `source_unsupported`
reasons instead of invented identifiers. Reviewed sponsor-primary URLs are
retained as metadata only, and every reviewed fund bypasses corporate filing
and insider semantics.

Item 8.01 primary-document enrichment is intentionally bounded rather than a
general SEC semantic parser. The versioned `sec-primary-document-v1` rules cover
explicit completed debt offerings, entered or amended equity distribution
agreements, actual share-repurchase activity, and filed prospectus supplements.
They record the selected rule and version, reject proposed or negated near
matches, preserve amendment semantics, and leave multiple specific events
generic rather than choosing an arbitrary first match. Representative HTML,
table, and inline-XBRL fixtures exercise those boundaries. Unsupported wording
or filing structures remain `other_material_event` and require human review.

No numeric scorer change was justified because the real corpus contains no
forward-return labels. The scorer remains deterministic and explicitly
unbacktested. Paid options flow, licensed OHLC, sentiment, hosted deployment, and
broader SEC semantic extraction are future capabilities. Version 0.1.4 ships only the
local, self-serve surface.

In older implementation notes and runtime messages, “production” means the
real non-fixture composition path used by the local MCP. It does not imply a
hosted service, third-party provider role, paid account, or consumer rollout.

## Install

Python 3.10+ and [uv](https://docs.astral.sh/uv/) are required. Register the pinned PyPI
package with 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.4' catalyst-edge-mcp
```

Open a fresh task and confirm discovery of exactly `catalyst_edge_score` and
`catalyst_edge_claim_sources`. The complete Codex, Claude Desktop, privacy, and rollback
procedure is in
[`docs/demo/customer-installation-runbook.md`](https://github.com/rm0nroe/catalyst-edge-mcp/blob/main/docs/demo/customer-installation-runbook.md).

## Build and verify from source

Maintainers can verify the source checkout with the locked toolchain:

```bash
uv sync --frozen --extra dev
uv run --frozen pytest
uv run --frozen ruff check .
uv build --no-sources --out-dir dist
```

All default tests are offline. Provider tests use sanitized fixtures and
`httpx.MockTransport`; live credentials are not required. Direct SEC event,
ownership, Form 144, N-CEN, and NPORT parsing plus issuer RSS/Atom collection,
event-graph behavior, and GDELT Web NGrams discovery are implemented with fixed fixtures.
Official-host Bluesky partial-attention collection is also fixture-covered.
Phase 5 sentiment/options gates and 28 dated Phase 6 synthetic contract cases are also
executable offline.

Pull requests and release tags run the required Python 3.10/3.14 offline matrix,
stdio/loopback contract suite, clean build, and installed-artifact verifier in
`.github/workflows/validation.yml`. The workflow has read-only repository permissions
and contains no package publish, release creation, registry, credential, or artifact-upload step.

The same workflow validates the MCPB release candidate with pinned Node/npm and
`@anthropic-ai/mcpb` versions, a locked dependency integrity, zero known npm audit
findings, a fail-closed file inventory, and deterministic ZIP metadata. Maintainers can
run the identical packaging lane from a source checkout:

```bash
npm ci --ignore-scripts
npm audit --audit-level=low
npm run mcpb:validate
npm run mcpb:pack
uv run --frozen python scripts/verify_mcpb.py \
  --bundle dist/catalyst-edge-mcp-0.1.4.mcpb
```

This produces an unsigned compatibility artifact for maintainer QA. It is not distributed
as a production-trusted Claude one-click package.

The live Web NGrams replacement evidence is recorded in
[`docs/validation/gdelt-web-ngrams-live-2026-07-14.md`](https://github.com/rm0nroe/catalyst-edge-mcp/blob/main/d