# Quant Brain MCP

**A model-independent local company research desk, with evidence-backed workflows through MCP.**

Connect Claude, GPT, Gemini or a local model through an MCP-capable client. The
core server does not require a model account or inference SDK. See the
[client connection guide](docs/clients/mcp-clients.md) and [self-host operations](docs/selfhost-operations.md).
The separate Codex background research workflow is optional and requires its own setup.
For local, VPS and Render hosting, follow the [MCP-only deployment guide](docs/deploy-mcp.md).

Browse the [documentation index](docs/README.md) or [repository layout](docs/repository-layout.md)
for the Python services, tools, tests, examples and operator scripts.

| Workflow | Implemented capability |
| --- | --- |
| Financials | Stored quarterly and annual facts, aligned QoQ/YoY comparisons, conservative TTM derivations and point-in-time revisions |
| Filing updates | Supported document ingestion, SEC discovery adapter and a local polling worker that reevaluates saved theses |
| Screening | Explicit pass/fail/unknown criteria, financial ratios, source references and currency/period checks |
| Valuation | User-defined DCF scenarios, FCFF/FCFE distinction and bounded reverse-DCF implied growth |
| Guidance | Immutable sourced guidance ranges compared with matching reported actuals |

### Run the MCP research server

Use Python 3.12. The core research tools need no model account, broker or hosted
database. Models access them through an MCP-capable client:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install --require-hashes -r requirements_filing.lock
python scripts/setup_research_desk.py
source .quant-brain/research-desk.env
python fastmcp_server.py
```

Connect a local client to the authenticated endpoint at `http://127.0.0.1:8000/mcp`,
or use the canonical stdio launcher in the [client guide](docs/clients/mcp-clients.md).
For a research view inside a model client, select the optional `company_dashboard`
MCP prompt or use the [natural-language request guide](docs/claude-dashboard.md).
The prompt returns instructions for using the existing tools; it does not run a
web interface, fetch new sources or send a model request. Presentation depends
on the client.

Keep the generated configuration private. See [operator controls](docs/selfhost-operations.md)
for storage, backups, source permissions and the separate filing worker.

The Next.js dashboard is deferred and excluded from this change. The existing
Streamlit interfaces remain optional legacy entry points. The [research desk guide](docs/research-desk.md)
describes their setup and the underlying MCP workflows. For an offline CLI journey,
install the documented desk profile and run `python scripts/demo_research_desk.py`.

Each self-hosting user supplies their own SEC contact locally. SEC setup is optional:
run `python scripts/setup_research_desk.py --configure-sec`, then source the generated
`.quant-brain/research-sec.env` alongside `research-desk.env` before starting the
dashboard, MCP or filing worker. No contact is bundled in the project or required
for offline tools.

US discovery targets recent SEC filings; reviewed official document URLs can also be
configured for US or Indian issuers. These links cover only the documents supplied
and do not themselves discover new issuer URLs. Configured official RSS/Atom feeds
now discover supported new reports, including NSE integrated financial XBRL.
The official issuer directory supplies searchable metadata; financial coverage
requires successfully imported supported reports. Saved copies can be used explicitly when an
eligible retrieval fails, with their age and degraded status shown. See [filing
reliability](docs/filing-reliability.md) for setup and limits.
Optional PDF repair, local password-based decryption, and review-only OCR are
described in [PDF preprocessing](docs/document-processing.md).

The NSE archive route passed a real TCS quarterly filing through authenticated MCP,
including 12 extracted facts and retained-original verification. Its graphical
rupee label requires explicit, warned INR confirmation. SEC, Microsoft and Infosys
routes returned **HTTP 403** here. Apple report retrieval succeeded, but its mixed
quarterly/annual PDF layout is refused; US structured filing support is separate.
Coverage remains bounded to supported formats and configured documents.
No paid competitor data is scraped or bundled.

Automated NSE/BSE requests are now **disabled by default**. Upload permitted reports
or configure exchange access only when separately authorized. The local dashboards
are pinned to loopback; telemetry is opt-in. See the [review fixes and limits](docs/review-resolution.md)
and [operator controls](docs/selfhost-operations.md).

### Saved assumptions and changes

**Thesis Watch** turns selected financial assumptions into reproducible checks.
Register a revenue-growth floor or a margin threshold against saved financial facts,
then evaluate a later disclosure. The report shows new breaches, recoveries,
missing evidence, exact arithmetic and source locations. Definitions and dated
checkpoints persist in owner-scoped SQLite; repeating a checkpoint is idempotent.
This closes the basic "what changed in my thesis?" loop without a paid model.

Try the clearly labelled synthetic journey after installing `requirements.txt`:

```bash
python scripts/demo_thesis_watch.py
```

It demonstrates **holding → breached → holding → incomplete**. To use the four
new tools on the authenticated server, enable `QUANT_THESIS_ENABLED=1` and follow
the [Thesis Watch setup and MCP example](docs/thesis-watch.md). Checks run when
called or by a configured filing worker. SEC discovery and recurring local checks
are implemented; Telegram/email delivery and broader issuer discovery remain
future work. Source extraction and caller-supplied facts remain unverified;
"holding" means the selected numeric rules passed, not that an investment is safe.

Start with the authenticated server and its 66 tools. Follow the
[local MCP setup](docs/getting-started.md#run-the-original-mcp-server-locally)
to install dependencies, generate a private token and launch it. Then run
`python smoke_test.py --live` from a second configured terminal to verify real
quotes, company data, indicators, the SMA backtest and historical risk scenarios through MCP.
No dashboard, paid model or brokerage account is needed for that workflow.

The original backtests now fill completed-bar signals at the next bar's open,
reject insufficient history clearly, and return null for unavailable metrics.
See [the original-server repair checks](docs/original-mcp-validation.md).

## Original MCP server

Quant Brain combines 25 market tools with four research-job tools, five
financial-fact tools, three filing tools, four thesis tools and twenty-five company-research tools
(66 in total). Ask for a quote,
run a backtest, inspect historical risk distances, or start an Indian-equity research job
that coordinates Codex specialists and returns evidence, disagreements, and an
execution trace. An MCP-capable client can present the report using its chosen model.

[![Tests](https://github.com/paarths-collab/quant-brain-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/paarths-collab/quant-brain-mcp/actions/workflows/test.yml)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](requirements.txt)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Current capabilities and target design

The extended backend provides market calculations, optional NSE agent research and bounded India/US filing comparisons. Its annual **Earnings Evidence** workflow accepts a document and supported financial question, discovers primary statements in large text PDFs, and saves source-linked arithmetic and review flags. See the [filing-to-answer workflow](docs/filing-workflow.md) for document inputs, source locations, compatibility checks and evidence exports. The next
architecture extends that foundation into a global research desk with browser
investigation, broader evidence verification, and wider-market monitoring. Those extensions are
planned; they are not activated by installing the current release.

| Area | Current implementation | Planned extension |
|---|---|---|
| Markets | NSE research jobs; broader provider-supported symbols in individual tools | Exchange-aware research across India, the US, and other markets |
| Data | Yahoo history/quotes, supported filing extraction, quarterly/TTM facts and SEC discovery adapter | More providers, broker feeds and broader document coverage |
| Research | Six Codex roles; company and quant analysis in parallel | Task-selected filing, valuation, macro, forensic, and portfolio specialists |
| Web access | Live web search; bounded official HTML/PDF retrieval; browser control disabled | Isolated browser worker, OCR and broader sources |
| Verification | Schema checks, model audit, SDK tool traces, retrieved source excerpts/hashes and explicit quality gaps | Per-claim evidence matching and independently reproducible calculations |
| Memory | Saved jobs/reports, thesis checkpoints and scheduled local SEC watches | Wider disclosure sources, external notifications and historical replay |
| Operation | Authenticated MCP and CLI, optional legacy Streamlit; separate extended MCP services | Resumable jobs and provider plugins |

See the [target architecture](docs/architecture.md#target-global-research-architecture)
and [delivery roadmap](docs/global-research-roadmap.md).

Recent reliability improvements include separate internal stream/calculation limits, explicit financial units, reproducibility metadata for all indicators, and report downgrades for failed calls or unavailable source documents. See [validation results](docs/testing-results.md) and the [VPS update procedure](docs/vps-deployment.md#update-an-existing-personal-vps).

## How the current version works

```mermaid
flowchart TB
    User["You"] --> Claude["Claude / MCP client"]
    Claude -->|"Bearer-authenticated HTTP"| Outer["Quant Brain MCP<br/>25 market + 4 research tools"]
    Outer -->|"Direct market requests"| Engines["Calculation engines"]
    Outer -->|"Background research job"| Worker["Codex research roles"]
    Worker --> Search["Live web search"]
    Worker -->|"Separate internal token"| Inner["Private MCP<br/>22 read-only tools"]
    Inner --> Engines
    Engines --> Data["Yahoo Finance / yfinance"]
    Worker --> Report["Evidence + review + execution trace"]
    Report -->|"Poll and retrieve"| Claude
    Claude --> Answer["Answer with sources and limitations"]
```

The optional research runtime runs on the same host as the MCP servers, either a
personal computer or a VPS. It uses Codex's
supported sign-in flow; credentials stay with the runtime. Claude receives a
separate MCP bearer token. No Google login is required. There is no order execution.

## Start here

| What you want | Guide |
|---|---|
| Run research locally and connect Claude Code | [Personal research setup](docs/research-runtime.md) |
| Connect Claude Desktop/web or another client | [Getting started](docs/getting-started.md) |
| Deploy the MCP without a dashboard | [Local, VPS and Render setup](docs/deploy-mcp.md) |
| Host personal research continuously on a VPS | [VPS deployment design](docs/vps-deployment.md) |
| Understand the system and its boundaries | [Architecture and diagrams](docs/architecture.md) |

The optional six-role Codex workflow requires its own supported login and model
access; those costs are separate from the free workbench. For that research setup, install Python 3.12 dependencies with
`python -m pip install -r requirements_research.txt`, then follow the research
setup guide to generate private tokens, start both servers, and connect Claude.
The base market server only needs `requirements.txt`.

**Claude Code can reach your local HTTP endpoint.** Claude Desktop/web remote
connectors connect from Anthropic's cloud and need a reachable HTTPS endpoint;
they cannot reach your computer's `localhost`. Local Desktop stdio integrations
are a separate connection method and are not configured by this research setup.

The existing hosted endpoint is `https://mcp-quant-brain.onrender.com/mcp`.
It requires an operator-issued bearer token. Its deployed version, research
configuration, and Codex sign-in must be checked separately; a GitHub push or
successful CI run does not verify that hosted deployment.

## The six research roles

See the [agent and tool map](docs/agents-and-tools.md) for inputs, outputs, exact
tool names, current shared permissions, and proposed specialist permissions.

| Role | Responsibility |
|---|---|
| Lead | Break the question into a research plan. |
| Company analyst | Investigate the business, filings, and news. |
| Quant analyst | Use calculation tools and identify data limitations. |
| Skeptic | Challenge assumptions and conflicting evidence. |
| Auditor | Review existing claims, request corrections, and retain uncertainty. |
| Synthesizer | Assemble the audited conclusions and unresolved points. |

Company and quant work run in parallel. **Quick** uses four roles/calls;
**standard** adds the lead and skeptic with up to one correction round (6–8 calls);
**deep** permits two correction rounds (6–10 calls). Calls and jobs have timeouts.
Reports persist in owner-scoped SQLite storage; clients poll rather than hold a
single HTTP request open. LangGraph orchestrates the research roles: company and
quant run in parallel, then review and bounded correction precede synthesis.
It runs locally inside the backend; no LangGraph cloud account is needed.
SQLite stores jobs and reports; automatic graph crash-resume is not enabled.
See the [workflow and lifecycle diagrams](docs/architecture.md).
Separate jobs execute one at a time; parallel role execution does not mean
unlimited simultaneous research jobs.

## Target global research workflow

This diagram describes proposed components, not the current tool catalog.

```mermaid
flowchart TD
    Q["Question or monitored event"] --> Plan["Plan tasks and budget"]
    Plan --> F["Filing and browser research"]
    Plan --> A["Quant, valuation, macro and portfolio analysis"]
    Providers["Market and disclosure adapters"] --> Gate["Instrument, time, currency and freshness checks"]
    Gate --> F
    Gate --> A
    F --> E["Captured evidence and calculation records"]
    A --> E
    E --> Review["Deterministic validation, skeptic and auditor"]
    Review --> Report["Cited report with unresolved disagreements"]
    Report --> Client["Claude or another MCP client"]
    Report --> Memory["Thesis history and change monitoring"]
    Memory --> Q
```

Independent investigations run in parallel; review follows their results. Simple
requests go directly to calculation tools. The planned browser worker investigates
documents and websites; a market-data adapter supplies quotes and candles.

Example request supported by the current version:

> Use Quant Brain to run quick research on TCS.NS. Check the latest available
> quote and company disclosures. Poll until finished, retrieve the report,
> and give your judgment with source dates, uncertainties, and disagreements.

## What you can use it for

| Ask Claude | What Quant Brain does |
|---|---|
| “Research TCS.NS and explain the strongest counterargument.” | Collects evidence, runs quant tools, challenges claims, and returns an audited report. |
| “Compare RELIANCE.NS and INFY.NS over two years.” | Retrieves historical data and computes requested indicators or backtests. |
| “Show a historical risk scenario for ₹100,000 notional and a 1% budget.” | Reports swing/ATR reference distances and the caller-defined arithmetic budget, with dates and limitations. |
| “Review this portfolio's historical risk.” | Fits allocation on training history and evaluates frozen weights on held-out observations. |
| “Watch these prices.” | Stores owner-scoped alerts; an external scheduler/client must poll and deliver notifications. |

### From a question to an answer

1. Claude calls `start_research` with your question, 1–5 NSE symbols, and a depth.
2. Quant Brain returns a job ID and runs the specialists in the background.
3. Claude polls `get_research_status`, then fetches `get_research_report`.
4. Claude uses the evidence, audit warnings, and execution trace to explain its judgment.

Use `cancel_research` to stop an owned job. A completed job can still report
`insufficient_evidence`; successful execution does not imply a confident answer.
For direct calculations, Claude calls the market tools without starting agents.

## Tools

| Area | Tools and capabilities |
|---|---|
| Research jobs | `start_research`, `get_research_status`, `get_research_report`, `cancel_research` |
| Market research | Quotes, news, historical risk scenarios, watchlist scans, persistent price alerts |
| Thesis Watch | `create_thesis`, `evaluate_thesis`, `get_thesis`, `list_theses`: source-linked assumption checks and change history |
| Company research | Financial statements, filing ingestion/discovery/watches, issuer catalogs and screens, PDF preprocessing, worker health, peers, valuation scenarios and guidance tracking |
| Indicators | Six grouped tools exposing 38 curated indicators |
| Portfolio | Seven optimization methods with chronological holdout evaluation |
| Backtests | Seven rule-based strategy tools |
| Intelligence | Company profiles, sector ranking, sector-to-stock pipeline |
| Charts | Chart packs returned as rendered images |
| Filing analysis | `inspect_filing` (read-only, also available internally) and `analyze_filings` (saved India/US document comparisons); [workflow and limits](docs/filing-workflow.md) |
| Financial facts | Five typed-fact tools (`record_fact`, `get_fact`, `compare_periods`, `calculate_metric`, `get_run_evidence`) over caller-supplied, unverified facts; see the [fact contract](docs/fact-contract.md) |

All **66 tool names, parameters, and response conventions** are documented in the
[tool reference](docs/tools.md). The internal research MCP exposes only 22
read-only tools; alerts, charts, and research orchestration are excluded.

## Validation and limits

The current review-fix release passed **1,578 local tests**, with three optional
skips, and **292 tests in a fresh hash-locked desk installation**. All 18 retained
real India/US filing checks were enabled. Protocol, native PDF, source retention,
privacy, units and dashboard exposure checks passed. See the
[review resolution](docs/review-resolution.md) and [validation report](docs/research-desk-validation.md).

The earlier 29 October reliability milestone added failure/recovery checks,
retained-original verification, source revision guards and supported Indian interim
extraction. At that revision, a real NSE TCS filing passed through the authenticated
MCP with its then-current **55 tools**, and all
**18 retained real India/US filing checks** passed. The offline fallback/outage/recovery
demo runs in both installation profiles. See the [release checks](docs/research-desk-validation.md)
and [filing reliability](docs/filing-reliability.md) for current results and limits.

The earlier 29 October Thesis Watch release passed **1,268 tests**, with 21 optional
integration skips, plus **24 thesis tests in the lean demo environment**.
The synthetic journey passed through the running authenticated MCP over HTTP,
and the original six-call live market check also passed. The checks cover the
deterministic engine, persistence, filing-to-thesis and MCP/HTTP paths. See [Thesis Watch](docs/thesis-watch.md)
for the exact supported scope. These checks do not validate a hosted deployment
or automatic monitoring.

The October 2026 workbench release passed **1,219 tests** locally, with 21
explicit integration skips, plus **47 tests in a clean demo-only environment**.
The actual browser save flow, stdio MCP calls, real chart export, and a Yahoo
history download were also exercised. See [demo validation](docs/demo-validation.md)
for commands, exact scope, and remaining limitations.

An earlier alert/reliability milestone passed **379 tests**, including PostgreSQL and
VPS updater rollback checks, plus HTTP and real PNG export smoke tests. A quick
Codex research job completed with six successful MCP calls and five web-search
events. Blocked source retrieval remained visible and the final report stayed
insufficient-evidence/low-confidence. See the [validation report](docs/testing-results.md)
for exact scope, historical results and limitations; consult CI for the published
revision's Linux checks.

- **Data freshness:** free data can be delayed or unavailable. `as_of` and
  `fetched_at` are retrieval times, not verified trade timestamps. A recent fetch
  does not establish a fresh market price.
- **Evidence:** SDK traces show that tools ran. They do not independently prove
  every claim, citation, or model-written excerpt. `verification_basis` is
  `model_review`.
- **Backtests:** holdout performance is historical. Costs vary by tool; portfolio
  holdout results omit fees, slippage, taxes, and currency conversion.
- **Risk scenarios:** historical reference distances and user-defined budgets
  are not execution levels or loss limits. The public tool returns no share count
  or order instruction; gaps, slippage and fees are not modeled by its distances.
- **Scope:** research jobs currently accept NSE symbols. The broader market tools
  also support US and BSE symbols where their providers do. No automatic trading.

## Optional dashboard and lightweight workbench

Run a complete demo without API keys, a broker account, a model, or network access
after installation. Load clearly labelled synthetic prices or your own daily
OHLCV CSV, inspect indicators, backtest an SMA strategy with next-open fills and
modeled costs, and save the results in SQLite. Optional Yahoo downloads require
network access; provider failures are shown explicitly.

### Run the optional dashboard

Use **Python 3.12**:

```bash
git clone https://github.com/paarths-collab/quant-brain-mcp.git
cd quant-brain-mcp
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements_demo.txt
python -m streamlit run dashboard.py --server.address 127.0.0.1
```

Open `http://localhost:8501`. On Windows, activate with
`.venv\Scripts\Activate.ps1` instead. The default sample is **synthetic**, not a
market-price claim. The app also accepts standard and supported NSE CSV formats.

For a terminal demo:

```bash
python workbench_cli.py demo --output-dir .quant-brain/demo
```

For a local MCP client, launch `python workbench_mcp.py` as a **stdio** server.
It exposes `demo_backtest`, `backtest_csv`, and `describe_data_sources` using the
same calculation engine. See the [five-minute demo and client setup](docs/demo-walkthrough.md)
and [free data sources and limitations](docs/free-data-sources.md).

The workbench is a single-user research tool. Its backtests are historical
simulations, not evidence of future profitability; it does not submit orders.


## Documentation

- [Proposed global market research roadmap](docs/global-research-roadmap.md)
- [Architecture, workflow, job lifecycle, and security boundaries](docs/architecture.md)
- [Evaluation metrics and public benchmark design](docs/evaluation.md)
- [Agents, exact tool catalog, and proposed permissions](docs/agents-and-tools.md)
- [Research runtime, authentication, and Claude connection](docs/research-runtime.md)
- [Tool reference](docs/tools.md) and [example prompts](docs/examples.md)
- [Price alerts](docs/price-alerts.md)
- [Deployment and operations](docs/deployment.md)
- [MCP-only deployment: local clients, Linux supervision and Render](docs/deploy-mcp.md)
- [VPS topology, credentials, persistence, and acceptance checks](docs/vps-deployment.md)
- [Ubuntu VPS installer](scripts/setup-personal-vps.sh) and [environment template](.env.example)
- [Dependency maintenance](docs/dependency-maintenance.md)
- [Validation results and remaining limitations](docs/testing-results.md)

## License

[MIT](LICENSE).


The local filing workflow also supports `analyze_filings(documents, question=...)`
without manual comparison selectors: annual facts, balance-sheet snapshots, EPS,
lookups and guarded arithmetic. The bounded English planner returns its explicit
plan and asks for clarification on ambiguous questions. See
[the filing workflow](docs/filing-workflow.md) for identity, vintage, availability,
units and format limits; this is not arbitrary document QA or a valuation model.

Current document/question test results and comparison limits: [filing-question validation](docs/filing-question-validation.md).

Annual earnings review for non-financial equity research: [use case, workflow and current validation](docs/trader-use-case.md).