# HyperDD — equity research evidence over MCP

> 15 tools over one stateless MCP endpoint: stateless Jev artifact evaluation
> and optional memo ratings, immutable evidence snapshots, bounded search,
> reads and changes, raw source evidence per ticker, the research wiki, and
> the CPE research methodology as prompt text. Read-only except `gather`.
> Metered calls: `gather` and `jev_evaluate`.

Endpoint: https://hyperdd.com/mcp
Transport: stateless MCP, JSON-RPC over a single POST. No session, no stdio.
Auth: `Authorization: Bearer <token>` on every call. Obtain a token from an operator.

## Agent setup

- [Download the HyperDD companion skill](https://hyperdd.com/skills/hyperdd/SKILL.md):
  Self-contained instructions for evidence research, limits and failure handling.
- [MCP connection guide](https://hyperdd.com/mcp.md): Registration, authentication,
  skill installation, examples and verified compatibility.

Discovery does not install a skill or register a server. Obtain a token from
an operator. Jev evaluation is metered and runs only when explicitly called.

## How to use it

Start with `evidence_snapshot`, pin its version, then use `evidence_search`
and `evidence_read` for bounded passages with stable citations. Follow cursors
and preserve missing, skipped-file and truncation warnings. Research runs in
your Claude or Codex session; the server does not generate or publish research.

For larger files, use snapshot download URLs and verify their source hashes.
`raw_list` and `raw_manifest` are a fallback for mutable raw evidence, or exact
historical bytes when supplied a publication revision. Raw manifests default
to 15-minute URLs and at most 200 files; narrow to an exact path or directory.
Historical wiki pages are retained publications, not newly generated research.

## Tools

### get_coverage(ticker)
Coverage report for one ticker: which manifest sources landed.
  ticker: Ticker symbol

### gather(ticker, [source], [force])
Start a corpus fetch for one ticker. Returns a Modal call id.
  ticker: Ticker symbol
  source: Limit to one source name
  force: Re-fetch even when the file already exists. Requires `source`.

### status(no arguments)
State of the most recent manual gather run.

### raw_list(ticker, [revision], [prefix])
List the raw evidence files fetched for a ticker, with sizes. Start here, then raw_manifest for the files you want.
  ticker: Ticker symbol
  revision: Publication revision for exact cited bytes
  prefix: Exact file path or directory; not a filename prefix

### raw_manifest(ticker, [revision], [prefix], [expires_in])
Signed download URLs for a ticker's raw evidence. Use this to GET the files yourself; the bytes never enter the conversation.
  ticker: Ticker symbol
  revision: Publication revision for exact cited bytes
  prefix: Exact file path or directory; not a filename prefix
  expires_in: URL lifetime in seconds, max 86400

### evidence_snapshot(ticker, [version], [download], [cursor], [limit])
Return a paginated immutable inventory. Set download=true for signed URLs; follow every next_cursor with the pinned version to download the complete corpus.
  ticker: Ticker symbol
  version: Pinned evidence version
  download: Include 15-minute signed immutable download URLs
  cursor: Last returned path
  limit: Page size, max 200

### evidence_read(ticker, path, [version], [max_bytes], [start])
Read bounded bytes from one immutable source snapshot with a stable locator.
  ticker: Ticker symbol
  path: Snapshot-relative source path
  version: Evidence version; defaults to current
  max_bytes: Source bytes per chunk, max 64000; includes text and exact base64
  start: Byte offset for continuation

### evidence_search(ticker, query, [version], [max_results], [context_chars], [prefix], [cursor], [max_scan_bytes])
Search bounded source text in one immutable evidence snapshot.
  ticker: Ticker symbol
  version: Evidence version; defaults to current
  max_results: Match cap, max 50
  context_chars: Match context cap, max 2000
  prefix: Limit search to a snapshot path or directory
  cursor: Opaque next_cursor from prior search; repeat version, query and prefix
  max_scan_bytes: Total scan budget, max 4000000

### evidence_changes(ticker, from_version, [to_version], [cursor], [limit])
Compare immutable evidence source hashes since a pinned version.
  ticker: Ticker symbol
  from_version: Prior evidence version
  to_version: Target version; defaults to current
  cursor: Last changed path
  limit: Page size, max 200

### wiki_read(ticker, [full])
Read the wiki page for a ticker: thesis, drivers, dependencies.
  ticker: Ticker symbol
  full: Return the whole page, not a summary

### wiki_neighbors(ticker, [min_confidence])
Companies this ticker depends on or is depended on by.
  ticker: Ticker symbol
  min_confidence: Drop edges below this, 0-1

### wiki_search(query)
Full-text search across every wiki page.

### skills_list(no arguments)
List the CPE equity-research skills and the files each one has.

### skill_read(skill, [path])
Read one skill's SKILL.md, or a named file under it such as references/lenses.md.
  skill: Skill name from skills_list
  path: Relative file, defaults to SKILL.md

### jev_evaluate(kind, artifact, [evidence], [metadata])
Run a metered Jev evaluation using a research review skill. Supply the artifact and bounded cited evidence. Only kind jev-rating returns investment stars; other kinds return qualitative findings. Missing evidence or unavailable Jev is not a pass. No research agent, publication or background job is started.
  artifact: Text or structured artifact; jev-rating requires fixed memo text
  evidence: Evidence records using the review skill's schema
  metadata: Source/version metadata; rating requires its rubric inputs