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

pip install -r requirements.txt

2. Configure API key

cp .env.example .env
# Edit .env and set OPENROUTER_API_KEY

Get a free key at openrouter.ai/keys.

---

Running

Start the Resume Matching Agent

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

# 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

# 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 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 (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.