Skip to content

Commit 316ac11

Browse files
claude[bot]olaservo
andcommitted
feat(filesystem): ignore dot directories by default to reduce token usage
- Add environment variable MCP_FILESYSTEM_INCLUDE_HIDDEN (default: false) - Filter dot-prefixed files/directories in list_directory, directory_tree, search_files - Reduces token usage from large directories like .git, .terraform, etc. - Enhances security by avoiding exposure of potentially sensitive hidden files - Includes comprehensive tests for the new filtering functionality - Update documentation to explain the new behavior and environment variable Fixes modelcontextprotocol#2219 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Ola Hungerford <[email protected]>
1 parent 82e5ecf commit 316ac11

4 files changed

Lines changed: 139 additions & 20 deletions

File tree

‎src/filesystem/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,20 @@ Node.js server implementing Model Context Protocol (MCP) for filesystem operatio
1515

1616
The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).
1717

18+
### Hidden Files and Directories
19+
20+
By default, the filesystem server **ignores dot-prefixed files and directories** (like `.git`, `.env`, `.terraform`, etc.) to:
21+
- Reduce token usage (especially from large directories like `.git`)
22+
- Enhance security by avoiding exposure of potentially sensitive hidden files
23+
- Follow the convention that dot-prefixed items are typically "hidden" for good reason
24+
25+
To include hidden files and directories, set the environment variable:
26+
```bash
27+
export MCP_FILESYSTEM_INCLUDE_HIDDEN=true
28+
```
29+
30+
This affects the following operations: `list_directory`, `list_directory_with_sizes`, `directory_tree`, and `search_files`.
31+
1832
### Method 1: Command-line Arguments
1933
Specify Allowed directories when starting the server:
2034
```bash

‎src/filesystem/__tests__/lib.test.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ import {
1818
searchFilesWithValidation,
1919
// File editing functions
2020
applyFileEdits,
21+
// Hidden files filtering functions
22+
shouldIncludeHidden,
23+
shouldFilterHiddenEntry,
2124
tailFile,
2225
headFile
2326
} from '../lib.js';
@@ -699,3 +702,84 @@ describe('Lib Functions', () => {
699702
});
700703
});
701704
});
705+
706+
describe('Hidden Files Filtering', () => {
707+
describe('shouldIncludeHidden', () => {
708+
const originalEnv = process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
709+
710+
afterEach(() => {
711+
// Restore original environment variable
712+
if (originalEnv === undefined) {
713+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
714+
} else {
715+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = originalEnv;
716+
}
717+
});
718+
719+
it('should return false by default (when env var not set)', () => {
720+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
721+
expect(shouldIncludeHidden()).toBe(false);
722+
});
723+
724+
it('should return false when env var is set to "false"', () => {
725+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = 'false';
726+
expect(shouldIncludeHidden()).toBe(false);
727+
});
728+
729+
it('should return true when env var is set to "true"', () => {
730+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = 'true';
731+
expect(shouldIncludeHidden()).toBe(true);
732+
});
733+
734+
it('should return false for any other value', () => {
735+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = 'yes';
736+
expect(shouldIncludeHidden()).toBe(false);
737+
});
738+
});
739+
740+
describe('shouldFilterHiddenEntry', () => {
741+
const originalEnv = process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
742+
743+
afterEach(() => {
744+
// Restore original environment variable
745+
if (originalEnv === undefined) {
746+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
747+
} else {
748+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = originalEnv;
749+
}
750+
});
751+
752+
it('should filter dot-prefixed names by default', () => {
753+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
754+
expect(shouldFilterHiddenEntry('.git')).toBe(true);
755+
expect(shouldFilterHiddenEntry('.env')).toBe(true);
756+
expect(shouldFilterHiddenEntry('.terraform')).toBe(true);
757+
expect(shouldFilterHiddenEntry('.vscode')).toBe(true);
758+
});
759+
760+
it('should not filter regular names by default', () => {
761+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
762+
expect(shouldFilterHiddenEntry('README.md')).toBe(false);
763+
expect(shouldFilterHiddenEntry('package.json')).toBe(false);
764+
expect(shouldFilterHiddenEntry('src')).toBe(false);
765+
expect(shouldFilterHiddenEntry('test.txt')).toBe(false);
766+
});
767+
768+
it('should not filter any names when hidden files are included', () => {
769+
process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN = 'true';
770+
expect(shouldFilterHiddenEntry('.git')).toBe(false);
771+
expect(shouldFilterHiddenEntry('.env')).toBe(false);
772+
expect(shouldFilterHiddenEntry('README.md')).toBe(false);
773+
expect(shouldFilterHiddenEntry('package.json')).toBe(false);
774+
});
775+
776+
it('should handle edge cases correctly', () => {
777+
delete process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN;
778+
expect(shouldFilterHiddenEntry('')).toBe(false); // empty string
779+
expect(shouldFilterHiddenEntry('.')).toBe(true); // single dot
780+
expect(shouldFilterHiddenEntry('..')).toBe(true); // double dot
781+
expect(shouldFilterHiddenEntry('name.')).toBe(false); // dot at end
782+
expect(shouldFilterHiddenEntry('name.with.dots')).toBe(false); // dots in middle
783+
});
784+
});
785+
});

‎src/filesystem/index.ts‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
tailFile,
3030
headFile,
3131
setAllowedDirectories,
32+
shouldFilterHiddenEntry,
3233
} from './lib.js';
3334

3435
// Command line argument parsing
@@ -449,6 +450,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
449450
const validPath = await validatePath(parsed.data.path);
450451
const entries = await fs.readdir(validPath, { withFileTypes: true });
451452
const formatted = entries
453+
.filter((entry) => !shouldFilterHiddenEntry(entry.name))
452454
.map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`)
453455
.join("\n");
454456
return {
@@ -464,27 +466,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
464466
const validPath = await validatePath(parsed.data.path);
465467
const entries = await fs.readdir(validPath, { withFileTypes: true });
466468

467-
// Get detailed information for each entry
469+
// Get detailed information for each entry (excluding hidden entries)
468470
const detailedEntries = await Promise.all(
469-
entries.map(async (entry) => {
470-
const entryPath = path.join(validPath, entry.name);
471-
try {
472-
const stats = await fs.stat(entryPath);
473-
return {
474-
name: entry.name,
475-
isDirectory: entry.isDirectory(),
476-
size: stats.size,
477-
mtime: stats.mtime
478-
};
479-
} catch (error) {
480-
return {
481-
name: entry.name,
482-
isDirectory: entry.isDirectory(),
483-
size: 0,
484-
mtime: new Date(0)
485-
};
486-
}
487-
})
471+
entries
472+
.filter((entry) => !shouldFilterHiddenEntry(entry.name))
473+
.map(async (entry) => {
474+
const entryPath = path.join(validPath, entry.name);
475+
try {
476+
const stats = await fs.stat(entryPath);
477+
return {
478+
name: entry.name,
479+
isDirectory: entry.isDirectory(),
480+
size: stats.size,
481+
mtime: stats.mtime
482+
};
483+
} catch (error) {
484+
return {
485+
name: entry.name,
486+
isDirectory: entry.isDirectory(),
487+
size: 0,
488+
mtime: new Date(0)
489+
};
490+
}
491+
})
488492
);
489493

490494
// Sort entries based on sortBy parameter
@@ -541,6 +545,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
541545
const result: TreeEntry[] = [];
542546

543547
for (const entry of entries) {
548+
// Skip hidden files/directories unless explicitly enabled
549+
if (shouldFilterHiddenEntry(entry.name)) continue;
550+
544551
const relativePath = path.relative(rootPath, path.join(currentPath, entry.name));
545552
const shouldExclude = excludePatterns.some(pattern => {
546553
if (pattern.includes('*')) {

‎src/filesystem/lib.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,17 @@ export interface SearchResult {
4040
isDirectory: boolean;
4141
}
4242

43+
// Check if hidden files/directories should be included
44+
// Environment variable MCP_FILESYSTEM_INCLUDE_HIDDEN controls this (default: false)
45+
export function shouldIncludeHidden(): boolean {
46+
return process.env.MCP_FILESYSTEM_INCLUDE_HIDDEN === 'true';
47+
}
48+
49+
// Check if a file/directory name should be filtered out (dot-prefixed items)
50+
export function shouldFilterHiddenEntry(name: string): boolean {
51+
return !shouldIncludeHidden() && name.startsWith('.');
52+
}
53+
4354
// Pure Utility Functions
4455
export function formatSize(bytes: number): string {
4556
const units = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -361,6 +372,9 @@ export async function searchFilesWithValidation(
361372
const entries = await fs.readdir(currentPath, { withFileTypes: true });
362373

363374
for (const entry of entries) {
375+
// Skip hidden files/directories unless explicitly enabled
376+
if (shouldFilterHiddenEntry(entry.name)) continue;
377+
364378
const fullPath = path.join(currentPath, entry.name);
365379

366380
try {

0 commit comments

Comments
 (0)