# Filesystem MCP Server with Ignore File Support

A Node.js MCP server for filesystem operations with support for custom ignore files (`.gitignore`, `.cursorignore`, `.cascadeignore`, `.claudeignore`, etc.).

**Protect sensitive data** by controlling which files AI agents can access using gitignore-style patterns.

## Features

- **Ignore File Support**: Filter files using `.gitignore`, `.cursorignore`, `.cascadeignore`, or any custom ignore file
- **Unified File Operations**: Single endpoints for reading/writing/editing multiple files
- **Automatic Project Detection**: Detects Laravel, Python, Node.js, and other project types
- **Token Optimization**: Smart truncation and compact directory trees for large projects
- **MCP Resources**: Exposes workspace info and project details as MCP resources
- **Dynamic Access Control**: Via command-line args or [MCP Roots protocol](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)

## Installation & Usage

### Quick Start with NPX

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@a13-team/filesystem-mcp-ignore",
        "/path/to/your/project"
      ]
    }
  }
}
```

### With Ignore Files

To enable ignore file filtering, use the `--ignore-files` or `-i` flag:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@a13-team/filesystem-mcp-ignore",
        "-i", ".gitignore,.cursorignore",
        "/path/to/your/project"
      ]
    }
  }
}
```

### Supported Ignore Files

- `.gitignore` - Standard Git ignore patterns
- `.cursorignore` - Cursor AI editor ignore
- `.cascadeignore` - Windsurf/Cascade ignore
- `.claudeignore` - Claude AI ignore
- `.codeiumignore` - Codeium ignore
- Any custom file with gitignore-style patterns

### Ignore Pattern Syntax

Patterns follow `.gitignore` syntax:

```gitignore
# Comments start with #
node_modules/       # Ignore directories
*.log               # Glob patterns
!important.log      # Negation (include)
/root-only.txt      # Root-relative patterns
**/*.test.ts        # Match in any directory
```

## API

### Tools (8 unified endpoints)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `read_file` | Read single or multiple files (auto-detects text/binary) | readOnly: true |
| `write_file` | Write single or multiple files | destructive: true |
| `edit_file` | Edit single or multiple files with find/replace | destructive: true |
| `move_file` | Move/rename single or multiple files | destructive: false |
| `create_directory` | Create directories (recursive) | idempotent: true |
| `list_directory` | List directory contents with sizes | readOnly: true |
| `directory_tree` | Get JSON tree structure (compact mode) | readOnly: true |
| `search_files` | Search files by glob pattern | readOnly: true |

### Tool Details

#### `read_file` (Universal Read)

Read one or more files with automatic type detection.

```typescript
{
  paths: string | string[],  // Single path or array
  encoding?: 'text' | 'base64' | 'auto',  // Default: 'auto'
  head?: number,  // First N lines (text only)
  tail?: number,  // Last N lines (text only)
  maxTokens?: number  // Approx token limit for response size
}
```

- **Text files**: Returns content as text (code, config, markdown, etc.)
- **SVG files**: Returns as text (viewable XML code)
- **Binary files**: Returns metadata only with message to use native tools
- **Large files**: Automatically truncated with option to use head/tail

Binary files return metadata shaped like:

```json
{
  "type": "binary_info",
  "path": "/path/to/image.png",
  "mimeType": "image/png",
  "size": 12345,
  "message": "Binary file. Use native tools or download to view."
}
```

#### `write_file` (Universal Write)

Write one or more files.

```typescript
{
  files: { path: string, content: string } | Array<{ path: string, content: string }>
}
```

- Creates parent directories automatically
- Overwrites existing files (use with caution)

#### `edit_file` (Universal Edit)

Make text replacements in one or more files.

```typescript
{
  edits: {
    path: string,
    changes: Array<{ oldText: string, newText: string }>
  } | Array<{ path: string, changes: Array<{ oldText: string, newText: string }> }>,
  dryRun?: boolean  // Preview without applying
}
```

- Returns git-style diff showing changes
- Supports whitespace-flexible matching
- Use `dryRun: true` to preview changes

#### `move_file` (Universal Move)

Move or rename files/directories.

```typescript
{
  operations: { source: string, destination: string } | Array<{ source: string, destination: string }>
}
```

#### `list_directory`

List directory contents with optional detail formatting.

```typescript
{
  path: string,
  showSizes?: boolean,  // Default: false
  sortBy?: 'name' | 'size' | 'modified',
  format?: 'compact' | 'detailed' // Default: 'compact'
}
```

- `format: 'detailed'` or `showSizes: true` includes size and mtime summaries.

#### `directory_tree`

Get recursive directory structure as JSON.

```typescript
{
  path: string,
  maxDepth?: number,  // Default: 10
  excludePatterns?: string[],
  compact?: boolean,  // Default: true - collapses large dirs
  omitEmptyDirs?: boolean // Default: false
}
```

Compact mode automatically:
- Collapses `node_modules/`, `vendor/`, `.git/`, etc.
- Groups many similar files: `*.svg (15 files)`

### MCP Resources

The server exposes these resources:

| URI | Description |
|-----|-------------|
| `workspace://allowed-directories` | List of allowed directories |
| `workspace://project-info` | Detected project type and stack |
| `workspace://tree/{path}` | Directory tree JSON for a path |

## Project Detection

The server automatically detects project types and exposes info via `workspace://project-info` resource:

- **Laravel/PHP**: Detects Livewire, Inertia, Blade, Vue, React, Tailwind, Vite
- **Python**: Django, Flask, FastAPI with database detection
- **Node.js**: Next.js, Nuxt, Express, NestJS, React, Vue, Angular, Svelte
- **Other**: Ruby/Rails, Go, Rust, Java (Maven/Gradle), .NET

## Directory Access Control

Directories can be specified:

1. **Via command-line arguments** (shown above)
2. **Via MCP Roots protocol** (recommended for dynamic updates)

MCP clients supporting [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update allowed directories at runtime.

## Token Optimization

- **Response truncation**: Large files truncated at ~50k chars with message to use head/tail
- **Compact trees**: Directory trees collapse `node_modules/`, `vendor/`, etc.
- **File grouping**: Many similar files shown as `*.svg (15 files)`
- **Binary handling**: Binary files return metadata only (no base64 bloat)

## License

MIT License. See [LICENSE](LICENSE).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md).