@j0hanz/filesystem-context-mcp 1.0.4 → 1.0.7

package/README.md

@@ -5,7 +5,7 @@ A secure, read-only MCP server for filesystem scanning, searching, and analysis
 [![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/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7.2-blue)](https://www.typescriptlang.org/)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.12.0-purple)](https://modelcontextprotocol.io)
 
 ## One-Click Install
@@ -196,7 +196,7 @@ Search for files using glob patterns.
 | `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)          |
+| `maxResults`      | number   | ❌       | -       | Maximum matches to return (max 10,000)        |
 | `sortBy`          | string   | ❌       | `path`  | Sort by: `name`, `size`, `modified`, `path`   |
 | `maxDepth`        | number   | ❌       | -       | Maximum directory depth to search (1-100)     |
 
@@ -218,15 +218,15 @@ Search for files using glob patterns.
 
 Read the contents of a text file.
 
-| 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                           |
+| 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, min 1) for reading a range          |
+| `lineEnd`   | number | ❌       | -       | End line (1-indexed, inclusive, min 1) for reading a range |
+| `head`      | number | ❌       | -       | Read only first N lines                                    |
+| `tail`      | number | ❌       | -       | Read only last N lines                                     |
 
 > **Note:** Cannot specify both `head` and `tail` simultaneously. Use `lineStart`/`lineEnd` for range reading.
 
@@ -301,13 +301,13 @@ Search for text content within files using regular expressions.
 
 Analyze a directory structure and return statistics.
 
-| 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   |
+| 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 (max 1000) |
+| `excludePatterns` | string[] | ❌       | `[]`    | Glob patterns to exclude                 |
+| `includeHidden`   | boolean  | ❌       | `false` | Include hidden files and directories     |
 
 **Returns:** Statistics including total files/directories, total size, file type distribution, largest files, and recently modified files.
 
@@ -317,14 +317,14 @@ Analyze a directory structure and return statistics.
 
 Get a JSON tree structure of a directory, optimized for AI parsing.
 
-| 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) |
+| 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 (max 100,000) |
 
 **Returns:** Hierarchical tree structure with file/directory nodes.
 
@@ -500,6 +500,7 @@ This server implements multiple layers of security:
 src/
 ├── index.ts              # Entry point, CLI argument parsing
 ├── server.ts             # MCP server setup, roots protocol handling
+├── instructions.md       # AI instructions for tool usage (bundled with dist)
 ├── config/
 │   └── types.ts          # Shared TypeScript types
 ├── lib/

package/dist/config/types.d.ts

@@ -149,7 +149,7 @@ export interface DetailedError {
     details?: Record<string, unknown>;
 }
 export interface ErrorResponse {
-    [x: string]: unknown;
+    [key: string]: unknown;
     content: {
         type: 'text';
         text: string;

package/dist/config/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"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"}

package/dist/instructions.md

@@ -0,0 +1,209 @@
+# Filesystem Context MCP Server
+
+> **Read-only** tools for exploring directories, searching files, and analyzing codebases via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+This server enables AI assistants to safely explore and analyze filesystem contents without modification capabilities. All operations are sandboxed to explicitly allowed directories.
+
+---
+
+## Quick Reference
+
+| Goal                | Tool                       | Key Parameters                      |
+| ------------------- | -------------------------- | ----------------------------------- |
+| Check access        | `list_allowed_directories` | —                                   |
+| Project structure   | `directory_tree`           | `maxDepth`, `excludePatterns`       |
+| List contents       | `list_directory`           | `recursive`, `sortBy`               |
+| Directory stats     | `analyze_directory`        | `topN`, `excludePatterns`           |
+| Find files          | `search_files`             | `pattern` (glob), `maxResults`      |
+| Search in files     | `search_content`           | `pattern` (regex), `contextLines`   |
+| Read file           | `read_file`                | `head`, `tail`, `lineStart/lineEnd` |
+| Read multiple files | `read_multiple_files`      | `paths[]` — **preferred for 2+**    |
+| File metadata       | `get_file_info`            | `path`                              |
+| Binary/media files  | `read_media_file`          | `maxSize`                           |
+
+---
+
+## Workflows
+
+### Project Discovery
+
+```text
+list_allowed_directories → directory_tree(maxDepth=3) → analyze_directory → read_multiple_files([package.json, README.md])
+```
+
+### Find & Read Code
+
+```text
+search_files(pattern="**/*.ts") → read_multiple_files([...results])
+```
+
+### Search Patterns
+
+```text
+search_content(pattern="TODO|FIXME", filePattern="**/*.ts", contextLines=2)
+```
+
+### Common Glob Patterns
+
+| Pattern               | Matches                                   |
+| --------------------- | ----------------------------------------- |
+| `**/*.ts`             | All TypeScript files                      |
+| `src/**/*.{js,jsx}`   | JS/JSX files under `src/`                 |
+| `**/test/**`          | All files in any `test/` directory        |
+| `**/*.test.ts`        | Test files by naming convention           |
+| `!**/node_modules/**` | Exclude `node_modules/` (use in excludes) |
+
+---
+
+## Best Practices
+
+**Do:**
+
+- Use `read_multiple_files` for 2+ files (parallel, resilient)
+- Set `maxResults`, `maxDepth`, `maxEntries` limits
+- Use `excludePatterns=["node_modules", ".git", "dist"]`
+- Preview with `head=50` before full reads
+
+**Don't:**
+
+- Loop `read_file` — batch with `read_multiple_files`
+- Recursive search without `maxDepth`
+- Search without `maxResults` on large codebases
+
+## Tool Details
+
+### `directory_tree`
+
+JSON tree structure for AI parsing.
+
+| Parameter         | Default | Description           |
+| ----------------- | ------- | --------------------- |
+| `path`            | —       | Directory path        |
+| `maxDepth`        | 5       | Depth limit (0-50)    |
+| `excludePatterns` | []      | Glob patterns to skip |
+| `includeHidden`   | false   | Include dotfiles      |
+| `includeSize`     | false   | Show file sizes       |
+| `maxFiles`        | —       | Limit total files     |
+
+### `search_files`
+
+Find files by glob pattern.
+
+| Parameter         | Default | Description               |
+| ----------------- | ------- | ------------------------- |
+| `path`            | —       | Base directory            |
+| `pattern`         | —       | Glob: `**/*.ts`, `src/**` |
+| `excludePatterns` | []      | Patterns to skip          |
+| `maxResults`      | —       | Limit (up to 10,000)      |
+| `sortBy`          | "path"  | `name/size/modified/path` |
+
+### `search_content`
+
+Grep-like regex search in files.
+
+| Parameter       | Default | Description               |
+| --------------- | ------- | ------------------------- |
+| `path`          | —       | Base directory            |
+| `pattern`       | —       | Regex: `TODO\|FIXME`      |
+| `filePattern`   | `**/*`  | Glob filter               |
+| `contextLines`  | 0       | Lines before/after (0-10) |
+| `caseSensitive` | false   | Case matching             |
+| `wholeWord`     | false   | Word boundaries           |
+| `isLiteral`     | false   | Escape regex              |
+| `maxResults`    | 100     | Limit matches             |
+| `skipBinary`    | true    | Skip binary files         |
+
+### `read_file`
+
+Read single file with line selection.
+
+| Parameter   | Default | Description                     |
+| ----------- | ------- | ------------------------------- |
+| `path`      | —       | File path                       |
+| `encoding`  | utf-8   | `utf-8/ascii/base64/hex/latin1` |
+| `maxSize`   | 10MB    | Size limit                      |
+| `head`      | —       | First N lines                   |
+| `tail`      | —       | Last N lines                    |
+| `lineStart` | —       | Start line (1-indexed)          |
+| `lineEnd`   | —       | End line (inclusive)            |
+
+> ⚠️ Cannot combine `head/tail` with `lineStart/lineEnd`
+
+### `read_multiple_files`
+
+Parallel batch reads — failures don't block others.
+
+| Parameter  | Default | Description        |
+| ---------- | ------- | ------------------ |
+| `paths`    | —       | Array (max 100)    |
+| `encoding` | utf-8   | Encoding for all   |
+| `maxSize`  | 10MB    | Per-file limit     |
+| `head`     | —       | First N lines each |
+| `tail`     | —       | Last N lines each  |
+
+### `list_directory`
+
+Flat listing with metadata.
+
+| Parameter    | Default | Description               |
+| ------------ | ------- | ------------------------- |
+| `path`       | —       | Directory path            |
+| `recursive`  | false   | Include subdirs           |
+| `sortBy`     | "name"  | `name/size/modified/type` |
+| `maxDepth`   | 10      | Depth when recursive      |
+| `maxEntries` | —       | Limit (up to 100,000)     |
+
+### `analyze_directory`
+
+Statistics: counts, sizes, types, largest/recent files.
+
+| Parameter         | Default | Description        |
+| ----------------- | ------- | ------------------ |
+| `path`            | —       | Directory path     |
+| `maxDepth`        | 10      | Analysis depth     |
+| `topN`            | 10      | Top largest/recent |
+| `excludePatterns` | []      | Patterns to skip   |
+
+### `read_media_file`
+
+Binary files as base64 with MIME type and dimensions.
+
+| Parameter | Default | Description     |
+| --------- | ------- | --------------- |
+| `path`    | —       | Media file path |
+| `maxSize` | 50MB    | Size limit      |
+
+### `get_file_info`
+
+Detailed metadata about a file or directory.
+
+| Parameter | Default | Description               |
+| --------- | ------- | ------------------------- |
+| `path`    | —       | Path to file or directory |
+
+**Returns:** name, path, type, size, created, modified, accessed, permissions, isHidden, mimeType, symlinkTarget (if applicable).
+
+---
+
+## Error Codes
+
+| Code                  | Cause                        | Solution                              |
+| --------------------- | ---------------------------- | ------------------------------------- |
+| `E_ACCESS_DENIED`     | Path outside allowed dirs    | Check `list_allowed_directories`      |
+| `E_NOT_FOUND`         | Path doesn't exist           | Verify path with `list_directory`     |
+| `E_NOT_FILE`          | Expected file, got directory | Use `list_directory` instead          |
+| `E_NOT_DIRECTORY`     | Expected directory, got file | Use `read_file` instead               |
+| `E_TOO_LARGE`         | File exceeds size limit      | Use `head/tail` or increase `maxSize` |
+| `E_BINARY_FILE`       | Binary in text operation     | Use `read_media_file`                 |
+| `E_TIMEOUT`           | Operation took too long      | Reduce limits                         |
+| `E_INVALID_PATTERN`   | Malformed glob/regex         | Check glob/regex syntax               |
+| `E_PERMISSION_DENIED` | OS-level access denied       | Check file permissions                |
+
+---
+
+## Security
+
+- **Read-only** — no writes, deletes, or modifications
+- **Path validation** — symlinks cannot escape allowed directories
+- **Binary detection** — prevents accidental base64 bloat
+- **Input sanitization** — patterns validated for ReDoS protection

package/dist/lib/directory-helpers.d.ts

@@ -0,0 +1,5 @@
+export declare function createExcludeMatcher(excludePatterns: string[]): (name: string, relativePath: string) => boolean;
+export declare function handleDirectoryError(error: unknown): void;
+export declare function classifyAccessError(error: unknown): 'symlink' | 'inaccessible';
+export declare function insertSorted<T>(arr: T[], item: T, compare: (a: T, b: T) => boolean, maxLen: number): void;
+//# sourceMappingURL=directory-helpers.d.ts.map

package/dist/lib/directory-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/directory-helpers.ts"],"names":[],"mappings":"AAKA,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,EAAE,GACxB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAOjD;AAGD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEzD;AAGD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,SAAS,GAAG,cAAc,CAS5B;AAGD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,CAAC,EAAE,EACR,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,EAChC,MAAM,EAAE,MAAM,GACb,IAAI,CASN"}

package/dist/lib/directory-helpers.js

@@ -0,0 +1,39 @@
+import { Minimatch } from 'minimatch';
+import { ErrorCode, McpError } from './errors.js';
+// Create matcher from exclude patterns
+export function createExcludeMatcher(excludePatterns) {
+    if (excludePatterns.length === 0) {
+        return () => false;
+    }
+    const matchers = excludePatterns.map((pattern) => new Minimatch(pattern));
+    return (name, relativePath) => matchers.some((m) => m.match(name) || m.match(relativePath));
+}
+// Handle directory traversal errors (silently ignored to avoid log noise)
+export function handleDirectoryError(error) {
+    void error.code;
+}
+// Classify symlink/access errors for summary tracking
+export function classifyAccessError(error) {
+    if (error instanceof McpError &&
+        (error.code === ErrorCode.E_ACCESS_DENIED ||
+            error.code === ErrorCode.E_SYMLINK_NOT_ALLOWED)) {
+        return 'symlink';
+    }
+    return 'inaccessible';
+}
+// Insert item into sorted array maintaining sort order (descending by comparator)
+export function insertSorted(arr, item, compare, maxLen) {
+    if (maxLen <= 0)
+        return;
+    const idx = arr.findIndex((el) => compare(item, el));
+    if (idx === -1) {
+        if (arr.length < maxLen)
+            arr.push(item);
+    }
+    else {
+        arr.splice(idx, 0, item);
+        if (arr.length > maxLen)
+            arr.pop();
+    }
+}
+//# sourceMappingURL=directory-helpers.js.map

package/dist/lib/directory-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-helpers.js","sourceRoot":"","sources":["../../src/lib/directory-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAElD,uCAAuC;AACvC,MAAM,UAAU,oBAAoB,CAClC,eAAyB;IAEzB,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1E,OAAO,CAAC,IAAY,EAAE,YAAoB,EAAW,EAAE,CACrD,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,KAAM,KAA+B,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,mBAAmB,CACjC,KAAc;IAEd,IACE,KAAK,YAAY,QAAQ;QACzB,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,eAAe;YACvC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,qBAAqB,CAAC,EACjD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAC1B,GAAQ,EACR,IAAO,EACP,OAAgC,EAChC,MAAc;IAEd,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO;IACxB,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACrD,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,IAAI,GAAG,CAAC,MAAM,GAAG,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACzB,IAAI,GAAG,CAAC,MAAM,GAAG,MAAM;YAAE,GAAG,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/lib/file-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-operations.d.ts","sourceRoot":"","sources":["../../src/lib/file-operations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-operations.d.ts","sourceRoot":"","sources":["../../src/lib/file-operations.ts"],"names":[],"mappings":"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"}

package/dist/lib/file-operations.js

@@ -3,21 +3,14 @@ import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { createReadStream } from 'node:fs';
 import fg from 'fast-glob';
-import { Minimatch } from 'minimatch';
 import safeRegex from 'safe-regex2';
 import { DEFAULT_MAX_DEPTH, DEFAULT_MAX_RESULTS, DEFAULT_TOP_N, DIR_TRAVERSAL_CONCURRENCY, getMimeType, MAX_LINE_CONTENT_LENGTH, MAX_MEDIA_FILE_SIZE, MAX_SEARCHABLE_FILE_SIZE, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, REGEX_MATCH_TIMEOUT_MS, } from './constants.js';
+import { classifyAccessError, createExcludeMatcher, handleDirectoryError, insertSorted, } from './directory-helpers.js';
 import { ErrorCode, McpError } from './errors.js';
 import { getFileType, isHidden, isProbablyBinary, readFile, runWorkQueue, } from './fs-helpers.js';
 import { parseImageDimensions } from './image-parsing.js';
 import { validateExistingPath, validateExistingPathDetailed, } from './path-validation.js';
-// Create matcher from exclude patterns
-function createExcludeMatcher(excludePatterns) {
-    if (excludePatterns.length === 0) {
-        return () => false;
-    }
-    const matchers = excludePatterns.map((pattern) => new Minimatch(pattern));
-    return (name, relativePath) => matchers.some((m) => m.match(name) || m.match(relativePath));
-}
+import { createSearchResultSorter, createSorter } from './sorting.js';
 // Process items in parallel with controlled concurrency
 async function processInParallel(items, processor, concurrency = PARALLEL_CONCURRENCY) {
     const results = [];
@@ -64,12 +57,10 @@ function countRegexMatches(line, regex, timeoutMs = REGEX_MATCH_TIMEOUT_MS) {
         }
         // Check timeout periodically
         if (count % 100 === 0 && Date.now() > deadline) {
-            console.error(`[countRegexMatches] Regex matching timed out after ${timeoutMs}ms on line (length: ${line.length})`);
             return -1; // Signal timeout
         }
         // Safety check for runaway regex
         if (iterations > maxIterations) {
-            console.error(`[countRegexMatches] Max iterations exceeded (${maxIterations}) on line (length: ${line.length})`);
             return -1; // Signal runaway regex
         }
     }
@@ -181,10 +172,7 @@ export async function listDirectory(dirPath, options = {}) {
         }
         catch (error) {
             skippedInaccessible++;
-            const { code } = error;
-            if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM') {
-                console.error(`[listDirectory] Error reading directory ${currentPath}:`, error);
-            }
+            handleDirectoryError(error);
             return;
         }
         const visibleItems = includeHidden
@@ -268,22 +256,7 @@ export async function listDirectory(dirPath, options = {}) {
                 enqueue(enqueueDir);
         }
     }, DIR_TRAVERSAL_CONCURRENCY);
-    entries.sort((a, b) => {
-        switch (sortBy) {
-            case 'size':
-                return (b.size ?? 0) - (a.size ?? 0);
-            case 'modified':
-                return (b.modified?.getTime() ?? 0) - (a.modified?.getTime() ?? 0);
-            case 'type':
-                if (a.type !== b.type) {
-                    return a.type === 'directory' ? -1 : 1;
-                }
-                return a.name.localeCompare(b.name);
-            case 'name':
-            default:
-                return a.name.localeCompare(b.name);
-        }
-    });
+    entries.sort(createSorter(sortBy));
     return {
         path: validPath,
         entries,
@@ -359,19 +332,7 @@ export async function searchFiles(basePath, pattern, excludePatterns = [], optio
         }
     }
     await flushBatch();
-    results.sort((a, b) => {
-        switch (sortBy) {
-            case 'size':
-                return (b.size ?? 0) - (a.size ?? 0);
-            case 'modified':
-                return (b.modified?.getTime() ?? 0) - (a.modified?.getTime() ?? 0);
-            case 'name':
-                return path.basename(a.path).localeCompare(path.basename(b.path));
-            case 'path':
-            default:
-                return a.path.localeCompare(b.path);
-        }
-    });
+    results.sort(createSearchResultSorter(sortBy));
     return {
         basePath: validPath,
         pattern,
@@ -427,11 +388,7 @@ export async function searchContent(basePath, searchPattern, options = {}) {
     const needsReDoSCheck = !isLiteral && !isSimpleSafePattern(finalPattern);
     if (needsReDoSCheck && !safeRegex(finalPattern)) {
         throw new McpError(ErrorCode.E_INVALID_PATTERN, `Potentially unsafe regular expression (ReDoS risk): ${searchPattern}. ` +
-            'Avoid patterns with nested quantifiers, overlapping alternations, or exponential backtracking.', basePath, {
-            searchPattern,
-            finalPattern,
-            reason: 'ReDoS risk detected by safe-regex2',
-        });
+            'Avoid patterns with nested quantifiers, overlapping alternations, or exponential backtracking.', basePath, { reason: 'ReDoS risk detected' });
     }
     let regex;
     try {
@@ -568,7 +525,6 @@ export async function searchContent(basePath, searchPattern, options = {}) {
                     const matchCount = countRegexMatches(line, regex);
                     if (matchCount < 0) {
                         linesSkippedDueToRegexTimeout++;
-                        console.error(`[searchContent] Skipping line ${lineNumber} in ${validFile} due to regex timeout`);
                         if (lineBuffer) {
                             lineBuffer.push(trimmedLine);
                         }
@@ -646,20 +602,6 @@ export async function analyzeDirectory(dirPath, options = {}) {
     const largestFiles = [];
     const recentlyModified = [];
     const shouldExclude = createExcludeMatcher(excludePatterns);
-    const insertSorted = (arr, item, compare, maxLen) => {
-        if (maxLen <= 0)
-            return;
-        const idx = arr.findIndex((el) => compare(item, el));
-        if (idx === -1) {
-            if (arr.length < maxLen)
-                arr.push(item);
-        }
-        else {
-            arr.splice(idx, 0, item);
-            if (arr.length > maxLen)
-                arr.pop();
-        }
-    };
     await runWorkQueue([{ currentPath: validPath, depth: 0 }], async ({ currentPath, depth }, enqueue) => {
         if (depth > maxDepth)
             return;
@@ -670,10 +612,7 @@ export async function analyzeDirectory(dirPath, options = {}) {
         }
         catch (error) {
             skippedInaccessible++;
-            const { code } = error;
-            if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM') {
-                console.error(`[analyzeDirectory] Error reading directory ${currentPath}:`, error);
-            }
+            handleDirectoryError(error);
             return;
         }
         for (const item of items) {
@@ -711,9 +650,7 @@ export async function analyzeDirectory(dirPath, options = {}) {
                 }
             }
             catch (error) {
-                if (error instanceof McpError &&
-                    (error.code === ErrorCode.E_ACCESS_DENIED ||
-                        error.code === ErrorCode.E_SYMLINK_NOT_ALLOWED)) {
+                if (classifyAccessError(error) === 'symlink') {
                     symlinksNotFollowed++;
                 }
                 else {
@@ -770,9 +707,7 @@ export async function getDirectoryTree(dirPath, options = {}) {
                 await validateExistingPathDetailed(currentPath));
         }
         catch (error) {
-            if (error instanceof McpError &&
-                (error.code === ErrorCode.E_ACCESS_DENIED ||
-                    error.code === ErrorCode.E_SYMLINK_NOT_ALLOWED)) {
+            if (classifyAccessError(error) === 'symlink') {
                 symlinksNotFollowed++;
             }
             else {