Result Limiting Mechanism in grep-mcp: How It Caps Search Results at 10

The grep-mcp server enforces a hard-coded limit of 10 results by slicing the raw Grep API response array, ensuring concise outputs regardless of how many total matches the API returns.

The result limiting mechanism in grep-mcp is designed to prevent overwhelming downstream consumers with excessive data. Located in the core server implementation, this logic intercepts the raw search results from the Grep API and truncates them before formatting the final JSON response.

How grep-mcp Implements Result Limiting

The limiting strategy relies on a simple but effective slice operation applied to the incoming hits array. This approach ensures consistent performance and predictable response sizes across all queries.

The Hard-Coded Limit Constant

Inside src/grep_mcp/server.py, a constant defines the maximum number of results to return:

result_limit = 10

This variable is defined immediately before the hit-processing loop at lines 295-298. The value is static and does not adjust based on query parameters or result set size.

Slicing the API Response

The server applies the limit by slicing the raw hits array returned by the Grep API:

for hit in hits[:result_limit]:
    # Process and format each hit...

This operation at lines 298-301 ensures that only the first ten entries of the potentially large hits array are iterated over and included in the response. The remaining matches are discarded without processing.

Impact on the JSON Output

After grouping the selected hits by repository, the response includes a summary field indicating how many results survived the limit:

{
  "summary": {
    "total_results": 42,
    "results_shown": 10
  }
}

The results_shown field (lines 49-51 in the source) always reflects the capped count, providing transparency to the consumer about the truncation.

Code Example: Querying with Result Limits

When invoking the grep_query tool registered with FastMCP, the limit applies automatically regardless of filters:

# Example: Using the Grep MCP tool from an LLM-driven workflow

await grep_query(
    query="def parse_json",
    language="python",
    repo="pallets/flask",
    path="src/"
)

The resulting JSON payload demonstrates the limiting mechanism in action:

{
  "query": "def parse_json",
  "summary": {
    "total_results": 42,
    "results_shown": 10,
    "repositories_found": 3,
    "top_languages": ["python"],
    "top_repositories": ["pallets/flask"]
  },
  "results_by_repository": [
    {
      "repository": "pallets/flask",
      "matches_count": 6,
      "files": [
        {
          "file_path": "src/flask/json.py",
          "branch": "main",
          "total_matches": 1,
          "line_numbers": [12],
          "language": "python",
          "code_snippet": "```python\ndef parse_json(...):\n    ...\n```"
        }
      ]
    }
  ]
}

Even though the raw API reported 42 matches, only the first ten are processed and returned.

Summary

• Hard-coded constant: The limit is defined as result_limit = 10 in src/grep_mcp/server.py.
• Array slicing: The server slices the raw hits array using hits[:result_limit] to truncate results before processing.
• Transparent reporting: The results_shown field in the JSON response indicates exactly how many results were included (maximum 10).
• Consumer protection: This mechanism prevents overwhelming downstream systems with excessive data from large result sets.

Frequently Asked Questions

Why does grep-mcp limit results to 10?

The 10-result limit ensures concise responses that fit within typical context windows of LLM-driven workflows and prevents overwhelming the caller with excessive data. According to the source code in src/grep_mcp/server.py, this balance provides sufficient context for most code search tasks while maintaining fast response times.

Can I increase the result limit in grep-mcp?

No, the result limit is hard-coded as a constant result_limit = 10 in src/grep_mcp/server.py at lines 295-298. There is no configuration parameter or environment variable exposed to modify this value. To return more results, you would need to fork the repository and modify the source code directly.

How does the result limiting affect the API response structure?

The limiting occurs before the response formatting stage, so the JSON structure remains consistent regardless of how many results are returned. The summary.results_shown field always indicates the actual number of results included (capped at 10), while summary.total_results shows the full count available from the Grep API. The results_by_repository array only contains entries for the repositories represented in the first ten hits.

Where is the result limiting logic located in the source code?

The result limiting mechanism is implemented in src/grep_mcp/server.py within the helper function that converts raw Grep API payloads into the final JSON structure. Specifically, lines 295-298 define the result_limit = 10 constant, and lines 298-301 perform the slicing operation for hit in hits[:result_limit]: to enforce the cap during hit processing.

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