# 🤖 MCP Filesystem Server + LangGraph Agent

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![MCP](https://img.shields.io/badge/MCP-2.2.0-green)
![LangGraph](https://img.shields.io/badge/LangGraph-1.2.11-orange)
![Tests](https://img.shields.io/badge/tests-30%2B%20passing-brightgreen)

> **A Model Context Protocol (MCP) filesystem server + LangGraph agent for agentic resume matching.**

## 📋 Overview

This project converts a traditional filesystem toolbox into a **standardized MCP server** that any MCP-compatible client (VSCode, Claude Desktop, Cursor) can connect to. It then demonstrates a real-world use case: a **LangGraph resume matching agent** that uses only MCP resources for filesystem access.

### Key Features

- 🔌 **Full MCP Server** — JSON-RPC 2.0 compliant, stdio transport
- 🛠️ **6 Filesystem Tools** — read, list, write, search, watch, batch
- 📊 **Metrics Tracking** — request counts, latencies, error codes
- 🧪 **30+ Tests** — unit + integration scenarios
- 🤖 **LangGraph Agent** — no direct filesystem access, all via MCP
- 📈 **Resource Discovery** — `tools/list`, `resources/list`
- 🔐 **Security** — allowed roots, size limits, format allowlist

## 🏗️ Architecture

See [docs/state_machine.md](docs/state_machine.md) for the full state machine diagram.

```
┌────────────────┐   stdio    ┌───────────────────┐
│ LangGraph      │◄──────────►│ MCP Server        │
│ Agent          │  JSON-RPC  │ (filesystem)      │
│ + MCP Client   │   2.0      │ 6 tools           │
└────────────────┘            └────────┬──────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │  Filesystem     │
                              │  (allowed roots)│
                              └─────────────────┘
```

## 🚀 Quick Start

### 1. Install

```bash
git clone https://github.com/PatrickSekey/mcp-filesystem-server.git
cd mcp-filesystem-server
python -m venv venv
venv\Scripts\activate          # Windows
pip install -e .
```

### 2. Configure

```bash
copy .env.example .env
# Edit .env and set OPENROUTER_API_KEY
```

### 3. Run the MCP server standalone

```bash
python -m mcp_filesystem_server
```

### 4. Run the LangGraph agent

```bash
python test_agent.py
```

### 5. Run the test suite

```bash
pytest tests/ -v
```

## 🔌 Connecting VSCode / Claude Desktop / Cursor

See [docs/vscode_setup.md](docs/vscode_setup.md) for full instructions.

Quick config:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\mcp-filesystem-server\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_filesystem_server"],
      "cwd": "C:\\mcp-filesystem-server",
      "env": { "PYTHONPATH": "C:\\mcp-filesystem-server\\src" }
    }
  }
}
```

## 🛠️ Tools Reference

| Tool | Description |
|------|-------------|
| **read_file** | Read PDF/TXT/DOCX/MD/JSON with metadata |
| **list_files** | List directory with extension filter |
| **write_file** | Write with auto-create + overwrite control |
| **search_in_file** | Case-sensitive/insensitive search with context |
| **watch_directory** ⭐ | Bounded directory watcher |
| **batch_process** ⭐ | Efficient multi-file processing |

## 🧪 Test Scenarios

8 scenarios in `tests/test_scenarios.py`:

1. Handshake and tool discovery
2. Read all resumes via MCP
3. Search for a skill inside a resume
4. Batch summary of resumes
5. Write + read round-trip
6. Bounded directory watch
7. Error handling (-32001 for missing file)
8. Full agent workflow via MCP

## 📊 Error Codes

| Code | Meaning |
|------|---------|
| -32700 | PARSE_ERROR |
| -32600 | INVALID_REQUEST |
| -32601 | METHOD_NOT_FOUND |
| -32602 | INVALID_PARAMS |
| -32603 | INTERNAL_ERROR |
| -32001 | FILE_NOT_FOUND |
| -32002 | FILE_ACCESS_DENIED |
| -32003 | UNSUPPORTED_FORMAT |
| -32004 | FILE_TOO_LARGE |
| -32005 | READ_ERROR |
| -32006 | WRITE_ERROR |
| -32007 | WATCH_ERROR |
| -32008 | BATCH_ERROR |

## 📁 Project Structure

```
mcp-filesystem-server/
├── src/mcp_filesystem_server/
│   ├── server.py           # Main MCP server
│   ├── json_rpc.py         # JSON-RPC 2.0 handler
│   ├── resources.py        # Tool discovery
│   ├── errors.py           # Error codes
│   ├── metrics.py          # Performance tracking
│   ├── tools/              # 6 filesystem tools
│   ├── mcp_client/         # Client wrapper
│   └── agent/              # LangGraph agent
├── tests/                  # 30+ tests
├── examples/               # Sample resumes
├── docs/                   # Diagrams + VSCode guide
└── README.md
```

## 🎓 Assignment Deliverables

| Requirement | Status |
|-------------|--------|
| `filesystem_mcp_server.py` (converted to package) | ✅ `src/mcp_filesystem_server/` |
| JSON-RPC 2.0 compliant | ✅ `json_rpc.py` |
| Resource discovery endpoints | ✅ `resources.py` |
| `watch_directory()` | ✅ `tools/watch_directory.py` |
| `batch_process()` | ✅ `tools/batch_process.py` |
| Refactored agent using MCP | ✅ `agent/matching_agent.py` |
| State machine diagram | ✅ `docs/state_machine.md` |
| Test scenarios | ✅ `tests/test_scenarios.py` |
| Configuration management | ✅ `config.py` + `.env` |

## 📝 License

Educational — MCP Integration assignment.

## 🙏 Acknowledgments

- [Anthropic MCP](https://modelcontextprotocol.io/) for the protocol
- [LangGraph](https://github.com/langchain-ai/langgraph) for the agent framework