Skip to main content
Glama
j0hanz

filesystem-mcp

by j0hanz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search and Replace

replace_text
Destructive

Replace every occurrence of a text or regex pattern in all files matching a glob, with optional diff preview before writing.

Instructions

Bulk search-and-replace across files matching a glob pattern. Replaces ALL occurrences per file (unlike edit, which replaces only the first match). Set returnDiff=true to preview changes as a unified diff before or after writing. Literal matching by default; set isRegex=true to enable RE2 regex with capture groups ($1, $2).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathNoFile to rewrite, or directory to rewrite under. Omitting it targets the ENTIRE first allowed root — scope it deliberately, and pair a wide scope with dryRun=true first
dryRunNoPreview replacements without writing to disk (default: false = apply changes)
isRegexNoTreat searchPattern as a RE2 regex (default: literal text match)
patternNoGlob to restrict replacements to specific file types (e.g. **/*.ts); default: all text files
maxDepthNoMax directory depth to scan; 0 = base directory only, omit for unlimited
maxFilesNoMaximum number of files to process
wholeWordNoMatch whole words only (word boundary anchoring)
maxResultsNoMaximum total match count across all files before stopping
returnDiffNoInclude a unified diff of all changes in the response
replacementYesReplacement text. Use capture group references ($1, $2, etc.) when isRegex=true. Use an empty string to delete all matches.
caseSensitiveNoEnable case-sensitive matching (default: case-insensitive)
includeHiddenNoInclude hidden items (starting with .)
searchPatternYesExact literal text or RE2 regex pattern to search for. When isRegex=true, uses RE2 syntax (no lookahead, lookbehind, or backreferences are supported). Cannot be empty or whitespace-only.
includeIgnoredNoInclude ignored items (node_modules, .git, etc).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.4.1
    • addedInput schema / $schema
      Added value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / pattern / examples
      Added value: +[
+  "**/*.ts",
+  "src/**/*.js",
+  "*.{ts,tsx}"
+]
    • addedInput schema / properties / replacement / examples
      Added value: +[
+  "$1_renamed",
+  "",
+  "TODO: fix"
+]
    • addedInput schema / properties / searchPattern / examples
      Added value: +[
+  "TODO",
+  "function\\s+(\\w+)",
+  "import.*from"
+]
  2. Changed1 schema field changedv2.1.5
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": false,
-  "properties": {
-    "diff": {
-      "description": "Unified diff of all changes (present when returnDiff=true or dryRun=true)",
-      "type": "string"
-    },
-    "diffTruncated": {
-      "description": "True when the diff was cut due to the size limit",
-      "type": "boolean"
-    },
-    "filesScanned": {
-      "description": "Total number of files examined",
-      "minimum": 0,
-      "type": "integer"
-    },
-    "results": {
-      "description": "Per-file results: modified files, then any that could not be processed",
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "error": {
-            "additionalProperties": false,
-            "description": "Error details; present on failure",
-            "properties": {
-              "code": {
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              },
-              "path": {
-                "type": "string"
-              },
-              "suggestion": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "code",
-              "message"
-            ],
-            "type": "object"
-          },
-          "path": {
-            "description": "File path relative to the search root",
-            "type": "string"
-          },
-          "value": {
-            "additionalProperties": false,
-            "description": "Replacement outcome; present on success",
-            "properties": {
-              "matches": {
-                "description": "Replacements applied in this file",
-                "minimum": 0,
-                "type": "integer"
-              }
-            },
-            "required": [
-              "matches"
-            ],
-            "type": "object"
-          }
-        },
-        "required": [
-          "path"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "resultsTruncated": {
-      "description": "True when the results list holds fewer entries than summary.total: the changed-file or failed-file cap was hit. Trust summary over results.length.",
-      "type": "boolean"
-    },
-    "stoppedReason": {
-      "description": "Why enumeration stopped early: maxResults = match cap reached, maxFiles = file cap reached, timeout = time limit hit or cancelled. Absent when every matching file was enumerated. Marks the sweep incomplete, not the writes; files already dispatched still complete.",
-      "enum": [
-        "maxResults",
-        "maxFiles",
-        "timeout"
-      ],
-      "type": "string"
-    },
-    "summary": {
-      "additionalProperties": false,
-      "properties": {
-        "failed": {
-          "minimum": 0,
-          "type": "integer"
-        },
-        "succeeded": {
-          "minimum": 0,
-          "type": "integer"
-        },
-        "total": {
-          "minimum": 0,
-          "type": "integer"
-        }
-      },
-      "required": [
-        "total",
-        "succeeded",
-        "failed"
-      ],
-      "type": "object"
-    },
-    "totalMatches": {
-      "description": "Total number of replacements made across all files",
-      "minimum": 0,
-      "type": "integer"
-    }
-  },
-  "required": [
-    "results",
-    "summary",
-    "totalMatches",
-    "filesScanned"
-  ],
-  "type": "object"
-}New value: +null
  3. Addedv2.0.0

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds key behaviors: 'Replaces ALL occurrences per file', literal-by-default matching, and RE2 regex support. However, the wording 'Set returnDiff=true to preview changes... before or after writing' is slightly ambiguous because `returnDiff` alone does not prevent writing; `dryRun` is the true preview-without-write parameter, so this could mislead an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly focused sentences, front-loaded with the tool's core purpose and key distinction from `edit`. Every sentence earns its place; there is no filler or redundant restating of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the most critical context for a destructive bulk operation: it replaces all occurrences, can be scoped by glob, and can return a diff. Given a rich 100%-coverage schema and the destructiveHint annotation, it is nearly complete. The only gap is the ambiguous `returnDiff`/`dryRun` preview guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining `isRegex` and `replacement` semantics: 'Literal matching by default; set isRegex=true to enable RE2 regex with capture groups ($1, $2).' This synthesizes parameter behavior beyond the schema's individual descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb and resource: 'Bulk search-and-replace across files matching a glob pattern.' It clearly distinguishes itself from a sibling: 'unlike edit, which replaces only the first match.' An agent can immediately tell this tool replaces all occurrences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly contrasts with the `edit` tool ('unlike edit, which replaces only the first match'), telling the agent when this tool is the right choice. It also advises using `returnDiff=true` to preview changes, giving practical guidance on how to use it safely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools