@j0hanz/filesystem-context-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,369 +1,571 @@
 # Filesystem Context MCP Server
 
-A secure Model Context Protocol (MCP) server for filesystem scanning, searching, and analysis. Built with TypeScript and the official MCP SDK.
+A secure, read-only MCP server for filesystem scanning, searching, and analysis with comprehensive security validation.
 
-## Security Features
+[![npm version](https://img.shields.io/npm/v/@j0hanz/filesystem-context-mcp.svg)](https://www.npmjs.com/package/@j0hanz/filesystem-context-mcp)
+[![License](https://img.shields.io/npm/l/@j0hanz/filesystem-context-mcp)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12.0-purple)](https://modelcontextprotocol.io)
 
-- **Path Validation**: All file operations are restricted to explicitly allowed directories
-- **Symlink Attack Prevention**: Symlinks are resolved before validation to prevent escaping allowed directories
-- **Path Traversal Protection**: Attempts to access paths outside allowed directories are blocked
-- **Read-Only Operations**: All tools are marked with `readOnlyHint` annotation
+## One-Click Install
 
-## Features
+[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-context&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-context-mcp%40latest%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D)[![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-context&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-context-mcp%40latest%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders)
 
-This server provides the following tools for filesystem operations:
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=filesystem-context&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1jb250ZXh0LW1jcEBsYXRlc3QiLCIke3dvcmtzcGFjZUZvbGRlcn0iXX0=)
 
-| Tool                       | Description                                                  |
-| -------------------------- | ------------------------------------------------------------ |
-| `list_allowed_directories` | List directories this server is allowed to access            |
-| `list_directory`           | List files and directories with optional recursive traversal |
-| `search_files`             | Search for files using glob patterns                         |
-| `read_file`                | Read file contents with optional line range                  |
-| `read_multiple_files`      | Read multiple files in parallel efficiently                  |
-| `get_file_info`            | Get detailed file/directory metadata                         |
-| `search_content`           | Search for text within files using regex patterns            |
-| `analyze_directory`        | Analyze directory structure and get statistics               |
-| `directory_tree`           | Get JSON tree structure of a directory                       |
-| `read_media_file`          | Read binary/media files as base64-encoded data               |
+## ✨ Features
 
-## Installation
+| Feature                    | Description                                                            |
+| -------------------------- | ---------------------------------------------------------------------- |
+| 📂 **Directory Listing**   | List and explore directory contents with recursive support             |
+| 🔍 **File Search**         | Find files using glob patterns like `**/*.ts`                          |
+| 📝 **Content Search**      | Search text within files using regex with context lines                |
+| 📊 **Directory Analysis**  | Get statistics, file types, largest files, and recently modified files |
+| 🌳 **Directory Tree**      | JSON tree structure optimized for AI parsing                           |
+| 📄 **File Reading**        | Read single or multiple files with head/tail and line range support    |
+| 🖼️ **Media File Support**  | Read binary files (images, audio, video) as base64                     |
+| 🔒 **Security First**      | Path validation, symlink escape protection, and access control         |
+| ⚡ **Parallel Operations** | Efficient batch file reading with configurable concurrency             |
 
-```bash
-# Clone the repository
-git clone <repository-url>
-cd filesystem-context-mcp
+## 🎯 When to Use
 
-# Install dependencies
-npm install
+| Task                             | Tool                       |
+| -------------------------------- | -------------------------- |
+| Explore project structure        | `list_directory`           |
+| Find specific file types         | `search_files`             |
+| Search for code patterns/text    | `search_content`           |
+| Understand codebase statistics   | `analyze_directory`        |
+| Get AI-friendly project overview | `directory_tree`           |
+| Read source code                 | `read_file`                |
+| Batch read multiple files        | `read_multiple_files`      |
+| Get file metadata (size, dates)  | `get_file_info`            |
+| Read images or binary files      | `read_media_file`          |
+| Check available directories      | `list_allowed_directories` |
 
-# Build the project
-npm run build
-```
+## 🚀 Quick Start
 
-## Usage
-
-### Running the Server
-
-**Important**: You must specify at least one allowed directory when starting the server:
+### NPX (Recommended - Zero Config)
 
 ```bash
-# Production mode - specify allowed directories
-node dist/index.js /path/to/allowed/dir1 /path/to/allowed/dir2
-
-# Development mode with tsx
-npx tsx src/index.ts /path/to/allowed/dir
-
-# Windows example
-node dist/index.js C:\Users\Projects C:\Users\Documents
+# Works in current directory automatically!
+npx -y @j0hanz/filesystem-context-mcp@latest
 ```
 
-### Testing with MCP Inspector
+Or specify directories explicitly:
 
 ```bash
-npm run inspector
+npx -y @j0hanz/filesystem-context-mcp@latest /path/to/your/project
 ```
 
-Then connect to the server via stdio, providing allowed directories as arguments.
-
-### Configuration with MCP Clients
+### VS Code (with workspace folder)
 
-#### Claude Desktop
-
-Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+Add to your VS Code settings (`.vscode/mcp.json`):
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "filesystem-context": {
-      "command": "node",
+      "command": "npx",
       "args": [
-        "C:\\path\\to\\filesystem-context-mcp\\dist\\index.js",
-        "C:\\Users\\Projects",
-        "C:\\Users\\Documents"
+        "-y",
+        "@j0hanz/filesystem-context-mcp@latest",
+        "${workspaceFolder}"
       ]
     }
   }
 }
 ```
 
-#### VS Code with Copilot
+> **Tip:** `${workspaceFolder}` automatically uses your current VS Code workspace. You can also omit it and the server will use its current working directory.
+
+### Claude Desktop
 
-Add to your VS Code settings or `.vscode/mcp.json`:
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
 
 ```json
 {
-  "mcp": {
-    "servers": {
-      "filesystem-context": {
-        "command": "node",
-        "args": ["${workspaceFolder}/dist/index.js", "${workspaceFolder}"]
-      }
+  "mcpServers": {
+    "filesystem-context": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-context-mcp@latest"]
     }
   }
 }
 ```
 
-## Tool Documentation
+> **Note:** Claude Desktop will use the current working directory automatically. No path arguments needed!
 
-All tools return both a human-readable `content` text block and a machine-friendly `structuredContent` payload (with `outputSchema` declared in the server).
+## 📦 Installation
 
-### list_directory
+### NPX (No Installation)
 
-List all files and directories in a given path.
+```bash
+npx -y @j0hanz/filesystem-context-mcp@latest /path/to/dir1 /path/to/dir2
+```
 
-**Parameters:**
+### Global Installation
 
-- `path` (string, required): The directory path to list
-- `recursive` (boolean, default: false): Whether to list recursively
-- `includeHidden` (boolean, default: false): Include hidden files (dotfiles)
-- `maxDepth` (number, default: 10): Maximum depth for recursive listing
-- `maxEntries` (number, optional): Maximum number of entries to return (prevents huge responses)
+```bash
+npm install -g @j0hanz/filesystem-context-mcp
+filesystem-context-mcp /path/to/your/project
+```
 
-**Example:**
+### From Source
 
-```json
-{
-  "path": "C:\\Users\\Projects",
-  "recursive": true,
-  "maxDepth": 2
-}
+```bash
+git clone https://github.com/j0hanz/filesystem-context-mcp-server.git
+cd filesystem-context-mcp-server
+npm install
+npm run build
+node dist/index.js /path/to/your/project
 ```
 
-### search_files
+## ⚙️ Configuration
 
-Search for files and directories matching a glob pattern.
+### Directory Resolution (Priority Order)
 
-**Parameters:**
+The server determines which directories to access in this order:
 
-- `path` (string, required): Base directory to search from
-- `pattern` (string, required): Glob pattern to match (e.g. `**/*.ts`)
-- `excludePatterns` (string[], optional): Glob patterns to exclude
-- `maxResults` (number, optional): Maximum number of matches to return (prevents huge responses)
+1. **CLI Arguments** - Explicitly passed paths take highest priority
+2. **MCP Roots Protocol** - Directories provided by the MCP client
+3. **Current Working Directory** - Automatic fallback for plug-and-play experience
 
-**Example:**
+This means you can run the server with zero configuration and it will work!
 
-```json
-{
-  "path": "./src",
-  "pattern": "**/*.ts",
-  "excludePatterns": ["**/*.test.ts"]
-}
+### Command Line Arguments
+
+Optionally specify one or more directory paths as arguments:
+
+```bash
+filesystem-context-mcp /home/user/project /home/user/docs
 ```
 
-### read_file
+### MCP Roots Protocol
+
+If no CLI arguments are provided, the server will use the MCP Roots protocol to receive allowed directories from the client (if supported).
+
+### Zero-Config Mode
+
+If neither CLI arguments nor MCP Roots provide directories, the server automatically uses the current working directory. This makes it truly plug-and-play!
+
+### Environment Variables
+
+| Variable   | Description                                   |
+| ---------- | --------------------------------------------- |
+| `NODE_ENV` | Set to `production` for optimized performance |
+
+## 🔧 Tools
+
+### `list_allowed_directories`
 
-Read the contents of a file (optionally a line range).
+List all directories that this server is allowed to access.
+
+| Parameter | Type | Required | Default | Description            |
+| --------- | ---- | -------- | ------- | ---------------------- |
+| _(none)_  | -    | -        | -       | No parameters required |
+
+**Returns:** Array of allowed directory paths.
+
+---
+
+### `list_directory`
+
+List contents of a directory with optional recursive listing.
+
+| Parameter               | Type    | Required | Default | Description                                 |
+| ----------------------- | ------- | -------- | ------- | ------------------------------------------- |
+| `path`                  | string  | ✅       | -       | Directory path to list                      |
+| `recursive`             | boolean | ❌       | `false` | List recursively                            |
+| `includeHidden`         | boolean | ❌       | `false` | Include hidden files                        |
+| `maxDepth`              | number  | ❌       | `10`    | Maximum depth for recursive listing (0-100) |
+| `maxEntries`            | number  | ❌       | -       | Maximum entries to return (1-100,000)       |
+| `sortBy`                | string  | ❌       | `name`  | Sort by: `name`, `size`, `modified`, `type` |
+| `includeSymlinkTargets` | boolean | ❌       | `false` | Include symlink target paths                |
 
-**Parameters:**
+**Returns:** List of entries with name, type, size, and modified date.
 
-- `path` (string, required): Path to the file
-- `encoding` (string, default: "utf-8"): File encoding
-- `maxSize` (number, default: 10485760): Maximum file size in bytes (default 10MB)
-- `lineStart` (number, optional): Start line (1-based)
-- `lineEnd` (number, optional): End line (inclusive)
+---
+
+### `search_files`
+
+Search for files using glob patterns.
+
+| Parameter         | Type     | Required | Default | Description                                   |
+| ----------------- | -------- | -------- | ------- | --------------------------------------------- |
+| `path`            | string   | ✅       | -       | Base directory to search from                 |
+| `pattern`         | string   | ✅       | -       | Glob pattern (e.g., `**/*.ts`, `src/**/*.js`) |
+| `excludePatterns` | string[] | ❌       | `[]`    | Patterns to exclude                           |
+| `maxResults`      | number   | ❌       | -       | Maximum matches to return (1-10,000)          |
+| `sortBy`          | string   | ❌       | `path`  | Sort by: `name`, `size`, `modified`, `path`   |
+| `maxDepth`        | number   | ❌       | -       | Maximum directory depth to search (1-100)     |
+
+**Returns:** List of matching files with path, type, size, and modified date.
 
 **Example:**
 
 ```json
 {
-  "path": "./src/index.ts",
-  "lineStart": 1,
-  "lineEnd": 50
+  "path": "/project",
+  "pattern": "**/*.ts",
+  "excludePatterns": ["node_modules/**", "dist/**"]
 }
 ```
 
-### get_file_info
+---
+
+### `read_file`
+
+Read the contents of a text file.
 
-Get detailed information about a file or directory.
+| Parameter   | Type   | Required | Default | Description                                      |
+| ----------- | ------ | -------- | ------- | ------------------------------------------------ |
+| `path`      | string | ✅       | -       | File path to read                                |
+| `encoding`  | string | ❌       | `utf-8` | File encoding (`utf-8`, `ascii`, `base64`, etc.) |
+| `maxSize`   | number | ❌       | 10MB    | Maximum file size in bytes                       |
+| `lineStart` | number | ❌       | -       | Start line (1-indexed) for reading a range       |
+| `lineEnd`   | number | ❌       | -       | End line (inclusive) for reading a range         |
+| `head`      | number | ❌       | -       | Read only first N lines                          |
+| `tail`      | number | ❌       | -       | Read only last N lines                           |
 
-**Parameters:**
+> **Note:** Cannot specify both `head` and `tail` simultaneously. Use `lineStart`/`lineEnd` for range reading.
 
-- `path` (string, required): Path to the file or directory
+**Returns:** File contents as text.
 
-**Returns:** File metadata including size, timestamps, permissions, and type.
+---
 
-### search_content
+### `read_multiple_files`
 
-Search for text content within files using a regular expression.
+Read multiple files in parallel for efficient batch operations.
 
-**Parameters:**
+| Parameter  | Type     | Required | Default | Description                          |
+| ---------- | -------- | -------- | ------- | ------------------------------------ |
+| `paths`    | string[] | ✅       | -       | Array of file paths (max 100)        |
+| `encoding` | string   | ❌       | `utf-8` | File encoding                        |
+| `maxSize`  | number   | ❌       | 10MB    | Maximum file size per file           |
+| `head`     | number   | ❌       | -       | Read only first N lines of each file |
+| `tail`     | number   | ❌       | -       | Read only last N lines of each file  |
 
-- `path` (string, required): Base directory to search in
-- `pattern` (string, required): Regular expression pattern
-- `filePattern` (string, default: "\*_/_"): Glob pattern to filter files
-- `excludePatterns` (string[], optional): Glob patterns to exclude (e.g. `node_modules/**`)
-- `caseSensitive` (boolean, default: false): Case-sensitive search
-- `maxResults` (number, default: 100): Maximum number of matches to return
-- `maxFileSize` (number, optional): Maximum file size in bytes to scan (default 1MB)
-- `maxFilesScanned` (number, optional): Maximum number of files to scan before stopping
-- `timeoutMs` (number, optional): Timeout in milliseconds for the search operation
-- `skipBinary` (boolean, default: true): Skip likely-binary files
+**Returns:** Array of results with content or error for each file.
+
+---
+
+### `get_file_info`
+
+Get detailed metadata about a file or directory.
+
+| Parameter | Type   | Required | Default | Description               |
+| --------- | ------ | -------- | ------- | ------------------------- |
+| `path`    | string | ✅       | -       | Path to file or directory |
+
+**Returns:** Metadata including name, type, size, created/modified/accessed timestamps, permissions, MIME type, and symlink target (if applicable).
+
+---
+
+### `search_content`
+
+Search for text content within files using regular expressions.
+
+| Parameter         | Type     | Required | Default | Description                                      |
+| ----------------- | -------- | -------- | ------- | ------------------------------------------------ |
+| `path`            | string   | ✅       | -       | Base directory to search in                      |
+| `pattern`         | string   | ✅       | -       | Regex pattern to search for                      |
+| `filePattern`     | string   | ❌       | `**/*`  | Glob pattern to filter files                     |
+| `excludePatterns` | string[] | ❌       | `[]`    | Glob patterns to exclude                         |
+| `caseSensitive`   | boolean  | ❌       | `false` | Case-sensitive search                            |
+| `maxResults`      | number   | ❌       | `100`   | Maximum number of results (1-10,000)             |
+| `maxFileSize`     | number   | ❌       | 1MB     | Maximum file size to scan                        |
+| `maxFilesScanned` | number   | ❌       | -       | Maximum files to scan before stopping            |
+| `timeoutMs`       | number   | ❌       | -       | Timeout in milliseconds (100-3,600,000)          |
+| `skipBinary`      | boolean  | ❌       | `true`  | Skip binary files                                |
+| `contextLines`    | number   | ❌       | `0`     | Lines of context before/after match (0-10)       |
+| `wholeWord`       | boolean  | ❌       | `false` | Match whole words only                           |
+| `isLiteral`       | boolean  | ❌       | `false` | Treat pattern as literal string (escape special) |
+
+**Returns:** Matching lines with file path, line number, content, and optional context.
 
 **Example:**
 
 ```json
 {
-  "path": "./src",
-  "pattern": "TODO:",
+  "path": "/project/src",
+  "pattern": "TODO|FIXME",
   "filePattern": "**/*.ts",
-  "maxResults": 50
+  "contextLines": 2
 }
 ```
 
-### analyze_directory
+---
 
-Analyze a directory structure and compute summary statistics.
+### `analyze_directory`
 
-**Parameters:**
+Analyze a directory structure and return statistics.
 
-- `path` (string, required): Directory path to analyze
-- `maxDepth` (number, default: 10): Maximum depth to traverse
-- `topN` (number, default: 10): Number of “top” items to return (largest/recent)
+| Parameter         | Type     | Required | Default | Description                            |
+| ----------------- | -------- | -------- | ------- | -------------------------------------- |
+| `path`            | string   | ✅       | -       | Directory to analyze                   |
+| `maxDepth`        | number   | ❌       | `10`    | Maximum depth to analyze (0-100)       |
+| `topN`            | number   | ❌       | `10`    | Number of top items to return (1-1000) |
+| `excludePatterns` | string[] | ❌       | `[]`    | Glob patterns to exclude               |
+| `includeHidden`   | boolean  | ❌       | `false` | Include hidden files and directories   |
 
-**Returns:** Statistics including file counts by extension, total size, largest files, and recently modified files.
+**Returns:** Statistics including total files/directories, total size, file type distribution, largest files, and recently modified files.
 
-### list_allowed_directories
+---
 
-List all directories that this server is allowed to access.
+### `directory_tree`
 
-**Parameters:** None
+Get a JSON tree structure of a directory, optimized for AI parsing.
 
-**Returns:** Array of allowed directory paths. Use this to understand the scope of available file operations.
+| Parameter         | Type     | Required | Default | Description                             |
+| ----------------- | -------- | -------- | ------- | --------------------------------------- |
+| `path`            | string   | ✅       | -       | Directory path to build tree from       |
+| `maxDepth`        | number   | ❌       | `5`     | Maximum depth to traverse (0-50)        |
+| `excludePatterns` | string[] | ❌       | `[]`    | Glob patterns to exclude                |
+| `includeHidden`   | boolean  | ❌       | `false` | Include hidden files and directories    |
+| `includeSize`     | boolean  | ❌       | `false` | Include file sizes in the tree          |
+| `maxFiles`        | number   | ❌       | -       | Maximum total files to include (1-100k) |
 
-### read_multiple_files
+**Returns:** Hierarchical tree structure with file/directory nodes.
 
-Read the contents of multiple files in parallel. More efficient than reading files one by one.
+---
 
-**Parameters:**
+### `read_media_file`
 
-- `paths` (string[], required): Array of file paths to read
-- `encoding` (string, default: "utf-8"): File encoding
-- `maxSize` (number, default: 10485760): Maximum file size in bytes per file (default 10MB)
+Read a binary/media file and return it as base64-encoded data.
 
-**Example:**
+| Parameter | Type   | Required | Default | Description                            |
+| --------- | ------ | -------- | ------- | -------------------------------------- |
+| `path`    | string | ✅       | -       | Path to the media file                 |
+| `maxSize` | number | ❌       | 50MB    | Maximum file size in bytes (max 500MB) |
+
+**Supported formats:** Images (PNG, JPG, GIF, WebP, SVG, etc.), Audio (MP3, WAV, FLAC, etc.), Video (MP4, WebM, etc.), Fonts (TTF, WOFF, etc.), PDFs, and more.
+
+**Returns:** Base64-encoded data with MIME type, size, and dimensions (for images).
+
+## 🔌 Client Configuration
+
+<details>
+<summary><b>VS Code</b></summary>
+
+Add to `.vscode/mcp.json` (recommended) or `.vscode/settings.json`:
 
 ```json
 {
-  "paths": ["./src/index.ts", "./src/server.ts", "./package.json"],
-  "encoding": "utf-8"
+  "servers": {
+    "filesystem-context": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@j0hanz/filesystem-context-mcp@latest",
+        "${workspaceFolder}"
+      ]
+    }
+  }
 }
 ```
 
-**Returns:** Array of results, each containing the file path and either its content or an error message. Individual file errors do not fail the entire operation.
-
-### directory_tree
+> **Note:** `${workspaceFolder}` is expanded by VS Code to the current workspace path.
 
-Get a JSON tree structure of a directory. More efficient for AI parsing than flat file lists.
+</details>
 
-**Parameters:**
+<details>
+<summary><b>Claude Desktop</b></summary>
 
-- `path` (string, required): Directory path to build tree from
-- `maxDepth` (number, default: 5): Maximum depth to traverse
-- `excludePatterns` (string[], optional): Glob patterns to exclude (e.g., `node_modules`, `*.log`)
-- `includeHidden` (boolean, default: false): Include hidden files and directories
-- `includeSize` (boolean, default: false): Include file sizes in the tree
-
-**Example:**
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
-  "path": "./src",
-  "maxDepth": 3,
-  "excludePatterns": ["__tests__"],
-  "includeSize": true
+  "mcpServers": {
+    "filesystem-context": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-context-mcp@latest"]
+    }
+  }
 }
 ```
 
-**Returns:** Nested tree structure with files and directories, useful for understanding project structure.
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
 
-### read_media_file
+Add to Cursor's MCP configuration:
 
-Read a binary/media file (image, audio, video, etc.) and return it as base64-encoded data.
+```json
+{
+  "mcpServers": {
+    "filesystem-context": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-context-mcp@latest"]
+    }
+  }
+}
+```
 
-**Parameters:**
+</details>
 
-- `path` (string, required): Path to the media file
-- `maxSize` (number, default: 52428800): Maximum file size in bytes (default 50MB)
+<details>
+<summary><b>Windsurf</b></summary>
 
-**Example:**
+Add to Windsurf's MCP configuration:
 
 ```json
 {
-  "path": "./assets/logo.png"
+  "mcpServers": {
+    "filesystem-context": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-context-mcp@latest"]
+    }
+  }
 }
 ```
 
-**Returns:** Object containing the file path, MIME type, size in bytes, and base64-encoded data.
+</details>
 
-## Development
+## 🔒 Security
 
-```bash
-# Run in development mode with hot reload
-npm run dev
+This server implements multiple layers of security:
 
-# Type checking
-npm run type-check
+| Protection                    | Description                                                               |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| **Access Control**            | Only explicitly allowed directories are accessible                        |
+| **Path Validation**           | All paths are validated before any filesystem operation                   |
+| **Symlink Protection**        | Symlinks that resolve outside allowed directories are blocked             |
+| **Path Traversal Prevention** | Attempts to escape via `../` are detected and blocked                     |
+| **Read-Only Operations**      | Server only performs read operations—no writes, deletes, or modifications |
+| **Safe Regex**                | Regular expressions are validated to prevent ReDoS attacks                |
+| **Size Limits**               | Configurable limits prevent resource exhaustion                           |
 
-# Linting
-npm run lint
+### Security Model
 
-# Build for production
-npm run build
+```text
+┌─────────────────────────────────────────────────────────┐
+│                    MCP Client                           │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│            Filesystem Context MCP Server                │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │              Path Validation Layer                │  │
+│  │  • Normalize paths                                │  │
+│  │  • Check against allowed directories              │  │
+│  │  • Resolve and validate symlinks                  │  │
+│  │  • Block traversal attempts                       │  │
+│  └───────────────────────────────────────────────────┘  │
+│                         │                               │
+│                         ▼                               │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │            Read-Only File Operations              │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│              Allowed Directories Only                   │
+│  /home/user/project  ✅                                 │
+│  /home/user/docs     ✅                                 │
+│  /etc/passwd         ❌ (blocked)                       │
+│  ../../../etc        ❌ (blocked)                       │
+└─────────────────────────────────────────────────────────┘
 ```
 
-## Architecture
+## 🛠️ Development
 
-```text
-filesystem-context-mcp/
-├── src/
-│   ├── index.ts           # Main server entry point
-│   └── lib/
-│       ├── types.ts       # TypeScript interfaces
-│       ├── path-utils.ts  # Path normalization utilities
-│       ├── path-validation.ts  # Security validation
-│       ├── file-operations.ts  # Core file operations
-│       └── formatters.ts  # Output formatting
-├── dist/                  # Compiled JavaScript output
-├── package.json           # Project configuration
-├── tsconfig.json          # TypeScript configuration
-└── README.md              # This file
-```
+### Prerequisites
+
+- Node.js >= 20.0.0
+- npm
 
-The server uses:
+### Scripts
 
-- **Transport**: StdioServerTransport for local MCP client integration
-- **Schema Validation**: Zod for input/output validation
-- **Glob Matching**: `fast-glob` for file pattern matching and `minimatch` for pattern testing
-- **Security**: Path validation against allowed directories with symlink resolution
+| Command                 | Description                      |
+| ----------------------- | -------------------------------- |
+| `npm run build`         | Compile TypeScript to JavaScript |
+| `npm run dev`           | Watch mode with tsx              |
+| `npm run start`         | Run compiled server              |
+| `npm run test`          | Run tests with Vitest            |
+| `npm run test:watch`    | Run tests in watch mode          |
+| `npm run test:coverage` | Run tests with coverage report   |
+| `npm run lint`          | Run ESLint                       |
+| `npm run format`        | Format code with Prettier        |
+| `npm run type-check`    | TypeScript type checking         |
+| `npm run inspector`     | Test with MCP Inspector          |
 
-## Security Considerations
+### Project Structure
 
-- **Required Configuration**: You must specify allowed directories via command line arguments
-- **Path Validation**: All paths are validated against allowed directories before any operation
-- **Symlink Protection**: Symlinks are resolved to their real paths before validation
-- **Read-Only**: The server only performs read operations (no file modifications)
-- **Annotations**: All tools are marked with `readOnlyHint: true` for MCP client awareness
+```text
+src/
+├── index.ts              # Entry point, CLI argument parsing
+├── server.ts             # MCP server setup, roots protocol handling
+├── config/
+│   └── types.ts          # Shared TypeScript types
+├── lib/
+│   ├── constants.ts      # Configuration constants and limits
+│   ├── errors.ts         # Error handling utilities
+│   ├── file-operations.ts# Core filesystem operations
+│   ├── formatters.ts     # Output formatting utilities
+│   ├── fs-helpers.ts     # Low-level filesystem helpers
+│   ├── image-parsing.ts  # Image dimension parsing
+│   ├── path-utils.ts     # Path manipulation utilities
+│   └── path-validation.ts# Security: path validation layer
+├── schemas/
+│   ├── common.ts         # Shared Zod schemas
+│   ├── inputs.ts         # Input validation schemas
+│   ├── outputs.ts        # Output validation schemas
+│   ├── validators.ts     # Custom validation functions
+│   └── index.ts          # Schema exports
+├── tools/
+│   ├── analyze-directory.ts
+│   ├── directory-tree.ts
+│   ├── get-file-info.ts
+│   ├── list-allowed-dirs.ts
+│   ├── list-directory.ts
+│   ├── read-file.ts
+│   ├── read-media-file.ts
+│   ├── read-multiple-files.ts
+│   ├── search-content.ts
+│   ├── search-files.ts
+│   └── index.ts          # Tool registration
+└── __tests__/            # Test files
+```
+
+### Testing with MCP Inspector
 
-## Troubleshooting
+```bash
+npm run inspector
+```
 
-### Server not starting
+This launches the MCP Inspector for interactive testing of all tools.
 
-1. Ensure Node.js >= 20.0.0 is installed
-2. Run `npm install` to install dependencies
-3. Run `npm run build` to compile TypeScript
+## ❓ Troubleshooting
 
-### Connection issues with MCP clients
+| Issue                       | Solution                                                                                 |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| "Access denied" error       | Ensure the path is within an allowed directory. Use `list_allowed_directories` to check. |
+| "Path does not exist" error | Verify the path exists. Use `list_directory` to explore available files.                 |
+| "File too large" error      | Use `head` or `tail` parameters for partial reading, or increase `maxSize`.              |
+| "Binary file" warning       | Use `read_media_file` for binary files, or set `skipBinary=false` in content search.     |
+| Unexpected directory access | Server defaults to CWD if no args/roots provided. Pass explicit paths to restrict.       |
+| Symlink blocked             | Symlinks that resolve outside allowed directories are blocked for security.              |
+| Regex timeout               | Simplify the regex pattern or use `isLiteral=true` for literal string search.            |
 
-1. Check the path in your client configuration is correct
-2. Ensure the server is built (`npm run build`)
-3. Test with MCP Inspector first: `npx @modelcontextprotocol/inspector`
+## 🤝 Contributing
 
-### File access errors
+Contributions are welcome! Please follow these steps:
 
-1. Verify the server process has read permissions
-2. Check that file paths are absolute or relative to the working directory
-3. Some files (binary, locked) may be skipped during search operations
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests and linting (`npm run lint && npm run test`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
 
-## License
+### Code Style
 
-MIT
+- Use TypeScript with strict mode
+- Follow ESLint configuration
+- Use Prettier for formatting
+- Write tests for new features