Skip to main content
Glama
Sign In
j0hanz

filesystem-mcp

by j0hanz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Content

search_text
Read-only

Search file contents for literal text or an RE2 regex like grep, returning matching lines with line numbers and paths ready to pass to read.

Instructions

Search file contents for literal text or an RE2 regex, like grep; returns matching lines with line numbers and paths relative to the root, ready to pass to read. searchPattern is the text to find, matched within one line; pattern filters files by glob. find_files matches file names.

Input Schema

NameRequiredDescriptionDefault
pathNoFile to search, or directory to search under (default: the whole first allowed root). Naming a file searches that file alone: pattern is ignored and hidden/ignored filtering does not apply.
cursorNoOpaque pagination cursor; pass unchanged for the next page. Pages slice one snapshot taken on the first call; it expires after ~60s — re-request without a cursor if rejected.
contextNoLines of context to return either side of each match, like grep -C (default: 0, max: 10)
isRegexNoTreat searchPattern as a regex (default: literal text match)
patternNoGlob to restrict search to specific file types (e.g. **/*.ts); default: all text files
maxDepthNoMax directory depth to scan; 0 = base directory only, omit for unlimited
maxResultsNoMaximum number of matching lines to return per page
caseSensitiveNoEnable case-sensitive matching (default: case-insensitive)
includeHiddenNoInclude hidden items (starting with .)
searchPatternYesExact literal text or RE2 regex pattern to search for in file contents. When isRegex=true, uses RE2 syntax (no lookahead, lookbehind, or backreferences). Cannot be empty or whitespace-only.
includeIgnoredNoInclude ignored items (node_modules, .git, etc).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.8.1
    • removedInput schema / properties / searchPattern / examples
      Removed value: -[
-  "TODO",
-  "function\\s+(\\w+)",
-  "import.*from"
-]
  2. Changed1 schema field changedv2.5.0
    • changedInput schema / properties / pattern / examples
      Previous value: -[
-  "**/*.ts",
-  "src/**/*.js",
-  "*.{ts,tsx}"
-]New value: +[
+  "**/*.ts",
+  "src/**/*.js",
+  "**/*.{ts,tsx}"
+]
  3. Changed3 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 / searchPattern / examples
      Added value: +[
+  "TODO",
+  "function\\s+(\\w+)",
+  "import.*from"
+]
  4. Changed1 schema field changedv2.3.0
    • addedInput schema / properties / context
      Added value: +{
+  "default": 0,
+  "description": "Lines of context to return either side of each match, like grep -C (default: 0, max: 10)",
+  "maximum": 10,
+  "minimum": 0,
+  "type": "integer"
+}
  5. Addedv2.0.0

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return shape (matching lines with line numbers and root-relative paths) and that matching is per-line. It omits pagination behavior and the cursor snapshot expiry, though the schema covers those.

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?

Two dense sentences, front-loaded with the core action and the most confusable parameter distinction. Every clause eliminates a likely mis-invocation; nothing is padding.

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?

For an 11-parameter tool with no output schema, the description covers purpose, return shape, and the key sibling boundary, which is enough to call it correctly. It leaves pagination and the ~60s snapshot expiry to the schema, a minor omission given the description's scope.

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?

With 100% schema coverage the baseline is 3, but the description earns more: it clarifies that searchPattern is matched within a single line and that 'pattern' is a file glob, not the content pattern — a naming ambiguity the schema alone leaves easy to misread. It also implies path/file-vs-directory inheritance from the schema.

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?

States a specific verb and resource ('Search file contents'), names both modes (literal text / RE2 regex) with a grep analogy, and explicitly differentiates from the sibling find_files ('find_files matches file names'). An agent can distinguish this from every other sibling without opening a schema.

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

Usage Guidelines4/5

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

Gives clear routing: use this for contents, find_files for names, and the output is 'ready to pass to read', which establishes the follow-up workflow. It stops short of exclusion rules (e.g., when not to use it on huge trees, or how it relates to replace_text for edits), so not a full 5.

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