# MCP Integration Project — Resume Matching Agent

> **Milestone 2**: Replaces direct file-system tool imports with a fully spec-compliant **Model Context Protocol (MCP)** server, consumed by a **LangGraph** agent.

---

## Architecture

```
User
 │
 ▼
matching_agent.py  (LangGraph state machine)
 │
 │  JSON-RPC 2.0 over stdio
 ▼
mcp_client.py  (subprocess manager + RPC transport)
 │
 ▼
filesystem_mcp_server.py  (MCP server, 6 tools)
 │
 ▼
resumes/  (file system)
```

### Key files

| File | Role |
|------|------|
| `filesystem_mcp_server.py` | JSON-RPC 2.0 MCP server exposing 6 file-system tools |
| `mcp_client.py` | Reusable stdio-transport MCP client with subprocess management |
| `matching_agent.py` | LangGraph agent — discovers + calls tools via MCP |
| `tests/test_mcp_server.py` | Unit tests for all JSON-RPC methods (no subprocess) |
| `tests/test_agent.py` | Integration tests with real subprocess + LangChain bridge |
| `diagrams/workflow_diagram.md` | 6 Mermaid diagrams of the system |

---

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure API key

```bash
cp .env.example .env
# Edit .env and set OPENROUTER_API_KEY
```
Get a free key at [openrouter.ai/keys](https://openrouter.ai/keys).

---

## Running

### Start the Resume Matching Agent

```bash
python matching_agent.py
```

Example queries:
- `"List all resumes in the resumes folder"`
- `"Find candidates with Python skills and rank them by experience"`
- `"Batch read all resumes and create a skills comparison report"`
- `"Watch the resumes folder for new candidates"`
- `"Read Alice Johnson's resume and write a one-paragraph summary"`

### Test the MCP server standalone

```bash
# Send a raw JSON-RPC request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | python filesystem_mcp_server.py

# Test the MCP client
python mcp_client.py
```

---

## Running Tests

```bash
# Unit tests (fast, no subprocess)
python -m pytest tests/test_mcp_server.py -v

# Integration tests (spawns subprocess)
python -m pytest tests/test_agent.py -v -s

# All tests
python -m pytest tests/ -v
```

---

## MCP Server — Available Tools

| Tool | Description |
|------|-------------|
| `read_file(filepath)` | Read PDF, DOCX, or TXT file; returns text + metadata |
| `list_files(directory, extension?)` | List files in a directory with optional filter |
| `write_file(filepath, content)` | Write text to a file (creates dirs as needed) |
| `search_in_file(filepath, keyword)` | Case-insensitive keyword search with context |
| `watch_directory(directory, reset?)` | **NEW** — Snapshot-diff monitoring for new/changed/deleted files |
| `batch_process(filepaths, operation, keyword?)` | **NEW** — Parallel multi-file processing via ThreadPoolExecutor |

## MCP Server — JSON-RPC Methods

| Method | Description |
|--------|-------------|
| `initialize` | MCP handshake; returns server capabilities |
| `initialized` | Client confirmation notification (no response) |
| `tools/list` | Resource discovery — lists all 6 tools with schemas |
| `tools/call` | Execute a named tool with arguments |
| `resources/list` | List file-system resources (resumes directory) |
| `resources/read` | Read a file resource by `file://` URI |
| `ping` | Liveness check |

---

## JSON-RPC 2.0 Error Codes

| Code | Name | When |
|------|------|------|
| `-32700` | Parse Error | Invalid JSON |
| `-32600` | Invalid Request | Not a valid JSON-RPC 2.0 message |
| `-32601` | Method Not Found | Unknown method or tool name |
| `-32602` | Invalid Params | Missing/wrong argument types |
| `-32000` | Tool Error | Tool execution failed |

---

## Workflow Diagrams

See [`diagrams/workflow_diagram.md`](diagrams/workflow_diagram.md) for 6 Mermaid diagrams:
1. System Architecture Overview
2. LangGraph State Machine
3. JSON-RPC 2.0 Message Flow (full sequence diagram)
4. `watch_directory` Polling Flow
5. `batch_process` Parallel Execution
6. Error Handling Flow

---

## Dependency on Milestone 1

This project is a refactoring of the [`LLM-Powered-File-System-Assistant`](../LLM-Powered-File-System-Assistant/) (Milestone 1). The 4 original tools (`read_file`, `list_files`, `write_file`, `search_in_file`) are ported into the MCP server. The direct `import fs_tools` in `llm_file_assistant.py` is replaced by the MCP protocol layer.