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.

Related MCP server: Meeting Transcript Analyzer

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

Stretch Features Implemented

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?"