Banking Intelligence Server

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 running locally with the models pulled:

   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

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

python main.py --company Apple --year 2024

Lab 2 (MCP):

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

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:

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:

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:

  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.