madankumar2473/File_Manipulationby_MCPServer

MCP Filesystem Web App

A full-stack web application that provides a modern interface for managing files using the Model Context Protocol (MCP). This application allows users to perform file operations through a React frontend, natural language commands, and a secure MCP backend.

🚀 Features

• Modern Web Interface: React-based frontend with drag-and-drop file upload
• Natural Language Commands: Execute file operations using plain English
• Secure File Operations: Create, read, edit, delete, and list files
• Real-time Logging: Live operation logs and status monitoring
• File Explorer: Interactive file tree with visual file management
• RESTful API: HTTP bridge for frontend-backend communication
• TypeScript: Full type safety across the entire stack

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• npm (v8 or higher)
• Git (for cloning the repository)

🏗️ Project Structure

mcp-filesystem/
├── client/                 # MCP Client SDK
│   ├── src/
│   │   ├── client.ts      # Type-safe MCP client
│   │   └── utils/
│   │       └── PromptParser.ts
│   └── package.json
├── frontend/              # React Frontend
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── utils/         # Utility functions
│   │   ├── clientHttp.ts  # HTTP client for API calls
│   │   └── main.tsx       # Main React app
│   ├── index.html
│   └── package.json
├── server/                # MCP Backend Server
│   ├── src/
│   │   ├── server.ts      # MCP server implementation
│   │   ├── httpBridge.ts  # HTTP bridge for frontend
│   │   └── main.tsx       # Server entry point
│   └── package.json
└── workspace/            # File storage directory

🛠️ Installation & Setup

Step 1: Clone the Repository

git clone <repository-url>
cd mcp-filesystem

Step 2: Install Dependencies

Install dependencies for all three components:

# Install client dependencies
cd client
npm install

# Install frontend dependencies
cd ../frontend
npm install

# Install server dependencies
cd ../server
npm install

Step 3: Create Workspace Directory

# From the project root
mkdir workspace

🚀 Running the Application

Step 1: Start the Backend Server

cd server
npm run http

This starts the HTTP bridge server on http://localhost:3001 with the following endpoints:

• GET /health - Health check
• POST /api/files - Create file
• PUT /api/files - Edit file
• DELETE /api/files - Delete file
• GET /api/files - Read file
• GET /api/files/list - List files

Step 2: Start the Frontend

cd frontend
npm run dev

This starts the React development server on http://localhost:5173.

Step 3: Access the Application

Open your browser and navigate to http://localhost:5173 to access the MCP Filesystem Web App.

📖 Usage Guide

File Upload

1. Drag and Drop: Drag files or folders directly onto the upload area
2. Click to Select: Click the upload area to open a file picker
3. Multiple Files: Select multiple files at once
4. Real-time Feedback: See upload progress and status

Natural Language Commands

Use the command input box to perform file operations using natural language:

Create Files

create test.txt
create config.json with content '{"key": "value"}'
make a new file called readme.md
new file called data.csv

Edit Files

edit test.txt
edit config.json with content '{"updated": "content"}'
modify readme.md
update data.csv

Delete Files

delete old.txt
remove temp.json
erase backup.log

Read Files

read config.json
show test.txt
display readme.md

List Files

list files
show all files
what files are in the directory

File Explorer

• Navigate: Click on folders to navigate into them
• Go Back: Use the ".." button to go back to parent directory
• File Actions: Use action buttons on files:
  • 👁️ Read file content
  • ✏️ Edit file content
  • 🗑️ Delete file
  • 📂 Open directory (for folders)
• Refresh: Click the refresh button to update the file list

Status Monitoring

The right panel shows:

• Connection Status: Real-time connection to MCP server
• Operation Logs: Detailed logs of all file operations
• Error Messages: Clear error reporting
• Success Confirmations: Operation success notifications

🔧 Development

Project Architecture

Frontend (React + TypeScript)

• Components: Modular React components for each UI section
• State Management: React hooks for local state
• HTTP Client: Custom client for API communication
• Styling: CSS modules with responsive design

Backend (Node.js + TypeScript)

• MCP Server: Implements Model Context Protocol
• HTTP Bridge: Express server for frontend communication
• File Operations: Secure file system operations
• Validation: Path and file extension validation

Client SDK (TypeScript)

• Type-safe API: Full TypeScript support
• Error Handling: Comprehensive error management
• Retry Logic: Automatic retry for failed operations

Key Components

FileUploader Component

• Handles drag-and-drop file uploads
• Supports multiple file selection
• Provides visual feedback during upload

PromptBox Component

• Natural language command input
• Real-time command parsing
• Command execution feedback

FileTree Component

• Interactive file explorer
• File operation buttons
• Directory navigation

StatusBar Component

• Connection status monitoring
• Operation log display
• Error reporting

API Endpoints

File Operations

// Create file
POST /api/files
{
  "path": "filename.txt",
  "content": "file content",
  "description": "optional description"
}

// Edit file
PUT /api/files
{
  "path": "filename.txt",
  "content": "new content",
  "description": "optional description"
}

// Delete file
DELETE /api/files
{
  "path": "filename.txt",
  "description": "optional description"
}

// Read file
GET /api/files?path=filename.txt

// List files
GET /api/files/list?path=.

🔒 Security Features

Path Validation

• Prevents path traversal attacks (../)
• Restricts operations to workspace directory
• Validates file extensions

File Extension Whitelist

Allowed file extensions:

• Text files: .txt, .md, .json, .log
• Code files: .js, .ts, .jsx, .tsx, .html, .css
• Data files: .csv, .xml, .yaml, .yml
• Scripts: .sh, .bat, .ps1
• Configuration: .ini, .cfg, .conf

Error Handling

• Comprehensive error catching
• User-friendly error messages
• Detailed logging for debugging

🧪 Testing

Manual Testing

1. File Upload: Test drag-and-drop and file picker
2. Natural Language: Test various command patterns
3. File Operations: Test create, read, edit, delete
4. Navigation: Test directory navigation
5. Error Handling: Test invalid commands and operations

API Testing

# Test health endpoint
curl http://localhost:3001/health

# Test file creation
curl -X POST http://localhost:3001/api/files \
  -H "Content-Type: application/json" \
  -d '{"path":"test.txt","content":"Hello World"}'

# Test file listing
curl http://localhost:3001/api/files/list

🐛 Troubleshooting

Common Issues

Frontend Not Loading

• Check if frontend server is running on port 5173
• Verify all dependencies are installed
• Check browser console for errors

Backend Connection Failed

• Ensure backend server is running on port 3001
• Check if workspace directory exists
• Verify server logs for errors

File Operations Not Working

• Check file permissions in workspace directory
• Verify file extension is allowed
• Check server logs for validation errors

Natural Language Commands Not Working

• Check browser console for parsing errors
• Verify command syntax matches supported patterns
• Check network tab for API call failures

Debug Mode

Enable debug logging by checking the browser console for detailed information about:

• Command parsing
• API calls
• File operations
• Error details

📝 Configuration

Environment Variables

Create a .env file in the server directory:

# Server Configuration
PORT=3001
WORKSPACE_PATH=../workspace

# Security
ALLOWED_EXTENSIONS=txt,md,json,js,ts,html,css
MAX_FILE_SIZE=10485760

Customization

Adding File Extensions

Edit server/src/server.ts:

private allowedExtensions: Set<string> = new Set([
  'txt', 'md', 'json', 'js', 'ts', 'jsx', 'tsx',
  // Add your extensions here
]);

Changing Ports

Edit the respective package.json files or use environment variables.

🤝 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

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol (MCP) for the underlying protocol
• React team for the frontend framework
• Node.js community for the backend runtime
• TypeScript team for type safety

📞 Support

For issues and questions:

1. Check the troubleshooting section
2. Review the logs and console output
3. Create an issue in the repository
4. Contact the development team

Happy File Management! 🎉