# MCP Filesystem Server

A comprehensive Model Context Protocol (MCP) server providing advanced filesystem operations with intelligent features for AI-assisted development workflows.

## Features

### 🔧 **Core Tools**

- **`batch_read`** - Read multiple files efficiently in a single operation
- **`rename_file`** - Rename files with safety checks
- **`move_file`** - Move files with automatic directory creation
- **`check_structure`** - Display project structure with smart filtering
- **`run_command`** - Execute commands with Python virtual environment auto-activation

### 🚀 **Advanced Capabilities**

- **Smart Virtual Environment Detection** - Automatically activates Python `.venv` when detected
- **Cross-Platform Support** - Works on Windows, macOS, and Linux
- **Intelligent Filtering** - Uses `.checkignore` files + built-in patterns for clean structure views
- **Command Prohibition** - Prevents file management command overlap between tools
- **Enhanced Quote Handling** - Proper execution of complex commands with quoted arguments
- **Clean Output Format** - Focused, minimal output for better AI integration

## Quick Start

### Installation

```bash
npm install
npm run build
```

### Configuration

Create `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/dist/index.js"
      ],
      "env": {}
    }
  }
}
```

## Tool Documentation

### 📄 `batch_read`

Read multiple files concurrently with automatic encoding detection.

```typescript
{
  projectPath: "C:/project",
  relativePaths: ["src/index.ts", "package.json", "README.md"]
}
```

**Features:**
- Concurrent file reading for performance
- UTF-8 and binary (base64) support
- Empty file detection (`[EMPTY]` indicator)
- Graceful error handling for missing files

### 🔄 `rename_file`

Safely rename files with conflict detection.

```typescript
{
  projectPath: "C:/project", 
  currentPath: "src/oldname.js",
  newName: "newname.js"
}
```

**Safety Features:**
- Source file existence validation
- Destination conflict prevention
- Clear success/error feedback

### 📁 `move_file`

Move files with automatic directory creation.

```typescript
{
  projectPath: "C:/project",
  sourcePath: "src/component.tsx", 
  destinationPath: "src/components/component.tsx"
}
```

**Features:**
- Automatic parent directory creation
- Conflict detection and prevention
- Cross-directory moves

### 🌳 `check_structure`

Display clean project structure with intelligent filtering.

```typescript
{
  projectPath: "C:/project"
}
```

**Smart Filtering:**
- Built-in ignore patterns (node_modules, .git, dist, etc.)
- Custom `.checkignore` file support
- Empty directory detection
- Clean tree visualization

#### .checkignore Format

```bash
# Comments start with #
temp/
*.tmp
*.log
debug/
```

### 💻 `run_command`

Execute development commands with Python virtual environment auto-activation.

```typescript
{
  projectPath: "C:/project",
  command: "npm test"
}
```

**Features:**
- **Auto venv activation** - Detects `.venv` and activates automatically
- **Cross-platform** - Windows and Unix support
- **Quote handling** - Proper execution of complex quoted commands
- **Command prohibition** - Blocks file management commands (use dedicated tools)

**Prohibited Commands:**
- File reading: `cat`, `type`, `more`, etc. → Use `batch_read`
- File moving: `mv`, `move`, `ren` → Use `rename_file`/`move_file`
- File listing: `dir`, `ls`, `tree` → Use `check_structure`

## Examples

### Python Development Workflow

```typescript
// Check project structure
{ projectPath: "C:/python-project" }

// Read configuration files  
{
  projectPath: "C:/python-project",
  relativePaths: ["requirements.txt", "setup.py", "src/main.py"]
}

// Run tests (auto-activates .venv)
{
  projectPath: "C:/python-project", 
  command: "pytest tests/ -v"
}

// Install packages (in venv)
{
  projectPath: "C:/python-project",
  command: "pip install requests"
}
```

### Node.js Development Workflow

```typescript
// Build project
{
  projectPath: "C:/node-project",
  command: "npm run build"
}

// Run tests
{
  projectPath: "C:/node-project", 
  command: "npm test"
}

// Lint code
{
  projectPath: "C:/node-project",
  command: "npx eslint src/ --fix"
}
```

## Technical Details

### Virtual Environment Detection

The server automatically detects Python virtual environments:

- **Windows**: `.venv\Scripts\activate.bat`
- **Unix/Linux**: `.venv/bin/activate`

When detected, all Python commands are executed within the virtual environment context.

### Error Handling

All tools provide comprehensive error handling:

- **File not found** - Clear error messages with full paths
- **Permission denied** - Specific access error reporting  
- **Command failures** - Exit codes and stderr capture
- **Validation errors** - Pre-execution checks prevent issues

### Performance

- **Concurrent operations** - Multiple files read simultaneously
- **Smart filtering** - Reduces unnecessary filesystem traversal
- **Efficient command execution** - Minimal overhead for command operations

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm run dev  # Build and start
```

### Project Structure

```
src/
├── index.ts          # Main MCP server implementation
package.json          # Dependencies and scripts
tsconfig.json         # TypeScript configuration
.checkignore          # Structure filtering patterns
README.md            # This documentation
```

## License

MIT License

## Contributing

Contributions welcome! Please ensure all tools maintain the clean, focused output format and comprehensive error handling standards.