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:
- System Architecture Overview
- LangGraph State Machine
- JSON-RPC 2.0 Message Flow (full sequence diagram)
watch_directoryPolling Flowbatch_processParallel Execution- 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.
