Grepai Mcp Tools

yoanbernabeu/grepai-skills/skills/integration/grepai-mcp-tools

by yoanbernabeu382d40261c0d41109c6e11872574ba0be9b064d0No licenseListed Oct 9, 2026Updated Oct 9, 2026

Reference for all GrepAI MCP tools. Use this skill to understand available MCP tools and their parameters.

Instructions onlyAI & Agents Software Development

AI-generated overview

Reference documentation for GrepAI's MCP tools, covering parameters, responses and usage.

What it does: This skill is a reference document describing the tools exposed by GrepAI's MCP server: semantic code search, caller and callee tracing, call graph building, and index status checks. It lists each tool's parameters, defaults, example requests and JSON responses, including compact output keys and error codes. It also covers MCP protocol request and response formats and token-efficiency guidance for AI integration.
When to use it: Use it when you need to understand which GrepAI MCP tools exist, what parameters they accept, or how to interpret their responses. It is also useful when integrating GrepAI with an AI assistant or debugging MCP tool usage.
Requirements: Instructions only; no scripts are shipped. Using the described tools requires the GrepAI CLI with its MCP server started via the grepai mcp-serve command, plus a built code index and a reachable embedding provider such as Ollama.

GrepAI MCP Tools Reference

This skill provides a complete reference for all tools available through GrepAI's MCP server.

When to Use This Skill

Understanding available MCP tools
Learning tool parameters and options
Integrating GrepAI with AI assistants
Debugging MCP tool usage

Starting the MCP Server

The server exposes tools via the Model Context Protocol.

Available Tools

1. grepai_search

Semantic code search using embeddings.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Search query describing what to find
`limit`	number	No	10	Maximum results to return
`compact`	boolean	No	false	Return compact output (no content)
`format`	string	No	"json"	Output format: "json" or "toon" (v0.26.0+)

Example Request

json

{  "tool": "grepai_search",  "parameters": {    "query": "user authentication middleware",    "limit": 5,    "compact": true,    "format": "toon"  }}

{  "tool": "grepai_search",  "parameters": {    "query": "user authentication middleware",    "limit": 5,    "compact": true,    "format": "toon"  }}

Response (Compact)

json

{  "q": "user authentication middleware",  "r": [    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}  ],  "t": 3}

{  "q": "user authentication middleware",  "r": [    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}  ],  "t": 3}

Response (Full)

json

{  "query": "user authentication middleware",  "results": [    {      "score": 0.92,      "file": "src/auth/middleware.go",      "start_line": 15,      "end_line": 45,      "content": "func AuthMiddleware() gin.HandlerFunc {\n    ..."    }  ],  "total": 3}

{  "query": "user authentication middleware",  "results": [    {      "score": 0.92,      "file": "src/auth/middleware.go",      "start_line": 15,      "end_line": 45,      "content": "func AuthMiddleware() gin.HandlerFunc {\n    ..."    }  ],  "total": 3}

2. grepai_trace_callers

Find all functions that call a specified symbol.

Parameters

Parameter	Type	Required	Default	Description
`symbol`	string	Yes	-	Function/method name to trace
`compact`	boolean	No	false	Return compact output (no context)
`format`	string	No	"json"	Output format: "json" or "toon" (v0.26.0+)

Example Request

Response (Compact)

json

{  "q": "Login",  "m": "callers",  "c": 3,  "r": [    {"f": "handlers/auth.go", "l": 42, "fn": "HandleAuth"},    {"f": "handlers/auth_test.go", "l": 15, "fn": "TestLoginSuccess"},    {"f": "cmd/main.go", "l": 88, "fn": "RunCLI"}  ]}

{  "q": "Login",  "m": "callers",  "c": 3,  "r": [    {"f": "handlers/auth.go", "l": 42, "fn": "HandleAuth"},    {"f": "handlers/auth_test.go", "l": 15, "fn": "TestLoginSuccess"},    {"f": "cmd/main.go", "l": 88, "fn": "RunCLI"}  ]}

Response (Full)

json

{  "query": "Login",  "mode": "callers",  "count": 3,  "results": [    {      "file": "handlers/auth.go",      "line": 42,      "caller": "HandleAuth",      "context": "user.Login(ctx, credentials)"    }  ]}

{  "query": "Login",  "mode": "callers",  "count": 3,  "results": [    {      "file": "handlers/auth.go",      "line": 42,      "caller": "HandleAuth",      "context": "user.Login(ctx, credentials)"    }  ]}

3. grepai_trace_callees

Find all functions called by a specified symbol.

Parameters

Parameter	Type	Required	Default	Description
`symbol`	string	Yes	-	Function/method name to trace
`compact`	boolean	No	false	Return compact output (no context)
`format`	string	No	"json"	Output format: "json" or "toon" (v0.26.0+)

Example Request

json

{  "tool": "grepai_trace_callees",  "parameters": {    "symbol": "ProcessOrder",    "compact": true  }}

{  "tool": "grepai_trace_callees",  "parameters": {    "symbol": "ProcessOrder",    "compact": true  }}

Response (Compact)

json

{  "q": "ProcessOrder",  "m": "callees",  "c": 4,  "r": [    {"f": "services/order.go", "l": 45, "fn": "validateOrder"},    {"f": "services/order.go", "l": 48, "fn": "calculateTotal"},    {"f": "services/order.go", "l": 51, "fn": "applyDiscount"},    {"f": "services/order.go", "l": 55, "fn": "sendConfirmation"}  ]}

{  "q": "ProcessOrder",  "m": "callees",  "c": 4,  "r": [    {"f": "services/order.go", "l": 45, "fn": "validateOrder"},    {"f": "services/order.go", "l": 48, "fn": "calculateTotal"},    {"f": "services/order.go", "l": 51, "fn": "applyDiscount"},    {"f": "services/order.go", "l": 55, "fn": "sendConfirmation"}  ]}

4. grepai_trace_graph

Build a complete call graph starting from a symbol.

Parameters

Parameter	Type	Required	Default	Description
`symbol`	string	Yes	-	Root function for the graph
`depth`	number	No	2	Maximum recursion depth
`compact`	boolean	No	false	Return compact JSON format
`format`	string	No	"json"	Output format: "json" or "toon" (v0.26.0+)

Example Request

json

{  "tool": "grepai_trace_graph",  "parameters": {    "symbol": "main",    "depth": 3,    "compact": true  }}

{  "tool": "grepai_trace_graph",  "parameters": {    "symbol": "main",    "depth": 3,    "compact": true  }}

Response (Compact)

json

{  "q": "main",  "d": 3,  "r": {    "n": "main",    "c": [      {        "n": "initialize",        "c": [          {"n": "loadConfig"},          {"n": "connectDB"}        ]      },      {        "n": "startServer",        "c": [          {"n": "registerRoutes"}        ]      }    ]  },  "s": {"nodes": 6, "depth": 3}}

{  "q": "main",  "d": 3,  "r": {    "n": "main",    "c": [      {        "n": "initialize",        "c": [          {"n": "loadConfig"},          {"n": "connectDB"}        ]      },      {        "n": "startServer",        "c": [          {"n": "registerRoutes"}        ]      }    ]  },  "s": {"nodes": 6, "depth": 3}}

Response (Full)

json

{  "query": "main",  "mode": "graph",  "depth": 3,  "root": {    "name": "main",    "file": "cmd/main.go",    "line": 10,    "children": [      {        "name": "initialize",        "file": "cmd/main.go",        "line": 15,        "children": [...]      }    ]  },  "stats": {    "nodes": 6,    "max_depth": 3  }}

{  "query": "main",  "mode": "graph",  "depth": 3,  "root": {    "name": "main",    "file": "cmd/main.go",    "line": 10,    "children": [      {        "name": "initialize",        "file": "cmd/main.go",        "line": 15,        "children": [...]      }    ]  },  "stats": {    "nodes": 6,    "max_depth": 3  }}

5. grepai_index_status

Check the health and status of the code index.

Parameters

Example Request

Response

json

{  "status": "healthy",  "project": "/path/to/project",  "embedder": {    "provider": "ollama",    "model": "nomic-embed-text",    "status": "connected"  },  "store": {    "backend": "gob",    "location": ".grepai/index.gob"  },  "index": {    "files": 245,    "chunks": 1234,    "last_updated": "2025-01-28T10:30:00Z"  },  "daemon": {    "running": true,    "pid": 12345  }}

{  "status": "healthy",  "project": "/path/to/project",  "embedder": {    "provider": "ollama",    "model": "nomic-embed-text",    "status": "connected"  },  "store": {    "backend": "gob",    "location": ".grepai/index.gob"  },  "index": {    "files": 245,    "chunks": 1234,    "last_updated": "2025-01-28T10:30:00Z"  },  "daemon": {    "running": true,    "pid": 12345  }}

Compact Format Reference

When compact: true, responses use abbreviated keys:

Full Key	Compact Key	Description
`query`	`q`	Search query or symbol
`results`	`r`	Results array
`total`	`t`	Total count
`count`	`c`	Count
`score`	`s`	Similarity score
`file`	`f`	File path
`line`	`l`	Line number(s)
`mode`	`m`	Trace mode
`depth`	`d`	Graph depth
`name`	`n`	Node name
`children`	`c`	Child nodes
`stats`	`s`	Statistics
`function`	`fn`	Function name

Token Efficiency

Compact mode reduces tokens significantly:

Error Responses

Index Not Found

Embedder Connection Failed

json

{  "error": "Cannot connect to embedding provider. Is Ollama running?",  "code": "EMBEDDER_UNAVAILABLE"}

{  "error": "Cannot connect to embedding provider. Is Ollama running?",  "code": "EMBEDDER_UNAVAILABLE"}

Symbol Not Found

Invalid Parameters

Best Practices for AI Integration

Use compact mode: Reduces token usage by ~80%
Limit results: Request only what you need
Check status first: Use grepai_index_status before searches
Handle errors: Check for error responses
Combine tools: Search + trace for full understanding

MCP Protocol Details

Request Format

json

{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "grepai_search",    "arguments": {      "query": "authentication",      "limit": 5,      "compact": true    }  }}

{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "grepai_search",    "arguments": {      "query": "authentication",      "limit": 5,      "compact": true    }  }}

Response Format

json

{  "jsonrpc": "2.0",  "id": 1,  "result": {    "content": [      {        "type": "text",        "text": "{\"q\":\"authentication\",\"r\":[...],\"t\":5}"      }    ]  }}

{  "jsonrpc": "2.0",  "id": 1,  "result": {    "content": [      {        "type": "text",        "text": "{\"q\":\"authentication\",\"r\":[...],\"t\":5}"      }    ]  }}

Output Format

MCP tools reference summary:

📚 GrepAI MCP Tools Reference
Tools available:
1. grepai_search   - Semantic code search   - Params: query*, limit, compact
2. grepai_trace_callers   - Find function callers   - Params: symbol*, compact
3. grepai_trace_callees   - Find function callees   - Params: symbol*, compact
4. grepai_trace_graph   - Build call graph   - Params: symbol*, depth, compact
5. grepai_index_status   - Check index health   - Params: verbose
* = required parameter
Compact mode: ~80% token reduction

📚 GrepAI MCP Tools Reference
Tools available:
1. grepai_search   - Semantic code search   - Params: query*, limit, compact
2. grepai_trace_callers   - Find function callers   - Params: symbol*, compact
3. grepai_trace_callees   - Find function callees   - Params: symbol*, compact
4. grepai_trace_graph   - Build call graph   - Params: symbol*, depth, compact
5. grepai_index_status   - Check index health   - Params: verbose
* = required parameter
Compact mode: ~80% token reduction

Source and attribution

Source:yoanbernabeu/grepai-skillsinskills/integration/grepai-mcp-toolsat commit382d402

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Response Type	Full	Compact	Savings
Search (5 results)	~800	~150	81%
Trace callers (10)	~600	~120	80%
Trace graph (depth 3)	~1200	~250	79%

Grepai Mcp Tools

GrepAI MCP Tools Reference

When to Use This Skill

Starting the MCP Server

Available Tools

1. grepai_search

Parameters

Example Request

Response (Compact)

Response (Full)

2. grepai_trace_callers

Parameters

Example Request

Response (Compact)

Response (Full)

3. grepai_trace_callees

Parameters

Example Request

Response (Compact)

4. grepai_trace_graph

Parameters

Example Request

Response (Compact)

Response (Full)

5. grepai_index_status

Parameters

Example Request

Response

Compact Format Reference

Token Efficiency

Error Responses

Index Not Found

Embedder Connection Failed

Symbol Not Found

Invalid Parameters

Best Practices for AI Integration

MCP Protocol Details

Request Format

Response Format

Output Format

Source and attribution

More from yoanbernabeu/grepai-skills

Grepai Trace Graph

Grepai Trace Callers

Grepai Trace Callees

Grepai Storage Postgres

Grepai Storage Gob

Grepai Search Tips

More in AI & Agents

Ppt Template Creator

Skill Development

Plugin Structure

Command Development

Claude Md Improver

Find Skills