io.github.VelvetSP/web-retrieval-mcp

Overview Schema Source Related Servers Discussions Admin

research_github

Read-only

Search GitHub issues, pull requests, READMEs, and documentation to find code, bug fixes, API contracts, and discussions using natural-language queries. Returns Markdown passages for easy consumption.

Instructions

Search developer primary sources via the Firecrawl Developer Index: GitHub issues, merged pull requests and repository READMEs, PLUS curated documentation sites. Returns the matched passages in Markdown, so tables and code blocks survive. Use to find the CODE behind a paper, the issue where a bug was reported and fixed, an API contract, or the discussion behind an error message.

Args: query: natural-language query (method, kernel, repo topic, error message). k: number of results (1–25, default 8). passages: matched passages per result (1–5, default 2). types: restrict to any of exactly "doc", "issue", "pull_request", "readme". NOTE the request spelling is pull_request (snake_case). The response's repos[].types object uses camelCase (pullRequest) — echoing a key from there back into this argument is refused, not silently ignored. repos: "owner/repo" slugs. Scopes only the repository half of the index, so when types is also given it must contain at least one of issue/pull_request/readme.

Falls back to the de-documented legacy /v2/search/research/github ONLY when the Developer Index genuinely fails (transport, HTTP, malformed envelope, or every requested type unavailable) — never on a legitimate empty result, and never when types/repos were supplied, since the legacy endpoint accepts only query+k and would silently answer a different question than the one asked.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`k`	No
`query`	Yes
`repos`	No
`types`	No
`passages`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses valuable behavioral details: results are returned in Markdown, the request spelling `pull_request` differs from the response's camelCase `pullRequest`, echoing a response key is refused rather than ignored, and the legacy fallback is strictly conditioned. This gives the agent a clear model of how the tool behaves in edge cases.

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

Conciseness5/5

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

The description is front-loaded with the core purpose, followed by compact use-case examples, a clean Args breakdown, and a necessary fallback caveat. It is long but densely informative; every sentence contributes operational value and no filler is present.

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

Completeness5/5

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

Given the tool's five parameters, legacy fallback, and naming-format pitfalls, the description is remarkably complete. It covers input semantics, constraints, edge-case behavior, and return format, while the presence of an output schema means detailed return structure documentation is not required here.

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

Parameters5/5

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

Schema description coverage is 0%, but the description compensates fully by explaining every parameter: query's natural-language intent, k and passages ranges with defaults, valid types values, and repos format. It also documents the critical interaction between repos and types and the snake_case/camelCase pitfall.

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?

The description opens with a specific verb and resource: 'Search developer primary sources via the Firecrawl Developer Index', and enumerates the exact source types (GitHub issues, merged pull requests, READMEs, curated documentation). It also gives concrete use cases like finding the code behind a paper or a bug discussion, which clearly separates it from generic web search and paper-focused siblings.

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

Usage Guidelines4/5

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

The description provides strong when-to-use guidance with explicit use cases and a detailed fallback policy explaining when the legacy endpoint may and may not be used. However, it does not explicitly name sibling alternatives like web_search or research_papers or state when to prefer them over this tool.

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

Deploy Server