mcp-integration

MCP integration

This repository implements the assignment described below. For build, run, and design details of the implementation, jump to the Implementation & Usage Guide further down this file — all documentation lives in docs/ (start at docs/README.md): docs/design/ARCHITECTURE.md, docs/design/HLD.md, docs/design/LLD.md, docs/project/PROJECT_STRUCTURE.md, docs/guides/DEMO_SCRIPT.md.

Brief

Learning Objectives

• Understand Model Context Protocol

• Replace custom tools with MCP servers

• Implement standardized tool interfaces

• Deploy production-ready systems

Related MCP server: maic-server-fs-mcp

Assignment Requirements

Part A: MCP Server Implementation (50%)

Create filesystem_mcp_server.py:

• Convert File System Tools to MCP

• Implement MCP protocol specification

• Expose all Milestone 1 tools as MCP resources

• Add new MCP-specific capabilities:

  • watch_directory() - Monitor for new resumes

  • batch_process() - Handle multiple files efficiently

MCP Server Features

• JSON-RPC 2.0 compliant interface

• Proper error handling and status codes

• Resource discovery endpoints

• Configuration management

Part B: Agent Refactoring (30%)

Update matching_agent.py:

• Replace Custom Tools

  • Remove direct file system tools

  • Connect to MCP server via client

  • Maintain same functionality with cleaner architecture

Multi-MCP Integration (Bonus)

• Connect to additional MCP servers (e.g., web search, database)

• Demonstrate agent using multiple MCP resources

Submission Guidelines

Deliverables

• MCP-based filesystem server implementation (filesystem_mcp_server.py)

• Refactored LangGraph agent with MCP client integration (matching_agent.py)

• JSON-RPC 2.0 compliant MCP server with resource discovery

• Implementation of watch_directory() and batch_process() capabilities

• State machine/workflow diagram of agent ↔ MCP interaction

• Test scenarios demonstrating MCP resource usage and agent workflow

• Demo video (5–6 minutes) showing MCP server, agent integration, and end-to-end execution

Implementation & Usage Guide

Everything below documents how this repository fulfils the assignment above — architecture, how to install/run, the MCP surface, configuration, testing, and how prior feedback was incorporated.

An enterprise, production-oriented implementation of an MCP-based resume/profile matching system, delivered in two parts:

• Part A — MCP Server (filesystem_mcp_server.py): a JSON-RPC 2.0 Model Context Protocol server that exposes the Milestone-1 filesystem tools as MCP tools, adds the MCP-specific watch_directory and batch_process capabilities, and publishes resume documents as discoverable MCP resources.

• Part B — Matching Agent (matching_agent.py): a LangGraph agent that connects to the MCP server(s) as a client (no direct filesystem access), retrieves candidate evidence through a RAG pipeline, and produces a ranked, justified shortlist using Claude — with durable state, retries, and full observability.

Domain. This continues the resume/profile-matching line from the prior milestones (File System Tools → RAG Profile Matching → Agentic Profile Matching). Resumes land in a directory; the agent matches candidates to a job description.

Architecture at a glance

                         ┌──────────────────────────────────────────────┐
                         │                Matching Agent (Part B)         │
   Job description ─────▶ │  LangGraph state machine                       │
   Resumes dir           │   load_job → discover → ingest → retrieve →     │
                         │   rank(Claude) → report                         │
                         │                                                │
                         │   RAG pipeline   ┌──────────────┐              │
                         │   (extract →     │  Vector store │ (external,   │
                         │    chunk →       │  Chroma/disk  │  on-disk)    │
                         │    embed) ──────▶└──────────────┘              │
                         │        ▲                                        │
                         │        │ MCP client (langchain-mcp-adapters)    │
                         └────────┼───────────────────────────────────────┘
                                  │ JSON-RPC 2.0 over stdio / HTTP
                         ┌────────┴───────────────────────────────────────┐
                         │              MCP Server (Part A)               │
                         │  FastMCP · tools + resources · sandboxed FS    │
                         │  read_file · write_file · list_directory ·     │
                         │  file_exists · get_file_metadata · search_files│
                         │  watch_directory · batch_process · metrics     │
                         └────────────────────────────────────────────────┘
                                  │
                         ┌────────┴────────┐
                         │  Sandbox (data/) │  resumes/  jobs/  reports/
                         └─────────────────┘

Full detail: docs/design/ARCHITECTURE.md · docs/design/HLD.md · docs/design/LLD.md · docs/project/PROJECT_STRUCTURE.md · workflow state machine: docs/diagrams/workflow.md.

Quickstart

1. Install

Always install into a project virtualenv (keeps the global environment clean and avoids unrelated global pytest-plugin clashes):

python -m venv .venv
. .venv/Scripts/activate          # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -U pip

pip install -e ".[dev]"           # base + dev tools — light, no torch; offline path works
cp .env.example .env              # then edit as needed

The base install is deliberately small (no torch/chromadb). For the recommended production configuration — local sentence-transformers embeddings and a persistent Chroma store — add the extras:

pip install -e ".[full]"          # sentence-transformers + chromadb
# or individually: pip install -e ".[local]"   /   pip install -e ".[chroma]"

Without the extras the system runs on the offline path (hash embedder + disk store) and logs a one-line hint pointing at .[local].

Installing from a private index (e.g. AWS CodeArtifact): pip uses whatever index-url your pip config / environment defines — no special flags needed. Just ensure your CodeArtifact auth token is current (aws codeartifact login --tool pip …) before installing. To pin the public index instead: pip install -e ".[dev]" --index-url https://pypi.org/simple/.

2. Seed sample data (optional — samples are committed)

python scripts/seed_data.py --root ./data

3a. Run the agent (recommended — it launches the MCP server for you)

The agent, in mcp gateway mode, spawns the Part A server as a subprocess and talks to it over MCP. This is the full Part A + Part B path:

python matching_agent.py --job jobs/backend_engineer.md --resumes-dir resumes --top-n 3

Set ANTHROPIC_API_KEY for Claude-grade reasoning. Without a key it runs fully offline (deterministic stub reasoner + local/hash embeddings), so the whole system is demonstrable with zero external dependencies.

3b. Run the MCP server standalone

python filesystem_mcp_server.py                        # stdio (for MCP clients)
PM_MCP__TRANSPORT=streamable-http python filesystem_mcp_server.py   # networked

Fully-offline run (no API key, no model downloads, no network)

PM_EMBEDDING__PROVIDER=hash PM_VECTOR_STORE__PROVIDER=disk PM_LLM__FORCE_STUB=true \
python matching_agent.py --job jobs/backend_engineer.md --resumes-dir resumes --top-n 3

MCP surface (Part A)

Tools

Every tool returns a stable contract: {"ok": true, "result": …} or {"ok": false, "error": {"code", "message", "kind"}} — JSON-RPC error codes mapped in errors.py, so the client branches programmatically instead of parsing prose.

Resources (discovery)

Configuration

All configuration is typed (src/profile_matcher/config.py, pydantic-settings) and driven by PM_-prefixed env vars with __ nesting. See .env.example for the full list. Highlights:

Testing

pip install -e ".[dev]"
pytest                       # unit + agent tests (offline)
pytest -m integration        # real MCP subprocess end-to-end

Note (shared machines): if an unrelated global pytest plugin breaks collection, isolate the run: PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p pytest_asyncio.plugin.

The suite is fully offline (hash embedder + disk store + stub reasoner). Current status: 38 passing.

Run the embedding ablation study (feedback A):

python scripts/ablation.py --providers hash            # offline
python scripts/ablation.py --providers hash local      # add sentence-transformers

Assignment mapping

How prior feedback was addressed

• RAG (extractor & embedding validation + provider trade-offs). Extractors and embedders are pluggable behind protocols; scripts/ablation.py measures ranking quality (top-1, MRR, separation, cost) across providers, written up in docs/guides/ABLATION.md.

• Agentic (state persistence, error handling, observability). Durable SQLite checkpointing; per-node structured error capture with graceful degradation; structured logging, tracing spans, metrics, and scoped retries with backoff — see docs/guides/OBSERVABILITY.md.

Documentation

All documentation lives under docs/; docs/README.md is the hub.

License

Proprietary — coursework deliverable.