MCP Filesystem Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Filesystem Server read all resumes in examples/ and summarize the skills"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🤖 MCP Filesystem Server + LangGraph Agent
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_KEY3. Run the MCP server standalone
python -m mcp_filesystem_server4. Run the LangGraph agent
python test_agent.py5. 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:
Handshake and tool discovery
Read all resumes via MCP
Search for a skill inside a resume
Batch summary of resumes
Write + read round-trip
Bounded directory watch
Error handling (-32001 for missing file)
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 |
| ✅ |
JSON-RPC 2.0 compliant | ✅ |
Resource discovery endpoints | ✅ |
| ✅ |
| ✅ |
Refactored agent using MCP | ✅ |
State machine diagram | ✅ |
Test scenarios | ✅ |
Configuration management | ✅ |
📝 License
Educational — MCP Integration assignment.
🙏 Acknowledgments
Anthropic MCP for the protocol
LangGraph for the agent framework
Available Tools
6 toolsbatch_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA lightweight, stdio-based MCP server enabling AI assistants to perform local file system operations like reading, writing, searching, and executing commands.5,198 npmMIT
- FlicenseAqualityDmaintenanceAn MCP server that exposes filesystem operations — listing directories, reading, writing, and searching files — as tools an LLM can discover and invoke at runtime.4-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- FlicenseNot gradedqualityCmaintenanceProvides 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.-