# interview-prep-mcp

[![CI](https://github.com/shenmali/Interview-MCP-First/actions/workflows/ci.yml/badge.svg)](https://github.com/shenmali/Interview-MCP-First/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/interview-prep-mcp.svg)](https://pypi.org/project/interview-prep-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/interview-prep-mcp.svg)](https://pypi.org/project/interview-prep-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> An open-source Python MCP server for AI-assisted interview preparation. Runs in any
> MCP-compatible host — Claude Desktop, Cursor, Google Antigravity, Windsurf — and
> defaults to Google Gemini with optional OpenRouter for cross-provider model selection.

## What it does

`interview-prep-mcp` exposes 17 tools that cover the full interview-prep loop:

- **Parse** a job posting (URL or pasted text) and a CV (PDF or markdown).
- **Persist** company and interviewer research collected by the host's other MCPs
  (e.g. `firecrawl`, `exa`) — this server doesn't scrape itself.
- **Generate** personalized interview questions using the active LLM.
- **Submit** practice answers and get scored evaluations.
- **Analyze** weak areas across your practice history.

It also exposes:

- A `interview-prep://interviews/{id}` resource bundling the full prep state for one session.
- Two MCP prompts: `daily_prep` and `mock_interview`.

## Install

The fastest way — no global `pip install`:

```bash
uvx interview-prep-mcp
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "interview-prep": {
      "command": "uvx",
      "args": ["interview-prep-mcp"],
      "env": {
        "GEMINI_API_KEY": "AIza...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}
```

`OPENROUTER_API_KEY` is optional — leave it out if you only want to use Gemini.

### Google Antigravity

Antigravity uses the same `mcpServers` JSON in its MCP settings panel. Paste the same
block as above. Antigravity ships with Gemini already configured at the host level, so
you'll typically only need to add the MCP entry itself.

### Cursor (`~/.cursor/mcp.json`)

Same `mcpServers` block as Claude Desktop.

### Windsurf and other MCP-compatible hosts

Same `mcpServers` block; just paste it into whichever config path the host documents.

## Required env

| Variable | Required? | Purpose |
|---|---|---|
| `GEMINI_API_KEY` | Yes (default) | Direct Gemini API access. |
| `OPENROUTER_API_KEY` | No | Enables `set_model` to switch to any of 200+ OpenRouter models. |

You can run with only one of them set. If neither is set, the server still starts —
context tools (parsing, storage) work; smart tools will return a clear "no LLM provider
configured" error when invoked.

## Recommended companion MCPs

To research companies and interviewers, install these alongside:

- [`firecrawl-mcp`](https://github.com/mendableai/firecrawl-mcp-server) — scrape pages.
- [`exa-mcp-server`](https://github.com/exa-labs/exa-mcp-server) — web search.

The host orchestrates all three. `interview-prep-mcp` exposes `save_research_note` for
the host to persist whatever those companion MCPs returned.

## Quick start (5 minutes)

1. Set `GEMINI_API_KEY` and install the server in your host (see snippets above).
2. In a fresh chat: `parse_job_posting("https://example.com/jobs/123")`.
3. `parse_cv("/path/to/cv.pdf")` — first CV becomes active automatically.
4. `start_interview_prep("Acme", "Senior Backend Engineer", job_id=1, cv_id=1)`.
5. (Optional) Ask Claude to research the company via `firecrawl`/`exa` and call
   `save_research_note(interview_id=1, kind="company", content="...")`.
6. `generate_questions(interview_id=1, count=10, types=["technical","behavioral"])`.
7. Answer questions; each answer goes to `submit_practice_answer`.
8. After several answers: `analyze_weak_areas(interview_id=1)`.

## Tool reference

| Tool | LLM? | Description |
|---|---|---|
| `parse_job_posting(source_or_text, is_html?)` | no | URL or text → structured JobPosting. |
| `parse_cv(file_path)` | no | PDF/markdown → CVProfile. First CV is set active. |
| `list_cv_profiles()` | no | All CVs with their `is_active` flag. |
| `set_active_cv(cv_id)` | no | Switch which CV other tools default to. |
| `match_cv_to_job(job_id, cv_id?)` | yes | Score + strengths + gaps. |
| `start_interview_prep(company, role, job_id?, cv_id?)` | no | New prep session. |
| `list_interviews()` | no | Active prep sessions. |
| `save_research_note(interview_id, kind, content, subject?, source_url?)` | no | Persist markdown research. `kind ∈ {company, interviewer, other}`. |
| `get_research(interview_id)` | no | Grouped by kind. |
| `generate_questions(interview_id, count, types)` | yes | Personalized Qs using job + cv + research. |
| `list_questions(interview_id)` | no | Previously generated. |
| `submit_practice_answer(question_id, answer_text)` | yes | Returns evaluation. |
| `get_practice_history(interview_id)` | no | Past attempts. |
| `analyze_weak_areas(interview_id)` | yes | Recurring gaps + recommended topics. |
| `list_models(provider?, ...filters)` | no | Gemini (curated) + OpenRouter (24h cached). |
| `set_model(model_id, provider?)` | no | Persist active model. |
| `get_active_model()` | no | Current selection. |

## Architecture

```
MCP Host
├── firecrawl-mcp ──────┐
├── exa-mcp ────────────┤
└── interview-prep-mcp ─┘
        │
        ├── Tools layer
        ├── Service layer (parsers + storage + LLM router)
        ├── SQLite (~/.interview-prep/db.sqlite)
        ├── Config (~/.interview-prep/config.json)
        └── LLM router ──┬── Gemini (default)
                         └── OpenRouter (optional)
```

The MCP composes with companion MCPs — it does not scrape itself. The host's Claude
calls `firecrawl`/`exa`, then feeds findings into `save_research_note`.

## Contributing

```bash
git clone https://github.com/shenmali/Interview-MCP-First
cd interview-prep-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
mypy interview_prep_mcp
```

CI runs ruff + mypy + pytest on every PR.

## License

MIT — see `LICENSE`.