# MCP Smart Filesystem Server

An LLM-optimized Model Context Protocol (MCP) filesystem server with intelligent features designed for effective AI agent interaction.

## Features

### 🚀 **Intelligent File Pagination**
- Automatically chunks large files (>500 lines) into manageable pieces
- Simple `start_line` parameter for easy navigation
- Clear indicators when more content is available
- Prevents context overflow in LLM conversations

### ⚡ **Ripgrep Integration**
- Lightning-fast code searching across entire codebase
- Regex pattern support with helpful examples
- File-specific searching (like Ctrl+F with regex)
- Flexible filtering by file type, path, and more

### 🔒 **Security Sandboxing**
- Strict directory access control
- Symlink attack prevention
- Path traversal protection
- Only accesses files within allowed directories

### 🎯 **LLM-Friendly Design**
- Helpful suggestions in responses
- Examples for common search patterns
- Reading strategy recommendations for large files
- Clear error messages with actionable guidance

## Tools

### 1. **list_directory**
List directory contents with metadata.

```json
{
  "path": "src"
}
```

**Returns:** Files, directories, sizes, line counts, and summary statistics.

### 2. **read_file**
Read file contents with automatic pagination for large files.

```json
{
  "path": "src/large-file.ts",
  "start_line": 0
}
```

For files >500 lines, returns first 500 lines with `hasMore: true` and `nextStartLine`.  
Read next chunk with `start_line: 500`, then `1000`, etc.

### 3. **search_code**
Search for code patterns using ripgrep (very fast).

**Examples:**

Find any type declaration (class/struct/interface/enum):
```json
{
  "pattern": "\\b(class|struct|interface|enum)\\s+ServiceName\\b",
  "filePattern": "*.ts"
}
```

Find method with any access modifier:
```json
{
  "pattern": "\\b(public|private|protected).*\\s+methodName\\s*\\(",
  "path": "src/directory"
}
```

Find all async functions:
```json
{
  "pattern": "async\\s+.*\\s*\\(",
  "caseInsensitive": true,
  "contextLines": 3
}
```

**Options:**
- `pattern` (required): Regex pattern
- `path`: Limit to specific directory
- `filePattern`: File glob (e.g., `*.js`, `*.{ts,tsx}`, `!*test*`)
- `caseInsensitive`: Ignore case
- `contextLines`: Lines of context (default: 2)
- `maxResults`: Max results (default: 50)
- `literalString`: Treat as literal, not regex
- `wordBoundary`: Match whole words only

### 4. **search_in_file**
Search within a specific file (like Ctrl+F with regex).

```json
{
  "path": "src/server.ts",
  "pattern": "app\\.use\\(",
  "contextLines": 3
}
```

### 5. **find_files**
Find files by name pattern.

```json
{
  "pattern": "*Handler*.ts"
}
```

**Pattern examples:**
- `config.json` - Exact name
- `*.config` - Wildcard
- `*Service*` - Contains "Service"
- `*.{ts,tsx,js}` - Multiple extensions

### 6. **get_file_info**
Get file metadata without reading contents.

```json
{
  "path": "src/large-file.ts"
}
```

**Returns:** Size, line count, language, binary status, and reading strategy for large files.

### 7. **list_allowed_directories**
Show accessible directories (security boundaries).

```json
{}
```

## Installation

### Docker (Recommended)

```bash
# Build image
docker build -t mcp-filesystem-smart .

# Run with workspace mounted
docker run -i --rm \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart
```

The `:ro` flag makes the directory read-only for extra security.

### Configuration via Environment Variables

Customize behavior with environment variables:

```bash
docker run -i --rm \
  -e MCP_LINES_PER_PAGE=1000 \
  -e MCP_MAX_SEARCH_RESULTS=200 \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart
```

**Available Variables:**
- `MCP_LINES_PER_PAGE` - Lines per page when reading files (default: 500)
- `MCP_MAX_SEARCH_RESULTS` - Search results per page (default: 100)

### Local Installation

```bash
npm install
npm run build
node dist/index.js /path/to/allowed/directory
```

## Usage with MCP Clients

### Configuration Example

```json
{
  "mcpServers": {
    "filesystem-smart": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/projects/myapp:/workspace:ro",
        "mcp-filesystem-smart"
      ]
    }
  }
}
```

### Multiple Allowed Directories

```bash
# Local
node dist/index.js /path/to/dir1 /path/to/dir2

# Docker (mount multiple volumes)
docker run -i --rm \
  -v /path/to/dir1:/workspace1:ro \
  -v /path/to/dir2:/workspace2:ro \
  mcp-filesystem-smart /workspace1 /workspace2
```

## LLM Usage Patterns

### Pattern 1: Find Type Declaration (Unknown Kind)
When you don't know if something is a class, struct, interface, or record:

```javascript
search_code({
  pattern: "\\b(class|struct|record|interface|enum)\\s+MyType\\b",
  filePattern: "*.cs"
})
```

### Pattern 2: Explore Then Read
1. Search for what you need: `search_code(pattern="functionName")`
2. Get file info: `get_file_info(path="src/module.ts")` 
3. Read strategically: `read_file(path="src/module.ts", start_line=0)`

### Pattern 3: Large File Navigation
1. Check size: `get_file_info(path="big-file.ts")` → "1500 lines"
2. Search within: `search_in_file(path="big-file.ts", pattern="export class")`
3. Read around matches: Use line numbers from search to read specific chunks

### Pattern 4: Find Files, Then Search
1. Find files: `find_files(pattern="*Service*.ts")`
2. Search within results: `search_code(pattern="constructor", path="src/services")`

## Common Search Patterns

### C# / .NET
```javascript
// Find any type
"\\b(class|struct|record|interface|enum)\\s+TypeName\\b"

// Find method
"\\b(public|private|protected|internal).*\\s+MethodName\\s*\\("

// Find async methods
"async\\s+(Task|ValueTask)<.*>\\s+\\w+\\s*\\("
```

### TypeScript / JavaScript
```javascript
// Find function/method
"(function|const|let|var)\\s+\\w+\\s*=.*=>|function\\s+\\w+\\s*\\("

// Find class/interface
"(class|interface)\\s+\\w+"

// Find async functions
"async\\s+(function|\\w+\\s*=>|\\(.*\\)\\s*=>)"
```

### Python
```javascript
// Find class
"class\\s+\\w+.*:"

// Find function
"def\\s+\\w+\\s*\\("

// Find async function
"async\\s+def\\s+\\w+"
```

## Requirements

- **Node.js**: 22 or higher
- **ripgrep**: Must be installed and available in PATH
  - Alpine Linux: `apk add ripgrep`
  - Ubuntu/Debian: `apt install ripgrep`
  - macOS: `brew install ripgrep`
  - Windows: `choco install ripgrep`

## Security

This server implements multiple security layers:

1. **Directory Sandboxing**: Only accesses files within allowed directories
2. **Symlink Resolution**: Prevents symlink attacks by checking real paths
3. **Path Validation**: Blocks path traversal attempts (../, etc.)
4. **Read-Only Docker**: Mount volumes as `:ro` for read-only access

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test locally
node dist/index.js $(pwd)
```

## License

MIT

## Credits

Built on top of the Model Context Protocol (MCP) SDK and ripgrep.