# FAQ RAG + MCP Tool (Starter Skeleton)

This is a minimal starting point for the MCP option.

## Contents
- `rag_core.py` — RAG core
- `mcp_server.py` — MCP server exposing `ask_faq`
- `faqs/` — tiny sample corpus
- `requirements.txt`

## Quick Start
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

export OPENAI_API_KEY=sk-...

# Optional model overrides
# export EMBED_MODEL=text-embedding-ada-002
# export LLM_MODEL=gpt-3.5-turbo

# Run a quick CLI smoke test
python rag_core.py

# Configure your MCP client to spawn the server
# command: python
# args: [/absolute/path/to/mcp_server.py]
# env: { OPENAI_API_KEY: "sk-..." }
```

## Design Principles (Evaluation Criteria)

This implementation prioritizes **Simplicity**, **Practicality**, and **Interface Correctness**.

### 1. Simplicity over Over-Engineering
-   **No Vector Database**: Instead of adding heavy dependencies like Chroma or Pinecone, we use `numpy` for in-memory cosine similarity. For a filtered FAQ lists, this is faster, easier to debug, and removes deployment complexity.
-   **FastMCP**: We use the high-level `FastMCP` interface to reduce boilerplate, keeping the server code focused on logic rather than protocol details.
-   **Global State**: We preload the corpus at import time for simplicity in this specific "server" context, avoiding complex dependency injection containers.

### 2. Practicality
-   **Robust Error Handling**: The server uses structured logging and catches API errors (e.g., rate limits) to prevent crashes, returning user-friendly error messages to the LLM.
-   **Exposed Resources**: The `faq://` resource allows the LLM (and developers) to inspect the raw content of any FAQ file, which is crucial for verifying answers or debugging retrieval issues.
-   **Pre-defined Prompts**: The `ask_faq_expert` prompt helps users/LLMs start with the right context immediately.

### 3. Interface Correctness
-   **Standard MCP Patterns**: We strictly follow MCP standards by exposing Tools (action), Resources (data), and Prompts (context).
-   **Type Safety**: All tools use Python type hints (`str`, `int`) which `FastMCP` automatically converts to JSON-Schema for the LLM to understand.