Trading Desk

Multi-agent equity research for US markets, running on Claude Code subagents over MCP. Analysis-first: real money is never touched, and order flow goes to an Alpaca paper account.

Why this exists

Financial data is easy to fetch and easy to get wrong. US-GAAP XBRL concepts drift per company and over time, so reading a single hardcoded concept returns figures that are years stale with no error raised:

An agent given $62.9B for Apple writes a confident, completely wrong thesis. The whole design follows from preventing that.

Operating rules

1. Agents never compute and never recall. Every number comes from a tool call; ratios and indicators are calculated in Python.

2. Every value carries provenance — XBRL concept, period, form, accession, filing date — so any figure can be traced back to the filing.

3. Stale data raises. A number too old to answer the question is an error, not a footnote.

4. Concept resolution is code with tests, not a prompt instruction.

Related MCP server: ReadyTrader-Stocks

Status

Phase 4 complete: research, sizing, a scoreable record, the context around a name, and paper execution that cannot be reached except through an approved thesis.

• EDGAR client — rate limited, disk cached, no API key required

• Concept resolver with provenance and staleness enforcement

• Golden tests (23) pinned to filed 10-Ks

• desk MCP server, verified over stdio

• Phase 1 — fundamentals + chartist agents, /analyze

• Phase 2 — risk (veto) + journal, /journal

• Phase 3 — filings, macro, screener

• Phase 4 — pilot, Alpaca paper execution behind risk approval

• Phase 5 — /postmortem calibration loop

Setup

uv sync
uv run pytest tests/golden -q     # must be green before any agent work

Credentials

Keys live in the environment, never in the repo — .mcp.json reads them via ${VAR} expansion. Put them in ~/.zshrc so they cannot be committed by accident.

Paper trading needs no funding, identity check or approval — that applies only to live accounts.

Verify without exposing anything (the script prints presence and a masked prefix only, never a secret):

uv run python scripts/check_keys.py

Data sources

Deliberately not used: yfinance (unofficial endpoints, silent empty responses) and Stooq (now behind a JS proof-of-work wall). EDGAR is preferred for fundamentals because it is the source of record rather than a scrape of it.

MCP tools

Risk limits

The risk agent holds a veto and does not exercise judgement about it — the limits are policy, checked in Python, and quoted back with the reason they exist. get_risk_policy returns them at runtime.

Correlation is the one call the checks cannot make: three 1% positions on the same driver are one 3% position in disguise, and the agent is instructed to veto that even when every numeric limit passes.

The journal

Theses are JSON files under theses/, one per call, written at the moment the call is made — greppable, diffable, and reviewable alongside the code that produced them. A thesis will not record without at least one falsifier, and direction="watch" calls are recorded too: a watchlist name that ran away without you is as informative as a trade that failed, and only one of the two tends to get remembered. Realised R is computed on close from the recorded entry and stop, so outcomes compare across positions of different sizes.

Set DESK_THESES_DIR to keep the book somewhere other than the repository.

Execution

Paper only. The base URL is the paper endpoint, hardcoded with no environment variable that redirects it, and the account number is checked for Alpaca's PA prefix before any order is sent — live keys against the paper URL fail closed rather than trading.

The gate is the shape of the function rather than an instruction to an agent:

place_order(thesis_id)      # and nothing else

There is no symbol parameter, no quantity, no price. All of it is read back out of the journal entry, which exists only because the risk officer approved it and only carries a share count the risk officer computed. An agent asked to buy 100 shares of something has no way to express that.

An order is refused when the thesis is closed, is a watch call, carries a vetoed verdict, was sized at zero shares, lacks an entry or stop, or already has an order attached — the last of which is what stops a retried call from opening a second position in the same name.

Orders go out as brackets, so the stop the risk officer sized against is submitted with the entry rather than left to a later call that might never happen. reconcile_positions compares what the broker holds against what the journal knows about, which is the only way to see the untracked exposure that portfolio heat is blind to.

Known limitations

• Q4 quarterly gaps. Q4 gets no standalone 10-Q; it must be derived as FY minus Q1–Q3. Not yet implemented — quarterly series skip Q4.

• Alpaca free tier is IEX-only (~2% of consolidated volume), so daily-bar volume is unreliable for swing setups. The price layer sits behind an adapter so Tiingo or another EOD source can be swapped in without touching agent code. Same seam later carries a non-US broker.

• Non-US-GAAP filers (foreign issuers on IFRS) are not covered by the current concept registry.

• The screener has no universe. It ranks a list you give it and reads the venue's movers and most-active tables. It cannot screen "all US software above $2B" — there is no fundamental universe behind it, and a themed list assembled by an agent is a recollection, not a screen. The screener agent is instructed to say which it is.

• Filing text is text. get_filing_text strips markup and returns what was filed. Tables survive as readable rows, but nothing is parsed into figures — a number read out of filing prose has no XBRL concept behind it, so prefer get_financials whenever the figure exists there.

• Macro needs its own key. Without FRED_API_KEY the macro tools fail with a message saying where to get one. Nothing else on the desk depends on them.

• A submitted order is not a filled one. A limit entry may never fill, and the position does not exist until it does. The pilot agent is instructed never to describe one as the other.

• Portfolio heat only sees the journal. A position taken without recording it is invisible to the risk checks, so the heat number is exposure as recorded rather than exposure as held. size_position says so in its limitations on every call.

Not financial advice

A research tool, not a prediction engine. The /postmortem loop exists because calls need to be scored honestly rather than remembered selectively.