# Interview Prep AI — MCP Agent

An end-to-end interview coach that uses a real **Model Context Protocol (MCP)** server to ground an OpenAI agent in a candidate's resume and a target job description.

The project demonstrates MCP tool discovery, OpenAI Responses API tool calling, multi-step agent orchestration, document ingestion, deterministic evaluation logic, and a polished Streamlit UI.

## What it does

- Upload a resume (`PDF`, `DOCX`, `TXT`, or `MD`)
- Upload or paste a job description
- Analyze matched skills and priority gaps
- Generate role-specific technical, behavioral, and system-design questions
- Evaluate answers with a STAR, relevance, specificity, and quantified-impact rubric
- Inspect every MCP call in an in-app activity trace

## Architecture

```mermaid
flowchart LR
    U[Candidate] --> UI[Streamlit UI]
    UI --> A[OpenAI Responses agent]
    A <-->|tool schemas and calls| C[MCP client]
    C <-->|stdio| S[FastMCP server]
    S --> R[(Resume)]
    S --> J[(Job description)]
    S --> G[Gap analysis]
    S --> Q[Question generator]
    S --> E[Answer evaluator]
```

This is intentionally a genuine client/server MCP design. The LLM discovers JSON schemas from the MCP server, decides which tools to call, and receives each result through the Responses API function-calling loop.

## MCP tools

| Tool | Purpose |
|---|---|
| `get_resume()` | Reads the uploaded resume |
| `get_job_description()` | Reads the target job description |
| `analyze_skill_gaps()` | Compares resume evidence with JD requirements |
| `generate_interview_questions()` | Produces targeted practice questions |
| `evaluate_answer()` | Scores an answer and returns a coaching rubric |

## Run locally

Prerequisites: Python 3.11+ and an OpenAI API key.

```bash
git clone https://github.com/YOUR_USERNAME/interview-prep-mcp.git
cd interview-prep-mcp
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env
# Add your OPENAI_API_KEY to .env
streamlit run app.py
```

The default is `gpt-5.4-mini`, chosen as a cost-conscious tool-calling model. Set `OPENAI_MODEL` in `.env` to use a different compatible model.

## Test the MCP server

Run the unit tests without an API key:

```bash
pytest
ruff check .
```

Start the MCP server directly over stdio:

```bash
interview-prep-server
```

## Privacy

Uploaded resume and JD text are stored only in `.interview_prep/` on the local machine. That directory and `.env` are Git-ignored. Document text is sent to OpenAI only when the agent calls the relevant MCP tool during a workflow.

## Design choices

- **Auditable orchestration:** the UI displays the exact MCP tools used for each answer.
- **Testable core:** skill comparison and answer scoring are deterministic; the LLM interprets and coaches rather than hiding all logic in a prompt.
- **No invented experience:** the system prompt requires resume evidence before claims about the candidate.
- **Bounded agent loop:** tool execution stops after eight rounds to prevent runaway calls.

## Resume bullets

- Built an MCP-based Interview Preparation Agent using Python and OpenAI's Responses API, enabling an LLM to dynamically access resumes, job descriptions, and evaluation tools for personalized interview workflows.
- Implemented agentic tool-calling workflows for skill-gap analysis, targeted question generation, and rubric-based answer evaluation, with an auditable MCP activity trace.

## Roadmap

- Persist separate interview sessions in SQLite
- Add voice answers and transcription
- Export a preparation report as PDF
- Add eval datasets for question quality and scoring consistency
- Deploy the MCP server with authenticated Streamable HTTP transport

## References

- [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling)
- [OpenAI model guide](https://developers.openai.com/api/docs/guides/latest-model)
- [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server)

## License

[MIT](LICENSE)