Filesystem MCP Server SSE

🚀 File System MCP Server SSE

A Node.js-based Server-Sent Events (SSE) server for file system operations, implementing the Model Context Protocol (MCP).

✨ Features

• Read/write files
• Create/list/delete directories
• Move files/directories
• Search for files
• Get file metadata

⚠️ Important Note

The server only allows operations within the directory specified by the args parameter.

📚 Documentation

Resource Paths

• file://system: File system operation interface

Utility Methods

read_file

• Read the full content of a file.
• Input parameter: path (string).
• Read the entire file content using UTF-8 encoding.

read_multiple_files

• Read multiple files simultaneously.
• Input parameter: paths (array of strings).
• A failed read does not terminate the entire operation.

write_file

• Create a new file or overwrite an existing one (use with caution).
• Input parameters:
  • path (string): File path.
  • content (string): File content.

edit_file

• Perform selective editing using advanced pattern matching and formatting.
• Features:
  • Line-level and multi-line content matching.
  • Automatically detect and preserve indentation styles.
  • Support multiple edit operations and correct positioning.
  • Automatically generate Git-style diff output with context.
  • Preview changes in dry-run mode (default: false).
• Input parameters:
  • path (string): Path of the file to edit.
  • edits (array): List of edit operations.
    • oldText (string): Text to search and match (can be a substring).
    • newText (string): Text to replace.
  • dryRun (boolean): Preview changes without applying them (default: false).
• Return detailed diff and matching information in dry-run mode; otherwise, apply the changes.
• Best practice: Always use dry-run mode to preview changes before execution.

create_directory

• Create a new directory or ensure it exists.
• Input parameter: path (string).
• Automatically create parent directories if necessary.
• Silently succeed if the directory already exists.

list_directory

• List directory contents, prefixing files with [FILE] and directories with [DIR].
• Input parameter: path (string).

move_file

• Move or rename files and directories.
• Input parameters:
  • source (string): Source path.
  • destination (string): Destination path.
• The operation fails if the destination already exists.

search_files

• Recursively search for files/directories.
• Input parameters:
  • path (string): Starting directory.
  • pattern (string): Search pattern.
  • excludePatterns (array of strings): List of exclusion patterns, supporting glob format.
• Case-insensitive matching.
• Return full paths of matching files.

get_file_info

• Get detailed metadata of a file/directory.
• Input parameter: path (string).
• Returned results include:
  • name (string): Name.
  • type (string): "file" or "directory".
  • size (number): Size in bytes.
  • mtime (timestamp): Last modified time.
  • ctime (timestamp): Creation time.

get_file_list

• Get all files and subdirectories in a specified directory.
• Input parameters:
  • path (string): Directory path to list.
  • recursive (boolean, default: false): Whether to recursively traverse subdirectories.
• Return an array containing information about files and directories.

💻 Usage Examples

Local Run Example

1. Install dependencies:

npm install

2. Start the service:

node index.js

3. Test the API using curl:

curl -X POST http://localhost:3000/file-system/read-file \
  -H "Content-Type: application/json" \
  -d '{"path": "/test.txt"}'

Docker Run Example

1. Build the Docker image:

docker build -t file-system-mcp .

2. Start the container:

docker run -p 3000:3000 --name file-system-service file-system-mcp

⚠️ Important Note

All file operations should handle potential exceptions, such as insufficient permissions or non-existent files.

💡 Usage Tip

By default, the server performs basic authentication and authorization checks on all requests. It also supports setting limits on the maximum upload file size and the number of concurrent connections.

📄 License

This project is licensed under the MIT License. For more information, please refer to the LICENSE file in the project repository.