# Resume MCP

An MCP (Model Context Protocol) server that gives any compatible AI assistant two tools:

- **`get_master_resume`** — loads a master resume JSON file that the AI uses as its source of truth
- **`generate_resume`** — takes the AI's tailored resume JSON and renders it to a PDF using headless Chromium

When you paste a job description into your AI client, the server's system prompt instructs it to autonomously fetch your master resume, tailor it for the role, and generate a PDF — no extra prompting needed.

---

## How It Works

This server implements the [MCP specification](https://modelcontextprotocol.io) over HTTP using Server-Sent Events (SSE). It includes a full OAuth 2.0 authorization code + PKCE flow so it can be connected to remote AI clients like claude.ai.

```
AI Client (claude.ai, Cursor, etc.)
    ↓  OAuth 2.0 + PKCE
Resume MCP Server  (this repo)
    ↓  reads JSON
Master Resume Files  (your data/ directory)
    ↓  writes PDF
Output Directory  (your output/ directory)
```

---

## Prerequisites

- **Docker** (recommended) — handles all dependencies including Chromium automatically
- **OR** Node.js 20+ with pnpm and a local Chrome or Chromium installation
- A publicly accessible URL if connecting to a remote AI client (e.g. ngrok, Cloudflare Tunnel, or a VPS)

---

## Chrome / Chromium

PDF generation requires a Chrome or Chromium binary. **Docker handles this for you** — Chromium is installed in the container and no configuration is needed.

For local (non-Docker) runs, you need Chrome or Chromium installed on your machine:

- **macOS / Windows** — Google Chrome is almost certainly already installed
- **Ubuntu/Debian** — `sudo apt install chromium-browser`
- **Arch** — `sudo pacman -S chromium`

The server auto-detects common binary names (`google-chrome`, `chromium`, `chromium-browser`). You only need to set `CHROME_PATH` if it isn't found automatically — which is rare.

---

## Quick Start (Docker)

### 1. Clone the repo

```bash
git clone <repo-url> resume-mcp
cd resume-mcp
```

### 2. Create your environment file

```bash
cp .env.example .env
```

Edit `.env` and set at minimum:

```env
OAUTH_CLIENT_ID=resume-mcp-client
```

This value must match what your MCP client sends as `client_id` during the OAuth flow. For claude.ai it will be set automatically; for other clients check their MCP documentation.

### 3. Add your master resume

```bash
mkdir -p data/master-resumes output
```

Place your master resume at `data/master-resumes/default.json`. This is what the AI loads when you call `get_master_resume` without an owner argument.

You can store multiple resumes for different people:

```
data/master-resumes/
  default.json      ← loaded when no owner is specified
  alice.json        ← loaded with { "owner": "alice" }
  bob.json          ← loaded with { "owner": "bob" }
```

See [Master Resume Format](#master-resume-format) for the JSON schema.

### 4. Build and run

```bash
docker compose up --build
```

The server starts on `http://localhost:7331` by default.

### 5. Expose it publicly (required for remote AI clients)

The server must be reachable from the internet for clients like claude.ai. Use ngrok or any tunnel:

```bash
ngrok http 7331
```

Copy the `https://` forwarding URL — you'll use it when adding this server to your AI client.

### 6. Connect your AI client

Add this server to your MCP client using the public URL. The client will walk you through OAuth authorization on first connection, which writes a token to `data/oauth_tokens.json`.

---

## Running Without Docker

Requires Node.js 20+, pnpm, and Chrome/Chromium on your machine (see [Chrome / Chromium](#chrome--chromium) above).

```bash
pnpm install
pnpm start       # production
pnpm dev         # watch mode, restarts on file changes
```

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `OAUTH_CLIENT_ID` | *(required)* | Client ID accepted during OAuth. Must match your MCP client. |
| `OAUTH_CLIENT_SECRET` | *(empty)* | Optional client secret. Leave blank to skip secret verification. |
| `MCP_HOST` | `127.0.0.1` | Bind address. Set to `0.0.0.0` to accept external connections (Docker sets this automatically). |
| `MCP_PORT` | `7331` | Port the server listens on. |
| `DATA_DIR` | Platform data dir | Root directory for `oauth_tokens.json` and the default `master-resumes/` subdirectory. |
| `MASTER_RESUME_DIR` | `$DATA_DIR/master-resumes` | Directory containing master resume JSON files. |
| `MASTER_RESUME_PATH` | *(unset)* | Path to a single default master resume file. Overrides `MASTER_RESUME_DIR` for the default owner. |
| `GENERATED_RESUME_DIR` | Platform documents dir | Where generated PDFs are saved. |
| `CHROME_PATH` | Auto-detected | Path to Chrome or Chromium binary. Only needed if auto-detection fails. |

---

## Master Resume Format

The master resume is a JSON object. The AI uses this as its source of truth and reorganizes/trims it when tailoring for a specific role.

```json
{
  "name": "Jane Smith",
  "location": "San Francisco, CA",
  "email": "jane@example.com",
  "phone": "555-555-5555",
  "linkedin": "https://linkedin.com/in/janesmith",
  "github": "https://github.com/janesmith",
  "portfolio": "https://janesmith.dev",

  "sections": [
    {
      "name": "Technical Skills",
      "type": "grouped",
      "items": [
        { "title": "Languages", "bullets": ["TypeScript", "Python", "Go"] },
        { "title": "Frameworks", "bullets": ["React", "Node.js", "FastAPI"] },
        { "title": "Infrastructure", "bullets": ["Docker", "AWS", "PostgreSQL"] }
      ]
    },
    {
      "name": "Experience",
      "type": "timeline",
      "items": [
        {
          "title": "Acme Corp",
          "sub_title": "San Francisco, CA",
          "position": "Senior Software Engineer",
          "start_date": "2022",
          "end_date": "Present",
          "bullets": [
            "Led migration from monolith to microservices, reducing deploy time by 60%",
            "Built real-time data pipeline processing 2M events/day using Kafka and Go"
          ]
        }
      ]
    },
    {
      "name": "Projects",
      "type": "timeline",
      "items": [
        {
          "title": "My Project",
          "sub_title": "TypeScript, React, PostgreSQL",
          "link": "https://github.com/janesmith/my-project",
          "start_date": "2023",
          "end_date": "Present",
          "bullets": [
            "Description of the project and its impact"
          ]
        }
      ]
    },
    {
      "name": "Education",
      "type": "timeline",
      "items": [
        {
          "title": "State University",
          "sub_title": "City, State",
          "start_date": "2016",
          "end_date": "2020",
          "bullets": ["B.S. Computer Science"]
        }
      ]
    }
  ]
}
```

**Section types:**
- `"grouped"` — renders as a skill list (`Title: item, item, item`)
- `"timeline"` — renders as dated entries with bullets (used for experience, projects, education)

**Tips for a strong master resume:**
- Include everything — the AI removes irrelevant content when tailoring. More is better here.
- Use specific, measurable bullets ("reduced latency by 40%" beats "improved performance").
- List all technologies you've actually used, even if minor — the AI will surface the right ones.

---

## Generated PDFs

PDFs are written to the `output/` directory (or `GENERATED_RESUME_DIR`). When running via Docker, this is a mounted volume so files appear on your host machine immediately after generation.

The AI names files descriptively: `Jane Smith - Senior Engineer - Acme Corp.pdf`

---

## OAuth Notes

The server implements OAuth 2.0 authorization code flow with PKCE (S256). On first connection, your AI client will redirect you through an authorization page and store the resulting token locally. Tokens expire after 30 days, after which you'll need to re-authorize.

OAuth tokens are persisted in `data/oauth_tokens.json`. Do not commit this file.

---

## Multiple Users

To support multiple people generating resumes from the same server, add a named JSON file per person to `data/master-resumes/`:

```
data/master-resumes/alice.json
data/master-resumes/bob.json
```

Then instruct the AI to use a specific owner:

> "Generate a resume for alice targeting this job description: ..."

The AI will call `get_master_resume` with `{ "owner": "alice" }`.