Maximum Allowed Query Length in grep-mcp: 1000 Character Limit and Error Handling

The maximum allowed query length in grep-mcp is 1000 characters; exceeding this limit triggers an immediate error return without contacting the grep.app API.

The grep-mcp repository implements a hard limit on query string length to prevent invalid API requests. This validation occurs before any network traffic is initiated, ensuring that overly long queries fail fast with a descriptive error message. Understanding this constraint is essential when building MCP (Model Context Protocol) integrations that rely on the grep_query tool.

Where Query Length Validation Occurs in grep-mcp

The query length check resides in src/grep_mcp/server.py at line 185. This location handles the grep_query tool implementation and performs input sanitization before constructing the API request.

According to the source code, the function explicitly checks the character count of the query parameter:

if len(query) > 1000:
    return "❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."

This early-return pattern prevents unnecessary network overhead and API rate limit consumption. The validation logic is part of the core server implementation exposed through src/grep_mcp/__init__.py, which registers the tool with the MCP framework.

What Happens When You Exceed the Maximum Query Length

When a query string exceeds 1000 characters, grep-mcp immediately returns an error string without contacting the grep.app API. The error message follows this exact format:

❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query.

This behavior ensures that:

• No invalid requests reach the external API
• Users receive immediate feedback about query length constraints
• Network resources are conserved for valid queries

The error surfaces directly to the MCP client, allowing AI assistants to detect the failure and suggest query refinement strategies to users.

Code Examples: Valid and Invalid Queries

The following examples demonstrate the 1000-character boundary in grep-mcp:

Valid Query (Under 1000 Characters)

from grep_mcp import grep_query

# 50 characters - well within limit

result = await grep_query("asyncio timeout handling patterns")
print(result)  # Returns JSON with search results

Invalid Query (Exceeds 1000 Characters)

from grep_mcp import grep_query

# Generate 1001 characters

long_query = "x" * 1001

error = await grep_query(long_query)
print(error)

# Output: ❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query.

In production MCP environments, the tool would surface this error to the assistant, which could then prompt the user to break the query into smaller segments or remove unnecessary terms.

Why the 1000 Character Limit Exists

The maximum allowed query length in grep-mcp aligns with the underlying grep.app API constraints. By enforcing this limit client-side, the repository:

1. Prevents API errors that would result from over-length queries
2. Reduces latency by failing fast before network transmission
3. Conserves rate limits on the grep.app service
4. Improves user experience through clear, actionable error messages

The validation at src/grep_mcp/server.py:185 serves as a guardrail that maintains compatibility between the MCP tool and the external search service.

Summary

• The maximum allowed query length in grep-mcp is 1000 characters, enforced in src/grep_mcp/server.py at line 185.
• Exceeding this limit triggers an immediate error return: "❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query."
• No API request is made when the limit is exceeded, conserving network resources and providing fast feedback.
• The constraint aligns with grep.app API limitations and ensures reliable MCP tool operation.

Frequently Asked Questions

What is the exact maximum query length allowed in grep-mcp?

The exact maximum query length is 1000 characters. This limit is hardcoded in the query validation logic within src/grep_mcp/server.py at line 185. Any string exceeding this length, including whitespace and special characters, will trigger the length validation error.

Does grep-mcp truncate long queries automatically?

No, grep-mcp does not truncate long queries. Instead, it performs a strict validation check and returns an error message immediately if the query exceeds 1000 characters. The function returns the string: "❌ Error: 'query' is too long (max 1000 characters). Please use a shorter query." without contacting the grep.app API.

Where in the source code is the query length check implemented?

The query length validation is implemented in src/grep_mcp/server.py at line 185. This location is within the grep_query tool function, which handles the MCP tool execution. The check occurs before any network request construction, serving as an early validation gate for input parameters.

What happens if I send a query with exactly 1000 characters?

A query with exactly 1000 characters is considered valid and will be processed normally. The validation logic uses a greater-than comparison (len(query) > 1000), so 1000-character queries pass the check and proceed to the grep.app API call. Only queries of 1001 characters or more trigger the error response.

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