How grep-mcp Handles Empty or Whitespace-Only Search Queries

grep-mcp validates all search queries in src/grep_mcp/server.py by enforcing type checks and whitespace detection before sending requests to the grep.app API, returning immediate error messages for invalid inputs.

When building MCP (Model Context Protocol) tools that interface with external search APIs, robust input validation prevents unnecessary network requests and improves user experience. The grep-mcp repository implements strict validation logic for its grep_query tool to handle edge cases like empty strings and whitespace-only queries.

Validation Logic in grep-mcp

The validation occurs within the grep_query async function in src/grep_mcp/server.py (lines 78-84). This implementation uses a two-stage validation approach that short-circuits execution before any API communication begins.

Type and Existence Checks

First, the code verifies that the query parameter exists and is a string type:

if not query or not isinstance(query, str):
    return "❌ Error: 'query' parameter is required and must be a non-empty string"

This check catches both None values and non-string types (such as integers or dictionaries) that might be passed incorrectly by MCP clients.

Whitespace Detection

After confirming the input is a valid string, the code strips leading and trailing whitespace and checks the remaining length:

if len(query.strip()) == 0:
    return "❌ Error: 'query' cannot be empty or only whitespace"

This prevents queries containing only spaces, tabs, or newline characters from reaching the grep.app API.

Error Handling and User Feedback

When validation fails, grep-mcp returns descriptive error messages immediately without constructing URLs or initiating HTTP requests. This approach provides several benefits:

• Performance: No network overhead for invalid inputs
• API protection: Reduces unnecessary load on the grep.app service
• Developer experience: Clear, actionable error messages help debug MCP client implementations

Practical Code Examples

The following examples demonstrate how the validation handles various edge cases:

# Example 1: Empty string

await grep_query("")

# Returns: "❌ Error: 'query' parameter is required and must be a non-empty string"

# Example 2: Whitespace-only string

await grep_query("   \t\n")

# Returns: "❌ Error: 'query' cannot be empty or only whitespace"

# Example 3: Valid search term

await grep_query("asyncio")

# Proceeds to query the grep.app API and returns JSON results

Summary

• grep-mcp implements strict input validation in src/grep_mcp/server.py to handle empty and whitespace-only queries
• The validation uses a two-stage approach: type checking followed by whitespace detection
• Invalid queries return immediate error messages without contacting the external API
• This design pattern protects downstream services and improves response times for MCP clients

Frequently Asked Questions

What happens if I pass a null value to the grep_query tool?

If the query parameter is None or omitted, the type check if not query or not isinstance(query, str) triggers immediately, returning the error: "❌ Error: 'query' parameter is required and must be a non-empty string".

Does grep-mcp trim whitespace from valid queries before searching?

Yes, the code uses query.strip() to check for whitespace-only content, but it does not modify the original query variable before sending it to the API. The validation check len(query.strip()) == 0 determines if the query contains only whitespace characters.

Where is the validation logic located in the repository?

The validation logic resides in src/grep_mcp/server.py within the grep_query async function, specifically around lines 78-84. This file contains the MCP tool implementation that interfaces with the grep.app API.

Can I modify the error messages returned for empty queries?

Yes, since grep-mcp is open-source, you can fork the repository and modify the string literals in the return statements within src/grep_mcp/server.py. The error messages are hardcoded strings returned directly from the validation checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}