Project Explorer MCP Server

Overview Schema Source Related Servers Discussions Admin

search_files

Find code and file content by literal or regex pattern with filters for file type, size, date, and comment/string exclusion. Returns text or JSON results with sorting and grouping.

Instructions

Advanced file and code search tool with comprehensive filtering and matching capabilities. Searches files within allowed directories for a required literal or regex pattern, with file type filtering, size constraints, date filtering, and comment/string-aware match suppression (search always runs against the original, unmodified file content). Results can be formatted as text or JSON with configurable sorting and grouping. maxResults caps the total number of returned matches.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No	Alias for searchPath
`sortBy`	No	How to sort the results	relevance
`maxSize`	No	Maximum file size in bytes
`minSize`	No	Minimum file size in bytes
`pattern`	Yes	Search pattern - literal text or regex depending on regexMode. Required.
`maxDepth`	No	Maximum directory recursion depth. Unlimited if not specified
`multiline`	No	Whether to enable multiline regex matching
`regexMode`	No	Whether to treat pattern as a regular expression
`extensions`	No	Array of file extensions to include (e.g., ['.js', '.ts', '.py']). Include the dot prefix
`maxResults`	No	Maximum total number of matches to return (across all files)
`searchPath`	No	Directory path to search in. Must be within allowed directories. Defaults to first allowed directory if not specified
`groupByFile`	No	Whether to group results by file
`outputFormat`	No	Output format for results	text
`wordBoundary`	No	Whether to match whole words only
`caseSensitive`	No	Whether search should be case sensitive
`includeBinary`	No	Whether to search in binary files
`modifiedAfter`	No	Only include files modified after this date (ISO 8601 format)
`snippetLength`	No	Length of text snippet around matches
`excludeStrings`	No	Whether to exclude string literals from search
`followSymlinks`	No	Whether to follow symbolic links
`modifiedBefore`	No	Only include files modified before this date (ISO 8601 format)
`excludeComments`	No	Whether to exclude comments from search (language-aware)
`excludePatterns`	No	Array of filename patterns to exclude (supports simple wildcards)
`excludeGenerated`	No	Whether to skip code-generated Dart part files (.g.dart, .freezed.dart, .mocks.dart, .gr.dart, *.i18n.dart)
`excludeExtensions`	No	Array of file extensions to exclude

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.1.9Sep 18, 2026

addedInput schema / properties / excludeGenerated

Added value: +{
+  "default": false,
+  "description": "Whether to skip code-generated Dart part files (*.g.dart, *.freezed.dart, *.mocks.dart, *.gr.dart, *.i18n.dart)",
+  "type": "boolean"
+}

Changed5 schema fields changedv0.1.8Sep 11, 2026

changedInput schema / properties / maxResults / description

Previous value: -"Maximum number of match results to return"New value: +"Maximum total number of matches to return (across all files)"

changedInput schema / properties / outputFormat / enum

Previous value: -[
-  "text",
-  "json",
-  "structured"
-]New value: +[
+  "text",
+  "json"
+]

removedInput schema / properties / pattern / default
```
Removed value: -".*"
```

changedInput schema / properties / pattern / description

Previous value: -"Search pattern - can be literal text or regex depending on regexMode. Defaults to searching for common file types if not specified"New value: +"Search pattern - literal text or regex depending on regexMode. Required."

changedInput schema / required

Previous value: -[]New value: +[
+  "pattern"
+]

Changed1 schema field changedv0.1.2Aug 18, 2026

addedInput schema / properties / path

Added value: +{
+  "description": "Alias for searchPath",
+  "type": "string"
+}

First observedAug 15, 2025

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations provided, the description carries the behavioral disclosure burden. It reveals a nuanced behavior—searching against original unmodified content, plus comment/string-aware suppression, result caps, and formatting options—which goes well beyond a generic read-only statement. It could be more explicit about non-mutating guarantees or permission requirements, but for a search tool this is strong.

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

Conciseness4/5

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

The description is efficiently structured with the core purpose first, then matching behavior, then output options. It is slightly promotional with 'Advanced' and 'comprehensive' but every sentence carries real information, and it remains compact given the tool's 25 parameters.

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?

Given the tool's complexity and lack of annotations or output schema, the description covers the essential behavioral and output context well. It does not explain the JSON result shape or how to discover allowed directories, but for a search tool the high-level completeness is adequate for correct selection and invocation.

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 coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics by grouping capabilities (file type filtering, size constraints, date filtering), clarifying that maxResults caps total matches, and indicating that output can be formatted as text or JSON. This helps an agent understand how parameters interact beyond individual schema 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 clearly identifies a specific verb ('searches'), a resource ('files within allowed directories'), and key capabilities (literal/regex, filtering, output formatting). It distinguishes from siblings like explore_project and rename_file because it is framed as a search, not a browse or mutate operation.

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

Usage Guidelines3/5

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

The usage context is implied: use this when you need to find file/code matches. It states the search operates within allowed directories, but does not explicitly name alternatives or when not to use this tool, such as when exploring project structure (explore_project) or listing directories (list_allowed_directories).

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

Deploy Server

search_files

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools