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
MCPServer/
├── src/
│ └── index.ts # Main server implementation
├── build/ # Compiled JavaScript output
├── .vscode/
│ └── mcp.json # MCP server configuration
├── .github/
│ └── copilot-instructions.md
├── package.json # Node.js project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
📋 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
# Navigate to the project directory
cd MCPServer
# Install dependencies
npm install
# Build the project
npm run build
2. Test Your Server
You can test your server using the MCP Inspector:
# Install and run MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js
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
Can you list the contents of my Desktop folder?
Read a File
Please read the README.md file in my project directory
Search for Files
Find all JavaScript files in my project using the pattern "*.js"
Get File Information
What can you tell me about the package.json file?
Using Prompts
The server includes helpful prompts:
Project Exploration
Use the explore_project prompt with my code directory
File Analysis
Analyze my src directory focusing on TypeScript files
🔧 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 build - Test your changes using the MCP Inspector or restart your MCP client
Development Mode
For faster development, use watch mode:
npm run dev
This automatically recompiles when you make changes.
📚 Understanding the Code
Server Initialization
const server = new Server(
{ name: "filesystem-explorer", version: "1.0.0" },
{ capabilities: { tools: {}, resources: {}, prompts: {} } }
);
Adding a Tool
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case "your_tool_name": {
// Your tool logic here
return {
content: [{ type: "text", text: "Tool response" }]
};
}
}
});
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! 🚀