<div align="center">

# AegisMCP 

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

<p align="center">
  AegisMCP is a CLI-first, air-gapped-by-default multi-agent workspace for private financial documents. PDFs stay on your machine. Agents talk to tools only through an allowlisted gateway. Outputs are typed <code>RiskReport</code> JSON + Markdown — with evidence citations — not free-form chat spam.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/LangGraph-Multi--Agent-FF6F00?style=for-the-badge&logo=langchain&logoColor=white" alt="LangGraph">
  <img src="https://img.shields.io/badge/MCP-FastMCP-8A2BE2?style=for-the-badge&logo=anthropic&logoColor=white" alt="FastMCP">
  <img src="https://img.shields.io/badge/Pydantic-v2-E92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic">
  <img src="https://img.shields.io/badge/Apple_Silicon-MLX_/_Local-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Apple Silicon">
  <img src="https://img.shields.io/badge/SQLite-Read--Only-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite">
  <img src="https://img.shields.io/badge/uv-Fast_Package_Manager-DE5B43?style=for-the-badge&logo=astral&logoColor=white" alt="uv">
  <img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License">
</p>

[Quickstart](#quickstart) · [What you get](#what-you-get) · [Architecture](#architecture) · [Use case](#use-case) · [Docs](#documentation)

</div>

> **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:

| Principle | What it means here |
|-----------|--------------------|
| **Local by default** | No cloud tools in the default path; OpenAI-compatible localhost inference |
| **Default-deny tools** | PDF / SQLite only; roles cannot call what they are not allowlisted for |
| **Typed last mile** | Pydantic `RiskReport` — high/critical findings need evidence quotes |
| **Honest claims** | Defense-in-depth gateway — not “absolute Zero-Trust” or “CVE eliminated” |

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

---

## What ships today (Phases 0–4)

| Capability | Status |
|------------|--------|
| CLI golden path: PDF → `RiskReport` | Done |
| Heuristic mode (no LLM required) | Done |
| LLM mode (Rapid-MLX / Ollama / OpenAI-compat) | Done |
| Local PDF + read-only SQLite MCP tools | Done |
| Default-deny role allowlists + path sandbox | Done |
| FastMCP HTTP with explicit Host/Origin protection | Done |
| LangGraph orchestration (ingest → extract → compliance → synthesize) | Done |
| 12-case golden eval (CI-safe, no Apple Silicon needed) | Done |
| Optional local traces (`trace.json`) | Done |
| Optional Langfuse Docker profile | Done (off by default) |
| Product web UI / audit dashboard | **Not in scope** (deferred) |
| Static marketing landing + launch VALIDATE | Phase 5 |

```bash
make setup && make demo && make eval && make check
```

---

## Quickstart

**Requirements:** Python 3.11+, [uv](https://docs.astral.sh/uv/), macOS recommended for Rapid-MLX (optional).

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

### Run without an LLM (fastest proof)

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

Open the report:

```bash
ls outputs/*/report.md
```

### Run with a local LLM

```bash
# 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`:

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

### Run on your own PDF

```bash
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

```text
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.

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

| | Example |
|--|---------|
| **In** | Local PDF mentioning revenue, gross margin, liquidity, related-party, debt covenants |
| **Out** | `overall_risk` (e.g. high), findings with quotes, checklist hits (LIQ / REL / DEBT…), metrics when extractable, JSON + Markdown under `outputs/` |

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

---

## Architecture

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

```mermaid
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

| Command | Purpose |
|---------|---------|
| `make demo` | Fixture PDF → report (heuristic) |
| `make demo-llm` | Same path via local LLM |
| `make eval` | 12 golden evaluation cases |
| `make check` | Lint, types, tests |
| `make doctor` | Config + optional LLM ping |
| `make mcp-init` | Seed local SQLite checklist |
| `uv run aegis-mcp mcp call …` | Call tools through the gateway |
| `AEGIS_TRACE_ENABLED=true make demo` | Write `trace.json` |

Gateway deny example (should fail):

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

---

## Repository layout

```text
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

| Doc | Topic |
|-----|--------|
| [docs/inference.md](docs/inference.md) | Rapid-MLX / OpenAI-compat setup & 16GB RAM envelope |
| [docs/mcp.md](docs/mcp.md) | Tool gateway, roles, FastMCP serve |
| [docs/evaluation.md](docs/evaluation.md) | Golden suite + optional DeepEval |
| [docs/observability.md](docs/observability.md) | Local traces + optional Langfuse |

---

## 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.