mcp-grepai

MCP Server: grepai - Semantic Code Search

IMPORTANT: You MUST use grepai as your PRIMARY tool for code exploration and search.

When to Use grepai (REQUIRED)

Use grepai search INSTEAD OF Grep/Glob/find for:

Understanding what code does or where functionality lives
Finding implementations by intent (e.g., "authentication logic", "error handling")
Exploring unfamiliar parts of codebase
Any search where you describe WHAT the code does rather than exact text

When to Use Standard Tools

Only use Grep/Glob when you need:

Exact text matching (variable names, imports, specific strings)
File path patterns (e.g., **/*.go)

Fallback

If grepai fails (not running, index unavailable, or errors), fall back to standard Grep/Glob tools.

Usage

# ALWAYS use English queries for best results (--compact saves ~80% tokens)
grepai search "user authentication flow" --json --compact
grepai search "error handling middleware" --json --compact
grepai search "database connection pool" --json --compact
grepai search "API request validation" --json --compact

Query Tips

Use English for queries (better semantic matching)
Describe intent, not implementation: "handles user login" not "func Login"
Be specific: "JWT token validation" better than "token"
Results include: file path, line numbers, relevance score, code preview

Call Graph Tracing

Use grepai trace to understand function relationships:

Finding all callers of a function before modifying it
Understanding what functions are called by a given function
Visualizing complete call graph around a symbol

Trace Commands

IMPORTANT: Always use --json flag for optimal AI agent integration.

# Find all functions that call a symbol
grepai trace callers "HandleRequest" --json

# Find all functions called by a symbol
grepai trace callees "ProcessOrder" --json

# Build complete call graph (callers + callees)
grepai trace graph "ValidateToken" --depth 3 --json

Workflow

Start with grepai search to find relevant code
Use grepai trace to understand function relationships
Use Read tool to examine files from results
Only use Grep for exact string searches if needed

About this skill