Provides comprehensive file system exploration capabilities including directory listing, file reading, metadata retrieval, and file searching with wildcard pattern support
Mentioned as an advanced exercise for implementing git integration with status, log, and diff functionality
File System Explorer MCP Server
A beginner-friendly MCP (Model Context Protocol) server that demonstrates core MCP concepts through practical file system exploration tools. This project is perfect for learning MCP development while building something immediately useful.
๐ฏ What You'll Learn
This project teaches you essential MCP concepts:
Tools: Interactive functions that AI can call (like listing directories or reading files)
Resources: Static data sources that provide context (like current directory info)
Prompts: Reusable templates that help users accomplish specific tasks
Server Architecture: How to structure and implement a proper MCP server
Error Handling: Best practices for robust MCP server development
๐ Features
๐ ๏ธ Tools
list_directory
- List contents of any directory with file sizes and modification datesread_file
- Read text files with safety limits and error handlingget_file_info
- Get detailed metadata about files and directoriessearch_files
- Search for files using wildcard patterns (supports*
and?
)
๐ Resources
Current Directory - Provides information about the working directory
๐จ Prompts
explore_project
- Guided project exploration and analysisfile_analysis
- Analyze files in a directory for patterns and structure
๐๏ธ Project Structure
๐ Prerequisites
Before you begin, ensure you have:
Node.js 18+ installed (download here)
TypeScript knowledge (basic understanding)
VS Code (recommended for debugging)
๐ ๏ธ Installation & Setup
1. Clone and Install
2. Test Your Server
You can test your server using the MCP Inspector:
This opens a web interface where you can:
Test all available tools
View resources
Try out prompts
Debug server responses
๐ฎ How to Use
Basic Usage Examples
Once connected to an MCP client (like Claude Desktop), you can:
Explore a Directory
Read a File
Search for Files
Get File Information
Using Prompts
The server includes helpful prompts:
Project Exploration
File Analysis
๐ง Connecting to VS Code
Make sure you have the MCP extension installed in VS Code
The server is already configured in
.vscode/mcp.json
Restart VS Code to load the configuration
You should see the MCP server available in the sidebar
๐งช Development Workflow
Making Changes
Edit the source code in
src/index.ts
Rebuild the project:
npm run buildTest your changes using the MCP Inspector or restart your MCP client
Development Mode
For faster development, use watch mode:
This automatically recompiles when you make changes.
๐ Understanding the Code
Server Initialization
Adding a Tool
Security Features
The server includes several security measures:
Path validation to prevent directory traversal
File size limits to prevent reading huge files
Recursion limits in directory search
Error handling for permission issues
๐ Learning Exercises
Beginner Exercises
Add a new tool that counts lines in a text file
Modify the file size limit for reading files
Add a new resource that shows system information
Intermediate Exercises
Add file writing capabilities (create_file, write_file tools)
Implement a simple backup tool that copies files
Add support for binary files with proper handling
Advanced Exercises
Add file watching capabilities using Node.js file system events
Implement a simple git integration (status, log, diff)
Add compression/decompression tools for zip files
๐ Troubleshooting
Common Issues
Server not starting:
Check that Node.js is installed:
node --version
Ensure dependencies are installed:
npm install
Verify build completed:
ls build/
(should contain index.js)
Permission errors:
Make sure the server has read access to directories
On Windows, avoid system directories that require admin access
Build errors:
Clear and reinstall dependencies:
rm -rf node_modules && npm install
Check TypeScript configuration in
tsconfig.json
๐ Next Steps
Once you've mastered this server:
Explore other MCP servers in the official repository
Build your own specialized server for your domain (database, API, etc.)
Contribute to the MCP community with your own implementations
Learn about remote MCP servers for cloud-based tools
๐ Additional Resources
๐ค Contributing
Want to improve this learning resource?
Fork the repository
Make your improvements
Add tests if applicable
Submit a pull request
Ideas for contributions:
Additional example tools
Better error messages
More comprehensive prompts
Performance improvements
Additional security features
๐ License
MIT License - feel free to use this code for learning and building your own MCP servers!
๐ Congratulations!
You've successfully set up your first MCP server! This foundation will help you understand the Model Context Protocol and build more sophisticated integrations. The concepts you've learned here - tools, resources, prompts, and proper error handling - apply to all MCP server development.
Happy coding! ๐
local-only server
The server can only run on the client's local machine because it depends on local resources.
A beginner-friendly MCP server that enables AI to explore file systems through tools for listing directories, reading files, searching with wildcards, and getting file metadata. Perfect for learning MCP development while providing practical file system interaction capabilities.
- ๐ฏ What You'll Learn
- ๐ Features
- ๐๏ธ Project Structure
- ๐ Prerequisites
- ๐ ๏ธ Installation & Setup
- ๐ฎ How to Use
- ๐ง Connecting to VS Code
- ๐งช Development Workflow
- ๐ Understanding the Code
- ๐ Learning Exercises
- ๐ Troubleshooting
- ๐ Next Steps
- ๐ Additional Resources
- ๐ค Contributing
- ๐ License
- ๐ Congratulations!