# Milestone 2 — MCP-Based Resume Matching System

## Architecture Overview

```
┌─────────────────────────┐     JSON-RPC 2.0 (TCP)    ┌─────────────────────────────┐
│   matching_agent.py     │ ◄──────────────────────── │  filesystem_mcp_server.py   │
│   (LangGraph + GPT-4)   │ ──────────────────────── ►│  (MCP Server, port 8765)    │
│                         │                            │                             │
│  Nodes:                 │   tools/call → result      │  Tools exposed:             │
│  1. load_job_desc       │                            │  • read_file                │
│  2. load_resumes        │                            │  • write_file               │
│  3. watch_new_resumes   │                            │  • list_directory           │
│  4. match_candidates────┼──► GPT-4o (OpenAI API)    │  • search_files             │
│  5. save_report         │                            │  • get_file_info            │
└─────────────────────────┘                            │  • delete_file              │
                                                       │  • watch_directory ★        │
                                                       │  • batch_process ★          │
                                                       └─────────────────────────────┘
```

## Setup

```bash
pip install -r requirements.txt
export OPENAI_API_KEY="sk-..."
```

## Running

### Step 1 — Start the MCP server (TCP mode)
```bash
python filesystem_mcp_server.py --transport tcp --port 8765
```

### Step 2 — Run the agent (separate terminal)
```bash
python matching_agent.py --jd job_descriptions/senior_engineer.txt --resumes resumes/
```

### Step 3 — Run tests
```bash
python -m pytest tests/ -v
```

### Demo (all-in-one)
```bash
python demo_runner.py
```

## Files

| File | Purpose |
|------|---------|
| `filesystem_mcp_server.py` | MCP server — JSON-RPC 2.0, 8 tools, stdio + TCP transport |
| `mcp_client.py` | Async MCP client used by the agent |
| `matching_agent.py` | LangGraph agent with 5 nodes, all I/O via MCP |
| `tests/test_mcp_system.py` | 29 unit tests (JSON-RPC, tools, batch, watch) |
| `demo_runner.py` | End-to-end demo script |
| `resumes/` | Sample resume files (alice_chen.txt, bob_martinez.txt, priya_nair.txt) |
| `job_descriptions/` | Sample JD (senior_engineer.txt) |
| `logs/` | Server logs + generated match reports |

## MCP Protocol Details

The server implements **MCP 2024-11-05** over JSON-RPC 2.0.

### Lifecycle
```
Client → initialize (protocolVersion, capabilities)
Server → {protocolVersion, capabilities, serverInfo}
Client → initialized  (notification, no response)
```

### Tool call
```json
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"batch_process","arguments":{...}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{...}"}],"isError":false}}
```

### Error codes
| Code | Meaning |
|------|---------|
| -32700 | Parse error (invalid JSON) |
| -32601 | Method not found |
| -32602 | Invalid params (missing required field) |
| -32001 | File not found |
| -32002 | Permission denied / path traversal |

## watch_directory

Polls a directory every N seconds for new `*.txt` files. Returns `file_created` events:
```json
{"event": "file_created", "path": "resumes/new_candidate.txt", "timestamp": "...", "size_bytes": 1234}
```

## batch_process

Processes multiple files in one RPC call. Operations:
- `read_all` — return full content of each file
- `word_count` — words, lines, chars per file
- `extract_emails` — regex-extracted emails per file
- `summarize_stats` — compact metadata for matching pipeline