AbhishekCbanaj/MCP-Filesystem-Server

MCP Filesystem Server

A Model Context Protocol (MCP) server implementation for filesystem operations with a web-based frontend interface.

Features

• MCP Server: Complete filesystem operations (create, read, edit, delete files and directories)
• MCP Client: JavaScript client to communicate with the server
• Web Frontend: Interactive interface for file management with drag-and-drop support
• Command Processing: Natural language commands for file operations

Project Structure

mcp-filesystem-server/
├── src/
│   ├── server.js          # MCP server implementation
│   ├── client.js          # MCP client implementation
│   └── frontend.html      # Web interface
├── package.json           # Dependencies and scripts
├── README.md             # This file
└── workspace/            # Default working directory (created automatically)

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Installation

1. Clone or create the project directory:

   mkdir mcp-filesystem-server
   cd mcp-filesystem-server
   

2. Initialize the project:

   npm init -y
   

3. Install dependencies:

   npm install @modelcontextprotocol/sdk
   npm install --save-dev nodemon
   

4. Create the project structure:

   mkdir src
   mkdir workspace
   

5. Copy the provided files:

   • Copy server.js to src/server.js
   • Copy client.js to src/client.js
   • Copy frontend.html to src/frontend.html
   • Update package.json with the provided configuration

Usage

Running the MCP Server

# Start the server
npm start

# Or for development with auto-reload
npm run dev

Using the Web Interface

1. Open src/frontend.html in a web browser
2. The interface will automatically simulate connection to the MCP server
3. Upload a folder using drag-and-drop or the file picker
4. Use the command prompt to perform operations

Available Commands

• create file filename.txt with content Hello World!
• read file filename.txt
• edit file filename.txt with content Updated content
• delete file filename.txt
• list files

MCP Client Usage (Programmatic)

import { FilesystemMCPClient } from './src/client.js';

const client = new FilesystemMCPClient();
await client.connect();

// Create a file
await client.createFile('./workspace/test.txt', 'Hello World!');

// Read a file
const result = await client.readFile('./workspace/test.txt');
console.log(result);

// Process natural language commands
const response = await client.processPrompt('create file hello.txt with content Hello MCP!');

MCP Server Tools

The server implements the following MCP tools:

1. create_file: Create a new file with specified content
2. read_file: Read the contents of an existing file
3. edit_file: Edit an existing file by replacing its content
4. delete_file: Delete a file
5. list_files: List all files in a directory
6. create_directory: Create a new directory

API Reference

Server Endpoints

All tools follow the MCP protocol specification:

{
  "method": "tools/call",
  "params": {
    "name": "create_file",
    "arguments": {
      "filepath": "path/to/file.txt",
      "content": "File content here"
    }
  }
}

Error Handling

The server includes comprehensive error handling for:

• File not found errors
• Permission errors
• Invalid file paths
• Network connectivity issues

Development

Adding New Tools

To add a new tool to the MCP server:

1. Add the tool definition in ListToolsRequestSchema handler
2. Implement the tool logic in CallToolRequestSchema handler
3. Add corresponding client method in FilesystemMCPClient

Extending the Frontend

The frontend is built with vanilla HTML/CSS/JavaScript and can be extended with:

• Additional command types
• File preview capabilities
• Syntax highlighting
• Real-time collaboration features

Security Considerations

• The server operates within the specified working directory only
• File paths are validated to prevent directory traversal attacks
• No network file access is permitted
• All operations are logged for audit purposes

Troubleshooting

Common Issues

1. Connection Failed: Ensure the MCP server is running before starting the client
2. File Permission Errors: Check that the workspace directory has proper read/write permissions
3. Port Conflicts: The server uses stdio transport, so no port conflicts should occur

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=mcp:* npm start

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Assignment Submission Notes

This project demonstrates:

1. Complete MCP Server Implementation: All required filesystem operations
2. MCP Client Integration: Proper SDK usage and connection handling
3. Frontend Interface: Interactive web application with file upload and command processing
4. Error Handling: Comprehensive error management throughout the stack
5. Documentation: Complete setup and usage instructions

Demo Commands for Testing

create file demo.txt with content This is a demo file
read file demo.txt
edit file demo.txt with content This file has been updated
list files
delete file demo.txt

The implementation showcases understanding of the MCP protocol, client-server architecture, and modern web development practices.