Skip to main content
Glama
github-fetcher

github-fetcher

by KurvCygnus

GitHub file grep

github_file_grep
Read-onlyIdempotent

Search a single GitHub file with a regular expression and get line numbers plus context. Use it to pinpoint where patterns occur in one file instead of scanning whole repos.

Instructions

Search a single file's text with a regular expression and get line numbers with context. Cache-first: a warm cache costs zero upstream calls; a miss costs 1 core call. Use github_search_code for repo-wide or cross-repo search (30 requests/minute, GitHub index lag). Matching runs in a worker thread with a 2000 ms (default; GITHUB_MCP_GREP_TIMEOUT_MS) time budget; overruns degrade to matches_truncated instead of blocking the session. Returns {repo, path, ref, pattern, total_lines, matches, matches_truncated, meta}; an overrun returns no matches and carries hint instead.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "repo": "<repo>",
      "path": "<path>",
      "pattern": "<pattern>"
    },
    "name": "github_file_grep"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoBranch, tag, or commit; defaults to the repository default branch
pathYesFile path inside the repository
repoYesRepository in owner/name form
freshNoBypass the local cache
patternYesRegular expression (JavaScript syntax) matched globally over the file text; matches report 1-based line and column
max_matchesNoMaximum number of matches to return; defaults to 50; matches_truncated reports more remained
context_linesNoContext lines before and after each match; defaults to 2

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: cache-first cost model, worker-thread execution, a 2000 ms time budget with env override, and graceful degradation to matches_truncated rather than blocking. It even discloses the overrun edge case where no matches are returned and a hint is carried instead. Slight gap: it doesn't say what the hint content looks like, but this is well above the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and scope, then cost model, then timeout semantics, then return shape. Dense but every sentence carries information; the only mild cost is the compressed technical packing that makes it harder to scan quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the return fields (repo, path, ref, pattern, total_lines, matches, matches_truncated, meta) and the degraded-response shape. Combined with the alternative-tool routing and timeout behavior, an agent has what it needs to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining the cache semantics that govern the fresh parameter and by tying max_matches truncation to the matches_truncated output flag. It doesn't restate ref/path/pattern formats, which the schema already handles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: regex text search within a single file, returning line numbers with context. It explicitly contrasts scope with github_search_code (repo-wide/cross-repo), so an agent can pick between them without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing guidance: use this tool for one file, use github_search_code for repo-wide or cross-repo search, and even names that alternative's constraints (30 requests/minute, index lag). No exclusions are left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.