Skip to main content
Glama
MCP Filesystem Server

MCP Filesystem Server

by PatrickSekey

🤖 MCP Filesystem Server + LangGraph Agent

Python MCP LangGraph Tests

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

Related MCP server: File System MCP Server

🏗️ Architecture

See 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

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

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

3. Run the MCP server standalone

python -m mcp_filesystem_server

4. Run the LangGraph agent

python test_agent.py

5. Run the test suite

pytest tests/ -v

🔌 Connecting VSCode / Claude Desktop / Cursor

See docs/vscode_setup.md for full instructions.

Quick config:

{
  "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

Available Tools

6 tools
batch_processC

Process multiple files in a single call (read/stat/summary)

Inputs: directory (required), max_files, operation, recursive, +1 more.

list_filesC

List files in a directory with optional extension filtering

Inputs: directory, recursive, extensions, max_results.

read_fileC

Read PDF, TXT, DOCX, MD, JSON files with rich metadata

Inputs: file_path (required).

search_in_fileA

Search for a query inside a file, returning matches with context

Inputs: query (required), file_path (required), max_results, context_lines, +1 more.

watch_directoryC

Watch a directory for changes over a fixed duration (MCP-bound watcher)

Inputs: directory (required), extensions, poll_interval, duration_seconds.

write_fileC

Write content to a file with automatic directory creation

Inputs: content (required), file_path (required), overwrite, create_dirs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools target distinct actions (read, list, write, search, watch), but batch_process overlaps with read_file and list_files by performing multi-file reads and summaries, creating minor ambiguity about when to use it versus the single-file tools.

    Naming Consistency4/5

    All names use snake_case and mostly follow a verb_noun pattern (read_file, list_files, write_file, search_in_file, watch_directory). batch_process deviates slightly from verb_noun order, but the convention remains readable.

    Tool Count5/5

    Six tools is well-scoped for a filesystem server, with each tool covering a distinct operation (read, list, write, search, watch, batch) and no redundant endpoints.

    Completeness3/5

    Core read/write/search/list/watch workflows are present, but the filesystem surface lacks common operations like delete, move/rename, and copy. These are notable gaps for a general filesystem server.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight, stdio-based MCP server enabling AI assistants to perform local file system operations like reading, writing, searching, and executing commands.
      5,198 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents and MCP clients to read, list, write, search, watch, and batch-process files within configured allowed directories, while exposing discoverable file resources and structured error codes.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides secure filesystem operations, including reading, searching, and batch processing files, with directory monitoring to detect new files, designed for integration with MCP clients such as LangGraph agents.
      -