AegisMCP

Local financial PDF risk notes — behind a default-deny MCP tool gateway.

Quickstart · What you get · Architecture · Use case · Docs

Disclaimer: Analyst assistant / research automation only. Not a certified audit opinion, regulatory filing, or legal advice. Human review required.

Why this exists

Most “finance agent” demos are thin wrappers around cloud APIs. That is a non-starter for board packs, M&A drafts, or internal MD&A.

AegisMCP is built for the opposite constraint:

Primary target: Apple Silicon (16GB-class) via Rapid-MLX. Any OpenAI-compatible server (Ollama, vLLM, …) works by changing .env.

Related MCP server: Loki Mode

What ships today (Phases 0–4)

make setup && make demo && make eval && make check

Quickstart

Requirements: Python 3.11+, uv, macOS recommended for Rapid-MLX (optional).

git clone https://github.com/BennedictQuanTon/AegisMCP.git
cd AegisMCP
make setup

Run without an LLM (fastest proof)

make demo    # uses fixtures/pdfs/sample_fy2024_mdna.pdf
make eval    # 12 golden cases
make check   # ruff + mypy + pytest

Open the report:

ls outputs/*/report.md

Run with a local LLM

# Terminal A — one model only on 16GB machines
rapid-mlx serve qwen3.5-4b-4bit --port 8000

# Terminal B
cp -n .env.example .env
make doctor
make llm-smoke
make demo-llm

Ollama instead of Rapid-MLX — same code, different .env:

OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=<your-tag>

Run on your own PDF

cp /path/to/private.pdf ./fixtures/pdfs/
uv run aegis-mcp run fixtures/pdfs/private.pdf --mode heuristic
# or: --mode llm

Paths must stay under AEGIS_WORKSPACE_ROOT (sandbox).

What you get

Input

• One or more local PDFs

• Mode: heuristic (deterministic / CI) or llm (local model)

Output

outputs/<run_id>/
  report.json    # typed RiskReport (schema_version 1.0)
  report.md      # human-readable risk notes
  chunks.json    # optional debug
  trace.json     # if AEGIS_TRACE_ENABLED=true

report.md includes overall risk, executive summary, findings with page-level evidence quotes, compliance checklist results, extracted metrics, limitations, and the analyst disclaimer.

Use case

Scenario: You have a synthetic FY2024 MD&A PDF and want structured risk notes without uploading it anywhere.

uv run aegis-mcp run fixtures/pdfs/sample_fy2024_mdna.pdf --mode heuristic

That is a draft for a human analyst — not an audit sign-off.

Architecture

CLI
 └─ LangGraph  (ingest → condense → extract → compliance → synthesize)
      ├─ OpenAI-compat client  →  Rapid-MLX / Ollama / vLLM  (localhost)
      └─ DefaultDenyGateway
           ├─ pdf.*     (sandboxed)
           └─ sqlite.*  (read-only checklist / run metadata)

flowchart LR
  user[CLI] --> lg[LangGraph]
  lg --> llm[OpenAI_Compat_Local]
  lg --> gw[DefaultDeny_Gateway]
  gw --> pdf[PDF_MCP]
  gw --> db[SQLite_MCP]
  lg --> out[RiskReport_JSON_MD]

Security posture (accurate wording):

• Default deny + role allowlists

• Typed tool arguments

• Workspace path sandbox

• No shell/exec / cloud scrape tools in v1

• FastMCP Host/Origin protection explicitly enabled on HTTP serve

Useful commands

Gateway deny example (should fail):

uv run aegis-mcp mcp call pdf.extract_meta --role synthesis --path fixtures/pdfs/sample_fy2024_mdna.pdf

Repository layout

src/aegis_mcp/     # CLI, graph, agents, schemas, LLM, MCP gateway, eval, obs
tests/             # unit + integration
fixtures/          # sample PDF, checklist, golden eval cases
docs/              # inference, MCP, evaluation, observability
docker/            # optional Langfuse (--profile obs)
Makefile
pyproject.toml

Documentation

Roadmap snapshot

• Done: Phases 0–4 (scaffold, inference contract, MCP gateway, orchestration MVP, obs + eval)

• Next (Phase 5): OSS ship surface — architecture visuals, static docs landing, demo recording, contributor issues, pre-launch VALIDATE checklist

• Explicitly deferred: product audit dashboard UI, dual-model hot-swap, cloud tools, huge DeepEval CI on GitHub-hosted runners

License

MIT © Long Quan (Bennedict) Ton

Disclaimer (again, on purpose)

AegisMCP helps you draft structured risk notes from local PDFs. It does not produce certified audit opinions, regulatory filings, or legal advice. Always review outputs before any professional use.