Pozsar Corpus MCP

Rust tooling for building a local, source-cited knowledge base from a Zoltan Pozsar PDF corpus, exposing it through a read-only MCP server, generating file-based cross-asset market context snapshots, and composing advisor-ready context.

The CLI can fetch historical closes from a Yahoo-compatible endpoint, but it only writes local snapshot artifacts. The MCP and advisor paths never fetch market data directly. The project does not include streaming feeds, trading signals, backtesting, portfolio management, broker or exchange adapters, or execution code.

Why Pozsar

Zoltan Pozsar's work is important because it connects macroeconomics to the balance-sheet plumbing that often drives markets: collateral, repo, eurodollars, FX swaps, reserves, shadow banking, safe assets, and commodity-linked money. His writing is useful for studying how liquidity moves through the financial system and why stress can appear outside the places covered by standard macro indicators.

This project turns that corpus into a local, source-cited research layer so agents and analysts can retrieve the original passages behind a macro or liquidity question instead of relying on unsourced summaries.

What It Does

• Downloads and verifies source PDFs from a hash-pinned source map
• Manifests local PDFs in docs/
• Extracts page-level text from PDFs
• Chunks extracted pages with source metadata
• Tags chunks with deterministic macro/liquidity themes
• Writes versioned corpus artifacts under data/knowledge/
• Builds a Tantivy BM25 index over text and source metadata
• Validates generated corpus artifacts with corpus inspect
• Runs fixture-backed retrieval, advisor, and policy evaluations
• Runs a read-only MCP server for source-cited search and evidence workflows
• Prepares Qdrant-compatible payloads for future vector indexing
• Builds deterministic market context JSON from local price CSV files
• Fetches supported historical market closes through a Yahoo-compatible adapter
• Builds deterministic advisor snapshots that combine corpus liquidity signals with market context
• Builds deterministic advisor policy JSON from advisor snapshots without producing trade recommendations

Repository Layout

crates/
  advisor-core/   Offline advisor snapshot composition logic
  advisor-policy/ Deterministic advisor policy assessment logic
  corpus-cli/     Corpus, evaluation, market-context, and advisor CLI
  market-data-adapters/ Historical market-data provider abstraction and Yahoo adapter
  market-context/ Offline cross-asset market context library
  pozsar-common/  Artifact envelopes, typed operational errors, and exit codes
  pozsar-kb/      Corpus pipeline, inspection, BM25 indexing, search, and fallback retrieval
  pozsar-mcp/     Read-only MCP server over generated corpus chunks
docs/             Source map, usage docs, and ignored downloaded PDFs
data/knowledge/   Generated corpus artifacts; ignored by git
data/market/      Local/sample market CSV inputs and ignored generated JSON context
data/advisor/     Ignored generated advisor snapshots and policy artifacts

Local PDF Inputs

This repository does not redistribute Pozsar PDFs. PDF files in docs/ are ignored by git and are excluded from release archives. Users rebuild the local corpus by downloading the documents from public source links recorded in docs/SOURCE_MAP.md and Zoltan-Pozsar-Bibliography.html.

corpus download-sources can rebuild the local PDF set, and corpus verify-sources checks local PDF hashes and source URLs before corpus generation.

See docs/README.md for details.

Fresh Clone Install And Run

For a shorter guided path with a raw MCP demo search, see docs/QUICKSTART.md.

From a fresh clone:

git clone <repo-url>
cd zp_base
cargo build --workspace
cargo run -p corpus-cli -- download-sources --docs docs --source-map docs/SOURCE_MAP.md
cargo run -p corpus-cli -- verify-sources --docs docs --bibliography Zoltan-Pozsar-Bibliography.html --source-map docs/SOURCE_MAP.md
cargo run -p corpus-cli -- build --docs docs --out data/knowledge
cargo run -p corpus-cli -- inspect --out data/knowledge
cargo build --release -p pozsar-mcp
target/release/pozsar-mcp --version

Run the MCP server with the generated chunk artifact:

POZSAR_CHUNKS_JSONL="$PWD/data/knowledge/chunks/pozsar_chunks.jsonl" \
  target/release/pozsar-mcp

The MCP server uses stdio, so this command waits for an MCP client instead of printing an interactive prompt.

Build The Corpus

Download the local PDF corpus first:

cargo run -p corpus-cli -- download-sources --docs docs --source-map docs/SOURCE_MAP.md

cargo run -p corpus-cli -- build --docs docs --out data/knowledge

This writes:

data/knowledge/manifest.json
data/knowledge/extracted_pages.jsonl
data/knowledge/chunks/pozsar_chunks.jsonl
data/knowledge/lexical_index/

The default build includes the lexical index. Building corpus-cli with --no-default-features omits Tantivy and leaves search on the compatibility keyword fallback.

Inspect The Corpus

cargo run -p corpus-cli -- inspect --out data/knowledge

The inspection command reports document/page/chunk counts, empty pages, pages without chunks, validation issues, and theme distribution. It exits nonzero if validation issues are found.

Search And Retrieval Modes

The default search path uses Tantivy BM25 over chunk text, title, canonical themes, file name, and citation. Requests can filter by theme, document ID, file name, and page. Results report the requested and resolved modes, warnings, BM25 score, matched terms, rank, and source citation.

lexical, vector, and hybrid are accepted mode names, but this release resolves all three to lexical. Embeddings, vector lookup, Qdrant collection management, and lexical/vector fusion are not implemented. When a compatible lexical_index/ is absent or stale, search attaches a warning and uses the deterministic keyword fallback for older artifacts.

answer_pozsar_research_question is a separate deterministic evidence-bundle workflow. It plans keyword/theme queries, returns cited passages with neighboring context, and suggests follow-ups; it does not generate a prose answer. Liquidity-signal and advisor workflows currently build on this evidence path rather than raw BM25 search.

Build Market Context

Generate an offline market context snapshot from a local CSV file:

cargo run -p corpus-cli -- market-context \
  --prices data/market/sample_prices.csv \
  --out data/market/context.json

Input CSV columns:

date,symbol,close
2026-06-24,BTC,101000
2026-06-25,BTC,103000

The output includes per-asset returns, 20-observation trend, annualized volatility, drawdown, and a deterministic cross-asset regime summary. This is local market context only; it does not produce trade recommendations.

Fetch Historical Market Context

Fetch a point-in-time set of historical closes through the Yahoo-compatible CSV adapter, normalize them into date,symbol,close, reuse the existing market-context calculations, and write the same local MarketContext JSON format plus a health sidecar:

cargo run -p corpus-cli -- fetch-market-context \
  --provider yahoo \
  --assets BTC,ETH,SPY,QQQ,GLD,TLT,DXY \
  --lookback 60 \
  --out data/market/context.json

The supported symbols are BTC, ETH, SPY, QQQ, GLD, TLT, and DXY. The command prints a health report for freshness, missing assets, stale prices, and insufficient history. It exits nonzero if blocking health issues are found. MCP and advisor tools consume only the generated files; they do not fetch market data directly.

Generated files:

data/market/context.json
data/market/context.health.json

Build Advisor Snapshot

Combine corpus liquidity evidence with a local market context snapshot:

cargo run -p corpus-cli -- advisor-snapshot \
  --chunks data/knowledge/chunks/pozsar_chunks.jsonl \
  --market-context data/market/context.json \
  --market-health data/market/context.health.json \
  --question "What does collateral scarcity imply for cross-asset liquidity?" \
  --assets BTC,ETH,SPY,QQQ,GLD,TLT,DXY \
  --themes collateral,dollar_liquidity,repo \
  --out data/advisor/snapshot.json

The output includes source-cited liquidity signals, market context, per-asset macro/market alignment, and a combined regime label such as macro_tightening_market_risk_on. It is deterministic context for a future advisor layer, not trading advice.

If --market-health is supplied, its as_of must match the market context as_of. Health status is retained in the snapshot and affects policy confidence and risk fields; an as_of mismatch is rejected.

Build Advisor Policy

Convert an advisor snapshot into deterministic asset assessments:

cargo run -p corpus-cli -- advisor-policy \
  --snapshot data/advisor/snapshot.json \
  --out data/advisor/policy.json

The policy output includes per-asset stance, confidence, drivers, risks, and required checks. It remains context-only: no trade recommendation, position sizing, or execution instruction is emitted.

Verify PDF Sources

cargo run -p corpus-cli -- verify-sources \
  --docs docs \
  --bibliography Zoltan-Pozsar-Bibliography.html \
  --source-map docs/SOURCE_MAP.md

The verifier compares local ignored docs/*.pdf files with direct PDF links in the bibliography, checks each source-map URL and SHA-256 hash, and exits nonzero on mismatch.

Evaluate Retrieval

Run fixture-backed golden-query checks against a chunk artifact:

cargo run -p corpus-cli -- eval-search \
  --chunks data/knowledge/chunks/pozsar_chunks.jsonl \
  --cases eval/fixtures/pozsar_eval.json \
  --limit 5 \
  --tool research-question \
  --format text \
  --fail-fast \
  --output data/eval/research-question-report.json

The eval command reports pass/fail per case, returned citations, expected citation ranks, missing citations, category summaries, and a summary count. Use --tool search to test raw local search or --tool research-question to test the research bundle path. Use --format json for CI or machine-readable regression artifacts. Use --output <path> to write the report to disk while printing only the output path and summary to stdout. Use --fail-fast to stop after the first failing case. It exits nonzero if any expected citation is missing or ranked too low. Keep public-safe fixtures under eval/fixtures/; use ignored local files under eval/local/ or eval/*.json for private corpus cases.

To evaluate the BM25 path specifically, select the raw search tool and lexical mode:

cargo run -p corpus-cli -- eval-search \
  --chunks data/knowledge/chunks/pozsar_chunks.jsonl \
  --cases eval/fixtures/ci_eval.json \
  --tool search \
  --mode lexical \
  --limit 5

Eval cases can include optional max_rank to require each expected citation to appear by that rank:

{
  "name": "collateral dollar liquidity",
  "category": "dollar_liquidity",
  "notes": "Core liquidity plumbing query; should surface Safe Asset Glut early.",
  "query": "collateral dollar liquidity",
  "themes": ["collateral"],
  "expected_citations": ["The_Safe_Asset_Glut.pdf:7"],
  "max_rank": 3
}

Run The MCP Server

By default, the MCP server reads data/knowledge/chunks/pozsar_chunks.jsonl:

cargo run -p pozsar-mcp

To point it at another chunk artifact or market context snapshot:

POZSAR_CHUNKS_JSONL=/path/to/pozsar_chunks.jsonl \
POZSAR_MARKET_CONTEXT_JSON=/path/to/context.json \
  cargo run -p pozsar-mcp

Available MCP tools:

• get_pozsar_kb_status
• list_pozsar_docs
• list_pozsar_themes
• search_pozsar_kb
• explain_pozsar_search
• read_pozsar_source
• read_pozsar_page_context
• answer_pozsar_research_question
• extract_pozsar_liquidity_signals
• get_pozsar_advisor_snapshot
• get_pozsar_advisor_policy

Search tools return a versioned envelope containing requested/resolved mode, warnings, and ranked results. Results include citations in file_name:page format. The server is read-only, uses stdio, and loads the chunk snapshot once at startup.

Run a raw MCP advisor snapshot demo after building the release binary and local artifacts:

scripts/demo-mcp-advisor.sh

Run the raw search and page-context demo with:

scripts/demo-mcp-search.sh

For Claude Desktop and Codex configuration examples, tool parameters, and response shapes, see docs/MCP.md.

Check the MCP binary version without starting the stdio server:

cargo run -p pozsar-mcp -- --version

Package a release tarball under dist/:

scripts/package-release.sh

Smoke-test the package against a built corpus:

scripts/smoke-package.sh \
  dist/pozsar-corpus-mcp-0.1.0-<target>.tar.gz \
  data/knowledge/chunks/pozsar_chunks.jsonl

For example MCP prompts and a sample eval report, see docs/EXAMPLES.md.

For the full maintainer release flow, see RELEASE.md.

Before public publishing, complete docs/PUBLICATION_CHECKLIST.md, especially the PDF redistribution review.

Current Limits

• No vector search, embeddings, hybrid fusion, or reranking; Qdrant support is payload-only.
• No incremental corpus builds, OCR fallback, table extraction, or structure-aware chunking.
• No MCP HTTP transport, authentication, resources, prompts, pagination, or hot reload.
• No generated narrative answer; research and advisor outputs are deterministic structured data.
• No trading recommendations, P&L backtests, positions, portfolio risk, or order execution.
• Retrieval evaluation checks expected citations and rank ceilings; it does not yet report MRR, Recall@K, or nDCG.

License

This project's source code and documentation are distributed under the MIT License; see LICENSE.

The Pozsar PDFs are not distributed by this repository or release packages. They are downloaded by users from public source URLs listed in docs/SOURCE_MAP.md, and those documents remain subject to their original publishers' terms.

Development Checks

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo check -p pozsar-kb --no-default-features
cargo check -p corpus-cli --no-default-features

Git Policy

Tracked:

• Rust workspace source
• Cargo.lock
• LICENSE and CHANGELOG.md
• README files
• source-map and bibliography files for rebuilding PDFs
• tests and small fixtures

Ignored:

• target/
• data/knowledge/
• dev_docs/
• docs/*.pdf
• local env/log files