NovaCorp Operations Assistant

MCP + CrewAI — Week 14 Mini-Project (Futurense AI Clinic)

A multi-agent operations assistant that answers business questions by searching local documents and order records. Built with FastMCP (MCP server) and CrewAI (agents). Runs locally with a free/local LLM — no paid API required.

---

What It Does

Given a natural-language question, a crew of three agents:

1. Researcher — searches NovaCorp's policy docs, product notes, and support tickets; reads order records by ID
2. Writer — synthesises evidence into a sourced markdown report saved to outputs/
3. Critic — cross-checks every claim in the report against the retrieved evidence

Every answer cites its source. If no evidence is found, the agent says so rather than guessing.

---

Project Structure

.
├── data/
│   ├── documents/           # 10 NovaCorp policy/product/ticket docs
│   └── records.csv          # 23-row orders dataset
├── mcp_server/
│   └── server.py            # FastMCP server: 3 tools + 1 resource
├── crew/
│   ├── agents.py            # Researcher, Writer, Critic agents
│   ├── tasks.py             # Task definitions
│   └── main.py              # Crew entry point (CLI)
├── tests/
│   ├── test_tools.py        # Unit tests (no server needed) — 18 passing
│   └── test_crew_e2e.py     # End-to-end crew test
├── examples/                # 3 sample Q&A outputs with Critic verdicts
├── traces/                  # Auto-saved run traces (JSON + MD)
├── outputs/                 # Reports written by save_report tool
├── docs/                    # Original assignment brief
├── .env.example             # Copy to .env — no secrets committed
├── ai_usage_log.md          # AI tool usage + real bugs found
├── decision_log.md
├── reflection.md
└── requirements.txt

---

Quick Start (Fresh Clone)

1. Clone and install dependencies

git clone <repo-url>
cd <repo-folder>
pip install -r requirements.txt

2. Configure your LLM

Copy .env.example to .env and choose one LLM backend:

Option A — Ollama (recommended, fully local & free)

# Install Ollama from https://ollama.com, then pull the model:
ollama pull llama3.2:3b
# Then:
cp .env.example .env   # already configured for llama3.2:3b

Option B — Groq (free tier, cloud)

cp .env.example .env
# Edit .env: uncomment GROQ_API_KEY and set your key from console.groq.com

Option C — OpenAI (paid)

cp .env.example .env
# Edit .env: uncomment OPENAI_API_KEY and set your key

3. Run the crew

python crew/main.py "What is the return policy for damaged goods?"
python crew/main.py "What is the status of order ORD-0021?"
python crew/main.py "What warranty does the NX-500 carry?"

The crew will:

• Connect to the MCP server automatically over stdio
• Search documents and/or read order records
• Write a sourced report to outputs/
• Save a run trace to traces/
• Ask for your approval before writing the report (unless AUTO_APPROVE=true in .env)

---

Inspect the MCP Server

Open the MCP Inspector to verify all tools and the resource are registered:

npx @modelcontextprotocol/inspector python mcp_server/server.py

You should see three tools (search_documents, read_record, save_report) and one resource (documents://list).

---

Run Tests

# Unit tests — no LLM needed
pytest tests/test_tools.py -v

# End-to-end test — requires a running LLM
pytest tests/test_crew_e2e.py -v

---

Environment Variables

Variable	Default	Description
OLLAMA_MODEL	ollama/llama3.2:3b	Ollama model to use
OLLAMA_BASE_URL	http://localhost:11434	Ollama endpoint
GROQ_API_KEY	(unset)	Groq API key — overrides Ollama if set
GROQ_MODEL	groq/llama3-70b-8192	Groq model
OPENAI_API_KEY	(unset)	OpenAI key — overrides Ollama if set
OPENAI_MODEL	openai/gpt-4o-mini	OpenAI model
AUTO_APPROVE	false	Skip human approval gate for save_report
USE_HIERARCHICAL	false	Use CrewAI hierarchical (manager) process

---

Stretch Features Implemented

Feature	How
Human approval gate	save_report writes approval prompt to stderr; operator creates outputs/.approve to allow (or set AUTO_APPROVE=true)
Self-check / Critic	Third agent verifies Writer's claims against evidence using search_documents
Observability	Every run saves traces/trace_*.json + traces/run_report_*.md with timing
Hierarchical process	Set USE_HIERARCHICAL=true for manager + worker process via Process.hierarchical

---

Security Notes

• All tool inputs validated with Pydantic; path traversal attempts are rejected
• No secrets committed — use .env only (never .env.example with real keys)
• save_report requires explicit human approval before writing to disk
• MCP server runs over stdio — only trusted local processes connect to it
• max_iter=5 on all agents prevents runaway loops

---

Sample Questions

1. "What is the return policy for damaged goods?"
2. "What is the status of order ORD-0021?"
3. "What warranty does the NX-500 carry and what is its price?"
4. "What was the resolution for support ticket #0019?"
5. "When should a support ticket be escalated to Tier 3?"