Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/search-files-empty-result-hint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@modelcontextprotocol/server-filesystem": patch
---

`search_files` no longer answers a search that matched nothing with a bare `No matches found`. The result still begins with those words, and now names the pattern and the directory searched, says the pattern is a case-sensitive glob over names relative to that directory (never file contents), and, for a pattern with no `**`, suggests the `**/` form that reaches subdirectories. The tool's description and its `pattern` input also gain realistic example patterns (`**/*.json`, `**/*report*`) next to the generic ones.
8 changes: 7 additions & 1 deletion src/filesystem/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,9 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
- `path` (string): Starting directory
- `pattern` (string): Glob matched, case-sensitively, against each entry's
path relative to `path`: `*.ext` matches entries directly under `path`,
`**/*.ext` or `**/name` matches at any depth
`**/*.ext` or `**/name` matches at any depth. For example, `**/*.json`
finds every JSON file and `**/*report*` every entry with `report` in its
name
- `excludePatterns` (string[]): Entries to leave out, read the same way as
`directory_tree`'s. A bare name such as `node_modules` excludes an entry
of that name at any depth and everything below it; it matches whole
Expand All @@ -297,6 +299,10 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
entirely.
- Glob-style pattern matching
- Returns full paths to matches
- When nothing matches, the result begins `No matches found` and goes on to
name the pattern and the directory searched and to say how the pattern is
read. For a pattern with no `**`, which only matches at one depth, it also
suggests the `**/` form that matches at any depth
- Bounded: see [Slow and very large trees](#slow-and-very-large-trees)
- A subdirectory that cannot be read (no permission, say) is skipped, and the
result says so: after the matches, a note that the search is incomplete
Expand Down
2 changes: 1 addition & 1 deletion src/filesystem/__tests__/exclude-glob-prunes-dir.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ describe('excludePatterns ending in "/**" (#5445)', () => {
excludePatterns: ["**/node_modules/**"],
});
expect(result.isError).toBeFalsy();
expect(textOf(result)).toBe("No matches found");
expect(textOf(result)).toMatch(/^No matches found for pattern /);
});

it("directory_tree does not list the excluded directory, even as empty", async () => {
Expand Down
55 changes: 54 additions & 1 deletion src/filesystem/__tests__/search-files-description.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@
// the files, so the description now says the tool matches names, never
// contents. These tests pin that wording and each matching rule it states, so
// the description cannot drift from the behavior again.
//
// They also pin the realistic example patterns the description carries next to
// the generic ones, and what an empty result says (#5553): a bare "No matches
// found" gave a model nothing to correct a pattern with, so it repeated
// '*.ext' patterns that cannot reach a subdirectory. The empty result now
// names the pattern and the directory, restates how the pattern is read, and
// suggests the '**/' form when the pattern has no '**'.

import fs from "fs/promises";
import path from "path";
Expand Down Expand Up @@ -61,8 +68,54 @@ describe("search_files description (#896, #3419)", () => {
expect(description).not.toContain("working directory");
});

it("gives realistic example patterns, each of which matches as described", async () => {
const { tools } = await client.listTools();
const tool = tools.find((t) => t.name === "search_files");
expect(tool?.description).toContain("'**/*.json'");
expect(tool?.description).toContain("'**/*report*'");
const properties = tool?.inputSchema.properties as Record<
string,
{ description?: string }
>;
expect(properties.pattern.description).toContain("'**/*report*'");

await fs.writeFile(path.join(dir, "src", "config", "app.json"), "");
await fs.writeFile(path.join(dir, "src", "q3-report-final.txt"), "");
expect(await search("**/*.json")).toEqual([
path.join(dir, "src", "config", "app.json"),
]);
expect(await search("**/*report*")).toEqual([
path.join(dir, "src", "q3-report-final.txt"),
]);
});

it("does not match a file's contents", async () => {
expect(await search("**/needle")).toEqual(["No matches found"]);
expect(await search("**/needle")).toEqual([
`No matches found for pattern '**/needle' under ${dir}. ` +
"The pattern is a glob matched case-sensitively against each entry's path " +
"relative to that directory: it matches names, never file contents.",
]);
});

it("suggests the '**/' form when an empty search's pattern has no '**'", async () => {
const result = await call(client, "search_files", {
path: dir,
pattern: "app*.md",
});
expect(result.isError).toBeFalsy();
const text = textOf(result);
expect(text).toBe(
`No matches found for pattern 'app*.md' under ${dir}. ` +
"The pattern is a glob matched case-sensitively against each entry's path " +
"relative to that directory: it matches names, never file contents. " +
"It has no '**', so it only matches at one depth ('*.ext' only directly " +
"under the directory); try '**/app*.md' to match at any depth.",
);
expect(result.structuredContent).toEqual({ content: text });
// The suggested pattern is one that works.
expect(await search("**/app*.md")).toEqual([
path.join(dir, "src", "app.md"),
]);
});

it("matches '*.ext' only directly under path", async () => {
Expand Down
2 changes: 1 addition & 1 deletion src/filesystem/__tests__/search-unreadable.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ describe("search_files with an unreadable subdirectory (#5189)", () => {
});
expect(result.isError).toBeFalsy();
const [matches, note] = textOf(result).split("\n\n");
expect(matches).toBe("No matches found");
expect(matches).toMatch(/^No matches found for pattern /);
const [heading, ...listed] = note.split("\n");
expect(heading).toBe(
"The search is incomplete: 2 directories could not be read, and any matches inside are missing:",
Expand Down
2 changes: 1 addition & 1 deletion src/filesystem/__tests__/server-tools.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2122,7 +2122,7 @@ describe("search_files", () => {
path: dir,
pattern: "*.none",
});
expect(textOf(result)).toBe("No matches found");
expect(textOf(result)).toMatch(/^No matches found for pattern '\*\.none' /);
});

it("silently skips a symlink that leaves the allowed directories", async () => {
Expand Down
25 changes: 22 additions & 3 deletions src/filesystem/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,8 @@ const SearchFilesArgsSchema = z.object({
.string()
.describe(
"Glob matched against each entry's path relative to path, never its content: " +
"'*.ts' matches directly under path, '**/*.ts' at any depth.",
"'*.ts' matches directly under path, '**/*.ts' at any depth, " +
"'**/*report*' any name containing 'report'.",
),
excludePatterns: z
.array(z.string())
Expand Down Expand Up @@ -1030,7 +1031,8 @@ export function createServer(
description:
"Find files and directories by NAME, not by content: this tool never reads or searches inside files. " +
"It walks the tree under 'path' and matches a glob pattern against each entry's path relative to 'path' (case-sensitive). " +
"Use '*.ext' to match entries directly under 'path', and '**/*.ext' or '**/name' to match at any depth. " +
"Use '*.ext' to match entries directly under 'path', and '**/*.ext' or '**/name' to match at any depth: " +
"for example, '**/*.json' finds every JSON file and '**/*report*' every entry with 'report' in its name. " +
"Returns full paths to all matching items. Great for finding files when you don't know their exact location. " +
"Only searches within allowed directories.",
inputSchema: jsonSchema2020(SearchFilesArgsSchema.shape),
Expand Down Expand Up @@ -1063,7 +1065,24 @@ export function createServer(
},
},
);
let text = results.length > 0 ? results.join("\n") : "No matches found";
// An empty result says what was searched and how the pattern is read,
// and how to widen a pattern that cannot reach subdirectories: a bare
// "No matches found" left a model repeating the same '*.ext' pattern
// (#5553). It stays one paragraph, opening with those three words.
let text: string;
if (results.length > 0) {
text = results.join("\n");
} else {
text =
`No matches found for pattern '${args.pattern}' under ${args.path}. ` +
"The pattern is a glob matched case-sensitively against each entry's path " +
"relative to that directory: it matches names, never file contents.";
if (!args.pattern.includes("**")) {
text +=
" It has no '**', so it only matches at one depth ('*.ext' only directly " +
`under the directory); try '**/${args.pattern}' to match at any depth.`;
}
}
if (unreadable.length > 0) {
text +=
`\n\nThe search is incomplete: ${unreadable.length} ` +
Expand Down
Loading