Skip to content

Commit 94b6fbb

Browse files
JessicaMuleinJessicaMulein
committed
Add mcp-filesystem
1 parent e14985d commit 94b6fbb

File tree

3 files changed

+774
-0
lines changed

3 files changed

+774
-0
lines changed

‎servers/mcp-filesystem/readme.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# MCP Filesystem Server
2+
3+
Advanced filesystem operations for AI agents with strict security boundaries.
4+
5+
## Overview
6+
7+
The MCP Filesystem Server provides AI agents with advanced file operations beyond basic read/write, including batch operations, directory watching, file search/indexing, and permission management, all within strict security boundaries.
8+
9+
## Features
10+
11+
### Core Capabilities
12+
13+
- **Batch Operations**: Execute multiple file operations (copy, move, delete) atomically with automatic rollback on failure
14+
- **Directory Watching**: Monitor filesystem changes in real-time with event filtering and recursive watching
15+
- **File Search & Indexing**: Fast full-text search with metadata filtering using Lunr.js
16+
- **Checksum Operations**: Compute and verify file integrity using MD5, SHA-1, SHA-256, or SHA-512
17+
- **Symlink Management**: Create and manage symbolic links within workspace boundaries
18+
- **Disk Usage Analysis**: Analyze directory sizes, identify large files, and get file type breakdowns
19+
- **Directory Operations**: Recursive copy, sync (only newer/missing files), and atomic file replacement
20+
21+
### Security Features
22+
23+
The server implements defense-in-depth security with 10 layers of path validation:
24+
25+
1. **Absolute Path Resolution**: Prevents relative path tricks
26+
2. **Workspace Boundary Check**: Ensures path is within workspace
27+
3. **Path Traversal Detection**: Blocks `..` and `./` sequences
28+
4. **System Path Blocklist**: Hardcoded system directories (cannot be overridden)
29+
5. **Sensitive Pattern Blocklist**: Hardcoded sensitive files (cannot be overridden)
30+
6. **Subdirectory Restrictions**: Optional allowlist within workspace
31+
7. **User Blocklist**: Custom blocked paths
32+
8. **User Pattern Blocklist**: Custom blocked patterns
33+
9. **Read-Only Mode**: Prevents write/delete operations
34+
10. **Symlink Validation**: Validates symlink targets are within workspace
35+
36+
### Hardcoded Security (Cannot Be Disabled)
37+
38+
**System Paths (Always Blocked):**
39+
40+
- `/etc`, `/sys`, `/proc`, `/dev`, `/boot`, `/root`
41+
- `C:\Windows`, `C:\Program Files`
42+
- `/System`, `/Library`, `/Applications` (macOS)
43+
- `/bin`, `/sbin`, `/usr/bin`, `/usr/sbin`
44+
45+
**Sensitive Patterns (Always Blocked):**
46+
47+
- `.ssh/`, `.aws/`, `.kube/`
48+
- `id_rsa`, `*.pem`, `*.key`, `*.p12`, `*.pfx`
49+
- Files containing: `password`, `secret`, `token`
50+
- `.env` files
51+
52+
## Installation
53+
54+
### NPM
55+
56+
```bash
57+
npm install -g @ai-capabilities-suite/mcp-filesystem
58+
```
59+
60+
### Docker
61+
62+
```bash
63+
docker pull digitaldefiance/mcp-filesystem:latest
64+
```
65+
66+
## Configuration
67+
68+
### Required Configuration
69+
70+
Create a configuration file (e.g., `mcp-filesystem-config.json`):
71+
72+
```json
73+
{
74+
"workspaceRoot": "/path/to/your/workspace",
75+
"blockedPaths": [".git", ".env", "node_modules"],
76+
"blockedPatterns": ["*.key", "*.pem", "*.env"],
77+
"maxFileSize": 104857600,
78+
"maxBatchSize": 1073741824,
79+
"maxOperationsPerMinute": 100,
80+
"enableAuditLog": true,
81+
"readOnly": false
82+
}
83+
```
84+
85+
### MCP Client Configuration
86+
87+
Add to your MCP client configuration:
88+
89+
```json
90+
{
91+
"mcpServers": {
92+
"filesystem": {
93+
"command": "mcp-filesystem",
94+
"args": ["--config", "/path/to/mcp-filesystem-config.json"]
95+
}
96+
}
97+
}
98+
```
99+
100+
## Available Tools
101+
102+
The server exposes 12 MCP tools:
103+
104+
1. **fs_batch_operations** - Execute multiple operations atomically
105+
2. **fs_watch_directory** - Monitor directory for changes
106+
3. **fs_get_watch_events** - Retrieve accumulated events
107+
4. **fs_stop_watch** - Stop watch session
108+
5. **fs_search_files** - Search by name, content, or metadata
109+
6. **fs_build_index** - Build searchable file index
110+
7. **fs_create_symlink** - Create symbolic link
111+
8. **fs_compute_checksum** - Compute file checksum
112+
9. **fs_verify_checksum** - Verify file integrity
113+
10. **fs_analyze_disk_usage** - Analyze disk usage
114+
11. **fs_copy_directory** - Recursively copy directory
115+
12. **fs_sync_directory** - Sync directories (only newer/missing)
116+
117+
## Usage Examples
118+
119+
### Batch File Operations
120+
121+
```typescript
122+
{
123+
"operations": [
124+
{ "type": "copy", "source": "file1.txt", "destination": "backup/file1.txt" },
125+
{ "type": "move", "source": "temp.txt", "destination": "archive/temp.txt" },
126+
{ "type": "delete", "source": "old.txt" }
127+
],
128+
"atomic": true
129+
}
130+
```
131+
132+
### Watch Directory
133+
134+
```typescript
135+
{
136+
"path": "src",
137+
"recursive": true,
138+
"filters": ["*.ts", "*.js"]
139+
}
140+
```
141+
142+
### Search Files
143+
144+
```typescript
145+
{
146+
"query": "TODO",
147+
"searchType": "content",
148+
"fileTypes": [".ts", ".js"],
149+
"useIndex": true
150+
}
151+
```
152+
153+
### Verify File Integrity
154+
155+
```typescript
156+
{
157+
"path": "important-file.zip",
158+
"checksum": "abc123...",
159+
"algorithm": "sha256"
160+
}
161+
```
162+
163+
## Security Warnings
164+
165+
⚠️ **CRITICAL SECURITY CONSIDERATIONS**
166+
167+
1. **Workspace Jail**: All operations are confined to the configured workspace root. This cannot be changed after server starts.
168+
169+
2. **System Paths**: The server blocks access to system directories. This is hardcoded and cannot be disabled.
170+
171+
3. **Sensitive Files**: The server blocks access to SSH keys, AWS credentials, and other sensitive files. This is hardcoded and cannot be disabled.
172+
173+
4. **Rate Limiting**: Configure appropriate rate limits to prevent abuse.
174+
175+
5. **Audit Logging**: Enable audit logging for security monitoring and forensics.
176+
177+
6. **Read-Only Mode**: Consider using read-only mode for untrusted agents.
178+
179+
## Documentation
180+
181+
- **Full Documentation**: [GitHub Repository](https://github.com/Digital-Defiance/ai-capabilities-suite/tree/main/packages/mcp-filesystem)
182+
- **Security Guide**: [SECURITY.md](https://github.com/Digital-Defiance/ai-capabilities-suite/blob/main/packages/mcp-filesystem/SECURITY.md)
183+
- **Docker Guide**: [DOCKER.md](https://github.com/Digital-Defiance/ai-capabilities-suite/blob/main/packages/mcp-filesystem/DOCKER.md)
184+
- **API Reference**: [README.md](https://github.com/Digital-Defiance/ai-capabilities-suite/blob/main/packages/mcp-filesystem/README.md)
185+
186+
## Support
187+
188+
- **Issues**: [GitHub Issues](https://github.com/Digital-Defiance/ai-capabilities-suite/issues)
189+
- **Email**: [email protected]
190+
191+
## License
192+
193+
MIT License - see [LICENSE](https://github.com/Digital-Defiance/ai-capabilities-suite/blob/main/packages/mcp-filesystem/LICENSE)
194+
195+
## Related Projects
196+
197+
- [MCP Debugger](https://github.com/Digital-Defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server) - Debug Node.js applications via MCP
198+
- [MCP Process](https://github.com/Digital-Defiance/ai-capabilities-suite/tree/main/packages/mcp-process) - Process management via MCP
199+
- [MCP Screenshot](https://github.com/Digital-Defiance/ai-capabilities-suite/tree/main/packages/mcp-screenshot) - Screenshot capture via MCP

‎servers/mcp-filesystem/server.yaml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
name: mcp-filesystem
2+
image: mcp/mcp-filesystem
3+
type: server
4+
meta:
5+
category: devops
6+
tags:
7+
- filesystem
8+
- file-operations
9+
- batch-operations
10+
- directory-watching
11+
- file-search
12+
- security
13+
- devops
14+
- ai-capabilities
15+
about:
16+
title: ACS Filesystem
17+
description: |
18+
Advanced filesystem operations for AI agents with strict security boundaries.
19+
20+
Features:
21+
- Batch Operations: Execute multiple file operations atomically with rollback
22+
- Directory Watching: Monitor filesystem changes in real-time with event filtering
23+
- File Search & Indexing: Fast full-text search with metadata filtering
24+
- Checksum Operations: Compute and verify file integrity (MD5, SHA-1, SHA-256, SHA-512)
25+
- Symlink Management: Create and manage symbolic links within workspace
26+
- Disk Usage Analysis: Analyze directory sizes and identify large files
27+
- Directory Operations: Recursive copy, sync, and atomic file replacement
28+
29+
Security Features:
30+
- 10-layer path validation
31+
- Workspace boundary enforcement
32+
- System path blocking (hardcoded, cannot be disabled)
33+
- Sensitive file pattern blocking (hardcoded, cannot be disabled)
34+
- Rate limiting
35+
- Audit logging
36+
37+
⚠️ SECURITY WARNING: This server provides powerful filesystem operations.
38+
Always configure strict security boundaries and review the SECURITY.md documentation.
39+
icon: https://www.google.com/s2/favicons?domain=digitaldefiance.org&sz=64
40+
source:
41+
project: https://github.com/Digital-Defiance/mcp-filesystem
42+
branch: main
43+
commit: 29e0fac10ce64449a70c8189b619afb7b443d0e0
44+
run:
45+
command:
46+
- "{{filesystem.workspaceRoot|volume-target|into}}"
47+
volumes:
48+
- "{{filesystem.workspaceRoot|volume|into}}"
49+
- "{{filesystem.configPath|volume|into}}"
50+
disableNetwork: true
51+
config:
52+
description: |
53+
Configure the MCP ACS Filesystem server with security boundaries and operational limits.
54+
55+
REQUIRED: workspaceRoot - All operations are confined to this directory
56+
57+
Security Configuration:
58+
- allowedSubdirectories: Further restrict operations to specific subdirectories
59+
- blockedPaths: Additional paths to block (relative to workspace)
60+
- blockedPatterns: Regex patterns to block
61+
62+
Resource Limits:
63+
- maxFileSize: Maximum file size in bytes (default: 100MB)
64+
- maxBatchSize: Maximum total size for batch operations (default: 1GB)
65+
- maxOperationsPerMinute: Rate limit per agent (default: 100)
66+
67+
Operational Settings:
68+
- enableAuditLog: Enable operation logging (default: true)
69+
- requireConfirmation: Require confirmation for destructive operations (default: true)
70+
- readOnly: Enable read-only mode (default: false)
71+
72+
See SECURITY.md for complete security documentation.
73+
parameters:
74+
type: object
75+
properties:
76+
workspaceRoot:
77+
type: string
78+
description: Absolute path to workspace directory (REQUIRED) - all operations confined to this directory
79+
default: /app/workspace
80+
configPath:
81+
type: string
82+
description: Path to configuration file
83+
default: /app/config/mcp-filesystem-config.json
84+
allowedSubdirectories:
85+
type: array
86+
items:
87+
type: string
88+
description: Optional subdirectories within workspace to restrict operations to
89+
default: []
90+
blockedPaths:
91+
type: array
92+
items:
93+
type: string
94+
description: Additional paths to block (relative to workspace)
95+
default:
96+
- .git
97+
- .env
98+
- node_modules
99+
- .ssh
100+
blockedPatterns:
101+
type: array
102+
items:
103+
type: string
104+
description: Regex patterns to block
105+
default:
106+
- "*.key"
107+
- "*.pem"
108+
- "*.env"
109+
- "*secret*"
110+
- "*password*"
111+
maxFileSize:
112+
type: integer
113+
description: Maximum file size in bytes
114+
default: 104857600
115+
maxBatchSize:
116+
type: integer
117+
description: Maximum total size for batch operations in bytes
118+
default: 1073741824
119+
maxOperationsPerMinute:
120+
type: integer
121+
description: Rate limit per agent
122+
default: 100
123+
enableAuditLog:
124+
type: boolean
125+
description: Enable operation logging
126+
default: true
127+
requireConfirmation:
128+
type: boolean
129+
description: Require confirmation for destructive operations
130+
default: true
131+
readOnly:
132+
type: boolean
133+
description: Enable read-only mode
134+
default: false
135+
required:
136+
- workspaceRoot

0 commit comments

Comments
 (0)