Skip to main content
← MCP Tools

find_pattern

Textual search over the repository. Runs git grep over the repo's tracked and untracked text files and returns path:line:col:text, optionally confined to a path prefix or to the files that import a given symbol.

This is the deliberate escape hatch. The graph answers structural questions exactly; some questions are not structural (a log string, a TODO, a magic constant, a config key), and pretending otherwise would send you elsewhere. It is not limited to the files the graph indexes: any file git shows as text can match, with known-binary formats and ignored paths removed. The scope argument is what narrows it, and files-importing(<symbol>) is the graph-aware form.

Availability: single-repo stdio (travsr mcp) and global stdio (travsr mcp --global). Not served over SSE.

Input schema​

{
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "POSIX ERE pattern to search for (use fixed:true for a literal string)"
},
"scope": {
"type": "string",
"description": "Optional scope: a repo-relative path prefix, or files-importing(<symbol>)"
},
"fixed": {
"type": "boolean",
"description": "Treat pattern as a literal string instead of a regular expression"
},
"context": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Lines of source to show after each match (git grep -A), capped at 10. Default 0."
},
"repo": {
"type": "string",
"description": "Repo name (run repos_list to discover). Only present in global (multi-repo) sessions."
}
},
"required": ["pattern"],
"additionalProperties": false
}

pattern is a POSIX extended regular expression, not PCRE. Set fixed: true for a literal search, which is also the right choice for anything containing regex metacharacters.

Scoping​

scope takes either form:

  • A repo-relative path prefix, for example crates/travsr-store/.
  • files-importing(<symbol>), which confines the search to files that import that symbol. This is the form that makes the tool graph-aware rather than a plain grep: it answers "where, among the code that actually depends on this, does this text appear".

Output format​

Plain text (wrapped in a <travsr-data> envelope), not JSON. On a match it opens with an N match(es): header line, then one git grep-style path:line:col:text line per match (a single very long line is cut at 512 bytes with a trailing …[line truncated]). A match that lands inside test code is prefixed with [test] . With context above 0, each match is followed by that many lines of source, written path-line-text (a hyphen where a match line has colons), and groups from different places are separated by a bare -- line. Only matches count toward the cap; context lines never do. Matches are capped at 500; past the cap the list ends with [truncated: showing 500 of N matches].

A pattern that ran and matched nothing returns [note: no matches], while input the tool rejected outright (an invalid or out-of-repo scope, a control character in the pattern) returns an empty envelope, so the two are no longer the same answer. The exception is when the pattern uses a construct POSIX ERE does not support (\b, \d, \w, \s, (?, and similar PCRE-only syntax), in which case the body is a one-line no matches. note: ... explaining that the construct is not supported under POSIX ERE and suggesting fixed: true or an ERE-safe alternative. A scope: files-importing(<symbol>) that matches no files returns No files import '<symbol>'. instead of running the search at all. A git grep failure returns pattern error: <detail>, with an extra hint appended when the failure looks like a regex complaint or a stale indexed repo path.

Example​

Request:

{ "pattern": "fn wrap_envelope", "fixed": true }

Response (from the Travsr repository; note that > in the matched line comes back escaped as &gt; inside the envelope):

1 match(es):
crates/travsr-mcp/src/sanitize.rs:138:12:pub(crate) fn wrap_envelope(content: &str) -&gt; String {

When to use​

  • Non-structural text: error strings, TODOs, feature flags, config keys.
  • Confirming an empty structural result. If find_references returns nothing and you suspect the index rather than the code, a textual search distinguishes "not there" from "not indexed".
  • Symbols the graph cannot model, such as a name built by string concatenation or reflection.

Notes​

  • Backed by git grep, so it sees tracked and untracked (not ignored) text files and respects the repo's ignore rules.
  • Returns text, not graph nodes. Results are not edges and carry no structural guarantee.
  • The CLI equivalent is travsr pattern "<regex>".