Skip to main content
Glama
Hemanth-hexo

GitHub Discovery MCP Server

by Hemanth-hexo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Gitty

An MCP server that helps Claude find, inspect, and compare open-source GitHub repos.

Test

An MCP server that helps Claude find relevant open-source GitHub repositories for research, learning, or a project you're building — and then dig into a specific repo's structure, code, history, and branches once you've found it worth a closer look.

Try it now — genuinely public, no setup: https://git-mcp-rvrp.onrender.com/mcp is live and open to anyone. In Claude, go to Settings → Connectors → Add custom connector, paste that URL, set Authentication to None, and connect — no token, no signup. It's free tier, so the first request after a few idle minutes can take 30-60 seconds to wake up — that's expected, just retry. See Rate limits if you want higher limits than the shared free tier gives you.

What it does

Discovery — find repos from a description or topic:

  • search_github_repos(query, filters) — free-text search, ranked by a blend of stars and recent activity so an actively maintained project can beat a similarly popular but abandoned one

  • search_by_topic(topic, filters) — search by GitHub's curated topic tags (e.g. rag, llm-agent) instead of free text

  • get_trending_repos(since, filters) — repos created recently that are already gaining stars fast, as an approximation of "trending" (GitHub's API has no official trending endpoint)

Inspection — once you've picked a repo, look inside it:

  • get_repo_overview(repo) — description, stars/forks/issues, license, topics, language breakdown, latest release, approx. contributor count, and a README preview

  • get_repo_structure(repo, path) — browse the file tree one directory at a time

  • get_file_content(repo, path) — read a specific file's contents

  • get_recent_commits(repo, branch, limit) — recent commit history

  • list_branches(repo, limit) — branches and what each currently points to

Comparison — deciding between a few candidates:

  • compare_repos(repos) — 2-4 repos side by side as a table (stars, forks, issues, license, language, contributors, age, activity)

All the repo parameters above accept either "owner/name" or a full GitHub URL — you can paste the full_name/URL straight out of a search result.

Shortcuts — MCP clients that support "prompts" (Claude Desktop, Claude Code, claude.ai) surface these as slash commands, e.g. /gitty:getinfo:

  • /getinfo repo:<owner/name> — full repo overview

  • /getcodeinfo repo:<owner/name> path:<file path> — read and explain one file

  • /findrepos query:<what you're looking for> — search

  • /comparerepos repos:<comma-separated list> — side-by-side comparison

These don't add any capability beyond the tools above — they're just a shortcut for the handful of things people ask for most, so you don't have to phrase the same request in full sentences every time. See tools/prompts.js.

Related MCP server: GitBridge

Requirements

  • Node.js 20 or later

  • No GitHub account or API key required for light use — see Rate limits for when you'll want one

Run it locally (optional)

Most people should just use the shared link above. Run it on your own machine instead only if you want to skip Render entirely — e.g. for development, or to avoid any shared rate limits.

git clone https://github.com/Hemanth-hexo/Git_mcp.git
cd Git_mcp
npm install

Or run it in Docker (mainly useful for deploying somewhere other than Render, which builds natively and doesn't need this):

docker build -t gitty-mcp .
docker run -p 3000:3000 --env GITHUB_TOKEN=your_token_here gitty-mcp

Add to Claude Desktop's config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), using the absolute path to server.js:

{
  "mcpServers": {
    "gitty": {
      "command": "node",
      "args": ["/absolute/path/to/Git_mcp/server.js"]
    }
  }
}

Restart Claude Desktop. No token needed here — this runs as a local process, not over the network, so the HTTP auth in Security doesn't apply. Optionally add GITHUB_TOKEN in an env block to raise GitHub's rate limits (see Rate limits). For quick manual testing without Claude Desktop at all, npm run inspect opens a local web UI to call tools by hand.

Deploy as a shared connector (a URL instead of a local install)

Everything above runs the server as a local process only you can use. To make it available to anyone — friends, strangers, whoever — without them installing anything, deploy server-http.js instead: it's the same tools over Streamable HTTP, so anyone can add it in Claude as a custom connector by pasting a URL (works on claude.ai, Claude Desktop, Cowork, and mobile — see Anthropic's docs).

Deploy to Render (free tier is fine to start):

  1. Push this repo to GitHub (already done if you're reading this from the repo).

  2. On render.com, create a new Web Service and connect this GitHub repo.

  3. Set the Build Command to npm install and the Start Command to npm run start:http. Leave the instance type on Free to start.

  4. Deploy. Render assigns a URL like https://your-app-name.onrender.com — MCP clients connect to https://your-app-name.onrender.com/mcp (note the /mcp, the bare domain only serves a health-check page).

That's it — no token setup required. The server is public by design: anyone with the URL can use it immediately.

(Optional) In Render's Environment tab, you can still add:

  • PUBLIC_HOST — just the hostname (e.g. your-app-name.onrender.com, no https://). Locks the server to that hostname instead of accepting any Host header — protects against DNS-rebinding-style tricks, not a login of any kind.

  • GITHUB_TOKEN — a personal access token this server falls back to for anonymous callers who don't bring their own (see Rate limits). Optional; the server works fine without it.

  • GEMINI_API_KEY — funds a small free daily trial of the AI-explanation feature for every visitor (see AI explanations). Optional; without it, that feature just asks people to bring their own AI API key instead.

Connect in Claude: Settings → Connectors → Add custom connector → paste https://your-app-name.onrender.com/mcp → set Authentication to None (this server doesn't use OAuth or any login) → connect. Share the URL with anyone — that's the whole distribution step, nothing else to hand out.

Worth knowing:

  • Render's free tier spins the service down after 15 minutes of inactivity; the next request after that takes 30-60 seconds to wake it back up.

  • Because it's genuinely open, GitHub's own rate limits are the only thing standing between this and abuse — see Rate limits for how that's handled and what its limits are.

REST API (for a web frontend, or anything that isn't an MCP client)

Everything above is for MCP clients (Claude, etc.). The same server also exposes a plain JSON REST API under /api — same deployment, same rate limiting, same bring-your-own-GitHub-token support, no MCP protocol involved. This is what a website or app would call directly. CORS is open (Access-Control-Allow-Origin: *) so it can be called straight from browser JavaScript on any origin — this is a fully public, read-only, unauthenticated-by-default API, so that doesn't widen access to anything.

Method & path

Query params

What it does

GET /api/search

q (required), language, minStars, limit

Free-text repo search

GET /api/search/topic

topic (required), language, minStars, limit

Search by GitHub topic tag

GET /api/trending

since (daily|weekly|monthly), language, minStars, limit

New repos gaining stars fast

GET /api/repos/:owner/:name

—

Full repo overview

GET /api/repos/:owner/:name/structure

path

List files/folders at a path

GET /api/repos/:owner/:name/file

path (required)

Read one file's contents

GET /api/repos/:owner/:name/commits

branch, limit

Recent commits

GET /api/repos/:owner/:name/branches

limit

List branches

POST /api/repos/:owner/:name/explain

headers: X-AI-Key, X-AI-Provider (both optional)

AI-generated explanation of the repo — see AI explanations

POST /api/compare

body: {"repos": ["owner/name", ...]} (2-4)

Side-by-side comparison

All responses are JSON. Send Authorization: Bearer <your GitHub token> on any request to use your own rate limit instead of the shared pool — identical to how the MCP connector's bring-your-own-token works. Errors come back as {"error": "<code>", "message": "..."} with a matching HTTP status (400 bad input, 404 not found, 429 rate limited with a Retry-After header, 502/500 for upstream/unexpected failures) — internal details are never included, same policy as the MCP error path (see Security).

Example:

curl "https://git-mcp-rvrp.onrender.com/api/search?q=rag&limit=3"
curl "https://git-mcp-rvrp.onrender.com/api/repos/facebook/react"

See routes/api.js for the exact route definitions, and core/ for the underlying logic — both the MCP tools and this API call the same functions there, so a bug fix or improvement in one benefits both automatically.

Web frontend

A plain HTML/CSS/JS website in web/ — search, repo detail (overview/files/commits/branches), and compare, all calling the REST API above. No build step, no framework: it's static files, so it deploys to Vercel (or any static host) by pointing it at the web/ folder directly.

Deploy to Vercel:

  1. Import this GitHub repo into Vercel.

  2. Set Root Directory to web, framework preset to Other (no build command needed — it's static).

  3. Deploy. That's it.

Run it locally:

cd web
npx serve .

It defaults to calling the live Render API. To point it at a local backend instead (e.g. while developing the API), open it with ?api= before the #, e.g. http://localhost:3000/?api=http://localhost:3000/api#/.

Security note on rendering repo content: README files and AI explanations come from arbitrary public repos (or an AI model summarizing them) and are rendered as Markdown via marked — which does not sanitize embedded raw HTML on its own. Everything rendered this way is passed through DOMPurify first (see renderMarkdown() in web/app.js); a malicious repo's README can't inject a working <script> tag through this page.

AI explanations

The Overview tab has an "✨ Explain this repo with AI" button — a genuinely thorough, decision-ready briefing generated from the README, repo stats (license, activity, contributor count, archived status, etc.), and a small sample of the repo's actual source code, not just a summary of the README. core/explain.js picks a manifest file (package.json, pyproject.toml, go.mod, etc.) plus one or two representative source files — searching conventionally-named directories (src, lib, packages, ...) breadth-first when the real code isn't at the repo root, which is the common case — so the write-up can comment on actual code, not just what the README claims. It covers up to eight sections depending on what's available: What it is, How it works, Code quality notes (only when source was sampled), Who it's for, Getting started, Strengths, Watch out for, and a direct Verdict ("use this if ___, skip it if ___") — aiming for ~700-1000 words, enough that someone shouldn't need to go ask a different AI follow-up questions about the same repo. This is the one place in the whole project that calls an LLM; everything else is deterministic GitHub API aggregation.

Two ways it gets paid for:

  1. The operator's free trial — if you (the operator) set a GEMINI_API_KEY environment variable (Google's Gemini API has an actual free tier, unlike most providers), every visitor gets a few free explanations per day, tracked per caller IP (see lib/aiTrialQuota.js) so it can't run up an unbounded bill. No key configured = no free trial; the button then just asks people to bring their own.

  2. Bring your own key — anyone can add their own Gemini or Anthropic API key in the website's Settings panel (stored only in their browser, sent as X-AI-Key/X-AI-Provider headers directly to the API). Unlimited use, at their own cost, and it never touches the trial quota.

If neither is available for a given request, the endpoint fails clearly (503, "bring your own key") rather than a confusing provider error.

This is the exact same shift-the-cost-to-whoever-wants-it pattern as the GitHub bring-your-own-token design (see Rate limits) — applied to AI instead of GitHub's API. The same trust note applies too: a bring-your-own AI key is sent to this server, which then calls Gemini/Anthropic on your behalf (the same shape as the GitHub token flow) — it is never sent directly from your browser to the AI provider. Verified by test that the key never appears in a log line, error message, or request body (see test/aiProvider.test.js), but that's a claim about this specific deployment, not a platform guarantee — the same "treat it like handing a password to a site you didn't build" caution applies here too.

Example prompts

Once connected, just talk to Claude naturally:

  • "Find me RAG implementation repos"

  • "Show me containerization examples in Go"

  • "What's trending in agent frameworks this week?"

  • "Find repos tagged with vector-database"

  • "Give me an overview of huggingface/transformers"

  • "What's the file structure of that repo look like?"

  • "Show me the recent commits on it"

  • "Compare langchain, llamaindex, and haystack for me"

Rate limits

GitHub's REST API has two separate rate-limit buckets, and this server's tools split across both:

Bucket

Used by

Anonymous

With a token

search

search_github_repos, search_by_topic, get_trending_repos

10 requests/min

30 requests/min

core

get_repo_overview, get_repo_structure, get_file_content, get_recent_commits, list_branches, compare_repos

60 requests/hour

5,000 requests/hour

The search bucket is generous enough for casual interactive use. The core bucket is not — it resets hourly, not per-minute, and some tools spend more than one request per call (get_repo_overview makes up to 4, compare_repos makes 2 per repo compared).

How tokens work on the deployed connector (this is the key design point): the server is public and takes no login, but it does read an optional Authorization: Bearer <token> header — and if you put your own GitHub personal access token there (no scopes needed), your requests use your own rate limit, not a pool shared with every other stranger using the same link. Order of priority per request:

  1. Your own GitHub token, if you sent one — you get your own 5,000/hour, unaffected by anyone else's usage.

  2. The operator's GITHUB_TOKEN (if set on the server) — a shared fallback pool for anonymous callers.

  3. Otherwise, GitHub's fully anonymous limit — the 60/hour (or 10/min search) figures above, shared across everyone not bringing their own token.

To use your own token when connecting in Claude: Add custom connector → Authentication: None → Additional request headers → Add header → name Authorization, value Bearer <your GitHub token>. Entirely optional — the server works with zero setup, this just gets you a bigger, un-shared quota.

If you do bring your own token, two things worth knowing:

  • You're trusting this server's operator not to log or misuse it — verified in code and by test that it never is (see Security), but that's a claim about this specific deployment, not a platform guarantee. Treat any third-party MCP connector's request for your token the same way you'd treat handing a password to a website you didn't build.

  • Use a token scoped to read-only, public-repo access only (no repo write scope, no admin/org scopes) — this server only ever makes read requests, but a token with broader permissions than that is unnecessary risk if it were ever exposed, regardless of how this server itself behaves. If your token happens to have access to private repos, this server will read those too when asked — same as any GitHub API client using that token would.

This server also has its own, separate rate limit — 30 requests/minute per caller (by IP), regardless of GitHub tokens. This isn't about GitHub's API quota; it protects this server's own bandwidth/compute from being hammered directly (see lib/rateLimit.js). Hitting it returns 429 with a Retry-After header and resets a minute later — normal interactive use won't come close to it.

Running locally (server.js/stdio), the same priority applies except there's no per-request header to bring — set GITHUB_TOKEN in the Claude Desktop config's env block (or your shell) to raise your own limit.

Response caching further reduces load on the shared/anonymous pool. Repo lookups, file contents, and search results are cached in memory for 5 minutes — so if two different people (or the same person twice) ask about the same repo or search within that window, only the first request actually calls GitHub; the rest are served from cache, instantly and without spending any quota. This only ever applies to anonymous/server-token requests, never to a caller's own token (two different tokens can have different access to the same URL, so caching across them could leak one caller's data to another — see Security and lib/cache.js). Verified live: a repeated get_repo_overview call dropped from ~1.4s to ~1ms.

If a rate limit is hit, the server returns a clear message (instead of failing silently) telling you when it resets and reminding you that bringing your own token is an option.

Security

This server underwent a security review, then a deliberate follow-up change: it moved from a single shared access token to fully public access with optional per-caller GitHub tokens (see Rate limits). Current posture:

  • Input validation — every tool argument is validated against a Zod schema before the handler runs; malformed input is rejected before it reaches any network call.

  • Public by design (HTTP transport) — /mcp takes no login and rejects nothing based on identity. It optionally reads an Authorization: Bearer <token> header and, when present, uses that value as that caller's own GitHub token for GitHub API calls made on their behalf — see lib/auth.js and createGitHubClient in lib/github.js. A caller's token is used only for their own request and never stored, logged, or reused for anyone else (verified by test — see test/githubClient.test.js's "no cross-caller leakage" case). server.js (stdio, for local/Claude Desktop use) is a separate, locally-spawned process, inherently scoped to whoever can run commands on that machine.

  • Untrusted content boundary — README previews and file contents fetched from GitHub repos are wrapped in explicit [UNTRUSTED CONTENT] delimiters with an instruction not to treat them as commands, and the two tool descriptions that return this content say the same. This is a mitigation for indirect prompt injection (a malicious repo's README or source could otherwise contain text phrased as instructions to the model reading it) — framing, not content filtering; the underlying text is never altered or stripped.

  • SSRF-safe file downloads — get_file_content follows GitHub's download_url for large files only if it resolves to https://raw.githubusercontent.com; any other host or scheme is refused rather than fetched (see isAllowedDownloadUrl in lib/github.js).

  • No write access — every GitHub API call this server makes is a read (GET). There is no code path that can create, modify, or delete anything on GitHub — including with a caller-supplied token, which is only ever attached to the same read-only calls every other request makes.

  • Error handling — GitHub API errors return their normal (already-safe) user-facing text. Any unexpected exception is logged in full server-side and reduced to a generic message for the client — internal details (stack traces, file paths, dependency internals) are never returned in a tool result. No token (a caller's own or the operator's GITHUB_TOKEN) is ever logged, echoed in output, or embedded in a URL.

  • Caller-token forwarding was verified, not assumed — since accepting an arbitrary caller-supplied credential and attaching it to outbound requests is the one genuinely new attack surface this change introduces, it was tested directly: an attempted header-injection payload (embedded CR/LF in the token) is rejected by Node's own fetch with a clean TypeError before any request leaves the server, caught by the existing error handling with no crash. A caller's token is confirmed (by code inspection and by test/githubClient.test.js) to reach only createGitHubClient — it's never interpolated into a log line, error message, or response text.

  • Per-caller rate limiting on this server itself — 30 requests/minute per IP, independent of GitHub's own limits; see Rate limits and lib/rateLimit.js. Protects the server's own bandwidth/compute from being hammered directly, which GitHub's API limits alone don't cover (they only throttle GitHub calls, not requests that never get that far).

  • Basic request logging — every /mcp request logs its timestamp, caller IP, JSON-RPC method, and tool name (for tools/call) to stderr (visible in Render's Logs tab). Deliberately excludes tool arguments, query text, and tokens — see lib/requestLog.js and its tests for what is and isn't logged.

  • CI — every push to main and every pull request runs the full test suite via GitHub Actions (.github/workflows/test.yml); the badge at the top of this README reflects the current status.

  • Response cache never crosses the token boundary — caching (see Rate limits) only applies when a request carries no caller-supplied token; a request bringing one always fetches fresh. This is deliberate: two different tokens can have different access to the same URL (e.g. a private repo), and a shared cache entry keyed only by URL would otherwise be able to serve one caller's authorized data to a different, unauthorized caller. Tested directly (see test/githubClient.test.js's "does not pollute the anonymous cache" and "never cached" cases).

  • AI-generated text is sanitized identically to README content — the web frontend renders both through the same renderMarkdown() (marked + DOMPurify) pipeline, so even if a repo's README contained a prompt-injection attempt that influenced the AI's output, the rendered result still can't execute a script in the viewer's browser.

  • The AI-explain trial has its own separate, much stricter budget — lib/aiTrialQuota.js caps the operator-funded free tier at a few calls per caller per day, independent of the general 30/minute rate limiter, since this one bounds real API spend rather than just server load. A caller bringing their own AI key skips this budget entirely (see AI explanations).

Remaining risks / not covered here:

  • Rate limiting is per-IP, not per-identity — there's no login, so a caller behind a shared/rotating IP (or simply willing to rotate IPs) isn't meaningfully throttled by this alone. It stops accidental or unsophisticated hammering, not a determined attacker.

  • Logging is basic (stderr text, 7-day retention on Render's free tier) — there's no persistent store, dashboard, or alerting on top of it; someone has to go look at the logs.

  • PUBLIC_HOST (Host-header validation) is still available and recommended, but it only restricts which hostname the server answers on the network layer — it has nothing to do with who's allowed to use the tools, since there's no identity concept here at all.

  • The trial quota (like the general rate limiter) is keyed by IP, not identity — the same caveat about shared/rotating IPs applies to AI-spend protection too, just with a much smaller daily budget at stake.

Project files

  • server.js — local entry point; serves the tools over stdio (for Claude Desktop / the Inspector)

  • server-http.js — deployable entry point; serves the same tools over Streamable HTTP, plus mounts the REST API, for a shared connector URL

  • lib/createServer.js — the shared McpServer factory both entry points use

  • core/discovery.js, core/inspect.js, core/compare.js — the actual GitHub logic (search ranking, repo inspection, comparison), as plain functions returning plain data. Both the MCP tools and the REST API call these directly — one implementation, two interfaces.

  • core/explain.js — builds the "explain this repo" prompt from repo data and calls whichever AI provider applies

  • routes/api.js — the REST API (see above); thin JSON/HTTP-status wrapping over core/

  • web/ — the static frontend (search, repo detail, compare); see Web frontend

  • tools/discovery.js, tools/inspect.js, tools/compare.js — the MCP tool registrations; thin text-formatting wrapping over the same core/ functions

  • tools/prompts.js — slash-command shortcuts: getinfo, getcodeinfo, findrepos, comparerepos

  • lib/github.js — shared GitHub API client (githubFetch, createGitHubClient), per-caller token priority, response caching, rate-limit/error handling, SSRF allowlist

  • lib/format.js — shared formatting helpers (relative dates, repo-ref parsing, truncation, untrusted-content wrapping)

  • lib/auth.js — extracts an optional caller-supplied GitHub token from the Authorization header; never blocks a request

  • lib/rateLimit.js — per-IP request rate limiting for the HTTP transport (protects this server, independent of GitHub's own limits)

  • lib/requestLog.js — minimal per-request logging (method, tool name, caller IP) with no arguments/tokens ever logged

  • lib/cache.js — in-memory TTL cache for anonymous/server-token GitHub responses (never for caller-supplied tokens — see Security)

  • lib/aiProvider.js — thin wrappers over the Gemini and Anthropic REST APIs for the "explain this repo" feature

  • lib/aiTrialQuota.js — the operator-funded free trial's per-caller daily budget, separate from the general rate limiter

  • Dockerfile — optional containerized build of the HTTP entry point, for deploying somewhere other than Render (Render itself doesn't need this — it builds natively from package.json)

  • test/ — unit and integration tests, run with npm test (Node's built-in test runner + @modelcontextprotocol/client/proxy-addr as devDependencies for tests specifically)

  • .github/workflows/test.yml — CI: runs the test suite on every push to main and every pull request

  • package.json — dependencies (@modelcontextprotocol/server, @modelcontextprotocol/express, @modelcontextprotocol/node, express, zod)

Available Tools

9 tools
compare_reposA

Compare 2-4 GitHub repos side by side as a table: stars, forks, open issues, license, primary language, approximate contributor count, and how recently each was created/updated. Use this to help decide between finalists after search_github_repos, instead of eyeballing separate results.

ParametersJSON Schema
NameRequiredDescriptionDefault
reposYes2 to 4 repos, each as 'owner/name' or a GitHub URL, e.g. ['facebook/react', 'vuejs/vue'].

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden. It discloses the return format as a table, lists the exact data points, and signals imprecision with 'approximate contributor count'. It does not mention rate limits or network dependency, but the compare operation is clearly non-mutating and well described.

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?

Two sentences with no filler. The first sentence front-loads the action, input count, and output contents; the second gives usage positioning. Every sentence earns its place.

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?

The description tells the agent exactly what to input and what fields will appear in the result, which is enough for a simple comparison tool with one well-schema'd parameter. Minor caveats about error behavior or rate limits are not stated, but they are not essential for correct invocation.

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

Parameters3/5

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

The schema already fully documents the single 'repos' parameter with min/max items and an example. The description repeats the 2-4 constraint and GitHub scope but adds no meaningful semantics beyond the schema. Baseline 3 is appropriate given the 100% schema coverage.

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 uses the specific verb 'Compare', names the resource '2-4 GitHub repos', and states the output form: 'side by side as a table' with a clear list of fields. This distinguishes it from sibling tools like search_github_repos and get_repo_overview.

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 explicitly says 'Use this to help decide between finalists after search_github_repos', giving a clear when-to-use context. It contrasts with 'eyeballing separate results' but does not name alternative tools for when not to use it, so it stops short of a full exclusion set.

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

get_file_contentA

Read the contents of one specific text file in a repo (source code, config, docs). Use get_repo_structure first if you're not sure of the exact path. Binary files (images, archives, etc.) are refused with a link instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesFile path inside the repo, e.g. 'src/index.js' or 'README.md'.
repoYesRepo as 'owner/name' (e.g. 'facebook/react') or a GitHub URL — usually copied straight from a search result.

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full transparency burden. It explicitly states that text file contents are returned and that binary files are refused with a link, which covers the main behavioral aspects. It does not mention auth requirements or side effects, but for a read-only operation, this is sufficient.

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 two concise sentences that efficiently cover purpose, usage guidance, and limitations. There is no redundant or extraneous information, and the structure is clear and direct.

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?

For a simple tool with two well-described parameters and no output schema, the description provides all necessary context: what it does, when to use it (including a hint about the sibling tool), and how it handles binary files. Nothing essential is missing.

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

Parameters3/5

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

Both parameters (repo and path) are fully described in the schema with examples, achieving 100% schema description coverage. The description itself adds no additional parameter-specific context, so it does not enhance beyond the schema. This aligns with the baseline of 3 for high schema coverage.

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 clearly states the tool's purpose: to read the contents of a single text file. It distinguishes itself from get_repo_structure by noting that it retrieves file contents rather than structure, and it specifies that binary files are refused, setting clear boundaries.

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?

The description provides explicit guidance on when to use this tool: it advises using get_repo_structure first if the exact path is unknown, and it warns that binary files are not supported, redirecting users with a link. This gives clear when-to and when-not-to usage instructions.

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

get_recent_commitsA

Get the most recent commits to a repo (or one branch), to see what's actively being worked on. Each entry shows the short SHA, author, when it happened, and the commit message.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepo as 'owner/name' (e.g. 'facebook/react') or a GitHub URL — usually copied straight from a search result.
limitNoHow many commits to return. Default: 10, max: 30.
branchNoBranch name to look at. Omit for the default branch.

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of explaining behavior. It does so effectively by disclosing the optional branch scoping and what each returned entry contains. It could mention ordering or lack of diffs, but the behavior is clear and unlikely to surprise the agent.

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 two sentences with no filler. The first sentence states the action, scope, and purpose; the second describes the return value. Every word earns its place, and the most important information is front-loaded.

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?

The description is complete enough for a straightforward read-only listing tool. It explains the return shape despite the absence of an output schema, and parameter details are fully covered by the schema. A minor gap is that it doesn't explicitly mention sorting order, but 'most recent' implies chronological order, so this is not a significant omission.

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

Parameters3/5

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

The input schema already provides complete descriptions for all three parameters, including format, defaults, bounds, and the meaning of omitting `branch`. The description adds no meaningful parameter-level detail beyond reinforcing that branch is optional, so the baseline score of 3 is appropriate.

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 clearly states a specific action ('Get the most recent commits') with a well-defined resource and scope ('to a repo (or one branch)'). It also distinguishes itself from sibling tools by focusing on commit history rather than repos, branches, or file contents. The addition of the output fields ('short SHA, author, when it happened, and the commit message') further clarifies what the tool is for.

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 phrase 'to see what's actively being worked on' provides clear contextual guidance on when to use this tool. It does not explicitly name alternatives or exclusions, but for a simple read-only commit listing tool, this level of usage context is sufficient.

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

get_repo_overviewA

Get a snapshot of one specific GitHub repo: description, stars/forks/open issues, license, topics, primary languages, latest release, approximate contributor count, and a README preview. Use this after search_github_repos to understand a specific candidate before diving into its code.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepo as 'owner/name' (e.g. 'facebook/react') or a GitHub URL — usually copied straight from a search result.

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently lists what the tool returns and even adds precision with 'approximate contributor count' and 'README preview,' which prevents over-expectations. It does not mention rate limits, error behavior, or data freshness, but for a read-only snapshot tool the disclosed output surface is fairly complete.

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?

Two sentences with no filler. The first sentence front-loads the operation and output fields; the second gives a clear usage directive. Every part contributes to selection and invocation.

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?

For a single-parameter tool with no output schema and no annotations, the description is nearly complete: it covers the input source, the full set of return values, and the intended workflow position. The only minor gaps are exact response formatting, error handling, and potential rate/resource limits, which are not critical for an overview snapshot.

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

Parameters3/5

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

Schema description coverage is 100%: the input schema already explains the 'owner/name' format, accepts GitHub URLs, and notes that the value is usually copied from a search result. The main description adds only that the repo is 'one specific GitHub repo,' which does not materially go beyond the schema. A baseline 3 is appropriate when the schema already handles parameter meaning.

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: 'Get a snapshot of one specific GitHub repo,' then enumerates the exact data categories returned (description, stars/forks/open issues, license, topics, languages, latest release, contributor count, README preview). This clearly differentiates it from search-oriented siblings like search_github_repos and code-focused tools like get_file_content.

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 explicit workflow context: 'Use this after search_github_repos to understand a specific candidate before diving into its code.' This tells the agent when in the discovery flow the tool belongs and signals that it is a pre-code step. It does not name explicit alternatives or exclusion conditions for siblings like compare_repos or get_repo_structure, so it stops short of a 5.

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

get_repo_structureA

List the files and folders at a path inside a repo, like browsing a file tree one level at a time. Start with no path to see the root, then call again with a subdirectory's path (e.g. 'src') to go deeper.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoDirectory path inside the repo, e.g. 'src/utils'. Omit for the repo root.
repoYesRepo as 'owner/name' (e.g. 'facebook/react') or a GitHub URL — usually copied straight from a search result.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden. It explicitly discloses that listing is one level at a time, that omitting path returns the root, and that repeated calls navigate deeper. It does not mention output formatting, ordering, or edge cases, but the core behavior is transparent.

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?

Two concise sentences front-load the core action and then give the key usage pattern. Every sentence earns its place; there is no redundant or filler content.

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?

For a relatively simple browsing tool with complete schema description and no output schema, the description is nearly sufficient. It explains how to start and how to go deeper, though it could be slightly more explicit about what the returned listing contains beyond 'files and folders'.

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 value beyond the schema by explaining path semantics ('Start with no path to see the root') and providing an example ('src'), which helps the agent correctly omit or supply the path parameter.

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 uses a specific verb ('List') and a clear resource ('files and folders at a path inside a repo'), and distinguishes this tool from sibling tools by describing directory-structure browsing rather than file content or branch listing. The file-tree analogy makes the purpose immediately understandable.

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 clear practical guidance: start at the root by omitting path, then call again with a subdirectory path to go deeper. It does not explicitly compare against alternatives like get_file_content or list_branches, but the step-by-step usage context is strong and unambiguous.

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

list_branchesA

List branches in a repo and the commit each currently points to. Useful for finding active feature branches or confirming the default branch name before calling other tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepo as 'owner/name' (e.g. 'facebook/react') or a GitHub URL — usually copied straight from a search result.
limitNoHow many branches to return. Default: 20, max: 100.

TDQS

A4/5.0
Behavior3/5

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool lists branches and the commit each points to, and implies a read-only operation, but it does not mention potential limits, pagination, or lack of side effects beyond what the schema already states.

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 two concise sentences. The primary capability is front-loaded in the first sentence, and the second sentence provides practical context without unnecessary detail.

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?

For a straightforward list operation, the description covers what the tool does and when it is useful. There is no output schema, but the stated output — branches and their commits — is clear enough for an agent to know what to expect.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both parameters, 'repo' and 'limit'. The description does not add extra semantic detail about parameters, but it does not need to; the schema is sufficient.

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 states a specific verb and resource: 'List branches in a repo' and adds the useful detail that it returns the commit each branch points to. This clearly distinguishes it from sibling tools like get_repo_overview or get_recent_commits.

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 gives concrete use cases: finding active feature branches and confirming the default branch name before calling other tools. It does not explicitly state when not to use it or name alternative tools, but the provided context is enough to guide appropriate selection.

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

search_by_topicA

Find GitHub repositories tagged with a specific topic label (GitHub's own categorization tags, e.g. 'machine-learning', 'llm-agent', 'containerization'). More precise than free-text search when you already know the ecosystem's term for what you want, since it matches curated tags rather than description text.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesA GitHub topic tag, e.g. 'rag', 'llm-agent', 'docker', 'vector-database'. Lowercase, hyphenated, no spaces.
filtersNoOptional filters to narrow or broaden the search.

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It does disclose a key behavior—matching curated GitHub topic tags rather than description text—and provides examples. However, it does not mention result ordering, pagination, error behavior, or any constraints on topic matching beyond lowercase/hyphenated guidance in the schema.

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?

Two sentences with no filler. The core action and examples come first, and the usage guidance is concise and immediately actionable.

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?

Given the rich schema covering all parameters and the clear differentiator from sibling tools, the description is nearly complete. The only notable gap is the lack of any statement about the return shape, and without an output schema the agent must infer that the result is a list of repository records.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents the topic and filter parameters well. The description adds useful context about what a topic tag is and how it differs from free-text, but it does not need to explain parameter syntax since the schema covers it.

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 states a specific verb ('Find') and resource ('GitHub repositories') and narrows the operation to topic-label matching. It explicitly contrasts with free-text search, distinguishing this tool from sibling search_github_repos without needing to inspect the schema.

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?

It gives clear guidance: use this tool when you already know the ecosystem's term for the topic, and frames it as more precise than free-text search. This effectively routes the agent between search_by_topic and search_github_repos with an explicit condition.

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

search_github_reposA

Search GitHub for open-source repositories relevant to a research topic, technology, or project idea. Returns the top matching repos ranked by a blend of popularity (stars) and how recently they've been maintained, each with a short summary of what makes it useful. Good for requests like 'find me RAG implementation repos' or 'show me containerization examples in Go'.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesWhat the user is building, researching, or learning, phrased as GitHub search terms, e.g. 'retrieval augmented generation vector database' or 'containerization examples'.
filtersNoOptional filters to narrow or broaden the search.

TDQS

A4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it delivers: it reveals the ranking blend (stars and maintenance recency) and the return shape (a short usefulness summary per repo). It does not disclose rate limits or result-count behavior, but for a read-only search tool the disclosed traits are the key ones.

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?

Three sentences with no waste: action/scope, ranking+output behavior, and usage examples. Each sentence earns its place and the core behavior is front-loaded in the first sentence.

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?

For moderate complexity (2 params, one nested object, no output schema, no annotations), the description covers the essential gaps: return value shape and ranking rationale. It is not exhaustive — result count, pagination, and explicit sibling differentiation are absent — but nothing an agent needs to call it correctly is critically missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents query phrasing and each filter parameter. The description's example queries add minor illustrative value but no new parameter information beyond what the schema provides.

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

Purpose4/5

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

The description states a specific verb and resource — 'Search GitHub for open-source repositories' — and gives the context (research topic, technology, project idea) plus example request phrasings. It stops short of 5 because it never names a sibling (e.g., search_by_topic) or explicitly says how it differs from them, though the ranking-and-summary output description partially distinguishes it.

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?

'Good for requests like...' with two concrete examples ('find me RAG implementation repos', 'show me containerization examples in Go') establishes clear when-to-use context. It lacks explicit when-not-to-use guidance or routing to alternatives among the eight sibling tools, so it does not earn a 5.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv2.0.0
    • First observedcompare_repos
    • First observedget_file_content
    • First observedget_recent_commits
    • First observedget_repo_overview
    • First observedget_repo_structure
    • First observedget_trending_repos
    • First observedlist_branches
    • First observedsearch_by_topic
    • First observedsearch_github_repos
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct stage: searching, topic filtering, trending, overview, structure, comparison, file content, commits, and branches. The two search tools are differentiated by free-text vs. curated topic tags, so an agent can choose without confusion.

Naming Consistency5/5

Tool names consistently follow a snake_case verb_noun pattern: search_, get_, compare_, and list_. The small variation in search_github_repos vs. search_by_topic does not break the overall predictability.

Tool Count5/5

Nine tools is well-scoped for a GitHub discovery server. Each tool earns its place in the workflow from finding repositories to inspecting their internals, without redundant or excessive surface area.

Completeness5/5

The tool set covers the full discovery lifecycle: find candidates via search/topic/trending, evaluate them via overview/compare, and explore details via structure/file/commits/branches. There are no obvious dead ends or missing operations for the server's stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers