Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Search Code MCP find all TODO comments in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A high-performance, unified Model Context Protocol (MCP) server combining the blazing speed of ripgrep (regex/text search) with the deep structural syntax awareness of ast-grep (AST pattern matching and refactoring).
Designed specifically for AI Coding Agents (Cursor, Claude Desktop, Antigravity, Cline / Roo Code, Windsurf, Zed).
6 Unified Tools (Zero Prefix Noise): Clean tool names without redundant prefixes: search, replace, count, find_symbols, dump_tree, and list_files.
Multi-Engine Driver Fallback (Zero Setup Friction): Automatically discovers and uses the best available CLI tool on your system without manual configuration:
Text & Regex: ripgrep (rg) ➜ ugrep ➜ git grep (runs out of the box on any developer machine with Git installed!).
Symbol Search: Universal Ctags (ctags) ➜ ast-grep ➜ ripgrep / git grep regex heuristic.
AST Search: ast-grep ➜ alias sg.
File Listing: rg --files ➜ git ls-files ➜ Native Node.js recursive directory walk.
Hybrid 2-Tier Search (type: "hybrid"): Scans candidate files with ripgrep in ~30ms, then parses AST with ast-grep only on matching files—giving 10x–50x speedups over pure AST searches on large codebases.
Project-Scoped Pagination Cache (./.cache/code-search/):
Automatically activates only when results exceed your chunk limit.
Returns a searchId for instant sub-millisecond scrolling through next pages (offset / limit) without re-scanning disk.
Creates an isolated ./.cache/code-search/ directory with an auto-generated .gitignore so cache files are never committed to git.
Gitignore Respected by Default: Both ripgrep and ast-grep automatically respect your project's .gitignore (noIgnore: false by default). Pass noIgnore: true only when you need to inspect ignored files.
Safe Structural Refactoring (replace): Defaults to dryRun: true to generate unified git-style diff previews and safety limits (maxReplacements: 50) before writing any changes to disk.
Token Protection & Truncation: Automatically trims overly long single lines (maxLineLength: 500) and strips ANSI color codes to protect LLM context windows.
Actionable Diagnostics: Syntax errors in AST patterns or YAML rules return helpful self-correction hints (e.g. suggesting dump_tree or stopBy: end).
Zero-Dependency Single-File Bundle: Packaged with tsup into a self-contained single executable bundle for instant startup via npx.
Related MCP server: MCP Smart Filesystem Server
search-code-mcp engine)Instead of installing binaries manually, you can run the built-in interactive engine manager to inspect your environment and automatically install missing tools with arrow keys (↑ / ↓) and [Enter]:
npx search-code-mcp engineIt automatically detects which text, AST, and symbol engines are installed, and presents an interactive selector to install any missing tools (via npm, choco, winget, or brew).
If you prefer to install engines manually, ensure the following CLI binaries are accessible in your system PATH:
rg) — Text & Regex SearchWindows: winget install BurntSushi.ripgrep.MSVC or choco install ripgrep
macOS: brew install ripgrep
Linux (Debian/Ubuntu): sudo apt install ripgrep
Linux (Arch): sudo pacman -S ripgrep
ast-grep) — Structural AST Search & Refactoringnpm (Recommended): npm install -g @ast-grep/cli
macOS: brew install ast-grep
Cargo (Rust): cargo install ast-grep --locked
Windows: choco install ast-grep or winget install ast-grep
ctags) — Symbol Search (Optional)Note: If ctags is not installed, the server automatically falls back to ripgrep regex heuristics.
Windows: choco install universal-ctags or winget install universal-ctags.universal-ctags
macOS: brew install universal-ctags
Linux (Debian/Ubuntu): sudo apt install universal-ctags
You can run search-code-mcp directly via npx without manual installation.
Add to your configuration file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"code-search": {
"command": "npx",
"args": ["-y", "search-code-mcp"]
}
}
}Add to your project's .cursor/mcp.json or in Cursor Settings > Features > MCP > Add New MCP Server:
{
"mcpServers": {
"code-search": {
"command": "npx",
"args": ["-y", "search-code-mcp"]
}
}
}Add to your MCP settings file:
{
"mcpServers": {
"code-search": {
"command": "npx",
"args": ["-y", "search-code-mcp"]
}
}
}searchUnified search engine supporting regex, literal text, AST patterns, relational YAML rules, and hybrid searches.
Parameter | Type | Default | Description |
|
| - | Search query: text, regex, AST pattern, or YAML rule. (Optional if |
|
|
| Target directory or file to search |
|
|
| Search engine mode: |
|
| - | ID of a previous search to view remaining results instantly from cache |
|
|
| Starting result index for pagination (1-based) |
|
|
| Maximum matches to return in this chunk |
|
| - | Glob pattern to filter files (e.g. |
|
| - | Ripgrep file type filter (e.g. |
|
| - | Glob pattern to exclude (e.g. |
|
|
| If |
|
| smart-case | Case sensitivity |
|
|
| Number of context lines before and after match ( |
|
|
| Match whole words only ( |
|
|
| Match regex across line breaks ( |
|
|
| Search hidden files and folders ( |
|
| auto | Programming language for AST mode (auto-detected from file extension if omitted) |
|
|
|
|
// Fast regex or text search
search({ query: "handleRequest", path: "./src" });
search({ query: "class.*Controller", type: "regex", context: 2 });
// AST structural pattern (ignores whitespace & formatting differences)
search({ query: "console.log($$$ARGS)", type: "ast", language: "typescript" });
// Hybrid 2-tier search: 10x-50x faster on huge codebases
search({ query: "class $NAME extends BaseService { $$$ }", type: "hybrid" });
// Complex relational YAML rule
search({
query: `
id: find-async-arrow
language: typescript
rule:
all:
- kind: arrow_function
- has:
pattern: await $EXPR
stopBy: end
`,
type: "ast_rule",
});
// Retrieve next chunk from cache using searchId
search({ searchId: "s_9f2a7b", offset: 51, limit: 50 });replaceStructural code refactoring and replacement engine. Supports AST rewrite patterns and Regex/Text replacements.
Parameter | Type | Default | Description |
|
| Required | Search pattern to replace (AST pattern or regex) |
|
| Required | Replacement string or AST rewrite pattern |
|
|
| Target directory or file |
|
|
| Replacement mode: |
|
|
| If |
|
|
| Safety limit on maximum matches to replace |
|
| - | Glob pattern to filter files |
|
| - | File type filter |
|
| - | Glob pattern to exclude |
|
|
| Whether to modify |
|
| auto | Programming language for AST mode |
// 1. Dry run preview (safe default, outputs unified git diff)
replace({
query: "fetchData($A, $B)",
replacement: "fetchData({ url: $A, options: $B })",
type: "ast",
dryRun: true,
});
// 2. Apply modifications to disk
replace({
query: "fetchData($A, $B)",
replacement: "fetchData({ url: $A, options: $B })",
type: "ast",
dryRun: false,
});countCount matching occurrences or lines across files without returning match content, saving tokens.
Parameter | Type | Default | Description |
|
| Required | Search pattern to count |
|
|
| Target directory or file |
|
|
| Engine mode: |
|
|
| Count matching lines ( |
|
|
| Show breakdown of matches per file |
|
| - | Glob pattern filter |
|
| - | File type filter |
|
| - | Glob exclude filter |
|
|
| Search inside ignored files |
|
| auto | Language for AST mode |
count({ query: "TODO:", type: "text" });
count({ query: "catch ($ERR) { $$$ }", type: "ast", perFile: true });find_symbolsFind and navigate code definitions (functions, classes, interfaces, methods, types, variables, structs, enums) across the codebase. Automatically selects the best available engine: Universal Ctags ➜ ast-grep ➜ ripgrep / git-grep regex heuristic.
Parameter | Type | Default | Description |
|
|
| Symbol name or substring to find (leave empty to list all symbols in target directory/file) |
|
|
| Target directory or file path |
|
| - | Filter by symbol kinds: |
|
|
| If |
|
| - | Glob pattern filter (e.g. |
|
| - | Ripgrep file type filter (e.g. |
|
| - | Glob pattern to exclude |
|
|
| Search inside ignored files |
|
|
| Maximum number of symbols to return |
|
|
| Output format: |
// Find exact function or class by name
find_symbols({ name: "handleSearch", exactMatch: true });
// List all functions in a module/directory
find_symbols({ path: "src/handlers", kinds: ["function"] });
// Search across whole repo with compact output
find_symbols({ name: "Schema", outputFormat: "compact" });dump_treeInspect concrete syntax trees (CST) or AST node structures to craft precise ast-grep patterns.
Parameter | Type | Default | Description |
|
| Required | Code snippet to inspect |
|
| Required | Programming language (e.g. |
|
|
| Tree format: |
dump_tree({
code: "const calculate = (a, b) => a + b;",
language: "typescript",
format: "cst",
});list_filesEnumerate files matching glob patterns or file types without scanning file contents.
Parameter | Type | Default | Description |
|
|
| Directory to search |
|
| - | Glob pattern filter (e.g. |
|
| - | Ripgrep file type filter |
|
| - | Glob pattern to exclude |
|
|
| List files ignored by |
|
|
| Include hidden files and folders |
list_files({ path: "./src", filePattern: "*.service.ts" });# 1. Clone the repository
git clone https://github.com/joutvhu/search-code-mcp.git
cd search-code-mcp
# 2. Install dependencies
npm install
# 3. Type check
npm run check
# 4. Build single-file bundle
npm run build
# 5. Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.jsThis project is licensed under the MIT License.
Count matching lines or total occurrences of a pattern in files without retrieving match content, saving tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory or file to count matches in (default: '.') | . |
| type | No | Engine mode: 'regex' (default), 'text', 'ast' | regex |
| query | Yes | Search pattern to count | |
| perFile | No | If true, shows breakdown of matches per file | |
| fileType | No | File type filter | |
| language | No | Language for AST mode | |
| noIgnore | No | Whether to count inside gitignored files | |
| countLines | No | Count matching lines (true) or total occurrences (false) | |
| filePattern | No | Glob pattern to filter files | |
| excludePattern | No | Glob pattern to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the key trait that no match content is returned (only counts), which is the main risk of confusing it with a retrieval tool. However, it does not state that the operation is read-only, that nothing is mutated, or that perFile=true changes the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the core action front-loaded and zero filler. Both clauses (what it counts, and the token-saving consequence) earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a ten-parameter tool with no annotations and no output schema, the description covers the core purpose but not the return-value shape. It never mentions that perFile=true produces a per-file breakdown or that results otherwise default to aggregate counts (countLines=true), which an agent needs to interpret output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all ten parameters are already documented in the schema, which sets the baseline at 3. The description's 'matching lines or total occurrences' loosely mirrors the countLines parameter but adds no syntax, format, or default detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (count) and resource (matching lines or total occurrences of a pattern in files) with a clear scope. It implicitly distinguishes itself from the sibling 'search' by noting it counts 'without retrieving match content', so an agent can tell the two apart without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'saving tokens' hints at the condition for choosing this tool over content-returning siblings like 'search', but it never explicitly says 'use this when you only need counts'. Usage is implied rather than stated, and no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the concrete syntax tree (CST) or AST of code to discover exact node kinds and structure for crafting ast-grep patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Code snippet or query pattern to inspect | |
| format | No | Tree dump format: 'cst' (concrete syntax tree), 'ast', or 'pattern' | cst |
| language | Yes | Programming language of the code (e.g. 'typescript', 'python', 'rust') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Inspect' reasonably conveys a read-only operation, and the purpose clause adds context, but it says nothing about output size, whether the dump is truncated, or any cost/latency characteristics of parsing arbitrary code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the action, the resource, and the reason for using it, with zero redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter read-only inspection tool with no output schema and full schema coverage, the description supplies the purpose and the intended workflow. It is nearly complete; only the return shape and the 'pattern' format mode are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (code, format, language) are already documented in the schema, including the format enum. The description reinforces the cst/ast distinction but omits the 'pattern' format value and adds no syntax or format guidance beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (Inspect) and resource (CST/AST of code) and states the downstream purpose (crafting ast-grep patterns), which implicitly separates it from siblings like search and find_symbols. It does not explicitly name or contrast any sibling, so a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for crafting ast-grep patterns' implies the workflow context (use before authoring a pattern), which is genuine but indirect guidance. There is no explicit when-to-use/when-not statement and no named alternative among search, replace, count, find_symbols, or list_files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code symbols (functions, classes, interfaces, methods, types, variables, structs, enums) across the codebase. Automatically selects best available engine: Universal Ctags -> ast-grep -> ripgrep regex heuristic.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Symbol name or substring pattern to find (leave empty to list all symbols in target path) | |
| path | No | File or directory to search symbols in (default: '.') | . |
| kinds | No | Filter by symbol kinds: 'function', 'class', 'interface', 'method', 'variable', 'type', 'struct', 'enum', 'trait', 'module' | |
| fileType | No | File type filter, e.g. 'ts', 'py', 'rust', 'go' | |
| noIgnore | No | Whether to search inside gitignored files | |
| exactMatch | No | If true, only match exact symbol name. If false (default), matches prefix or substring | |
| maxResults | No | Maximum number of symbols to return (default: 100) | |
| filePattern | No | Glob pattern to filter files, e.g. '*.ts' or '*.py' | |
| outputFormat | No | Output format: 'table' (default markdown table), 'json', or 'compact' (file:line: [kind] name) | table |
| excludePattern | No | Glob pattern to exclude, e.g. '**/node_modules/**', '**/dist/**' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It usefully reveals the engine fallback chain (Ctags -> ast-grep -> ripgrep) and implicitly that gitignored files are skipped by default, but it never states that the operation is read-only and non-mutating, nor how results are ordered or truncated beyond the maxResults parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the capability before the implementation detail about engines. No filler, though the parenthetical symbol enumeration is somewhat redundant with the kinds enum in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters fully covered by the schema but no output schema, the description is adequate for invocation but does not describe the shape of results or how outputFormat changes them. It says what is searched but not what comes back, leaving a modest gap for a tool with this much configuration surface.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, setting the baseline at 3. The description adds no parameter-level detail beyond what the schema provides, such as the interaction between exactMatch and name, so it neither helps nor hurts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Find) and resource (code symbols), and enumerates the symbol kinds it covers, so the agent knows what it returns. It does not name or distinguish itself from the sibling 'search' tool, which overlaps in intent, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance relative to siblings like search, count, or dump_tree. The mention of automatic engine selection implies the tool is a higher-level symbol-aware alternative to raw search, but the agent must infer that routing decision itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quickly list files matching glob patterns or file types without scanning contents.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory to list files in (default: '.') | . |
| fileType | No | File type filter | |
| noIgnore | No | Whether to list gitignored files | |
| filePattern | No | Glob pattern to filter files | |
| includeHidden | No | Include hidden files and directories | |
| excludePattern | No | Glob pattern to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the operation is fast and does not scan file contents, but omits read-only nature, permission requirements, recursion behavior, and return format. This is minimum viable for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every phrase contributes to purpose or scope, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There are no annotations and no output schema, so the description should ideally cover more behavioral context. It explains the core listing scope, but does not describe return values, recursion, or whether the result includes hidden/ignored files by default. Given the simple read operation and complete parameter schema, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters. The description references glob patterns and file types generically but adds no syntax, defaults, or behavior beyond the schema. The baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'list files'. It adds scope ('matching glob patterns or file types') and a differentiator from content-oriented siblings: 'without scanning contents'. An agent can distinguish this from search without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without scanning contents' implies the tool is for name/path listing rather than content search, which gives context against the sibling 'search'. However, it does not explicitly name alternatives or state when not to use this tool, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural code refactoring and replacement engine. Supports AST rewrite or Regex/Text replacement. By default, runs in dryRun mode producing a unified diff preview to ensure safe operations before writing changes to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory or file to perform replacement in (default: '.') | . |
| type | No | Replacement engine: 'ast' (default structural rewrite), 'regex', 'text' | ast |
| query | Yes | Target search pattern to replace (AST pattern or regex) | |
| dryRun | No | If true (default), outputs unified diff preview without modifying files on disk | |
| fileType | No | File type filter | |
| language | No | Programming language for AST mode (auto-detected if omitted) | |
| noIgnore | No | Whether to search inside gitignored files | |
| filePattern | No | Glob pattern to filter files | |
| replacement | Yes | Replacement string or AST rewrite pattern | |
| excludePattern | No | Glob pattern to exclude | |
| maxReplacements | No | Safety guardrail: maximum number of matches to replace (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully surfaces that dryRun defaults to true and returns a diff preview before touching disk, but this largely restates the dryRun schema entry, and it says nothing about irreversibility when dryRun=false, permission needs, or failure behavior on zero matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with zero filler, front-loaded with the tool's identity and followed immediately by the modes and the safety default. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with no annotations and no output schema, the description covers the core purpose and the critical dryRun safety default but omits guidance on mode selection, filter parameters, and the maxReplacements guardrail visible only in the schema. Adequate as a minimum viable definition, not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, including the dryRun default and the ast/regex/text enum. The description only echoes the engine-type distinction and adds no format, syntax, or interaction detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Structural code refactoring and replacement engine') and enumerates the modes (AST rewrite vs Regex/Text), which clearly separates it from read-only siblings like search and count. It stops short of explicitly naming an alternative tool or contrasting its scope with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the dryRun/default-preview sentence hints at a preview-then-write workflow, but there is no explicit 'use this when...' or 'prefer X instead' guidance, and nothing tells the agent when to pick AST versus regex versus text mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-performance unified code search engine combining ripgrep (regex/text) and ast-grep (AST patterns and YAML rules). Supports pagination with searchId and offset/limit for large results.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory or file to search in (default: current directory '.') | . |
| type | No | Search engine/type: 'regex' (default), 'text', 'ast', 'ast_rule', 'hybrid', 'symbol' | regex |
| limit | No | Maximum matches to return for this chunk (default: 50) | |
| query | No | Search query: plain text, regex, AST pattern, or YAML rule | |
| offset | No | Starting index for pagination (1-based, default: 1) | |
| context | No | Number of context lines before and after match (-C) | |
| fileType | No | Ripgrep file type filter, e.g. 'ts', 'py', 'rust', 'json' | |
| language | No | Target language (e.g. 'typescript', 'python'). If omitted, auto-detected from file extension | |
| noIgnore | No | If true, do NOT respect .gitignore (search ignored files). Default is false (respects .gitignore) | |
| searchId | No | Previous search result ID to view remaining results instantly without re-scanning | |
| multiline | No | Match regex across multiple lines (-U) | |
| wordMatch | No | Match whole words only (-w) | |
| filePattern | No | Glob pattern to filter files, e.g. '*.{ts,tsx}' or '!**/*.test.ts' | |
| outputFormat | No | Output format: 'content' (default), 'compact' (file:line only), 'files_only', 'json' | content |
| caseSensitive | No | Match case sensitively. If omitted, smart-case is used | |
| includeHidden | No | Search hidden files and folders (-.) | |
| maxLineLength | No | Max characters per line before truncating long lines (default: 500) | |
| excludePattern | No | Pattern to exclude, e.g. '**/dist/**', '**/*.spec.ts' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the pagination model (searchId with offset/limit lets you page without re-scanning), which is genuine behavioral context beyond the schema. However, it says nothing about permissions, default ignore behavior, result limits, or output shape for a mutation-free but heavy operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with no filler; the identity/summary is front-loaded before the pagination detail. It could be marginally improved by folding in engine-selection guidance rather than a bare mechanics note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter tool with no annotations and no output schema, the description is thin on engine-selection semantics (the six-value type enum and its implications) and on default scoping/inclusion behavior. It covers paging but leaves meaningful gaps for a tool this complex.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, warranting the baseline 3. The description ties searchId/offset/limit together into a paging workflow but adds no per-parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: a code search engine with named backends (ripgrep for regex/text, ast-grep for AST/YAML rules). It clearly conveys what the tool does, but does not distinguish it from siblings like find_symbols or count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling search-adjacent tools (find_symbols, count, list_files) or when each of the six search types is appropriate. Only a pagination workflow hint is offered, which is a mechanic rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0countdump_treefind_symbolslist_filesreplacesearchScored across 6 tools
Each tool has a distinct core purpose: search (find patterns), replace (modify), count (count only for token savings), dump_tree (AST inspection), find_symbols (symbol lookup), and list_files (glob listing). There is minor conceptual overlap between search, count, and find_symbols—all find code—but the descriptions clearly differentiate their outputs and use cases.
All names use snake_case consistently, which is good. However, the pattern is mixed: some are bare verbs (search, replace, count) while others are verb_noun (dump_tree, find_symbols, list_files), a minor deviation from a single predictable convention.
Six tools is well-scoped for a code search and refactoring server. Each tool serves a clear, non-redundant function, making the set efficient without being thin or bloated.
The surface covers the search/refactor lifecycle well: locate (search, find_symbols, list_files), inspect (dump_tree), quantify (count), and modify (replace). The main minor gap is a direct file-content read tool, though search and list_files let agents work around it.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
One searchable history across every AI coding tool, with secret scanning and a shared task board.
