Bsmi021 MCP File Operations Server

🚀 MCP Server for File Operations

A Model Context Protocol (MCP) server that provides enhanced file operation functions, supporting streaming, patch processing, and change tracking.

🚀 Quick Start

This MCP server offers a wide range of enhanced file operation capabilities. It supports basic file operations, directory management, change tracking, and efficient streaming for large - scale files.

✨ Features

• Basic File Operations: Copy, read, write, move, and delete files.
• Directory Operations: Create, remove, and copy directories.
• File Monitoring: Monitor changes to files and directories.
• Change Tracking: Track and query the history of file operations.
• Streaming Support: Efficiently handle large files.
• Resource Access: Access files and directories through MCP resources.
• Progress Reporting: Provide real - time progress updates for long - running operations.
• Rate Limiting: Protect against excessive requests.
• Enhanced Security: Perform path validation and input sanitization.
• Robust Error Handling: Comprehensive error handling and reporting.
• Type Safety: Full TypeScript support with strict type checking.

📦 Installation

Installation via Smithery

1. Visit https://smithery.ai/.
2. Log in and navigate to the "Workspace".
3. Click "Create a new workspace from a code repository".
4. Enter the repository address in the URL bar: git+ssh://github.com/bsmi021/mcp-file-operations-server.git.
5. After completing the workspace setup, click "Create".

Manual Installation

1. Clone this repository:

git clone git@github.com:bsmi021/mcp-file-operations-server.git
cd mcp-file-operations-server

2. Install dependencies:

npm install

3. Start the server:

node src/index.js

💻 Usage Examples

Basic Usage

• File Operations: Support copying, moving, reading, and writing files.
• Directory Management: Create, delete, and traverse directory structures.
• Change Tracking: Record and retrieve file change history.
• Streaming: Provide efficient chunked transfer when handling large files.

Advanced Usage

1. Create a new file:

POST /operations/create-file
Content-Type: application/json

{
  "path": "example.txt",
  "content": "Hello, World!"
}

2. Copy a file:

POST /operations/copy-file
Content-Type: application/json

{
  "sourcePath": "example.txt",
  "destinationPath": "copy_example.txt"
}

3. Read file content:

GET /operations/read-file?path=example.txt

📚 Documentation

Project Structure

1. Core Modules

   • file - system: Handle basic operations on files and directories.
   • operations: Contain various file operation tools.
   • resources: Define accessible resource interfaces.

2. Logging System

// Configure the logger
const logger = require('mcp-logger');

// Log information at different levels
logger.debug("Debug information");
logger.info("General information");
logger.warn("Warning information");
logger.error("Error information");

Dependency Management

The project uses npm for dependency management. The main dependencies include:

• express: A Web server framework.
• mcp - core: The core library of the MCP protocol.
• fs - extra: Enhanced file system operations.

🔧 Technical Details

Standard Error Codes

1. InvalidRequest: The request format or parameters are invalid.
2. MethodNotFound: The requested tool or resource does not exist.
3. InvalidParams: Parameter validation fails (e.g., an invalid path).
4. InternalError: An internal server error occurs.

Custom Error Types

• File operation failure.
• Rate limit exceeded.
• Path validation error.
• Resource access error.

Each error contains detailed context information, including the error code, specific message, and relevant metadata.

Configuration Options

Define server behavior through config.json:

{
  "rateLimits": {
    "requestsPerMinute": 100,
    "windowMs": 60000
  },
  "progressReporting": {
    "updateInterval": 1000,
    "detailLevel": "high"
  }
}

🤝 Contribution Guidelines

1. Participate in the project: Check Issues to find suitable tasks.
2. Submit code:
   • Create a feature branch: git checkout -b feature/amazing - feature.
   • Commit changes: git commit -m 'Add amazing feature'.
   • Push to the remote repository: git push origin feature/amazing - feature.
3. Create a pull request: Go to Pull Requests to submit your contribution.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for specific details.