@j0hanz/filesystem-context-mcp 1.0.0

package/README.md

@@ -0,0 +1,369 @@
+# 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.
+
+## Security Features
+
+- **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
+
+## Features
+
+This server provides the following tools for filesystem operations:
+
+| 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               |
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd filesystem-context-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Usage
+
+### Running the Server
+
+**Important**: You must specify at least one allowed directory when starting the server:
+
+```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
+```
+
+### Testing with MCP Inspector
+
+```bash
+npm run inspector
+```
+
+Then connect to the server via stdio, providing allowed directories as arguments.
+
+### Configuration with MCP Clients
+
+#### Claude Desktop
+
+Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "filesystem-context": {
+      "command": "node",
+      "args": [
+        "C:\\path\\to\\filesystem-context-mcp\\dist\\index.js",
+        "C:\\Users\\Projects",
+        "C:\\Users\\Documents"
+      ]
+    }
+  }
+}
+```
+
+#### VS Code with Copilot
+
+Add to your VS Code settings or `.vscode/mcp.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "filesystem-context": {
+        "command": "node",
+        "args": ["${workspaceFolder}/dist/index.js", "${workspaceFolder}"]
+      }
+    }
+  }
+}
+```
+
+## Tool Documentation
+
+All tools return both a human-readable `content` text block and a machine-friendly `structuredContent` payload (with `outputSchema` declared in the server).
+
+### list_directory
+
+List all files and directories in a given path.
+
+**Parameters:**
+
+- `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)
+
+**Example:**
+
+```json
+{
+  "path": "C:\\Users\\Projects",
+  "recursive": true,
+  "maxDepth": 2
+}
+```
+
+### search_files
+
+Search for files and directories matching a glob pattern.
+
+**Parameters:**
+
+- `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)
+
+**Example:**
+
+```json
+{
+  "path": "./src",
+  "pattern": "**/*.ts",
+  "excludePatterns": ["**/*.test.ts"]
+}
+```
+
+### read_file
+
+Read the contents of a file (optionally a line range).
+
+**Parameters:**
+
+- `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)
+
+**Example:**
+
+```json
+{
+  "path": "./src/index.ts",
+  "lineStart": 1,
+  "lineEnd": 50
+}
+```
+
+### get_file_info
+
+Get detailed information about a file or directory.
+
+**Parameters:**
+
+- `path` (string, required): Path to the file or directory
+
+**Returns:** File metadata including size, timestamps, permissions, and type.
+
+### search_content
+
+Search for text content within files using a regular expression.
+
+**Parameters:**
+
+- `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
+
+**Example:**
+
+```json
+{
+  "path": "./src",
+  "pattern": "TODO:",
+  "filePattern": "**/*.ts",
+  "maxResults": 50
+}
+```
+
+### analyze_directory
+
+Analyze a directory structure and compute summary statistics.
+
+**Parameters:**
+
+- `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)
+
+**Returns:** Statistics including file counts by extension, total size, largest files, and recently modified files.
+
+### list_allowed_directories
+
+List all directories that this server is allowed to access.
+
+**Parameters:** None
+
+**Returns:** Array of allowed directory paths. Use this to understand the scope of available file operations.
+
+### read_multiple_files
+
+Read the contents of multiple files in parallel. More efficient than reading files one by one.
+
+**Parameters:**
+
+- `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)
+
+**Example:**
+
+```json
+{
+  "paths": ["./src/index.ts", "./src/server.ts", "./package.json"],
+  "encoding": "utf-8"
+}
+```
+
+**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
+
+Get a JSON tree structure of a directory. More efficient for AI parsing than flat file lists.
+
+**Parameters:**
+
+- `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:**
+
+```json
+{
+  "path": "./src",
+  "maxDepth": 3,
+  "excludePatterns": ["__tests__"],
+  "includeSize": true
+}
+```
+
+**Returns:** Nested tree structure with files and directories, useful for understanding project structure.
+
+### read_media_file
+
+Read a binary/media file (image, audio, video, etc.) and return it as base64-encoded data.
+
+**Parameters:**
+
+- `path` (string, required): Path to the media file
+- `maxSize` (number, default: 52428800): Maximum file size in bytes (default 50MB)
+
+**Example:**
+
+```json
+{
+  "path": "./assets/logo.png"
+}
+```
+
+**Returns:** Object containing the file path, MIME type, size in bytes, and base64-encoded data.
+
+## Development
+
+```bash
+# Run in development mode with hot reload
+npm run dev
+
+# Type checking
+npm run type-check
+
+# Linting
+npm run lint
+
+# Build for production
+npm run build
+```
+
+## Architecture
+
+```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
+```
+
+The server uses:
+
+- **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
+
+## Security Considerations
+
+- **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
+
+## Troubleshooting
+
+### Server not starting
+
+1. Ensure Node.js >= 20.0.0 is installed
+2. Run `npm install` to install dependencies
+3. Run `npm run build` to compile TypeScript
+
+### Connection issues with MCP clients
+
+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`
+
+### File access errors
+
+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
+
+## License
+
+MIT

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { classifyError, createDetailedError, ErrorCode, formatDetailedError, getSuggestion, } from '../lib/errors.js';
+describe('Error Utilities', () => {
+    describe('classifyError', () => {
+        it('should classify access denied errors', () => {
+            const error = new Error('Path not within allowed directories');
+            expect(classifyError(error)).toBe(ErrorCode.E_ACCESS_DENIED);
+        });
+        it('should classify not found errors', () => {
+            const error = new Error('ENOENT: no such file or directory');
+            expect(classifyError(error)).toBe(ErrorCode.E_NOT_FOUND);
+        });
+        it('should classify not a file errors', () => {
+            const error = new Error('Not a file: /some/path');
+            expect(classifyError(error)).toBe(ErrorCode.E_NOT_FILE);
+        });
+        it('should classify file too large errors', () => {
+            const error = new Error('File too large: 100MB');
+            expect(classifyError(error)).toBe(ErrorCode.E_TOO_LARGE);
+        });
+        it('should classify permission errors', () => {
+            const error = new Error('EACCES: permission denied');
+            expect(classifyError(error)).toBe(ErrorCode.E_PERMISSION_DENIED);
+        });
+        it('should classify timeout errors', () => {
+            const error = new Error('Operation timeout');
+            expect(classifyError(error)).toBe(ErrorCode.E_TIMEOUT);
+        });
+        it('should return unknown for unrecognized errors', () => {
+            const error = new Error('Some random error');
+            expect(classifyError(error)).toBe(ErrorCode.E_UNKNOWN);
+        });
+        it('should handle non-Error objects', () => {
+            expect(classifyError('ENOENT error')).toBe(ErrorCode.E_NOT_FOUND);
+            expect(classifyError({ message: 'permission denied' })).toBe(ErrorCode.E_UNKNOWN);
+        });
+    });
+    describe('createDetailedError', () => {
+        it('should create detailed error object', () => {
+            const error = new Error('File not found');
+            const detailed = createDetailedError(error, '/some/path');
+            expect(detailed.code).toBe(ErrorCode.E_NOT_FOUND);
+            expect(detailed.message).toBe('File not found');
+            expect(detailed.path).toBe('/some/path');
+            expect(detailed.suggestion).toBeTruthy();
+        });
+        it('should include additional details', () => {
+            const error = new Error('Error');
+            const detailed = createDetailedError(error, '/path', { extra: 'info' });
+            expect(detailed.details).toEqual({ extra: 'info' });
+        });
+    });
+    describe('formatDetailedError', () => {
+        it('should format error for display', () => {
+            const detailed = {
+                code: ErrorCode.E_NOT_FOUND,
+                message: 'File not found',
+                path: '/some/path',
+                suggestion: 'Check the path exists',
+            };
+            const formatted = formatDetailedError(detailed);
+            expect(formatted).toContain('E_NOT_FOUND');
+            expect(formatted).toContain('File not found');
+            expect(formatted).toContain('/some/path');
+            expect(formatted).toContain('Check the path exists');
+        });
+        it('should handle missing optional fields', () => {
+            const detailed = {
+                code: ErrorCode.E_UNKNOWN,
+                message: 'Unknown error',
+            };
+            const formatted = formatDetailedError(detailed);
+            expect(formatted).toContain('E_UNKNOWN');
+            expect(formatted).toContain('Unknown error');
+        });
+    });
+    describe('getSuggestion', () => {
+        it('should return suggestions for all error codes', () => {
+            const errorCodes = Object.values(ErrorCode);
+            for (const code of errorCodes) {
+                const suggestion = getSuggestion(code);
+                expect(suggestion).toBeTruthy();
+                expect(typeof suggestion).toBe('string');
+            }
+        });
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/__tests__/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/file-operations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-operations.test.d.ts.map

package/dist/__tests__/file-operations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-operations.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/file-operations.test.ts"],"names":[],"mappings":""}