Content
# MCP Banking Intelligence Layer (Lab 1 + Lab 2)
This project turns a pile of financial documents into AI-generated **investment
briefs**. It is built in two stages:
- **Lab 1 — RAG + Multi-Agent (AutoGen):** a `ResearchAgent` writes a brief from
data retrieved out of a ChromaDB vector store, and a `CriticAgent` reviews it
until it meets a quality checklist.
- **Lab 2 — MCP Banking Intelligence Layer:** we take Lab 1's tangled retrieval
logic and expose it as a clean **MCP server** of reusable "banking tools."
A LangChain + Ollama agent then acts as the **MCP client**, discovering and
calling those tools at runtime to build the brief — and reuses the Lab 1
`CriticAgent` for the final review.
Lab 2 **reuses the Lab 1 data** (`chroma_db/`). You do **not** re-run `ingest.py`.
---
## 1. What is MCP, and why does it matter?
**MCP (Model Context Protocol)** is an open standard from Anthropic that defines
*how an AI application talks to external tools and data*. Think of it as a
universal adapter — like USB-C for AI tools.
Without MCP, every agent hardcodes its own data access. In Lab 1, the agent
reaches **directly** into ChromaDB. If a new team wants a loan advisor or a fraud
analyst, they must copy and modify the whole codebase.
With MCP, the data/tool logic lives behind a **standard server interface**:
| Concept | What it is | In this lab |
| --- | --- | --- |
| **MCP Server** | Exposes *tools* (typed functions) over a standard protocol | `server.py` — 4 banking tools + 1 bonus |
| **MCP Client** | Discovers and calls those tools at runtime | `client.py` — LangChain/Ollama agent |
| **Transport** | The channel between client and server | `stdio` (client launches server as a subprocess) |
| **Tool** | A typed, documented function the LLM can call | `search_financials`, `get_company_profile`, ... |
**Why this is powerful:** the agent code never names a database. Tomorrow you can
swap ChromaDB for a live Bloomberg feed by editing only `server.py` — the agent
in `client.py` does not change. Tools become *modular and shareable* across any
MCP-compatible client (Claude Desktop, Cursor, your own agent, etc.).
### Key idea: who thinks vs. who fetches
- The **server tools are "dumb" on purpose.** They only retrieve and process
data and return JSON. They **never call an LLM**.
- The **client agent does the thinking.** The LLM looks at the available tools,
decides which to call (this is *not* hardcoded), reads the JSON results, and
writes the brief.
---
## 2. Architecture
### Lab 1 pipeline (RAG + AutoGen)
```
data/financial/*.txt
│ ingest.py (run ONCE)
▼
┌──────────────┐ retriever.py ┌──────────────┐ APPROVED? ┌──────────┐
│ ChromaDB │ ───────────────────────►│ ResearchAgent│ ◄───────────► │ Critic │
│ financial_docs│ (semantic retrieval) │ (drafts) │ feedback │ Agent │
└──────────────┘ └──────────────┘ └──────────┘
│
▼
output/brief_{company}.txt
```
### Lab 2 pipeline (MCP)
```
┌──────────────────────── client.py (MCP CLIENT) ───────────────────────┐
│ │
--company Apple ─┤ LangChain ReAct agent (Ollama: llama3.1) │
│ │ "which tool should I call?" (LLM decides, not hardcoded) │
│ ▼ │
│ langchain-mcp-adapters ──── stdio ───► server.py (MCP SERVER) │
│ ▲ │ @mcp.tool() functions │
│ │ JSON tool results ▼ │
│ └─────────────────────────────── reads chroma_db/financial_docs │
│ │ (reuses retriever.py) │
│ ▼ │
│ draft brief ──► Lab 1 CriticAgent (one review round) ──► revise │
│ │
└──────────────────────────┬───────────────────────────────────────────┘
▼
output/mcp_brief_{company}.txt
```
---
## 3. The MCP tools (`server.py`)
All tools are defined with `@mcp.tool()`, have typed parameters, return
JSON-serializable dicts, and return `{"error": ...}` instead of crashing on bad
input.
| Tool | Signature | What it does |
| --- | --- | --- |
| `search_financials` | `(query: str, company: str, max_results: int)` | Semantic search over `financial_docs` for a company. |
| `get_company_profile` | `(company: str)` | Aggregated metadata: doc count, available years, doc types. |
| `compare_companies` | `(companies: list[str])` | Side-by-side financial summary of two companies. |
| `generate_risk_flags` | `(company: str)` | Scans risk-related docs and returns flagged risk keywords. |
| `get_market_news` *(bonus)* | `(company: str)` | Up to 3 recent headlines via DuckDuckGo (network, not LLM). |
Missing company → `{"error": "company not found", "company": "..."}`.
> Note: `stdio` uses stdout as the protocol channel, so `server.py` logs only to
> **stderr** — it never prints to stdout.
---
## 4. Project structure
```
MCP/
├── data/financial/*.txt # Lab 1 source documents
├── ingest.py # Lab 1 — builds chroma_db (run ONCE, do not re-run)
├── chroma_db/ # Lab 1 vector store (reused by Lab 2)
├── retriever.py # Lab 1 — semantic retrieval (reused by server.py)
├── agents.py # Lab 1 — ResearchAgent + CriticAgent (CriticAgent reused)
├── main.py # Lab 1 — AutoGen pipeline entry point
├── server.py # Lab 2 — NEW: MCP server (4 tools + bonus)
├── client.py # Lab 2 — NEW: LangChain MCP client + CriticAgent
├── output/ # briefs are written here
├── requirements.txt
└── README.md # this file
```
---
## 5. Setup
**Prerequisites**
1. Conda env `agentic` activated: `conda activate agentic`.
2. [Ollama](https://ollama.com) running locally with the models pulled:
```bash
ollama pull llama3.1:latest
ollama pull nomic-embed-text:latest
```
3. Lab 1 already ingested (`chroma_db/` exists). If not, run `python ingest.py` **once**.
**Install Lab 2 dependencies**
```bash
pip install mcp langchain langchain-community langchain-mcp-adapters langchain-ollama langgraph python-dotenv
# or simply:
pip install -r requirements.txt
```
---
## 6. How to run
**Lab 1 (AutoGen):**
```bash
python main.py --company Apple --year 2024
```
**Lab 2 (MCP):**
```bash
python client.py --company Apple
```
`client.py` automatically launches `server.py` as a subprocess — you do not start
the server yourself.
**Quick server smoke test** (optional — it will wait for a client on stdin):
```bash
python server.py # Ctrl+C to stop
```
Output is written to `output/mcp_brief_{company}.txt`.
Companies available in the dataset: **Apple, Amazon, Microsoft, Nvidia, Tesla**
(years 2023–2024).
---
## 7. How the constraints are satisfied
- **Server and client are separate files** — `server.py` and `client.py`.
- **Tools never call the LLM** — they only query/aggregate ChromaDB and return JSON.
- **Tool routing is not hardcoded** — the LLM in the ReAct agent decides which
MCP tools to call.
- **Reuses the existing `financial_docs` collection** — no new ChromaDB is created;
`compare_companies` even reuses Lab 1's `retriever.py`.
- **CriticAgent runs before saving** — `client.py` calls the Lab 1 `CriticAgent`
for one review round on every brief.
- **Errors return JSON** — invalid input yields `{"error": ...}`, never an
unhandled exception.
---
## 8. Troubleshooting
**`ModuleNotFoundError: No module named 'autogen'`**
The Lab 1 code uses the *classic* AutoGen API. The PyPI `pyautogen` name now
redirects to Microsoft's new `autogen-agentchat` packages, which do **not** ship
the `autogen` module. Install the classic-API fork instead:
```bash
pip install ag2
python -c "import autogen; from autogen import AssistantAgent; print('classic AutoGen OK')"
```
**The brief is full of numbers that aren't in our data (hallucination)**
This means the LLM did *not* actually call the MCP tools — it described the calls
in text and made up the answer. `client.py` now prints
`MCP tools actually called by the LLM: ...` and warns if the list is empty.
Confirm whether Ollama tool-calling works at all:
```bash
python diagnose_tools.py
```
- If `TOOL_CALLS` is empty, your Ollama server and/or `langchain-ollama` are too
old to emit structured tool calls. Upgrade both:
```bash
pip install -U langchain-ollama langchain-core langgraph
# update the Ollama server itself (Linux):
curl -fsSL https://ollama.com/install.sh | sh
ollama --version # need a recent version with tool-call support
```
- Tool calling needs a tool-capable model. `llama3.1` supports it; if it is still
flaky, try `ollama pull qwen2.5:7b-instruct` and set `MODEL` in `client.py`.
**`create_react_agent ... LangGraphDeprecatedSinceV10`**
Harmless warning — it still works. (It will move to
`from langchain.agents import create_agent` in a future major version.)
---
## 9. Bonus / extensions
- ✅ `get_market_news()` using DuckDuckGo (implemented).
- 💡 Expose the server over **SSE** transport instead of stdio.
- 💡 Add a `portfolio_summary` tool that calls `compare_companies` +
`generate_risk_flags` in sequence for a list of companies.
