A high-performance MCP server that unifies ripgrep text/regex search with ast-grep structural AST matching for AI coding agents.
search: Find code using regex, literal text, AST patterns, YAML rules, hybrid, or symbol modes, with pagination via searchId, glob/type filters, context lines, and multiple output formats.
replace: Refactor code structurally (AST) or via regex/text, defaulting to a safe dryRun diff preview with a maxReplacements guardrail before writing to disk.
count: Count matching lines or total occurrences across files without returning content, optionally per-file, to save tokens.
find_symbols: Locate functions, classes, methods, and other symbols, auto-selecting Universal Ctags ➜ ast-grep ➜ regex heuristic.
dump_tree: Inspect CST/AST structures of code to craft precise ast-grep patterns.
list_files: Enumerate files by glob pattern or file type without scanning contents.
Respects .gitignore by default, supports hidden/ignored files on demand, and trims long lines/ANSI codes to protect context windows.
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, Kiro, 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/search-code/):
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/search-code/ 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.
Flexible Path Handling: Supports both relative paths (e.g. ".", "./src") and absolute paths as input. By default, tool outputs return absolute paths. Set RELATIVE_PATHS=true in environment (or pass --relative-paths) to format output paths as clean relative paths to save LLM context window tokens.
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).
Agent Skill Included (skills/search-code): Pre-configured Agent Skill for Claude Code, Cursor, Antigravity, and Cline to automatically write AST patterns, YAML rules, and select optimal engines.
Zero-Dependency Single-File Bundle: Packaged with esbuild 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 the following configuration to your client's MCP configuration file:
{
"mcpServers": {
"search-code": {
"command": "npx",
"args": ["-y", "search-code-mcp"]
}
}
}Token-Saving Relative Paths: Add "env": { "RELATIVE_PATHS": "true" } (or pass "--relative-paths" in args) if you want tool outputs to return clean relative paths instead of full absolute paths.
Client | Configuration File Path |
Kiro | Workspace: |
Cursor | Workspace: |
Claude Desktop | macOS: |
Antigravity IDE |
|
Windsurf |
|
Cline / Roo Code | Click MCP Servers icon ➜ Configure MCP Servers |
Teach your AI coding agent (Cursor, Claude Code, Antigravity, Cline, Kiro) how to write high-precision ast-grep patterns, YAML rules, and choose the optimal search engine:
npx skills add joutvhu/search-code-mcpOr install locally in your project:
npx skills add ./skills/search-codesearchUnified 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. Run automated test suite
npm test
# 5. Build single-file bundle
npm run build
# 6. 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. Accepts relative or absolute paths (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 full behavioral burden. It usefully discloses one key trait: it returns counts rather than match content, which is a meaningful output-shape cue. It does not mention read-only nature, permission requirements, or gitignore handling (which the noIgnore param implies), leaving notable gaps.
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 tight sentence with the core purpose front-loaded and the token-saving rationale appended. No filler or redundancy.
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 read-oriented counting tool with no output schema and fully covered param schema, the description conveys the essential purpose and output nature. It lacks explicit sibling routing and any note on the perFile breakdown result shape, but is largely sufficient for correct invocation.
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. The description's mention of 'matching lines or total occurrences' mirrors the already-documented countLines parameter without adding syntax, format, or default information beyond it. 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?
States a specific verb (count) and resource (matching lines or total occurrences of a pattern in files), and distinguishes itself functionally from content-returning siblings by noting it does not retrieve match content. However, it never names the closest sibling (search) explicitly, so differentiation is implied rather than stated.
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 retrieving match content, saving tokens' implies when this tool is preferable to a content-returning search, but there is no explicit when-to-use vs when-not guidance or named alternative (search) among the five siblings. Usage is inferable but not spelled out.
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. Accepts relative or absolute paths (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 provided, so the description carries the full burden. It discloses the engine fallback chain (ctags -> ast-grep -> ripgrep) which is useful behavioral context, but omits auth requirements, rate limits, or what happens when no engine is available. Also doesn't mention output shape or result limits beyond what schema already shows.
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 primary purpose and symbol kinds, followed by the engine fallback. No wasted words and appropriately sized.
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 search tool with no output schema and no annotations, the description covers purpose and engine behavior but omits return format details, pagination/maxResults behavior beyond schema, and error conditions. It's adequate but not complete for full behavioral transparency.
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 10 parameters including defaults and enum values. The description adds no parameter-specific guidance beyond what the schema provides. Baseline 3 is correct when schema fully covers parameters.
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 kinds (functions, classes, interfaces, etc.). Clearly distinguishes from siblings like search, dump_tree, list_files by being symbol-aware rather than raw text/tree listing.
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 by 'Find code symbols... across the codebase' but no explicit when-to-use vs alternatives is given. It doesn't say when to use find_symbols instead of search or dump_tree, though the symbol kind enumeration hints at its niche.
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. Accepts relative or absolute paths (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 the performance trait ('quickly', 'without scanning contents') but says nothing about traversal depth (recursive or not), how gitignore/hidden defaults interact with results, ordering, or result shape — key unknowns for a 6-parameter listing 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?
A single front-loaded sentence with no filler; the core action leads and the constraint follows. It is efficient, though it is arguably too terse to fully exploit the space available.
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 no annotations and no output schema, the description must carry behavior on its own. It conveys purpose and a performance promise but omits traversal semantics, ignore/hidden defaults, and output structure, which is minimal-but-adequate rather than complete for a 6-param tool.
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 baseline is 3. The description references glob patterns and file types, loosely echoing filePattern/fileType, but adds no syntax, format, or interaction detail beyond what the schema already documents.
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 ('list files') and scopes it with the filter mechanism ('matching glob patterns or file types'). The qualifier 'without scanning contents' implicitly separates it from content-oriented siblings like search, but no sibling is named explicitly, so it falls short of the top score.
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?
'Quickly' and 'without scanning contents' imply this is the lightweight metadata-only path versus a content-searching sibling, giving implied usage guidance. However, it never states when to prefer this over dump_tree, search, or count, nor any prerequisites or exclusions.
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. Accepts relative or absolute paths (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 burden. It usefully discloses the dryRun default and diff preview behavior, which is valuable. However, it omits the maxReplacements safety guardrail, permission/auth requirements, whether changes are reversible, and whether dryRun can be overridden.
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 sentences, front-loaded with the core purpose, then modes, then the key safety behavior. Every sentence earns its place with zero waste.
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 complex 11-parameter mutation tool with no annotations and no output schema, the description covers purpose and the dryRun safety default but leaves significant gaps: the maxReplacements guardrail, mode selection guidance, and what happens on non-dryRun execution are not addressed.
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 coverage is 100%, so the schema already documents all 11 parameters including defaults, enums, and meanings. The description adds no parameter-level detail beyond the schema, so baseline 3 is appropriate.
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+resource ('Structural code refactoring and replacement engine') and identifies the two modes (AST or Regex/Text), clearly distinguishing it from sibling read-only tools like search and 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?
The description implies this is a mutation tool with a dryRun preview default, but it does not explicitly state when to use it vs sibling tools (e.g., use search to find patterns first, or count to preview match volume) or when to prefer AST vs regex vs 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. Accepts relative or absolute paths (default: '.') | . |
| 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 pagination behavior (searchId lets you view remaining results 'instantly without re-scanning'), which is real behavioral context. But it omits permission requirements, cost/latency characteristics of the heavier engines (ast_rule, hybrid), and what happens on invalid patterns.
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 tight sentences with zero padding, and the core capability is front-loaded. It is arguably too terse for an 18-parameter tool, but nothing present is wasted.
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: it never explains how engine choice changes results, what the response shape is, or when pagination via searchId is required. The rich schema compensates for parameter documentation, leaving this minimally adequate.
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 18 parameters are already documented, making 3 the baseline. The description adds only the searchId/offset/limit pagination relationship, which is largely mirrored in the schema descriptions themselves.
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+resource — a unified code search engine — and names the underlying engines (ripgrep, ast-grep). It does not differentiate itself from siblings like count or find_symbols, and the 'symbol' search type visibly overlaps find_symbols without any clarifying remark.
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 guidance: nothing says when to prefer this over count, find_symbols, or list_files, and no conditions for choosing among the six engine types are given. The only usage-adjacent statement concerns pagination mechanics, not tool selection.
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.2count1 field changedInput schema / properties / path / descriptionPrevious value: -"Directory or file to count matches in (default: '.')"New value: +"Directory or file to count matches in. Accepts relative or absolute paths (default: '.')"find_symbols1 field changedInput schema / properties / path / descriptionPrevious value: -"File or directory to search symbols in (default: '.')"New value: +"File or directory to search symbols in. Accepts relative or absolute paths (default: '.')"list_files1 field changedInput schema / properties / path / descriptionPrevious value: -"Directory to list files in (default: '.')"New value: +"Directory to list files in. Accepts relative or absolute paths (default: '.')"replace1 field changedInput schema / properties / path / descriptionPrevious value: -"Directory or file to perform replacement in (default: '.')"New value: +"Directory or file to perform replacement in. Accepts relative or absolute paths (default: '.')"search1 field changedInput schema / properties / path / descriptionPrevious value: -"Directory or file to search in (default: current directory '.')"New value: +"Directory or file to search in. Accepts relative or absolute paths (default: '.')"v1.0.0countdump_treefind_symbolslist_filesreplacesearchScored across 6 tools
Each tool has a fairly distinct purpose: search finds matches, replace rewrites, count tallies, find_symbols targets declarations, dump_tree inspects AST, list_files enumerates files. There is minor overlap between search, count, and find_symbols since all match patterns, but the descriptions make the boundaries clear enough to choose correctly.
Naming is mostly a verb or verb_noun pattern (dump_tree, find_symbols, list_files) with a few bare single-verb names (search, replace, count). All snake_case and readable, with only minor deviation from a strict verb_noun convention.
Six tools is well-scoped for a code search/refactor server, with each tool earning its place (search, replace, count, inspect, symbols, listing). No redundancy or bloat.
The surface covers discovery (list_files, dump_tree, find_symbols), search (search, count), and mutation (replace with dry-run), forming a coherent lifecycle. Minor gaps like reading file contents or explicit symbol-level navigation exist but core workflows are covered.
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.
