# How grep-mcp Validates Input Parameters for the grep_query Tool

> Learn how grep-mcp validates input parameters for its grep_query tool in server.py. Get user-friendly error messages for invalid input, not exceptions.

- Repository: [gal peretz/grep-mcp](https://github.com/galprz/grep-mcp)
- Tags: how-to-guide
- Published: 2026-02-19

---

**The `grep_query` tool in galprz/grep-mcp validates all arguments through explicit type and format checks in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), returning user-friendly error strings instead of raising exceptions when constraints like maximum length or required formatting are violated.**

The `grep_query` tool serves as the primary search interface for the galprz/grep-mcp project, enabling direct queries to the grep.app API through the Model Context Protocol (MCP). Before executing any network requests, the tool implements rigorous input validation to ensure data integrity and provide clear feedback to end users. Understanding how grep-mcp validates input parameters helps developers debug integration issues and ensures reliable search operations across code repositories.

## Validation Logic in src/grep_mcp/server.py

Inside [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), the `grep_query` function implements a defensive validation block immediately after its docstring. This approach ensures that malformed inputs never reach the external API, with each parameter undergoing specific constraint checks before assembly into the request payload.

### Query Parameter Validation (Required)

The `query` parameter is the only required argument and faces the strictest validation rules. The function first verifies that `query` exists and is a string instance, then checks that it contains non-whitespace content, and finally enforces a maximum length of 1000 characters.

```python
if not query or not isinstance(query, str):
    return "❌ Error: 'query' parameter is required and must be a non‑empty string"
if len(query.strip()) == 0:
    return "❌ Error: 'query' cannot be empty or only whitespace"
if len(query) > 1000:
    return "❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."

```

### Language Parameter Validation (Optional)

When provided, the `language` filter must be a non-empty string no longer than 50 characters. The validation ensures that empty strings or whitespace-only values are rejected while allowing valid language identifiers like `"python"` or `"javascript"`.

```python
if language is not None:
    if not isinstance(language, str) or len(language.strip()) == 0:
        return "❌ Error: 'language' parameter must be a non‑empty string when provided"
    if len(language) > 50:
        return "❌ Error: 'language' parameter is too long (max 50 characters)"

```

### Repository Parameter Validation (Optional)

The `repo` parameter requires precise formatting to match the `owner/repository` structure used by GitHub and similar platforms. Validation confirms the presence of exactly one forward slash and caps the total length at 100 characters.

```python
if repo is not None:
    if not isinstance(repo, str) or len(repo.strip()) == 0:
        return "❌ Error: 'repo' parameter must be a non‑empty string when provided"
    if "/" not in repo or repo.count("/") != 1:
        return "❌ Error: 'repo' parameter must be in format 'owner/repository' (e.g., 'fastapi/fastapi')"
    if len(repo) > 100:
        return "❌ Error: 'repo' parameter is too long (max 100 characters)"

```

### Path Parameter Validation (Optional)

For the `path` parameter, the validation ensures that directory or file path filters are non-empty strings with a maximum length of 200 characters, preventing excessively deep or malformed path specifications.

```python
if path is not None:
    if not isinstance(path, str) or len(path.strip()) == 0:
        return "❌ Error: 'path' parameter must be a non‑empty string when provided"
    if len(path) > 200:
        return "❌ Error: 'path' parameter is too long (max 200 characters)"

```

## Error Handling Strategy

Rather than raising exceptions that might interrupt the MCP runtime, `grep_query` returns descriptive error strings prefixed with `"❌ Error"`. This design choice allows the Model Context Protocol to surface validation failures directly to end users without crashing the server process. Each validation check operates independently, with the function returning immediately upon encountering the first constraint violation, ensuring predictable error messaging.

## Practical Usage Examples

The following examples demonstrate both successful parameter passing and common validation failures.

Valid search with all optional parameters:

```python
result = await grep_query(
    query="async def read(*",
    language="python",
    repo="galprz/grep-mcp",
    path="src/"
)
print(result)   # Returns JSON string with formatted search results

```

Invalid repository format triggers specific validation:

```python
result = await grep_query(
    query="socket",
    repo="invalid-repo-format"
)
print(result)

# Output:

# ❌ Error: 'repo' parameter must be in format 'owner/repository' (e.g., 'fastapi/fastapi')

```

Missing required query parameter:

```python
result = await grep_query(query="")
print(result)

# Output:

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

```

## Summary

- **Explicit type checking** ensures all parameters are strings before processing begins in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py).
- **Length constraints** protect against buffer overflow issues: 1000 characters for queries, 100 for repositories, 200 for paths, and 50 for languages.
- **Format validation** on the `repo` parameter enforces the `owner/repository` structure with exactly one forward slash.
- **Graceful error handling** returns user-friendly strings rather than raising exceptions, maintaining MCP server stability.
- **Whitespace trimming** prevents empty or invisible character submissions across all string parameters.

## Frequently Asked Questions

### What happens if I exceed the maximum character limits in grep_query?

If any parameter exceeds its defined length constraint—such as a query longer than 1000 characters or a repository string over 100 characters—the function immediately returns a specific error message indicating the maximum allowed length and terminates before making any API request.

### Why does grep-mcp return error strings instead of raising Python exceptions?

The tool returns formatted error strings to comply with the Model Context Protocol specification, allowing client applications to receive and display validation feedback without handling server-side crashes or stack traces that would disrupt the conversational AI workflow.

### How does the repository format validation work?

The validation logic checks that the `repo` string contains exactly one forward slash character, ensuring it follows the standard `owner/repository` format used by GitHub and similar platforms, while rejecting strings with zero or multiple slashes.

### Are there any restrictions on the language parameter values?

While the code validates that `language` is a non-empty string under 50 characters, it does not maintain a whitelist of valid programming languages; any string meeting the length and content requirements is accepted and passed directly to the grep.app API.