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

> Learn how grep-mcp limits search results to 10 by slicing the Grep API response. Discover its efficient result capping mechanism and ensure concise output.

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

---

**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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), a constant defines the maximum number of results to return:

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

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

```json
{
  "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:

```python

# 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:

```json
{
  "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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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.