dep-rank

dep-rank

Rank GitHub dependents by stars or trust.

dep-rank finds the most popular repositories that depend on a given GitHub project. It scrapes GitHub's dependents page, enriches results via the GraphQL API, and works as a command-line tool and as an MCP server for AI agents (see MCP server).

• [Rank dependents by stars](#dep-rank-deps--list-top-dependents) — find the most popular projects that use a repository.
• [Trust ranking](#trust-ranking) — a heuristic, pool-relative re-rank that weighs forks, issues and pull requests, and recent activity alongside stars. Not a fraud verdict.
• [Search code across dependents](#dep-rank-search--search-code-in-dependents) — see how real projects use an API.
• [MCP server](#mcp-server) — the same ranking and search as tools for AI agents, via uvx or the ghcr.io/j7an/dep-rank Docker image.

Also: JSON output, package download stats, choosing among multiple packages, local cache, Docker image, Python API.

Quick Start

pip install dep-rank

export DEP_RANK_TOKEN=ghp_your_token_here # see Authentication below dep-rank deps https://github.com/django/django --rows 5

A token is effectively required; see Authentication. Example output (numbers change over time). dep-rank also prints a scrape summary on stderr; this run stopped early, so the count is a lower bound, not a total (see Partial results):

       Top dependents of

https://github.com/django/django ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓ ┃ Repository ┃ Stars ┃ ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩ │ makeplane/plane │ 61K │ │ scalar/scalar │ 16K │ │ jetify-com/devbox │ 12K │ │ shiaho777/web-to-app │ 7.1K │ │ WeblateOrg/weblate │ 6.1K │ └──────────────────────┴───────┘

178 dependents at or above the star threshold

CLI Reference

dep-rank deps — List top dependents

dep-rank deps https://github.com/django/django

dep-rank deps https://github.com/django/django --rows 20 --min-stars 100 dep-rank deps https://github.com/django/django --descriptions --format json dep-rank deps https://github.com/django/django --packages

In table output (deps, search, and the live progress table), repository names are clickable links to their GitHub pages in terminals that support OSC 8 hyperlinks; piped or redirected output stays plain text.

dep-rank search — Search code in dependents

dep-rank search https://github.com/django/django "from django.db import"

dep-rank search https://github.com/django/django "middleware" --max-repos 20

search always runs a bounded non-adaptive top-K scrape (--no-adaptive-stop is not exposed; adaptive early-stop is permanently disabled for this command).

Rate-limited code searches are retried up to twice, honoring GitHub's wait headers; if GitHub keeps limiting, the remaining repositories are reported as not searched (rate limited).

Partial results

A scrape result (deps, and the search pre-pass) reports whether it finished: results include a complete flag and a reason. complete: false means the scrape stopped early — max_pages_reached (raise --max-pages), trend_converged (the adaptive heuristic judged the top-K stable; use --no-adaptive-stop to scrape until exhaustion or --max-pages), network_failure, or rate_limited. total_count/filtered_count are then lower bounds across the pages actually scraped, not population totals.

Repositories with several packages

Some repositories publish several packages, and GitHub's dependents page lists them in a dropdown (at most 100). Without --package-name, GitHub picks the package, and dep-rank names it and the others in a hint. JSON output then also carries package (the one scraped) and packages (every listed name).

dep-rank cache — Manage cache

dep-rank cache stats    # Show cache size

dep-rank cache clear # Clear all cached data

MCP server

dep-rank mcp runs an MCP server over stdio so AI agents can call dep-rank directly. It needs the optional mcp extra:

pip install "dep-rank[mcp]"

Client configuration (the command works with any MCP client that launches stdio servers):

{

"mcpServers": { "dep-rank": { "command": "uvx", "args": ["--with", "dep-rank[mcp]", "dep-rank", "mcp"], "env": { "DEP_RANK_TOKEN": "ghp_your_token_here" } } } }

DEP_RANK_TOKEN is required: both tools fail without it. The token is read from the server's environment only, never from a tool argument.

Tools:

• get_dependents — rank a repository's dependents by stars or trust (the dep-rank deps pipeline). Parameters mirror the CLI: url, rows, min_stars, dependent_type, descriptions, rank_by, trust_check, downloads, max_pages, adaptive_stop, package_name.
• search_dependents — search code across the top dependents (the dep-rank search pipeline): url, query, max_repos, min_stars, max_pages, package_name.

Caveats:

• Results can be partial. Check complete and reason before treating counts as totals; see Partial results.
• Trust scores are pool-relative heuristics, not quality or fraud verdicts; see Trust Ranking.
• Calls run one at a time; a call that arrives while another is running waits for it.
• Long calls report progress, including GitHub rate-limit waits. Claude Code moves MCP calls that run longer than two minutes into the background.
• The server honors HTTP_PROXY, HTTPS_PROXY, and NO_PROXY from its environment. A SOCKS proxy (for example ALL_PROXY=socks5://...) is not supported: tool calls fail with an error until it is removed from the server's environment.

Run the MCP server in Docker (MCP Toolkit)

The ghcr.io/j7an/dep-rank image runs the MCP server under Docker MCP Toolkit. You get:

• container isolation, with no host filesystem access;
• network access limited to GitHub when the gateway runs with --block-network;
• one profile shared by every agent harness you connect.

It does not change prompt-injection risk: tool results still contain text from third-party repositories, and your agent reads it.

Prerequisites: Docker Desktop with MCP Toolkit, and profiles enabled (the MCPWorkingSets feature flag in Docker Desktop, or docker mcp feature enable profiles).

1. Save this server definition as ~/.docker/mcp/catalogs/dep-rank.yaml. The gateway only reads file:// definitions from that directory.

   name: dep-rank

title: dep-rank type: server image: ghcr.io/j7an/dep-rank:latest description: Rank a GitHub repo's dependents by stars or trust heuristic, and search their code secrets:

• name: dep-rank.token env: DEP_RANK_TOKEN example: ghp_your_token_here volumes:
• dep-rank-cache:/cache allowHosts:
• github.com:443
• api.github.com:443

get_dependents with downloads also needs packages.ecosyste.ms:443, api.npmjs.org:443, and api.deps.dev:443 in allowHosts; without them, download stats are reported as unavailable.

1. Create the profile. Keep --id dep-rank: without it the ID becomes dep_rank, which won't match the harness config below.

   docker mcp profile create --name dep-rank --id dep-rank \

--server "file://$HOME/.docker/mcp/catalogs/dep-rank.yaml"

1. Store your GitHub token:

   gh auth token | docker mcp secret set dep-rank.token

If the secret is missing, the gateway passes the literal value as DEP_RANK_TOKEN, so calls fail with GitHub errors rather than a "token missing" message.

1. Point each harness at the gateway. Write the entry by hand so it includes --block-network, which is what enforces allowHosts:

   {

"mcpServers": { "dep-rank": { "command": "docker", "args": ["mcp", "gateway", "run", "--profile", "dep-rank", "--block-network"] } } }

docker mcp client connect -p dep-rank also works, but the entry it writes omits --block-network; add it yourself.

Notes:

• For reproducible installs, pin image to a release tag (ghcr.io/j7an/dep-rank: ) or an @sha256: digest. Verify an image's build provenance with gh attestation verify oci://ghcr.io/j7an/dep-rank: --repo j7an/dep-rank.
• Each tool call starts a fresh container. The dep-rank-cache volume keeps the cache warm between calls.
• The gateway can leave its proxy containers behind. Remove them with docker rm -f $(docker ps -aq --filter label=docker-mcp-proxy=true).

Python API (provisional)

Use dep_rank.core.dependents.get_dependents for the deps pipeline in Python. It returns dep_rank.core.models.DependentsResult; select repository or package dependents with dep_rank.core.models.DependentType. The API may change during 0.x.

import asyncio

import httpx2

from dep_rank.core.cache import SqliteCache from dep_rank.core.dependents import get_dependents from dep_rank.core.models import DependentsResult, DependentType

async def main(cache_dir: str | None = None) -> None: cache = SqliteCache(cache_dir) if cache_dir is not None else None try: if cache is not None: await cache.initialize() async with httpx2.AsyncClient() as session: result: DependentsResult = await get_dependents( session, "https://github