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

> Discover how grep-mcp handles empty or whitespace-only queries. Learn about its robust validation process in server.py for immediate error messaging before API requests.

- Repository: [gal peretz/grep-mcp](https://github.com/galprz/grep-mcp)
- Tags: internals
- Published: 2026-02-16

---

**grep-mcp validates all search queries in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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:

```python
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:

```python
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:

```python

# 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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py). The error messages are hardcoded strings returned directly from the validation checks.