Skip to main content
Glama
Lipdog

fossick-mcp

by Lipdog
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Contents

Related MCP server: github-rag-mcp

What is Fossick

fossick /ˈfɒsɪk/ verb (Australian/NZ) — to prospect or rummage for gems, especially the small-scale kind of mining where you sift creek beds and old tailings looking for what bigger operators missed.

That's exactly what this tool does — but for code.

Fossick gives your AI agent seven read-only tools to prospect across all of GitHub, PyPI, and npm, covering the full discovery loop end-to-end:

  1. Search and discover. Sift 200M+ repos with multi-query relevance ranking, find the small-but-good libraries that bigger tools bury, look up packages on PyPI and npm.

  2. Drill into any repo without cloning. Browse a remote repo's tree with depth and glob filters, read any file at any branch/tag/commit, and goto-definition for any class, function, or type — all on remote GitHub, no local checkout needed.

  3. Search code patterns across all of GitHub. Full-text, regex, qualifier-aware search across every public file — find how an API is actually used in production, not just in the docs.

Useful any time you'd benefit from your agent reaching into the world's largest code corpus:

  • Pick the right library. Find a small, focused, actively-maintained option for any task — not just the most popular one.

  • Discover hidden gems. Surface the 500-star library that ranks higher on relevance than the 50,000-star incumbent.

  • Drill into a repo you found. Walk its layout, read its README, find where its core API is defined — without git clone.

  • Find usage patterns in real code. Search how an API is called in production, then read the matched files in context.

  • Get inspired. See how others structured similar projects, what patterns they used, what tradeoffs they made.

  • Stay current. Discover what's trending, just-released, or new in an ecosystem — past your model's training cutoff.

It does not do code archaeology — git blame, PR history, version diffs. Reach for git and gh for that.

Examples

Once Fossick is connected, here's the kind of thing you can ask your agent.

Discover libraries and packages

  • "Find me a small, actively-maintained Rust TUI library — something newer than ratatui."

  • "What are people using instead of LangChain these days?"

  • "Show me trending Python web frameworks released in the last 90 days."

  • "What's a good lightweight alternative to Pydantic for runtime validation?"

Drill into a specific repo

  • "Browse the structure of astral-sh/uv — what's in crates/?"

  • "Read the main __init__.py from pydantic/pydantic."

  • "Where is the Stream class defined in anthropics/anthropic-sdk-python?"

  • "What's the latest release of modelcontextprotocol/python-sdk and when did it ship?"

Find code patterns in the wild

  • "How do production FastAPI apps actually set up structured logging with structlog and asyncio?"

  • "Show me real examples of tokio::select! being used with timeout cancellation."

  • "Find Dockerfiles that build multi-stage Python images with uv."

  • "How are people calling the OpenAI API streaming endpoint from Go?"

Vet a dependency before adopting it

  • "Is the requests library still maintained?"

  • "Compare freshness of httpx vs aiohttp — last release dates, recent activity."

  • "Who actually uses msgspec? Show me real usage in production codebases."

  • "Find the GitHub repo behind the polars PyPI package and check its last release."

Installation

Prerequisite: uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh. Then uvx will download and run Fossick on demand. No clone needed.

Claude Code

Three install scopes. Pick the one that matches how you want Fossick to be available — globally, shared with your team, or just for you in one project. The scope flag controls where the config gets written (Claude Code MCP scopes).

Global (recommended for personal use)

Available in every project on your machine. Stored in ~/.claude.json, private to your user account.

claude mcp add fossick --scope user uvx fossick-mcp

Team-shared (committed to git)

Stored in .mcp.json at the project root, checked into version control. Anyone who clones the repo gets the same MCP server. Use this when the whole team should have Fossick.

claude mcp add fossick --scope project uvx fossick-mcp

This project only (default)

Local scope is the default. Only enabled in the current project, only for you. Stored in ~/.claude.json under this project's path — not committed, not shared with collaborators.

claude mcp add fossick uvx fossick-mcp

Manual install

If you'd rather skip the CLI, write the config yourself. The JSON shape is the same regardless of scope — only the file changes:

  • ~/.claude.json for user / local scope

  • .mcp.json (project root) for project scope

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Other clients

Install in Cursor

Or add manually to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Install in VS Code

Or via CLI:

code --add-mcp '{"name":"fossick","command":"uvx","args":["fossick-mcp"]}'

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

Edit cline_mcp_settings.json via the Cline extension's MCP settings panel:

{
  "mcpServers": {
    "fossick": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}
codex mcp add fossick -- uvx fossick-mcp

Or edit ~/.codex/config.toml:

[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]
git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

Then point your MCP config at the local clone:

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

Tools

Seven read-only tools, organized by their role in the discovery workflow.

Find candidates

Tool

What it does

search_repos

Discover repositories by topic, stars, language, recency, or trending. Pass multiple query phrasings in one call for better recall.

search_packages

Direct lookup on PyPI or npm by package name. Returns version, description, links, and GitHub repo URL.

Evaluate a candidate

Tool

What it does

repo_tree

Browse a repo's file layout with depth and glob filtering.

get_file

Read any file at any branch, tag, or commit.

find_symbol

Goto-definition via real AST queries — find where a class, function, or type is actually declared, not just substring-matched.

list_tags

View tags and recent releases. The fastest "is this still maintained?" check.

Search code across GitHub

Tool

What it does

search_code

Full-text search across every public file on GitHub. Supports repo:, language:, path:, boolean operators, and regex. Find real-world usage patterns, config examples, or anything else in the world's largest code corpus.

All tools are read-only, idempotent, and safe to auto-approve. Every response ends with hint-chained next steps so the agent knows what to do next.

Why Fossick

  • Built for the discovery workflow. Tools follow the natural shape: find candidate → drill into it → read the API → see how others use it. Hint-chained next-step suggestions keep your agent on rails through the whole loop.

  • Drill into any public repo without cloning. Browse remote repo trees with depth + glob filters, read any file at any branch/tag/commit, and run real AST-based symbol search to goto-definition for any class, function, or type — all on remote GitHub.

  • Multi-query search with smart ranking. search_repos accepts a list of phrasings in one call and applies composite relevance ranking that prioritizes literal match over raw popularity — surfaces the 500-star gem that beats the 50,000-star incumbent.

  • Lean on tokens by design. 7 focused tools (not 30+), formatted-markdown outputs (not JSON dumps), TTL caching, hint chaining that cuts agent reasoning turns, and multi-query search that bundles N requests into 1. Every tool description and response is sized to keep your context budget free for real work.

  • Rate-limit aware. Tracks GitHub's Search and Core API buckets separately, sleeps on exhaustion, retries with exponential backoff.

  • Zero config for gh users. Already have the GitHub CLI authenticated? Nothing to configure.

  • Plays well with others. Read-only, idempotent, safe to auto-approve. Pair Fossick with github-mcp-server when you also need to act on your own repos (issues, PRs, Actions).

FAQ

Yes — without one you'll hit GitHub's 60-requests-per-hour unauthenticated limit almost immediately. The easiest path is to install the GitHub CLI and run gh auth login once. Fossick picks up your token automatically. No need to pass anything in the MCP config.

uvx runs Fossick in a transient, isolated environment without polluting your global Python. It downloads on first use, caches for subsequent runs, and updates effortlessly. You also don't need to manage a virtualenv or worry about Python version conflicts. If you'd rather use pip, pip install fossick-mcp works — just point your MCP client at the installed fossick-mcp binary.

Yes. Every search, file fetch, and tag list counts against your token's rate limits. Fossick splits requests across two buckets — Search API (30/min) and Core API (5,000/hr) — and pauses automatically when either is exhausted. For most discovery sessions you'll never hit the limits.

If your client supports the standard MCP stdio transport, yes. The standard uvx fossick-mcp config works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Codex, and most others. See the Installation section for client-specific snippets.

Only those your GitHub token can access. The token's permissions are the only constraint — Fossick doesn't have its own ACL layer. If your token can read a private repo, Fossick can search it; if not, it can't.

Deliberate scope decision. Code archaeology (who changed what, why, when) is a different shape of problem and is well-served by git and the gh CLI. Fossick stays focused on the discovery workflow — finding and evaluating, not investigating.

Live from GitHub on every request. Fossick caches results briefly to avoid hammering the API on repeated identical calls, with longer TTLs for content pinned to a specific commit SHA. Anything past the TTL is a fresh fetch.

Configuration

Authentication

Fossick resolves a GitHub token automatically:

  1. GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN env vars

  2. gh auth token from the GitHub CLI — no config needed if you're already logged in

To pass a token explicitly:

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

A token only needs public repo read access (no scopes selected is fine).

Rate limits

Fossick tracks both GitHub API buckets and pauses automatically when either is exhausted.

Bucket

Limit

Tools

Search API

30 req/min

search_repos, search_code, find_symbol

Core API

5,000 req/hr

get_file, repo_tree, list_tags

External

No GitHub limit

search_packages (hits PyPI/npm directly)

Retries use exponential backoff on rate-limited and transient errors. Results are cached briefly to avoid redundant API calls, with longer TTLs for content pinned to a specific commit SHA.

Development

Prerequisites

  • Python 3.11+

  • uv

Setup

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

Run

Launch the MCP server on stdio (for manual testing or local MCP-client config):

uv run fossick-mcp

Test

Unit and registration tests — no network, runs in seconds:

uv run pytest

Live integration tests — hits real GitHub against pinned modelcontextprotocol/python-sdk@v1.14.0:

uv run pytest -m live

Build

uv build

Produces dist/fossick_mcp-<version>.tar.gz and the corresponding wheel.

Architecture

See CLAUDE.md for the full architecture tour, key patterns, and the recipe for adding new tools.

Star history

License

MIT — fossick away.

Available Tools

7 tools
find_symbolA
Read-onlyIdempotent

Goto-definition: find where a symbol is defined in one repo or across all of GitHub.

How it works: queries GitHub's code-search index for files containing
the symbol name, parallel-fetches the top ~15 candidate files, parses
each with tree-sitter, and queries the AST for declaration nodes
(class, function, struct, trait, interface, etc.) whose name matches
exactly. Results are ranked with type-declaring kinds
(class/struct/trait) first, then functions, then methods, then
variables. Success responses include real absolute line numbers and
ripgrep-style context (2 lines above, match line, 5 lines below)
pulled from the full file, not GitHub's 3-line fragment.

Languages with AST-precise matching via tree-sitter: Python, JavaScript,
TypeScript, Go, Rust, Java, Ruby, C, C++. Other languages fall back to
a regex-on-fragment path that is less precise but still useful.

Best for **distinctive** symbol names — `FastMCP`, `DataLoader`,
`ClaudeAgentOptions`, `Runtime`, `Tokenizer`. These are names creators
chose to be findable, and the first-declaration-wins ranking is
almost always right.

NOT for generic names like `connect`, `handle`, `init`, `get`, `run`
that show up in every library. GitHub's text-relevance ranking puts
usage-heavy files above the one declaring them, so the declaration
file often isn't in the top 15 we fetch. For generic names, use
`search_code` with disambiguating keywords (e.g.
`search_code("export function connect", repo="reduxjs/react-redux")`)
or combine with `path:` qualifier to narrow the search.

NOT for finding call-sites or usage patterns — use `search_code`
with the symbol name and a `repo:` qualifier for that.
ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSymbol name (function, class, type, variable).
repoNoScope to one repo (owner/repo). Omit for cross-repo search.
languageNoFilter by programming language.
kindNoReserved for future kind filtering.
pathNoFile path filter (e.g. src/).
pageNoResult page.
per_pageNoResults per page (max 100).

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds extensive behavioral details: how the tool queries GitHub's code-search index, parallel-fetches candidate files, parses with tree-sitter, ranks results (type-declaring kinds first), and provides response format (absolute line numbers, context lines). It also covers language-specific behavior and fallback mechanisms.

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?

The description is relatively long but well-structured with clear sections, bullet points, and a 'How it works' explanation. While every sentence adds value, it could be slightly more concise without losing essential information. The front-loading of the core purpose is good.

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 complexity (symbol definition across repos, AST parsing, ranking), the description is highly complete. It covers use cases, limitations, fallback behavior, and response format. Even without an output schema, the description explains what results include (line numbers, context lines), making it sufficient for an agent to understand the tool's full behavior.

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 coverage is 100%, so baseline is 3. The description does not add new parameter-level details beyond what the schema already provides (e.g., the 'name' parameter is described in schema as 'Symbol name' and description doesn't elaborate further). However, the description sets overall context for parameters like 'repo' and 'language' by explaining when to use them.

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 explicitly states 'find where a symbol is defined', uses specific verb 'find' and resource 'symbol definition', and contrasts with sibling tools like search_code for usage patterns. It clearly distinguishes its purpose from other tools.

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 ('best for distinctive symbol names') and when not ('NOT for generic names'), with concrete alternatives such as using search_code with disambiguating keywords. It also specifies limitations for generic names and call-sites.

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

get_fileA
Read-onlyIdempotent

Read file content from one file in a GitHub repository. Returns full file with line numbers, supports line range slicing (start_line/end_line) and substring/regex match filtering with context lines. Truncates files over 500 lines unless a range or match is specified. Use after locating a file via search_code, find_symbol, or repo_tree.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepository in 'owner/name' format (e.g. 'modelcontextprotocol/python-sdk').
pathYesFile path within the repo.
refNoBranch, tag, or commit SHA. Defaults to the default branch.
start_lineNoFirst line to show (1-indexed).
end_lineNoLast line to show (1-indexed, inclusive).
matchNoShow only lines containing this substring (case-insensitive). Surround with / for regex.
match_contextNoContext lines around each match.

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already indicate readOnly/ idempotent behavior. Description adds key behavioral details: truncation of files over 500 lines, line range slicing, and match filtering with context lines. No contradictions with annotations.

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, front-loaded with primary purpose and features, then usage guidance. Every sentence carries essential information with no redundancy.

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 7 parameters and no output schema, description adequately covers core functionality, truncation, match filtering, and usage context. Could be slightly more detailed on response structure (e.g., metadata), but sufficient for an agent.

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 baseline is 3. Description adds value by explaining how parameters work together (e.g., truncation avoidance via range/match) and mentions line numbers in output, which is not in schema.

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?

Clearly states 'Read file content from one file in a GitHub repository', specifying verb and resource. Distinguishes from siblings by advising to use after search_code, find_symbol, or repo_tree, making its unique role explicit.

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?

Provides explicit context for when to use ('after locating a file via search_code, find_symbol, or repo_tree') and mentions truncation behavior that guides usage. Lacks explicit 'do not use' scenarios, but the context is clear.

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

list_tagsA
Read-onlyIdempotent

List tags or releases for one repository. Default mode returns lightweight tag names with commit SHAs. Release mode (releases=true) returns full release objects including tag name, title, changelog body, publish date, and attached assets. Use to check a library's freshness (is it actively maintained?), find the current version to pin against, or pick a specific release to read files at via get_file(ref=) or browse via repo_tree(ref=).

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepository in 'owner/name' format (e.g. 'modelcontextprotocol/python-sdk').
releasesNoIf true, fetch releases (with changelogs and assets) instead of bare tags.
pageNoResult page.
per_pageNoResults per page (max 100).

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare read-only, idempotent, non-destructive. The description adds behavioral details: default mode returns lightweight tags with commit SHAs, release mode returns full release objects with title, body, date, assets. No contradiction.

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?

Four sentences, no fluff. Front-loaded with purpose, then mode explanation, then usage examples. Every sentence adds value.

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 simple listing nature, complete coverage of modes and outputs. No output schema needed because the description explicitly states return types for both modes. Integrates well with sibling tools.

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 covers all parameters (100%). The description adds context for the 'releases' parameter by explaining mode difference and shows how outputs integrate with sibling tools, enhancing understanding beyond schema.

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 'List tags or releases for one repository' with a specific verb and resource. It distinguishes the two modes (default vs releases) and implies differentiation from siblings by mentioning how to use the output with get_file and repo_tree.

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 use cases: checking freshness, finding version, picking release. It does not explicitly state when not to use this tool, but the context is clear.

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

repo_treeA
Read-onlyIdempotent

View the file tree of a GitHub repository or subdirectory. Recursive listing with depth control (1-3 levels), glob pattern filtering (e.g. *.py), and optional file sizes. Automatically filters noise directories (node_modules, pycache, .venv, dist, etc.). Use to understand project layout and discover key files before reading them with get_file.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepository in 'owner/name' format (e.g. 'modelcontextprotocol/python-sdk').
pathNoSubdirectory to start from. Empty = root.
refNoBranch, tag, or commit SHA. Defaults to the default branch.
depthNoHow many levels deep to show (1-3).
patternNoGlob filter for filenames (e.g. *.py). Dirs always shown.
show_sizesNoInclude file sizes in the output.

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds depth control, glob filtering, size option, and noise directory filtering, which are behavioral traits beyond annotations.

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, front-loaded with the main purpose, no filler. Every sentence adds value.

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?

No output schema, but description implies the return type (file tree). Purpose and features are well covered. Could mention output format briefly, but not necessary given tool simplicity.

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 coverage is 100%, so baseline is 3. Description mentions depth, pattern, and show_sizes but not repo or ref. It adds context about noise filtering, which is behavioral, not parameter-specific. Adequate but not exceptional.

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?

Description clearly states 'View the file tree of a GitHub repository or subdirectory' with specific features (recursive, depth control, glob filtering, file sizes). It also distinguishes itself by suggesting use before get_file to understand project layout.

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?

Explicitly says 'Use to understand project layout and discover key files before reading them with get_file,' providing clear context. However, it does not explicitly exclude other use cases or mention when not to use it.

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

search_codeA
Read-onlyIdempotent

Search for code across all of GitHub (200M+ repos), or narrowed to one repo/org/path. Supports regex (/pattern/), tree-sitter symbol search (symbol:name), boolean operators (AND/OR/NOT), exact phrases, and code-search qualifiers: repo:, org:, user:, path:, language:, content:, symbol:, is:archived, is:fork, is:vendored, is:generated, size:, in:file, in:path, filename:, extension:. Convenience params repo, language, path are appended as qualifiers automatically. Use this to find real-world usage patterns (how do projects actually import and call library X?), discover who uses a library (search for its import/crate name across GitHub), or locate example code for a framework you're evaluating. NOT for finding where a symbol is defined (use find_symbol). IMPORTANT: GitHub's code-search endpoint does NOT support repository-level qualifiers like stars:, pushed:, forks:, created:, topic:, license:, archived: — GitHub silently matches them as literal file content, giving wrong results with no error. For popularity-filtered discovery, use search_repos instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesGitHub code search query. Supports regex (/pattern/), symbol:name, boolean (AND/OR/NOT), exact phrases. Code-search qualifiers: repo:, org:, user:, path:, language:, content:, symbol:, is:archived, is:fork, is:vendored, is:generated, size:, in:, filename:, extension:. Repository-level filters (stars:, pushed:, forks:, created:, topic:, license:, archived:) are NOT supported by code search — use `search_repos` for those.
repoNoScope to one repository (owner/repo).
languageNoFilter by programming language.
pathNoFilter by file path pattern (e.g. src/).
pageNoPage number for paginated results.
per_pageNoResults per page (max 100).
context_linesNoMax lines of code context per match (default 10).

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds critical behavioral details: that repository-level qualifiers silently match literal content (giving wrong results), and that convenience params are appended as qualifiers automatically. This significantly aids safe usage.

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?

The description is well-structured, starting with purpose, then features, use cases, and warnings. It is fairly concise given the amount of information, though slightly longer than minimalist. Every sentence adds value, but it could be slightly more streamlined.

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?

Despite no output schema, the description covers query syntax, scoping, convenience params, unsupported qualifiers, and pagination parameters. It distinguishes from siblings and provides complete guidance for effective use, making it contextually rich.

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 all 7 parameters adequately. The description adds minor context about automatic appending of repo/language/path as qualifiers, but does not substantially augment parameter meaning beyond the schema.

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 that this tool searches for code across all of GitHub or narrowed scopes, and distinguishes from sibling tool find_symbol by specifying what it is NOT for (finding symbol definitions). The verb 'search' and resource 'code' are explicit.

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?

Provides explicit use cases (finding usage patterns, discovering library users, locating examples) and clear when-not-to-use with alternative named (find_symbol). Also warns about unsupported repository-level qualifiers and directs to search_repos for popularity-filtered discovery.

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

search_packagesA
Read-onlyIdempotent

Search for a package on PyPI or npm (not GitHub — does not use GitHub API or rate limits). PyPI: exact-match lookup returning version, description, license, homepage, and GitHub URL. npm: text search returning multiple results with links. Use for looking up package metadata and versions — chain with search_repos to explore the source repository.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesPackage name to search for.
ecosystemNoPackage registry: pypi or npm.pypi
limitNoMax results (npm only; PyPI returns exact match).

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by confirming no GitHub API usage, no rate limits, and detailing return types (PyPI: exact match with specific fields; npm: multiple results with links). No contradictions.

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, front-loaded with the most critical clarification (not GitHub). Every sentence provides essential information with no redundancy or filler.

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 low complexity (3 params, simple read-only behavior) and no output schema, the description fully explains what to expect for both ecosystems and suggests chaining. It is complete for an agent to decide when and how to invoke it.

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 baseline is 3. The description adds meaning by explaining that 'limit' only applies to npm and PyPI returns an exact match regardless of limit, which goes beyond the schema's description. It also implies the 'ecosystem' parameter selects behavior.

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 it searches packages on PyPI or npm, explicitly excludes GitHub, and distinguishes itself from siblings like search_repos. It specifies the exact verb 'search' and the resource 'packages', and details the different behaviors for each ecosystem.

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 usage context: for looking up package metadata and versions, and suggests chaining with search_repos. It also clarifies what it does not do (GitHub API, rate limits). Although it doesn't explicitly state when not to use, the guidance is sufficient.

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

search_reposA
Read-onlyIdempotent

Discover GitHub repositories — the go-to tool for finding real, maintained, coherent repos during a coding session. Optimized for "find reference implementations / prior art / learning material / small-but-quality gems in an ecosystem," NOT for "rank by raw popularity." Returns per-result: name, full description, topics, primary language, star count, last-push date, license, homepage, and archived status.

Dev-session use cases this serves well:
  • "Rust agent harness — what are my options?" — finds frameworks/harnesses ranked by literal relevance, not star count
  • "Python async rate limiter — show me existing libraries" — dedicated libs beat big frameworks
  • "What's the landscape of LLM observability tools?" — surfaces the actual category leaders
  • "Is there already a tool for managing Claude Code sessions?" — hyper-specific gem hunting, small focused CLIs float up
  • "What's new in this ecosystem this week?" — set `trending=True` for repos created in the last 7 days
  • "Disambiguate a name the user mentioned" — one-hop metadata lookup

Ranking (multi-query mode): composite relevance score combining literal description match × 3, topic-tag match × 2, cross-phrasing robustness × 2, recency bonus (0-3), and log-scaled stars at half-weight. Stars are a TIEBREAK, not a driver — this is why a 500-star literal-match repo can outrank a 40,000-star repo that doesn't contain the query terms in its description. Tested against 6 dev-session queries in benchmarks/rank_experiment.py; composite scoring produced the best top-5 on 5/6 queries and consistently surfaced small-but-quality gems that star-first ranking buried.

Query sharpness — most→least noisy:
  • `topic:X` — self-assigned tags. Noisy for umbrella terms (e.g. `topic:mcp` returns opportunistic taggers like n8n). Sharp for tight niches (`topic:ratatui`).
  • `in:readme "phrase"` — matches any mention in the README. Medium.
  • `in:description "phrase"` — matches repos whose short description contains the phrase. Sharpest, but note that GitHub does literal substring matching — so `"embeddings database"` will also match "embedded database" (burned in testing). Prefer specific, domain-meaningful phrases.

SHORTLISTING — always use `queries=[...]` with 2-4 phrasings. Single-phrase `in:description` is sharp but narrow; popular options routinely describe themselves with different wording. For example, `in:description "Postgres operator"` returns Zalando's postgres-operator (5k★) but misses CloudNativePG (8k★), which describes itself as "Kubernetes-native PostgreSQL." Passing both phrasings via `queries=` runs them in parallel, dedupes by repo, and annotates each result with `matched K/N`. Recipe for concept X in language L: `queries=['in:description "X" language:L', 'in:description "X synonym" language:L', 'topic:X-slug language:L']`.

Other tips: keep queries short (GitHub uses AND logic — more terms = fewer results). Use the `language` filter instead of putting the language in the query. Use `archived:false` to exclude abandoned repos. Use `pushed:>YYYY-MM-DD` to filter by activity. For strict popularity filtering (production dependency shortlisting), add `stars:>N` explicitly — the tool no longer applies a star floor by default because gem-finding needs to see small repos.

NOT for: searching code inside repos (use `search_code`), fetching a repo you already know by name (use `get_file`/`repo_tree`), or authoritative library popularity (check package registries via `search_packages`).

IMPORTANT: repo search does NOT support file-level qualifiers like path:, filename:, extension:, content:, symbol: — GitHub silently matches them as literal content, giving misleading results with no error. Use `search_code` for those.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoRepository search query. Keep short (1-2 terms) — AND logic means more terms = fewer results. Use topic: for ecosystem discovery. Repo-search qualifiers: in:, repo:, user:, org:, size:, followers:, forks:, stars:, created:, pushed:, language:, topic:, license:, is:, mirror:, archived:, template:. File/content qualifiers (path:, filename:, extension:, content:, symbol:) are NOT supported by repo search — use `search_code` for those.
queriesNoList of query phrasings to run in parallel and merge. STRONGLY PREFERRED over `query` for shortlisting work — pass 2-4 different phrasings of the same concept (e.g. ['in:description "Postgres operator"', 'in:description "PostgreSQL" in:description "Kubernetes"', 'topic:postgres-operator']) and the tool will run them concurrently, dedupe by repo, and rank the union. Each result is annotated with `matched K/N` showing how many of your phrasings found it — a popular option found by only one phrasing would have been missed by a single-query call. If both `query` and `queries` are set, `query` is prepended to the list.
topicNoFilter by topic.
languageNoFilter by programming language.
trendingNoIf true, find repos created in the last 7 days sorted by stars.
sortNoSort by: stars, forks, updated, or best match.best match
orderNoSort order: asc or desc.desc
pageNoPage number.
per_pageNoResults per page (max 100).

TDQS

A4.9/5.0
Behavior5/5

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the ranking algorithm (composite relevance, star tiebreak), multi-query merging, and potential pitfalls (substring matching, noisy topic tags). This fully discloses behavior.

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?

Well-structured with clear sections and examples, but slightly verbose. Could trim some repetition in use-case examples while retaining all necessary information.

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 no output schema, the description lists return fields and explains ranking behavior. It covers all parameters and provides complete guidance for effective use, making it highly self-contained.

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 coverage is 100%, but the description adds significant value: explains query vs queries interaction, provides query examples, warns about unsupported qualifiers, and gives usage advice for language, archived, and stars filters.

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: 'Discover GitHub repositories' for finding maintained, coherent repos. It distinguishes from siblings like search_code, get_file, and search_packages by specifying what the tool is NOT for.

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 extensive guidance on when to use (e.g., 'find reference implementations', 'prior art', 'gem hunting') and when not to use (e.g., 'searching code inside repos'). It includes specific examples and tips like using queries parameter and avoiding file qualifiers.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a distinct purpose: find_symbol finds definitions, get_file reads files, list_tags lists releases, repo_tree shows directory structure, search_code searches code, search_packages queries package registries, and search_repos discovers repositories. No overlap in functionality.

Naming Consistency5/5

All tool names follow the verb_noun pattern with snake_case: find_symbol, get_file, list_tags, repo_tree, search_code, search_packages, search_repos. The naming is uniform and predictable.

Tool Count5/5

With 7 tools, the set is well-scoped for a code exploration server. It covers the core tasks of finding, reading, searching, and browsing code and repositories without being bloated or sparse.

Completeness4/5

The tool surface is largely complete for read-only exploration: symbol lookup, file reading, directory browsing, tag listing, and three types of search (code, packages, repos). Missing are operations like viewing commit history or blaming, which are secondary to the server's focus.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Lipdog/fossick-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server