MCP Resume Matching

A LangGraph resume-matching workflow that accesses resumes exclusively through an MCP stdio server. The official MCP Python SDK owns MCP initialization, capability discovery, and JSON-RPC 2.0 transport; application code does not implement JSON-RPC itself.

Architecture

LangGraph matching agent
        |
        v
Filesystem MCP client
        |
        | MCP / JSON-RPC 2.0 / stdio
        v
Filesystem MCP server
        |
        v
Filesystem service
        |
        v
Configured resume directory

See docs/architecture.md for the full component and workflow diagrams.

Related MCP server: filesystem-mcp-server

Install

Python 3.11 or newer is required.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"

Configuration

For example:

$env:RESUME_DIRECTORY = "$PWD\resumes"
$env:RESUME_EXTENSIONS = ".txt,.md,.pdf,.docx"

MCP Tools

Tool input schemas are generated from the Python type annotations by FastMCP. Domain failures include an error type and actionable message; the client raises a contextual MCPToolError for those failures.

MCP Resources

Resume text is also available through the parameterized resource URI:

resume://<filename>

For example, resume://candidate.txt returns the text for candidate.txt. This is a resource template, so MCP exposes it through resources/templates/list as resume://{file}; clients then read a concrete URI through resources/read. It applies the same root, extension, traversal, and symlink-escape checks as read_file.

Running the MCP Server

The server uses stdio and is normally launched by the client. To run it for MCP Inspector or another MCP host:

python filesystem_mcp_server.py

Do not type plain text into its terminal: it expects MCP JSON-RPC messages from its host.

Running the Agent

$env:RESUME_DIRECTORY = "$PWD\resumes"
python matching_agent.py

The agent starts and closes its own MCP subprocess, discovers required tools, batches the available resumes, and ranks them with the existing deterministic matching logic.

Batch Processing

batch_process accepts only relative paths. It keeps the first occurrence of duplicates, preserves first-seen order, uses bounded worker concurrency, and continues after a missing, unsupported, or malformed file.

{
  "files": ["alice.txt", "missing.txt", "alice.txt"],
  "max_concurrency": 4
}

Its result includes requested, duplicates_ignored, processed, successful, failed, and ordered per-file results.

Directory Watching

watch_directory is deliberately a single, stateless polling call rather than an unbounded MCP request or background worker. Call it once, retain known_files, then submit that list on the next call:

{"known_files": ["alice.txt", "bob.md"]}

It returns new_files and the refreshed known_files. Unsupported files are excluded. A missing or unavailable configured directory yields a structured error response instead of blocking indefinitely. The legacy files and known keys are retained as aliases for older callers.

Error Handling and Security

The filesystem service is the sole authority for filesystem access. It rejects absolute paths, .. traversal, paths resolving through a symlink outside the configured root, and extensions outside the configured allowlist. It exposes no arbitrary file read capability. Batch operations isolate expected per-file errors while unexpected errors are logged and represented in that file's result.

MCP connection, tool, and resource errors preserve the tool/resource name and diagnostic context. The service logs detailed operational failures but does not return absolute internal paths as part of file-read errors.

Testing

python -m pytest

The deterministic suite uses temporary directories and covers service behavior, filesystem boundaries, batch success/failure/duplicates/invalid input, bounded watching, MCP stdio startup and initialization, tool/resource discovery and reads, MCP error propagation, agent-to-MCP integration, and end-to-end ranking.

Demo Walkthrough (6 minutes)

Limitation

The repository's existing matching policy is deterministic token-overlap ranking. This MCP refactor preserves that existing behavior; it does not introduce an external LLM or a new paid model dependency.