File System MCP Server

A Model Context Protocol (MCP) server that provides secure file system operations with directory restrictions and optional command prefixes.

Features

• Secure Directory Access: All operations are restricted to a specified working directory
• Command Prefixes: Support for optional prefixes to run multiple server instances
• Complete File Operations: Full set of file and directory management tools
• Home Directory Support: Tilde (~) expansion for home directory paths
• Error Handling: Comprehensive error reporting for all operations

Environment Variables

• WORKDIR: Working directory to restrict all file operations (default: current directory)
• PREFIX: Optional prefix for all tool names (default: none)

Usage

Basic Usage

npx @dnap/dn-file-system-mcp

With Working Directory Restriction

WORKDIR=/path/to/allowed/directory npx @dnap/dn-file-system-mcp

With Command Prefix

PREFIX=memory_ npx @dnap/dn-file-system-mcp

Multiple Server Instances

# Memory server with restricted access
PREFIX=memory_ WORKDIR=/path/to/memory npx @dnap/dn-file-system-mcp

# Public server with different directory
PREFIX=public_ WORKDIR=/path/to/public npx @dnap/dn-file-system-mcp

Debugging and Inspection

Using MCP Inspector

For debugging and testing your MCP server, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector npx @dnap/dn-file-system-mcp

With environment variables:

WORKDIR=/path/to/directory PREFIX=test_ \
npx @modelcontextprotocol/inspector npx @dnap/dn-file-system-mcp

Claude Desktop Integration

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "dn_file_system": {
      "command": "npx",
      "args": ["@dnap/dn-file-system-mcp"],
      "env": {
        "WORKDIR": "/path/to/allowed/directory"
      }
    }
  }
}

With prefix for multiple instances:

{
  "mcpServers": {
    "memory_fs": {
      "command": "npx",
      "args": ["@dnap/dn-file-system-mcp"],
      "env": {
        "WORKDIR": "/path/to/memory",
        "PREFIX": "memory_"
      }
    },
    "public_fs": {
      "command": "npx",
      "args": ["@dnap/dn-file-system-mcp"],
      "env": {
        "WORKDIR": "/path/to/public",
        "PREFIX": "public_"
      }
    }
  }
}

VSCode/Cline Integration

For VSCode with Cline extension, add to your cline_mcp_settings.json:

{
  "mcpServers": {
    "dn_file_system": {
      "command": "npx",
      "args": ["@dnap/dn-file-system-mcp"],
      "env": {
        "WORKDIR": "/path/to/project"
      }
    }
  }
}

## Available Tools

### File and Directory Operations

#### `ls(path)` or `{prefix}ls(path)`
List directory contents
- **Parameters**: `path` (optional, default: ".")
- **Returns**: Directory contents with file/folder icons

#### `cd(path)` or `{prefix}cd(path)`
Change working directory (supports home directory expansion with `~`)
- **Parameters**: `path` (required)
- **Security**: Cannot navigate outside the configured working directory

#### `read_file(path)` or `{prefix}read_file(path)`
Read file contents
- **Parameters**: `path` (required)
- **Returns**: File contents as text

#### `write_file(path, content)` or `{prefix}write_file(path, content)`
Write content to a file
- **Parameters**: 
  - `path` (required)
  - `content` (required)
- **Action**: Creates or overwrites the specified file

#### `mkdir(path)` or `{prefix}mkdir(path)`
Create directory
- **Parameters**: `path` (required)
- **Features**: Supports recursive directory creation

#### `rm(path)` or `{prefix}rm(path)`
Remove file or empty directory
- **Parameters**: `path` (required)
- **Behavior**: 
  - Files: Deletes the file
  - Directories: Only removes if empty (use `rmdir` for non-empty directories)

#### `rmdir(path)` or `{prefix}rmdir(path)`
Remove directory and all contents recursively
- **Parameters**: `path` (required)
- **Warning**: Permanently deletes directory and all contents

#### `cp(src, dst)` or `{prefix}cp(src, dst)`
Copy file or directory
- **Parameters**: 
  - `src` (required): Source path
  - `dst` (required): Destination path
- **Features**: Supports both file and directory copying with recursion

#### `mv(src, dst)` or `{prefix}mv(src, dst)`
Move file or directory
- **Parameters**: 
  - `src` (required): Source path
  - `dst` (required): Destination path

### Editing and Searching

#### `edit_file(path, search, replace)` or `{prefix}edit_file(path, search, replace)`
Apply search/replace operations to a file
- **Parameters**: 
  - `path` (required): File path
  - `search` (required): Regular expression pattern to search for
  - `replace` (required): Replacement string
- **Features**: 
  - Uses global regex replacement
  - Reports number of replacements made
  - Handles cases where no matches are found

## Security Features

1. **Directory Sandboxing**: All file operations are restricted to the configured `WORKDIR`
2. **Path Validation**: Prevents directory traversal attacks (e.g., `../../../etc/passwd`)
3. **Error Handling**: Secure error messages that don't expose sensitive system information

## Examples

### Example 1: Basic File Operations
```bash
# Start server
npx @dnap/dn-file-system-mcp

# Tools available: ls, cd, read_file, write_file, etc.

Example 2: Multiple Servers with Prefixes

# Terminal 1: Memory server
PREFIX=memory_ WORKDIR=/home/user/memory npx @dnap/dn-file-system-mcp
# Tools: memory_ls, memory_cd, memory_read_file, etc.

# Terminal 2: Public server  
PREFIX=public_ WORKDIR=/home/user/public npx @dnap/dn-file-system-mcp
# Tools: public_ls, public_cd, public_read_file, etc.

Example 3: Secure Document Management

PREFIX=docs_ WORKDIR=/home/user/documents npx @dnap/dn-file-system-mcp
# Tools: docs_ls, docs_read_file, docs_write_file, etc.
# All operations restricted to /home/user/documents

Installation

Quick Start (Recommended)

No installation needed! Use npx to run directly:

# Test the server
npx @dnap/dn-file-system-mcp

# With environment variables
WORKDIR=/path/to/directory PREFIX=test_ npx @dnap/dn-file-system-mcp

# Debug with inspector
npx @modelcontextprotocol/inspector npx @dnap/dn-file-system-mcp

Development Setup

1. Clone the repository:

   git clone https://github.com/dnap/dn-file-system-mcp.git
   cd dn-file-system-mcp

2. Install dependencies:

   npm install

3. Test the server:

   # Test with inspector for debugging
   npm run debug
   # or
   npx @modelcontextprotocol/inspector node index.js

Optional: Local Installation

If you prefer to install locally:

npm install @dnap/dn-file-system-mcp

Dependencies

• @modelcontextprotocol/sdk: MCP server framework
• zod: Schema validation for tool parameters

Error Handling

The server provides comprehensive error handling for:

• File/directory not found
• Permission denied
• Path outside working directory
• Invalid operations (e.g., removing non-empty directory with rm)
• File system errors

All errors are returned in a consistent format with descriptive messages.