@m_sea_bass/relpath-filesystem-mcp/README.md

Secure MCP Filesystem Server with relative path support

# Relpath Filesystem MCP Server

A secure MCP (Model Context Protocol) filesystem server with relative path support.

## Features

- 🔒 **Enhanced Security**: Prevents path traversal attacks with robust path validation
- 📁 **Relative Path Support**: All operations use relative paths from a specified base directory
- 🛠️ **Complete Filesystem Operations**: 11 tools for comprehensive file and directory management
- 🚫 **Access Control**: Strict base directory enforcement prevents unauthorized access
- 🔗 **Symlink Safety**: Validates symlink targets to ensure they stay within allowed directories

## Installation

```bash
npx @m_sea_bass/relpath-filesystem-mcp
```

## Usage

### Command Line

```bash
# Run the server with a specific base directory
npx @m_sea_bass/relpath-filesystem-mcp /path/to/your/directory
```

### With MCP Clients

#### Cursor

Add to your `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@m_sea_bass/relpath-filesystem-mcp", "/path/to/your/directory"]
    }
  }
}
```

#### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@m_sea_bass/relpath-filesystem-mcp", "/path/to/your/directory"]
    }
  }
}
```

## Available Tools

1. **read_file** - Read complete file contents
2. **read_multiple_files** - Read multiple files simultaneously
3. **write_file** - Create or overwrite files
4. **edit_file** - Make line-based edits with git-style diff preview
5. **create_directory** - Create directories (with nested support)
6. **list_directory** - List directory contents
7. **directory_tree** - Get recursive directory tree as JSON
8. **move_file** - Move/rename files and directories
9. **search_files** - Search for files by pattern
10. **get_file_info** - Get detailed file/directory metadata
11. **list_allowed_directories** - Show base directory information

## Security Features

- **Path Traversal Protection**: Prevents `../` attacks
- **Base Directory Enforcement**: All operations restricted to specified directory
- **Symlink Validation**: Ensures symlink targets remain within allowed paths
- **Input Sanitization**: Comprehensive validation of all inputs
- **Error Handling**: Secure error messages that don't leak system information

## Examples

```javascript
// Using the MCP client
const client = new MCPClient();
await client.connect();

// Read a file (relative to base directory)
const content = await client.callTool('read_file', { path: 'example.txt' });

// Create a directory structure
await client.callTool('create_directory', { path: 'project/src' });

// Write a file
await client.callTool('write_file', { 
  path: 'project/README.md', 
  content: '# My Project' 
});
```

## Requirements

- Node.js >= 18.0.0
- Base directory must exist and be accessible


## Reference

This package was created with reference to the following package.
- [Filesystem MCP Server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem?activeTab=readme)

## License

MIT

## Contributing

Contributions are welcome! Please ensure all security features are maintained when making changes.