Filesystem MCP Server

🚀 File System Protocol Server

This is a file system protocol server based on the Model Context Protocol (MCP). It enables AI models to interact with the file system through the context protocol. The current implementation supports the following features:

✨ Features

• File Operations: Read, write, update, and delete files and directories.
• Directory Management: Create, list, move, and copy directories.
• State Management: Maintain session - level states (e.g., default paths).
• Logging and Error Handling: Integrate logging and error - handling mechanisms.
• Rate Limiting: Protective measures to prevent abuse.

File System Structure Diagram

+-filesystem-mcp-server/
| +-dist/                 # Compiled JavaScript output (generated after running npm run build)
| +-logs/                # Log files (created at runtime)
| +-node_modules/        # Project dependencies
| +-src/                 # TypeScript source code
|   +-config/             # Configuration loading (index.ts)
|   +-mcp-server/         # Core MCP server logic
|   | +-server.ts          # Server initialization and tool registration
|   | +-state.ts           # Session state management (e.g., default paths)
|   | +-tools/             # Implementations of individual tools (one sub - folder per tool)
|   | | +-readFile/
|   | | | +-index.ts
|   | | | +-readFileLogic.ts
|   | | | +-registration.ts
|   | | \-...              # Other tools (writeFile, updateFile, etc.)
|   +-types-global/       # Shared TypeScript types and interfaces
|   | +-errors.ts          # Custom error classes and codes
|   | +-mcp.ts             # MCP - related types
|   | \-tool.ts            # Tool definition types
|   +-utils/              # Reusable utility modules
|   | +-errorHandler.ts
|   | +-idGenerator.ts
|   | +-index.ts
|   | +-logger.ts
|   | +-rateLimiter.ts
|   | +-requestContext.ts
|   | \-sanitization.ts
|   \-index.ts            # Application entry point
| +-clinerules           # Cheatsheet for LLM code assistants
| +-gitignore
| +-LICENSE
| +-package.json
| +-package-lock.json
| +-README.md             # This file
| \-tsconfig.json         # TypeScript compiler options

📦 Installation

• Use npm for dependency management: npm install
• Compile the source code: tsc --build
• Run the server: node dist/server.js

💻 Usage Examples

Basic Usage

//.ReadFile.ts
export async function read_file(request: ReadFileRequest): Promise<ReadFileResponse> {
    const { path } = request;
    try {
        const content = await fs.promises.readFile(path, 'utf8');
        return { success: true, content };
    } catch (error) {
        return { success: false, error: error.message };
    }
}

📚 Documentation

Core Components

• Server.ts: The main server program, responsible for handling connections and message routing.
• State.ts: Maintains session - level states, including information such as default paths.
• Tools/: Specific implementations of various file operation tools.

Tool List

Basic File Operation Tools

| Tool Name | Input | Description |
|-------------------|--------------------|-----------------------------------------------|
| read_file | {path: string} | Read the content of a file from the specified path |
| write_file | {path: string, content: string} | Write content to a file at the specified path. Create the file if it doesn't exist |
| update_file | {path: string, content: string} | Update the content of a file at the specified path, keeping the original content |
| delete_file | {path: string} | Delete the file at the specified path |

Directory Management Tools

| Tool Name | Input | Description |
|-------------------|--------------------|-----------------------------------------------|
| create_dir | {path: string} | Create a directory at the specified path. Recursively create parent directories if they don't exist |
| list_dirs |  | List all sub - directories in the current working directory |
| move_dir | {from: string, to: string} | Move the specified source directory to the target path |
| copy_dir | {from: string, to: string} | Copy the specified source directory to the target path, preserving the file structure |

🔧 Technical Details

The project is implemented in TypeScript, providing strong type support.

📄 License

The project is licensed under the MIT License. For specific terms, refer to the LICENSE file.

🧑‍💻 Development Team

• Author: [Your Name]
• Contributors: [Your Name]
• Maintainers: [Your Name]

For more information about the Model Context Protocol, please visit Official Documentation.