MCP Integration — Submission Package

This covers the "MCP integration" assignment for the Backend AI Track: Part A (MCP server), Part B (agent refactor + bonus multi-MCP), and the required diagram/tests/demo materials.

Assumption stated up front: the assignment references "Milestone 1 tools." I don't have your actual Milestone 1 code, so I've assumed it was a basic file-reading toolkit (list_files, read_file, search_files) for a resume-matching agent — matching the matching_agent.py / watch_directory() (monitor for new resumes) hints in your brief. If your real Milestone 1 tools differ, swap the tool bodies in filesystem_mcp_server.py — the MCP wrapping pattern stays the same.

Files in this package

Related MCP server: Local Files MCP Server

1. Setup

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Copy .env.example to .env and add your OpenAI key (only needed for matching_agent.py's scoring step — filesystem_mcp_server.py and test_scenarios.py don't need any API key):

cp .env.example .env

Three sample resumes are already included under resumes/incoming/ so the project runs out of the box with no extra setup.

Run the tests:

pytest test_scenarios.py -v

Run the agent end-to-end (this spins up the MCP server itself as a subprocess via stdio, so you don't start it separately):

python matching_agent.py

2. State Machine / Workflow Diagram (Agent ↔ MCP Interaction)

stateDiagram-v2
    [*] --> StartWatch

    StartWatch: Agent calls watch_directory() via MCP client
    StartWatch --> ScanDirectory: MCP server begins polling "incoming/"

    ScanDirectory: Agent calls list_files() via MCP client
    ScanDirectory --> ReadResumes: MCP server returns file metadata (JSON)

    ReadResumes: Agent calls batch_process() via MCP client
    ReadResumes --> MatchAgainstJD: MCP server returns file contents (JSON)

    MatchAgainstJD: Agent scores each resume against the job description (LLM call, no MCP)
    MatchAgainstJD --> [*]: Return ranked matches + log

    note right of StartWatch
        Every arrow crossing into the MCP
        server is a JSON-RPC 2.0 request;
        every arrow back is a JSON-RPC
        2.0 response with status/code/data.
    end note

How to read this: the agent (LangGraph state machine) never touches the filesystem directly. Every box that says "via MCP client" is a JSON-RPC 2.0 call across the process boundary to filesystem_mcp_server.py, which does the actual file I/O and returns a structured JSON result.

3. Test Scenarios Summary (see test_scenarios.py for full code)

1. Listing an empty directory succeeds with an empty file list.

2. Reading a missing file returns a proper 404 error envelope.

3. Reading an existing resume returns its content.

4. Keyword search only returns files that actually contain the keyword.

5. batch_process() handles a mix of valid + missing files gracefully (partial success).

6. batch_process() rejects oversized batches with a 413 error instead of overloading.

7. watch_directory() + get_new_files() detects a resume dropped into the folder mid-run.

8. list_capabilities() (resource discovery) returns every registered tool.

9. Path traversal outside the base directory (e.g. ../../etc/passwd) is blocked with 403.

4. Demo Video Script (5–6 minutes)

0:00–0:45 — Problem & context

• Briefly explain: previously, matching_agent.py called filesystem functions directly (Milestone 1). Show the old direct-call code for contrast.

0:45–2:00 — MCP server walkthrough

• Open filesystem_mcp_server.py. Point out:

  • The Milestone 1 tools now wrapped as @mcp.tool().

  • The two new capabilities: watch_directory() and batch_process().

  • Error handling (_error() envelope with status codes) and list_capabilities() for resource discovery.

  • config.json for configuration management.

2:00–3:30 — Agent refactor walkthrough

• Open matching_agent.py. Point out:

  • MultiServerMCPClient connecting to the filesystem server.

  • No direct os/pathlib calls anywhere in the agent file.

  • The LangGraph nodes (start_watch → scan_directory → read_resumes → match_against_jd) each calling an MCP tool.

  • The commented bonus block showing how a second MCP server (e.g. web search) would be added.

3:30–4:30 — Live run

• Run pytest test_scenarios.py -v and show tests passing.

• Run python matching_agent.py, showing the log output: watch started → directory scanned → resumes batch-read → scores returned.

• Drop a new resume file into resumes/incoming/ during the run to show watch_directory() picking it up live.

4:30–5:30 — Wrap-up

• Show the state diagram from this README and narrate the JSON-RPC round trips.

• One sentence on why this is "production-ready": path-traversal protection, per-file error isolation in batch calls, and configuration externalized to config.json.

5. Deliverables Checklist

• filesystem_mcp_server.py — MCP-based filesystem server

• matching_agent.py — refactored LangGraph agent with MCP client integration

• JSON-RPC 2.0 compliant server (via FastMCP stdio transport) with list_capabilities() resource discovery

• watch_directory() and batch_process() implemented

• State machine / workflow diagram (above, Mermaid)

• Test scenarios (test_scenarios.py)

• Demo video (5–6 min) — record using the script in Section 4

• Multi-MCP bonus — uncomment and point the websearch entry in matching_agent.py at a second real MCP server if you want the bonus credit