@j0hanz/filesystem-mcp 1.13.1 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -100
- package/dist/completions.d.ts +0 -11
- package/dist/completions.js +1 -1
- package/dist/config.d.ts +0 -1
- package/dist/lib/constants.d.ts +0 -1
- package/dist/lib/constants.js +0 -1
- package/dist/lib/errors.d.ts +0 -1
- package/dist/lib/errors.js +5 -9
- package/dist/lib/file-operations/core.d.ts +3 -2
- package/dist/lib/file-operations/metadata.js +9 -3
- package/dist/lib/file-operations/search.d.ts +1 -59
- package/dist/lib/file-operations/search.js +9 -22
- package/dist/lib/file-operations/traversal.d.ts +2 -2
- package/dist/lib/fs-helpers.d.ts +1 -2
- package/dist/lib/fs-helpers.js +10 -12
- package/dist/lib/globs.d.ts +2 -0
- package/dist/lib/globs.js +19 -0
- package/dist/lib/paths.d.ts +0 -3
- package/dist/lib/paths.js +1 -4
- package/dist/lib/utils.d.ts +4 -4
- package/dist/lib/utils.js +1 -10
- package/dist/lib/zod-codecs.d.ts +2 -0
- package/dist/lib/zod-codecs.js +18 -0
- package/dist/pkg-info.d.ts +1 -0
- package/dist/pkg-info.js +2 -2
- package/dist/prompts.js +3 -3
- package/dist/resources/generated-instructions.js +3 -12
- package/dist/resources/tool-catalog.js +10 -41
- package/dist/resources/tool-info.d.ts +0 -1
- package/dist/resources/tool-info.js +24 -39
- package/dist/resources/workflows.js +8 -1
- package/dist/schemas.d.ts +179 -481
- package/dist/schemas.js +156 -169
- package/dist/server/bootstrap.d.ts +0 -10
- package/dist/server/bootstrap.js +3 -3
- package/dist/server/roots-manager.js +1 -1
- package/dist/tools/apply-patch.js +19 -8
- package/dist/tools/calculate-hash.js +3 -5
- package/dist/tools/create-directory.d.ts +1 -4
- package/dist/tools/create-directory.js +2 -2
- package/dist/tools/delete-file.js +2 -4
- package/dist/tools/diff-files.js +1 -3
- package/dist/tools/edit-file.d.ts +1 -7
- package/dist/tools/edit-file.js +6 -3
- package/dist/tools/list-directory.js +10 -15
- package/dist/tools/move-file.d.ts +1 -4
- package/dist/tools/move-file.js +15 -27
- package/dist/tools/read-multiple.js +12 -7
- package/dist/tools/read.js +1 -2
- package/dist/tools/replace-in-files.d.ts +1 -10
- package/dist/tools/replace-in-files.js +62 -97
- package/dist/tools/roots.js +2 -6
- package/dist/tools/search-content.js +152 -188
- package/dist/tools/search-files.js +10 -13
- package/dist/tools/shared.d.ts +10 -3
- package/dist/tools/shared.js +53 -12
- package/dist/tools/stat-many.js +6 -4
- package/dist/tools/stat.js +2 -2
- package/dist/tools/task-support.d.ts +0 -7
- package/dist/tools/task-support.js +7 -6
- package/dist/tools/tree.js +1 -1
- package/dist/tools/write-file.js +1 -5
- package/dist/tools.d.ts +0 -1
- package/dist/tools.js +0 -1
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/%40j0hanz%2Ffilesystem-mcp) [](#contributing-and-license)
|
|
4
4
|
|
|
5
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem
|
|
5
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
|
|
6
6
|
|
|
7
|
-
[](https://lmstudio.ai/install-mcp?name=filesystem
|
|
7
|
+
[](https://lmstudio.ai/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
|
|
8
8
|
|
|
9
9
|
A local filesystem MCP server that lets LLMs and AI agents read, write, search, diff, patch, and manage files safely and efficiently. Built for reliable, structured, and controlled filesystem interaction.
|
|
10
10
|
|
|
@@ -12,7 +12,7 @@ A local filesystem MCP server that lets LLMs and AI agents read, write, search,
|
|
|
12
12
|
|
|
13
13
|
A secure, production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants controlled access to the local filesystem. All operations are sandboxed to explicitly allowed directories with path traversal prevention, sensitive file blocking, and optional Bearer token authentication.
|
|
14
14
|
|
|
15
|
-
Supports
|
|
15
|
+
Supports stdio (default) and Streamable HTTP transport with SSE support. HTTP sessions are implemented with isolated per-session server state.
|
|
16
16
|
|
|
17
17
|
## Key Features
|
|
18
18
|
|
|
@@ -20,7 +20,7 @@ Supports **stdio** (default) and **Streamable HTTP + SSE** transports with per-s
|
|
|
20
20
|
- **Security-first** — path validation, symlink escape prevention, sensitive file denylist, localhost-only CORS, optional API key auth
|
|
21
21
|
- **Dual transport** — stdio for local use, Streamable HTTP with SSE for networked/multi-session deployments
|
|
22
22
|
- **Structured output** — all tools return typed `outputSchema` / `structuredContent` for reliable LLM parsing
|
|
23
|
-
- **Self-documenting** — 6 built-in resources (`internal://instructions`, `internal://tool-catalog`, etc.) and
|
|
23
|
+
- **Self-documenting** — 6 built-in resources (`internal://instructions`, `internal://tool-catalog`, etc.) and 4 built-in prompts (`get-help`, `compare-files`, `analyze-path`, `get-tool-help`)
|
|
24
24
|
|
|
25
25
|
## Requirements
|
|
26
26
|
|
|
@@ -31,7 +31,7 @@ Supports **stdio** (default) and **Streamable HTTP + SSE** transports with per-s
|
|
|
31
31
|
```json
|
|
32
32
|
{
|
|
33
33
|
"mcpServers": {
|
|
34
|
-
"filesystem
|
|
34
|
+
"filesystem": {
|
|
35
35
|
"command": "npx",
|
|
36
36
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
37
37
|
}
|
|
@@ -82,14 +82,14 @@ Examples:
|
|
|
82
82
|
<details>
|
|
83
83
|
<summary><b>Install in VS Code</b></summary>
|
|
84
84
|
|
|
85
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem
|
|
85
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D)
|
|
86
86
|
|
|
87
87
|
Add to `.vscode/mcp.json`:
|
|
88
88
|
|
|
89
89
|
```json
|
|
90
90
|
{
|
|
91
91
|
"servers": {
|
|
92
|
-
"filesystem
|
|
92
|
+
"filesystem": {
|
|
93
93
|
"command": "npx",
|
|
94
94
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
95
95
|
}
|
|
@@ -100,7 +100,7 @@ Add to `.vscode/mcp.json`:
|
|
|
100
100
|
Or install via CLI:
|
|
101
101
|
|
|
102
102
|
```sh
|
|
103
|
-
code --add-mcp '{"name":"filesystem
|
|
103
|
+
code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
|
|
104
104
|
```
|
|
105
105
|
|
|
106
106
|
</details>
|
|
@@ -108,14 +108,14 @@ code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/f
|
|
|
108
108
|
<details>
|
|
109
109
|
<summary><b>Install in VS Code Insiders</b></summary>
|
|
110
110
|
|
|
111
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem
|
|
111
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders)
|
|
112
112
|
|
|
113
113
|
Add to `.vscode/mcp.json`:
|
|
114
114
|
|
|
115
115
|
```json
|
|
116
116
|
{
|
|
117
117
|
"servers": {
|
|
118
|
-
"filesystem
|
|
118
|
+
"filesystem": {
|
|
119
119
|
"command": "npx",
|
|
120
120
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
121
121
|
}
|
|
@@ -126,7 +126,7 @@ Add to `.vscode/mcp.json`:
|
|
|
126
126
|
Or install via CLI:
|
|
127
127
|
|
|
128
128
|
```sh
|
|
129
|
-
code-insiders --add-mcp '{"name":"filesystem
|
|
129
|
+
code-insiders --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
|
|
130
130
|
```
|
|
131
131
|
|
|
132
132
|
</details>
|
|
@@ -134,14 +134,14 @@ code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","
|
|
|
134
134
|
<details>
|
|
135
135
|
<summary><b>Install in Cursor</b></summary>
|
|
136
136
|
|
|
137
|
-
[](https://cursor.com/en/install-mcp?name=filesystem
|
|
137
|
+
[](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
|
|
138
138
|
|
|
139
139
|
Add to `~/.cursor/mcp.json`:
|
|
140
140
|
|
|
141
141
|
```json
|
|
142
142
|
{
|
|
143
143
|
"mcpServers": {
|
|
144
|
-
"filesystem
|
|
144
|
+
"filesystem": {
|
|
145
145
|
"command": "npx",
|
|
146
146
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
147
147
|
}
|
|
@@ -156,10 +156,12 @@ Add to `~/.cursor/mcp.json`:
|
|
|
156
156
|
|
|
157
157
|
[](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
|
|
158
158
|
|
|
159
|
+
Add to `<SOLUTIONDIR>.mcp.json` or `%USERPROFILE%\.mcp.json`:
|
|
160
|
+
|
|
159
161
|
```json
|
|
160
162
|
{
|
|
161
|
-
"
|
|
162
|
-
"filesystem
|
|
163
|
+
"servers": {
|
|
164
|
+
"filesystem": {
|
|
163
165
|
"command": "npx",
|
|
164
166
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
165
167
|
}
|
|
@@ -172,17 +174,20 @@ Add to `~/.cursor/mcp.json`:
|
|
|
172
174
|
<details>
|
|
173
175
|
<summary><b>Install in Goose</b></summary>
|
|
174
176
|
|
|
175
|
-
[](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem
|
|
177
|
+
[](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
|
|
176
178
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
179
|
+
Add to `~/.config/goose/config.yaml`:
|
|
180
|
+
|
|
181
|
+
```yaml
|
|
182
|
+
extensions:
|
|
183
|
+
filesystem:
|
|
184
|
+
name: Filesystem MCP
|
|
185
|
+
cmd: npx
|
|
186
|
+
args:
|
|
187
|
+
- -y
|
|
188
|
+
- '@j0hanz/filesystem-mcp@latest'
|
|
189
|
+
enabled: true
|
|
190
|
+
type: stdio
|
|
186
191
|
```
|
|
187
192
|
|
|
188
193
|
</details>
|
|
@@ -190,12 +195,12 @@ Add to `~/.cursor/mcp.json`:
|
|
|
190
195
|
<details>
|
|
191
196
|
<summary><b>Add to LM Studio</b></summary>
|
|
192
197
|
|
|
193
|
-
[](https://lmstudio.ai/install-mcp?name=filesystem
|
|
198
|
+
[](https://lmstudio.ai/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
|
|
194
199
|
|
|
195
200
|
```json
|
|
196
201
|
{
|
|
197
202
|
"mcpServers": {
|
|
198
|
-
"filesystem
|
|
203
|
+
"filesystem": {
|
|
199
204
|
"command": "npx",
|
|
200
205
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
201
206
|
}
|
|
@@ -213,7 +218,7 @@ Add to `claude_desktop_config.json`:
|
|
|
213
218
|
```json
|
|
214
219
|
{
|
|
215
220
|
"mcpServers": {
|
|
216
|
-
"filesystem
|
|
221
|
+
"filesystem": {
|
|
217
222
|
"command": "npx",
|
|
218
223
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
219
224
|
}
|
|
@@ -230,12 +235,12 @@ Add to `claude_desktop_config.json`:
|
|
|
230
235
|
claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
|
|
231
236
|
```
|
|
232
237
|
|
|
233
|
-
Or add
|
|
238
|
+
Or add a project-scoped `.mcp.json`:
|
|
234
239
|
|
|
235
240
|
```json
|
|
236
241
|
{
|
|
237
242
|
"mcpServers": {
|
|
238
|
-
"filesystem
|
|
243
|
+
"filesystem": {
|
|
239
244
|
"command": "npx",
|
|
240
245
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
241
246
|
}
|
|
@@ -253,7 +258,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
|
253
258
|
```json
|
|
254
259
|
{
|
|
255
260
|
"mcpServers": {
|
|
256
|
-
"filesystem
|
|
261
|
+
"filesystem": {
|
|
257
262
|
"command": "npx",
|
|
258
263
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
259
264
|
}
|
|
@@ -270,12 +275,12 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
|
270
275
|
amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
|
|
271
276
|
```
|
|
272
277
|
|
|
273
|
-
Or add to
|
|
278
|
+
Or add to `settings.json`:
|
|
274
279
|
|
|
275
280
|
```json
|
|
276
281
|
{
|
|
277
|
-
"mcpServers": {
|
|
278
|
-
"filesystem
|
|
282
|
+
"amp.mcpServers": {
|
|
283
|
+
"filesystem": {
|
|
279
284
|
"command": "npx",
|
|
280
285
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
281
286
|
}
|
|
@@ -293,7 +298,7 @@ Add to `cline_mcp_settings.json`:
|
|
|
293
298
|
```json
|
|
294
299
|
{
|
|
295
300
|
"mcpServers": {
|
|
296
|
-
"filesystem
|
|
301
|
+
"filesystem": {
|
|
297
302
|
"command": "npx",
|
|
298
303
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
299
304
|
}
|
|
@@ -304,32 +309,35 @@ Add to `cline_mcp_settings.json`:
|
|
|
304
309
|
</details>
|
|
305
310
|
|
|
306
311
|
<details>
|
|
307
|
-
<summary><b>Install in Codex
|
|
312
|
+
<summary><b>Install in Codex</b></summary>
|
|
308
313
|
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
314
|
+
```sh
|
|
315
|
+
codex mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Or add to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
|
|
319
|
+
|
|
320
|
+
```toml
|
|
321
|
+
[mcp_servers.filesystem]
|
|
322
|
+
command = "npx"
|
|
323
|
+
args = ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
318
324
|
```
|
|
319
325
|
|
|
320
326
|
</details>
|
|
321
327
|
|
|
322
328
|
<details>
|
|
323
|
-
<summary><b>Install in GitHub Copilot</b></summary>
|
|
329
|
+
<summary><b>Install in GitHub Copilot Coding Agent</b></summary>
|
|
324
330
|
|
|
325
|
-
Add
|
|
331
|
+
Add this JSON in your repository's GitHub Copilot coding agent MCP configuration:
|
|
326
332
|
|
|
327
333
|
```json
|
|
328
334
|
{
|
|
329
|
-
"
|
|
330
|
-
"filesystem
|
|
335
|
+
"mcpServers": {
|
|
336
|
+
"filesystem": {
|
|
337
|
+
"type": "local",
|
|
331
338
|
"command": "npx",
|
|
332
|
-
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
339
|
+
"args": ["-y", "@j0hanz/filesystem-mcp@latest"],
|
|
340
|
+
"tools": ["*"]
|
|
333
341
|
}
|
|
334
342
|
}
|
|
335
343
|
}
|
|
@@ -343,7 +351,7 @@ Add to `.vscode/mcp.json`:
|
|
|
343
351
|
```json
|
|
344
352
|
{
|
|
345
353
|
"mcpServers": {
|
|
346
|
-
"filesystem
|
|
354
|
+
"filesystem": {
|
|
347
355
|
"command": "npx",
|
|
348
356
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
349
357
|
}
|
|
@@ -361,7 +369,7 @@ Add to `.kiro/settings/mcp.json`:
|
|
|
361
369
|
```json
|
|
362
370
|
{
|
|
363
371
|
"mcpServers": {
|
|
364
|
-
"filesystem
|
|
372
|
+
"filesystem": {
|
|
365
373
|
"command": "npx",
|
|
366
374
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
367
375
|
}
|
|
@@ -379,7 +387,7 @@ Add to `~/.gemini/settings.json`:
|
|
|
379
387
|
```json
|
|
380
388
|
{
|
|
381
389
|
"mcpServers": {
|
|
382
|
-
"filesystem
|
|
390
|
+
"filesystem": {
|
|
383
391
|
"command": "npx",
|
|
384
392
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
385
393
|
}
|
|
@@ -397,11 +405,10 @@ Add to `~/.config/zed/settings.json`:
|
|
|
397
405
|
```json
|
|
398
406
|
{
|
|
399
407
|
"context_servers": {
|
|
400
|
-
"filesystem
|
|
401
|
-
"
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
}
|
|
408
|
+
"filesystem": {
|
|
409
|
+
"command": "npx",
|
|
410
|
+
"args": ["-y", "@j0hanz/filesystem-mcp@latest"],
|
|
411
|
+
"env": {}
|
|
405
412
|
}
|
|
406
413
|
}
|
|
407
414
|
}
|
|
@@ -419,7 +426,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
|
|
|
419
426
|
"augment.advanced": {
|
|
420
427
|
"mcpServers": [
|
|
421
428
|
{
|
|
422
|
-
"id": "filesystem
|
|
429
|
+
"id": "filesystem",
|
|
423
430
|
"command": "npx",
|
|
424
431
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
425
432
|
}
|
|
@@ -436,7 +443,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
|
|
|
436
443
|
```json
|
|
437
444
|
{
|
|
438
445
|
"mcpServers": {
|
|
439
|
-
"filesystem
|
|
446
|
+
"filesystem": {
|
|
440
447
|
"command": "npx",
|
|
441
448
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
442
449
|
}
|
|
@@ -452,7 +459,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
|
|
|
452
459
|
```json
|
|
453
460
|
{
|
|
454
461
|
"mcpServers": {
|
|
455
|
-
"filesystem
|
|
462
|
+
"filesystem": {
|
|
456
463
|
"command": "npx",
|
|
457
464
|
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
|
|
458
465
|
}
|
|
@@ -536,6 +543,9 @@ Create directories, move/rename files, delete files, and verify file integrity v
|
|
|
536
543
|
|
|
|
537
544
|
+-- prompts/get ─────────────────────────────────────────
|
|
538
545
|
| +-- get-help (optional topic argument)
|
|
546
|
+
| +-- compare-files (original, modified)
|
|
547
|
+
| +-- analyze-path (path)
|
|
548
|
+
| +-- get-tool-help (name)
|
|
539
549
|
|
|
|
540
550
|
+-- Capabilities: logging, resources, tools, prompts, completions, tasks
|
|
541
551
|
```
|
|
@@ -602,26 +612,29 @@ Find files by glob pattern. Returns matching files with metadata.
|
|
|
602
612
|
|
|
603
613
|
Render a directory tree with bounded recursion. Returns ASCII tree + structured JSON.
|
|
604
614
|
|
|
605
|
-
| Parameter | Type | Required | Description
|
|
606
|
-
| ---------------- | ------- | -------- |
|
|
607
|
-
| `path` | string | no | Base directory (default: root)
|
|
608
|
-
| `maxDepth` | integer | no | Depth (0 = root node only). Default: 10, Max: 100
|
|
609
|
-
| `maxEntries` | integer | no | Max entries. Default: 5000, Max: 100000
|
|
610
|
-
| `includeHidden` | boolean | no | Include dotfiles. Default: `false`
|
|
611
|
-
| `includeIgnored` | boolean | no | Include ignored items. Default: `false`
|
|
615
|
+
| Parameter | Type | Required | Description |
|
|
616
|
+
| ---------------- | ------- | -------- | ---------------------------------------------------- |
|
|
617
|
+
| `path` | string | no | Base directory (default: root) |
|
|
618
|
+
| `maxDepth` | integer | no | Depth (0 = root node only). Default: 10, Max: 100 |
|
|
619
|
+
| `maxEntries` | integer | no | Max entries. Default: 5000, Max: 100000 |
|
|
620
|
+
| `includeHidden` | boolean | no | Include dotfiles. Default: `false` |
|
|
621
|
+
| `includeIgnored` | boolean | no | Include ignored items. Default: `false` |
|
|
622
|
+
| `includeSizes` | boolean | no | Include file sizes in tree entries. Default: `false` |
|
|
612
623
|
|
|
613
624
|
---
|
|
614
625
|
|
|
615
626
|
#### `read`
|
|
616
627
|
|
|
617
|
-
Read text file contents. Use `head` to preview first N lines of large files.
|
|
628
|
+
Read text file contents. Use `head`/`tail` to preview first/last N lines of large files.
|
|
618
629
|
|
|
619
|
-
| Parameter
|
|
620
|
-
|
|
|
621
|
-
| `path`
|
|
622
|
-
| `head`
|
|
623
|
-
| `
|
|
624
|
-
| `
|
|
630
|
+
| Parameter | Type | Required | Description |
|
|
631
|
+
| ------------- | ------- | -------- | ----------------------------------------------------------- |
|
|
632
|
+
| `path` | string | **yes** | Absolute path to file |
|
|
633
|
+
| `head` | integer | no | Read first N lines (1-100000) |
|
|
634
|
+
| `tail` | integer | no | Read last N lines (1-100000) |
|
|
635
|
+
| `startLine` | integer | no | Start line (1-based, inclusive) |
|
|
636
|
+
| `endLine` | integer | no | End line (1-based, inclusive). Requires `startLine` |
|
|
637
|
+
| `includeHash` | boolean | no | Include SHA-256 hash of full file content. Default: `false` |
|
|
625
638
|
|
|
626
639
|
---
|
|
627
640
|
|
|
@@ -633,6 +646,7 @@ Read multiple text files in one request.
|
|
|
633
646
|
| ----------- | -------- | -------- | ------------------------------- |
|
|
634
647
|
| `paths` | string[] | **yes** | Files to read (1-100 paths) |
|
|
635
648
|
| `head` | integer | no | Read first N lines of each file |
|
|
649
|
+
| `tail` | integer | no | Read last N lines of each file |
|
|
636
650
|
| `startLine` | integer | no | Start line (1-based) per file |
|
|
637
651
|
| `endLine` | integer | no | End line (1-based) per file |
|
|
638
652
|
|
|
@@ -789,23 +803,28 @@ Bulk search-and-replace across files matching a glob. Replaces **all** occurrenc
|
|
|
789
803
|
| `includeHidden` | boolean | no | Include dotfiles. Default: `false` |
|
|
790
804
|
| `includeIgnored` | boolean | no | Include ignored items. Default: `false` |
|
|
791
805
|
| `returnDiff` | boolean | no | Return diff even when not dry-run. Default: `false` |
|
|
806
|
+
| `maxFiles` | integer | no | Max files to process before stopping (1-10000) |
|
|
807
|
+
| `caseSensitive` | boolean | no | Case-sensitive matching. Default: `true` |
|
|
792
808
|
|
|
793
809
|
### Resources
|
|
794
810
|
|
|
795
|
-
| Resource | URI | MIME Type
|
|
796
|
-
| ------------ | ------------------------------ |
|
|
797
|
-
| Instructions | `internal://instructions` | text/markdown
|
|
798
|
-
| Tool Catalog | `internal://tool-catalog` | text/markdown
|
|
799
|
-
| Workflows | `internal://workflows` | text/markdown
|
|
800
|
-
| Tool Info | `internal://tool-info/{name}` | text/markdown
|
|
801
|
-
| Result Cache | `filesystem-mcp://result/{id}` | text/
|
|
802
|
-
| Metrics | `filesystem-mcp://metrics` |
|
|
811
|
+
| Resource | URI | MIME Type | Description |
|
|
812
|
+
| ------------ | ------------------------------ | ---------------- | ------------------------------------------------------------------ |
|
|
813
|
+
| Instructions | `internal://instructions` | text/markdown | Comprehensive usage rules and guidelines |
|
|
814
|
+
| Tool Catalog | `internal://tool-catalog` | text/markdown | Tool selection guide and data flow map |
|
|
815
|
+
| Workflows | `internal://workflows` | text/markdown | Standard operating procedures for exploration, search, edit, patch |
|
|
816
|
+
| Tool Info | `internal://tool-info/{name}` | text/markdown | Per-tool contract details, nuances, gotchas |
|
|
817
|
+
| Result Cache | `filesystem-mcp://result/{id}` | text/plain | Ephemeral cached tool output (large results externalized here) |
|
|
818
|
+
| Metrics | `filesystem-mcp://metrics` | application/json | Live per-tool call/error/avgDurationMs snapshot |
|
|
803
819
|
|
|
804
820
|
### Prompts
|
|
805
821
|
|
|
806
|
-
| Prompt
|
|
807
|
-
|
|
|
808
|
-
| `get-help`
|
|
822
|
+
| Prompt | Arguments | Description |
|
|
823
|
+
| --------------- | ---------------------- | ---------------------------------------------------------------------- |
|
|
824
|
+
| `get-help` | `topic` (optional) | Return usage instructions. Optionally filter by section heading prefix |
|
|
825
|
+
| `compare-files` | `original`, `modified` | Generate a workflow for comparing two files using `diff_files` |
|
|
826
|
+
| `analyze-path` | `path` | Generate a workflow for analyzing a file or directory |
|
|
827
|
+
| `get-tool-help` | `name` | Return a prompt with the authoritative contract for a specific tool |
|
|
809
828
|
|
|
810
829
|
## MCP Capabilities
|
|
811
830
|
|
|
@@ -814,8 +833,8 @@ Bulk search-and-replace across files matching a glob. Replaces **all** occurrenc
|
|
|
814
833
|
| `logging` | confirmed | `src/server/bootstrap.ts` — registered in capabilities |
|
|
815
834
|
| `resources` | confirmed | `src/server/bootstrap.ts` — 6 resources registered |
|
|
816
835
|
| `tools` | confirmed | `src/server/bootstrap.ts` — 18 tools registered |
|
|
817
|
-
| `prompts` | confirmed | `src/server/bootstrap.ts` —
|
|
818
|
-
| `completions` | confirmed | `src/completions.ts` — path
|
|
836
|
+
| `prompts` | confirmed | `src/server/bootstrap.ts` — 4 prompts registered |
|
|
837
|
+
| `completions` | confirmed | `src/completions.ts` — path, topic, and tool-name auto-completion |
|
|
819
838
|
| `tasks` | confirmed | `src/server/bootstrap.ts` — optional task support (list, cancel, requests) |
|
|
820
839
|
|
|
821
840
|
### Tool Annotations
|
|
@@ -881,18 +900,16 @@ When started with `--port <number>`, the server exposes a single MCP endpoint:
|
|
|
881
900
|
|
|
882
901
|
## Development
|
|
883
902
|
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
| `format` | `prettier --write .` | Format code |
|
|
895
|
-
| `inspector` | `npm run build && npx @modelcontextprotocol/inspector` | Launch MCP Inspector |
|
|
903
|
+
- `dev` — `tsc --watch --preserveWatchOutput` — Watch mode TypeScript compilation
|
|
904
|
+
- `dev:run` — `node --env-file=.env --watch dist/index.js` — Run server with auto-reload
|
|
905
|
+
- `start` — `node dist/index.js` — Run production server
|
|
906
|
+
- `build` — `node scripts/tasks.mjs build` — Clean build
|
|
907
|
+
- `test` — `node scripts/tasks.mjs test` — Build + run all tests
|
|
908
|
+
- `test:fast` — `node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts` — Run tests without build
|
|
909
|
+
- `lint` — `eslint .` — Lint source
|
|
910
|
+
- `type-check` — `node scripts/tasks.mjs type-check` — Type-check src + tests
|
|
911
|
+
- `format` — `prettier --write .` — Format code
|
|
912
|
+
- `inspector` — `npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}` — Launch MCP Inspector
|
|
896
913
|
|
|
897
914
|
## Build and Release
|
|
898
915
|
|
package/dist/completions.d.ts
CHANGED
|
@@ -1,13 +1,2 @@
|
|
|
1
1
|
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
-
interface CompletionResult {
|
|
3
|
-
values: string[];
|
|
4
|
-
total?: number;
|
|
5
|
-
hasMore?: boolean;
|
|
6
|
-
}
|
|
7
|
-
interface CompletionOptions {
|
|
8
|
-
argumentName?: string;
|
|
9
|
-
contextArguments?: Record<string, string>;
|
|
10
|
-
}
|
|
11
|
-
export declare function getPathCompletions(currentValue: string, options?: CompletionOptions): Promise<CompletionResult>;
|
|
12
2
|
export declare function registerCompletions(server: McpServer, instructions?: string): void;
|
|
13
|
-
export {};
|
package/dist/completions.js
CHANGED
|
@@ -409,7 +409,7 @@ function findMatchingRoots(searchDir, prefix, allowed) {
|
|
|
409
409
|
return path.basename(root).toLowerCase().startsWith(lowerPrefix);
|
|
410
410
|
});
|
|
411
411
|
}
|
|
412
|
-
|
|
412
|
+
async function getPathCompletions(currentValue, options = {}) {
|
|
413
413
|
const allowed = getAllowedDirectories();
|
|
414
414
|
try {
|
|
415
415
|
const contextBase = await resolveContextBaseDirectory(options.argumentName ?? '', options.contextArguments, allowed);
|
package/dist/config.d.ts
CHANGED
|
@@ -77,7 +77,6 @@ export interface SearchContentResult {
|
|
|
77
77
|
readonly skippedTooLarge: number;
|
|
78
78
|
readonly skippedBinary: number;
|
|
79
79
|
readonly skippedInaccessible: number;
|
|
80
|
-
readonly linesSkippedDueToRegexTimeout: number;
|
|
81
80
|
readonly stoppedReason?: 'maxResults' | 'maxFiles' | 'timeout';
|
|
82
81
|
};
|
|
83
82
|
}
|
package/dist/lib/constants.d.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
export declare function parseTrueEnvFlag(value: string | undefined): boolean;
|
|
2
2
|
export declare function parseEnvInt(envVar: string, defaultValue: number, min: number, max: number): number;
|
|
3
3
|
export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
|
|
4
|
-
export declare const REQUIRED_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
5
4
|
export declare const DEFAULT_TASK_TTL_MS: number;
|
|
6
5
|
export declare const MAX_TASK_TTL_MS: number;
|
|
7
6
|
export declare const MAX_CONCURRENT_TASKS: number;
|
package/dist/lib/constants.js
CHANGED
|
@@ -70,7 +70,6 @@ function parseEnvLogLevel(envVar, defaultValue) {
|
|
|
70
70
|
return defaultValue;
|
|
71
71
|
}
|
|
72
72
|
export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'info');
|
|
73
|
-
export const REQUIRED_MCP_PROTOCOL_VERSION = '2025-11-25';
|
|
74
73
|
// Default TTL for MCP tasks when the client does not specify one (5 minutes).
|
|
75
74
|
export const DEFAULT_TASK_TTL_MS = 5 * 60 * 1000;
|
|
76
75
|
export const MAX_TASK_TTL_MS = parseEnvInt('FILESYSTEM_MCP_MAX_TASK_TTL_MS', 60 * 60 * 1000, 1_000, 24 * 60 * 60 * 1000);
|
package/dist/lib/errors.d.ts
CHANGED
|
@@ -17,7 +17,6 @@ export declare class McpError extends Error {
|
|
|
17
17
|
path?: string | undefined;
|
|
18
18
|
details?: Record<string, unknown> | undefined;
|
|
19
19
|
constructor(code: ErrorCode, message: string, path?: string | undefined, details?: Record<string, unknown> | undefined, cause?: unknown);
|
|
20
|
-
static fromError(code: ErrorCode, message: string, originalError: unknown, path?: string, details?: Record<string, unknown>): McpError;
|
|
21
20
|
}
|
|
22
21
|
export declare function createDetailedError(error: unknown, path?: string, additionalDetails?: Record<string, unknown>): DetailedError;
|
|
23
22
|
export declare function formatDetailedError(error: DetailedError): string;
|
package/dist/lib/errors.js
CHANGED
|
@@ -173,13 +173,6 @@ export class McpError extends Error {
|
|
|
173
173
|
this.name = 'McpError';
|
|
174
174
|
Object.setPrototypeOf(this, McpError.prototype);
|
|
175
175
|
}
|
|
176
|
-
static fromError(code, message, originalError, path, details) {
|
|
177
|
-
const mcpError = new McpError(code, message, path, details, originalError);
|
|
178
|
-
if (originalError instanceof Error && originalError.stack) {
|
|
179
|
-
mcpError.stack = `${String(mcpError.stack)}\nCaused by: ${originalError.stack}`;
|
|
180
|
-
}
|
|
181
|
-
return mcpError;
|
|
182
|
-
}
|
|
183
176
|
}
|
|
184
177
|
const ERROR_SUGGESTIONS = {
|
|
185
178
|
[ErrorCode.E_ACCESS_DENIED]: 'Check that the path is within an allowed directory. Use roots to see available workspace roots.',
|
|
@@ -195,7 +188,10 @@ const ERROR_SUGGESTIONS = {
|
|
|
195
188
|
[ErrorCode.E_SYMLINK_NOT_ALLOWED]: 'Symbolic links that escape allowed directories are not permitted for security reasons.',
|
|
196
189
|
[ErrorCode.E_UNKNOWN]: 'An unexpected error occurred. Check the error message for details.',
|
|
197
190
|
};
|
|
198
|
-
const NOT_FOUND_PATTERNS = [
|
|
191
|
+
const NOT_FOUND_PATTERNS = [
|
|
192
|
+
'no such file or directory',
|
|
193
|
+
'does not exist',
|
|
194
|
+
];
|
|
199
195
|
const PERMISSION_DENIED_PATTERNS = [
|
|
200
196
|
'permission denied',
|
|
201
197
|
'not permitted',
|
|
@@ -241,7 +237,7 @@ function classifyError(error) {
|
|
|
241
237
|
return terminalCode ?? timeoutCode ?? fallbackCode ?? ErrorCode.E_UNKNOWN;
|
|
242
238
|
}
|
|
243
239
|
export function createDetailedError(error, path, additionalDetails) {
|
|
244
|
-
const message =
|
|
240
|
+
const message = formatUnknownErrorMessage(error);
|
|
245
241
|
const code = classifyError(error);
|
|
246
242
|
const suggestion = ERROR_SUGGESTIONS[code];
|
|
247
243
|
const resolvedPath = resolveErrorPath(error, path);
|
|
@@ -9,11 +9,11 @@ export interface DirentLike {
|
|
|
9
9
|
isSymbolicLink(): boolean;
|
|
10
10
|
}
|
|
11
11
|
export type EntryType = 'file' | 'directory' | 'symlink' | 'other';
|
|
12
|
-
|
|
12
|
+
interface IndexedValue<T> {
|
|
13
13
|
index: number;
|
|
14
14
|
value: T;
|
|
15
15
|
}
|
|
16
|
-
|
|
16
|
+
interface IndexedError {
|
|
17
17
|
index: number;
|
|
18
18
|
error: Error;
|
|
19
19
|
}
|
|
@@ -50,3 +50,4 @@ export declare function isIgnoredByGitignore(matcher: Ignore, root: string, abso
|
|
|
50
50
|
isDirectory?: boolean;
|
|
51
51
|
relativePath?: string;
|
|
52
52
|
}): boolean;
|
|
53
|
+
export {};
|