mirror of
https://github.com/modelcontextprotocol/servers.git
synced 2026-04-18 00:03:23 +02:00
Merge branch 'main' into fix_search_files
Resolved merge conflicts while preserving glob pattern functionality for search_files. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Adam Jones
@@ -9,8 +9,58 @@ Node.js server implementing Model Context Protocol (MCP) for filesystem operatio
|
||||
- Move files/directories
|
||||
- Search files
|
||||
- Get file metadata
|
||||
- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)
|
||||
|
||||
## Directory Access Control
|
||||
|
||||
The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).
|
||||
|
||||
### Method 1: Command-line Arguments
|
||||
Specify Allowed directories when starting the server:
|
||||
```bash
|
||||
mcp-server-filesystem /path/to/dir1 /path/to/dir2
|
||||
```
|
||||
|
||||
### Method 2: MCP Roots (Recommended)
|
||||
MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories.
|
||||
|
||||
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
|
||||
|
||||
**Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
|
||||
|
||||
This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.
|
||||
|
||||
### How It Works
|
||||
|
||||
The server's directory access control follows this flow:
|
||||
|
||||
1. **Server Startup**
|
||||
- Server starts with directories from command-line arguments (if provided)
|
||||
- If no arguments provided, server starts with empty allowed directories
|
||||
|
||||
2. **Client Connection & Initialization**
|
||||
- Client connects and sends `initialize` request with capabilities
|
||||
- Server checks if client supports roots protocol (`capabilities.roots`)
|
||||
|
||||
3. **Roots Protocol Handling** (if client supports roots)
|
||||
- **On initialization**: Server requests roots from client via `roots/list`
|
||||
- Client responds with its configured roots
|
||||
- Server replaces ALL allowed directories with client's roots
|
||||
- **On runtime updates**: Client can send `notifications/roots/list_changed`
|
||||
- Server requests updated roots and replaces allowed directories again
|
||||
|
||||
4. **Fallback Behavior** (if client doesn't support roots)
|
||||
- Server continues using command-line directories only
|
||||
- No dynamic updates possible
|
||||
|
||||
5. **Access Control**
|
||||
- All filesystem operations are restricted to allowed directories
|
||||
- Use `list_allowed_directories` tool to see current directories
|
||||
- Server requires at least ONE allowed directory to operate
|
||||
|
||||
**Note**: The server will only allow operations within directories specified either via `args` or via Roots.
|
||||
|
||||
|
||||
**Note**: The server will only allow operations within directories specified via `args`.
|
||||
|
||||
## API
|
||||
|
||||
@@ -20,10 +70,19 @@ Node.js server implementing Model Context Protocol (MCP) for filesystem operatio
|
||||
|
||||
### Tools
|
||||
|
||||
- **read_file**
|
||||
- Read complete contents of a file
|
||||
- Input: `path` (string)
|
||||
- Reads complete file contents with UTF-8 encoding
|
||||
- **read_text_file**
|
||||
- Read complete contents of a file as text
|
||||
- Inputs:
|
||||
- `path` (string)
|
||||
- `head` (number, optional): First N lines
|
||||
- `tail` (number, optional): Last N lines
|
||||
- Always treats the file as UTF-8 text regardless of extension
|
||||
|
||||
- **read_media_file**
|
||||
- Read an image or audio file
|
||||
- Inputs:
|
||||
- `path` (string)
|
||||
- Streams the file and returns base64 data with the corresponding MIME type
|
||||
|
||||
- **read_multiple_files**
|
||||
- Read multiple files simultaneously
|
||||
@@ -41,22 +100,16 @@ Node.js server implementing Model Context Protocol (MCP) for filesystem operatio
|
||||
- Features:
|
||||
- Line-based and multi-line content matching
|
||||
- Whitespace normalization with indentation preservation
|
||||
- Fuzzy matching with confidence scoring
|
||||
- Multiple simultaneous edits with correct positioning
|
||||
- Indentation style detection and preservation
|
||||
- Git-style diff output with context
|
||||
- Preview changes with dry run mode
|
||||
- Failed match debugging with confidence scores
|
||||
- Inputs:
|
||||
- `path` (string): File to edit
|
||||
- `edits` (array): List of edit operations
|
||||
- `oldText` (string): Text to search for (can be substring)
|
||||
- `newText` (string): Text to replace with
|
||||
- `dryRun` (boolean): Preview changes without applying (default: false)
|
||||
- `options` (object): Optional formatting settings
|
||||
- `preserveIndentation` (boolean): Keep existing indentation (default: true)
|
||||
- `normalizeWhitespace` (boolean): Normalize spaces while preserving structure (default: true)
|
||||
- `partialMatch` (boolean): Enable fuzzy matching (default: true)
|
||||
- Returns detailed diff and match information for dry runs, otherwise applies changes
|
||||
- Best Practice: Always use dryRun first to preview changes before applying them
|
||||
|
||||
@@ -149,6 +202,64 @@ Note: all directories must be mounted to `/projects` by default.
|
||||
}
|
||||
```
|
||||
|
||||
## Usage with VS Code
|
||||
|
||||
For quick installation, click the installation buttons below...
|
||||
|
||||
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders)
|
||||
|
||||
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders)
|
||||
|
||||
For manual installation, you can configure the MCP server using one of these methods:
|
||||
|
||||
**Method 1: User Configuration (Recommended)**
|
||||
Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
|
||||
|
||||
**Method 2: Workspace Configuration**
|
||||
Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
|
||||
|
||||
> For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/mcp).
|
||||
|
||||
You can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.
|
||||
|
||||
### Docker
|
||||
Note: all directories must be mounted to `/projects` by default.
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"filesystem": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
|
||||
"mcp/filesystem",
|
||||
"/projects"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### NPX
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"${workspaceFolder}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Build
|
||||
|
||||
Docker build:
|
||||
|
||||
Reference in New Issue
Block a user