{
  "markdown": "<div align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"Fossick\" width=\"220\" />\n\n  <h3>Prospect across all of GitHub from your AI agent.</h3>\n\n  <p><strong>Find libraries, discover gems, search code patterns, and read real production code — across 200M+ repos, PyPI, and npm.</strong></p>\n\n  <p>\n    <a href=\"https://pypi.org/project/fossick-mcp/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/fossick-mcp?color=blue&label=pypi\"></a>\n    <a href=\"https://pypi.org/project/fossick-mcp/\"><img alt=\"Downloads\" src=\"https://img.shields.io/pypi/dm/fossick-mcp?color=blue\"></a>\n    <a href=\"https://github.com/Lipdog/fossick-mcp/actions/workflows/test.yml\"><img alt=\"Tests\" src=\"https://img.shields.io/github/actions/workflow/status/Lipdog/fossick-mcp/test.yml?branch=main&label=tests\"></a>\n    <a href=\"https://github.com/Lipdog/fossick-mcp/commits/main\"><img alt=\"Last commit\" src=\"https://img.shields.io/github/last-commit/Lipdog/fossick-mcp?color=blue\"></a>\n    <a href=\"./LICENSE\"><img alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-green\"></a>\n    <a href=\"https://www.python.org/\"><img alt=\"Python 3.11+\" src=\"https://img.shields.io/badge/python-3.11+-blue\"></a>\n    <a href=\"https://modelcontextprotocol.io/\"><img alt=\"MCP Protocol\" src=\"https://img.shields.io/badge/MCP-1.0-orange\"></a>\n  </p>\n\n  <p>\n    <a href=\"https://cursor.com/en/install-mcp?name=fossick&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmb3NzaWNrLW1jcCJdfQ%3D%3D\"><img alt=\"Install in Cursor\" src=\"https://cursor.com/deeplink/mcp-install-dark.svg\"></a>\n    <a href=\"https://insiders.vscode.dev/redirect/mcp/install?name=fossick&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22fossick-mcp%22%5D%7D\"><img alt=\"Install in VS Code\" src=\"https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white\"></a>\n  </p>\n</div>\n\n---\n\n## Contents\n\n- [What is Fossick](#what-is-fossick)\n- [Examples](#examples)\n- [Installation](#installation)\n- [Tools](#tools)\n- [Why Fossick](#why-fossick)\n- [FAQ](#faq)\n- [Configuration](#configuration)\n- [Development](#development)\n- [License](#license)\n\n---\n\n## What is Fossick\n\n> **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.\n\nThat's exactly what this tool does — but for code.\n\nFossick 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:\n\n1. **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.\n2. **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.\n3. **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.\n\nUseful any time you'd benefit from your agent reaching into the world's largest code corpus:\n\n- **Pick the right library.** Find a small, focused, actively-maintained option for any task — not just the most popular one.\n- **Discover hidden gems.** Surface the 500-star library that ranks higher on _relevance_ than the 50,000-star incumbent.\n- **Drill into a repo you found.** Walk its layout, read its README, find where its core API is defined — without `git clone`.\n- **Find usage patterns in real code.** Search how an API is called in production, then read the matched files in context.\n- **Get inspired.** See how others structured similar projects, what patterns they used, what tradeoffs they made.\n- **Stay current.** Discover what's trending, just-released, or new in an ecosystem — past your model's training cutoff.\n\nIt does **not** do code archaeology — git blame, PR history, version diffs. Reach for `git` and `gh` for that.\n\n---\n\n## Examples\n\nOnce Fossick is connected, here's the kind of thing you can ask your agent.\n\n### Discover libraries and packages\n\n- _\"Find me a small, actively-maintained Rust TUI library — something newer than ratatui.\"_\n- _\"What are people using instead of LangChain these days?\"_\n- _\"Show me trending Python web frameworks released in the last 90 days.\"_\n- _\"What's a good lightweight alternative to Pydantic for runtime validation?\"_\n\n### Drill into a specific repo\n\n- _\"Browse the structure of `astral-sh/uv` — what's in `crates/`?\"_\n- _\"Read the main `__init__.py` from `pydantic/pydantic`.\"_\n- _\"Where is the `Stream` class defined in `anthropics/anthropic-sdk-python`?\"_\n- _\"What's the latest release of `modelcontextprotocol/python-sdk` and when did it ship?\"_\n\n### Find code patterns in the wild\n\n- _\"How do production FastAPI apps actually set up structured logging with `structlog` and `asyncio`?\"_\n- _\"Show me real examples of `tokio::select!` being used with timeout cancellation.\"_\n- _\"Find Dockerfiles that build multi-stage Python images with `uv`.\"_\n- _\"How are people calling the OpenAI API streaming endpoint from Go?\"_\n\n### Vet a dependency before adopting it\n\n- _\"Is the `requests` library still maintained?\"_\n- _\"Compare freshness of `httpx` vs `aiohttp` — last release dates, recent activity.\"_\n- _\"Who actually uses `msgspec`? Show me real usage in production codebases.\"_\n- _\"Find the GitHub repo behind the `polars` PyPI package and check its last release.\"_\n\n---\n\n## Installation\n\n> **Prerequisite:** [uv](https://docs.astral.sh/uv/) — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`.\n> Then `uvx` will download and run Fossick on demand. No clone needed.\n\n### Claude Code\n\nThree 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](https://code.claude.com/docs/en/mcp)).\n\n#### Global (recommended for personal use)\n\nAvailable in **every project** on your machine. Stored in `~/.claude.json`, private to your user account.\n\n```bash\nclaude mcp add fossick --scope user uvx fossick-mcp\n```\n\n#### Team-shared (committed to git)\n\nStored 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.\n\n```bash\nclaude mcp add fossick --scope project uvx fossick-mcp\n```\n\n#### This project only (default)\n\n**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.\n\n```bash\nclaude mcp add fossick uvx fossick-mcp\n```\n\n#### Manual install\n\nIf you'd rather skip the CLI, write the config yourself. The JSON shape is the same regardless of scope — only the file changes:\n\n- `~/.claude.json` for user / local scope\n- `.mcp.json` (project root) for project scope\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"]\n    }\n  }\n}\n```\n\n### Other clients\n\n<details>\n<summary><b>Cursor</b></summary>\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=fossick&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmb3NzaWNrLW1jcCJdfQ%3D%3D)\n\nOr add manually to `~/.cursor/mcp.json` or `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>VS Code</b></summary>\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=fossick&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22fossick-mcp%22%5D%7D)\n\nOr via CLI:\n\n```bash\ncode --add-mcp '{\"name\":\"fossick\",\"command\":\"uvx\",\"args\":[\"fossick-mcp\"]}'\n```\n\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n</details>\n\n<details>\n<summary><b>Windsurf</b></summary>\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Cline</b></summary>\n\nEdit `cline_mcp_settings.json` via the Cline extension's MCP settings panel:\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Codex</b></summary>\n\n```bash\ncodex mcp add fossick -- uvx fossick-mcp\n```\n\nOr edit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.fossick]\ncommand = \"uvx\"\nargs = [\"fossick-mcp\"]\n```\n\n</details>\n\n<details>\n<summary><b>From source (development)</b></summary>\n\n```bash\ngit clone https://github.com/Lipdog/fossick-mcp.git\ncd fossick-mcp\nuv sync\n```\n\nThen point your MCP config at the local clone:\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/fossick-mcp\", \"fossick-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n---\n\n## Tools\n\nSeven read-only tools, organized by their role in the discovery workflow.\n\n### Find candidates\n\n| Tool | What it does |\n|---|---|\n| **`search_repos`** | Discover repositories by topic, stars, language, recency, or trending. Pass multiple query phrasings in one call for better recall. |\n| **`search_packages`** | Direct lookup on PyPI or npm by package name. Returns version, description, links, and GitHub repo URL. |\n\n### Evaluate a candidate\n\n| Tool | What it does |\n|---|---|\n| **`repo_tree`** | Browse a repo's file layout with depth and glob filtering. |\n| **`get_file`** | Read any file at any branch, tag, or commit. |\n| **`find_symbol`** | Goto-definition via real AST queries — find where a class, function, or type is actually declared, not just substring-matched. |\n| **`list_tags`** | View tags and recent releases. The fastest \"is this still maintained?\" check. |\n\n### Search code across GitHub\n\n| Tool | What it does |\n|---|---|\n| **`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. |\n\nAll 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.\n\n---\n\n## Why Fossick\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Rate-limit aware.** Tracks GitHub's Search and Core API buckets separately, sleeps on exhaustion, retries with exponential backoff.\n- **Zero config for `gh` users.** Already have the GitHub CLI authenticated? Nothing to configure.\n- **Plays well with others.** Read-only, idempotent, safe to auto-approve. Pair Fossick with [github-mcp-server](https://github.com/github/github-mcp-server) when you also need to act on your own repos (issues, PRs, Actions).\n\n---\n\n## FAQ\n\n<details>\n<summary><b>Do I need a GitHub token?</b></summary>\n\nYes — without one you'll hit GitHub's 60-requests-per-hour unauthenticated limit almost immediately. The easiest path is to install the [GitHub CLI](https://cli.github.com/) and run `gh auth login` once. Fossick picks up your token automatically. No need to pass anything in the MCP config.\n\n</details>\n\n<details>\n<summary><b>Why <code>uvx</code> instead of <code>pip install</code>?</b></summary>\n\n`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.\n\n</details>\n\n<details>\n<summary><b>Does Fossick use my GitHub API quota?</b></summary>\n\nYes. 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.\n\n</details>\n\n<details>\n<summary><b>Will it work with MCP client X?</b></summary>\n\nIf 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](#installation) section for client-specific snippets.\n\n</details>\n\n<details>\n<summary><b>Does Fossick search private repos?</b></summary>\n\nOnly 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.\n\n</details>\n\n<details>\n<summary><b>Why doesn't it do <code>git blame</code> / PR history / version diffs?</b></summary>\n\nDeliberate 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.\n\n</details>\n\n<details>\n<summary><b>How fresh is the data?</b></summary>\n\nLive 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.\n\n</details>\n\n---\n\n## Configuration\n\n### Authentication\n\nFossick resolves a GitHub token automatically:\n\n1. `GH_TOKEN`, `GITHUB_TOKEN`, or `GITHUB_PERSONAL_ACCESS_TOKEN` env vars\n2. `gh auth token` from the [GitHub CLI](https://cli.github.com/) — **no config needed if you're already logged in**\n\nTo pass a token explicitly:\n\n```json\n{\n  \"mcpServers\": {\n    \"fossick\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fossick-mcp\"],\n      \"env\": { \"GITHUB_TOKEN\": \"ghp_your_token_here\" }\n    }\n  }\n}\n```\n\nA token only needs public repo read access (no scopes selected is fine).\n\n### Rate limits\n\nFossick tracks both GitHub API buckets and pauses automatically when either is exhausted.\n\n| Bucket | Limit | Tools |\n|---|---|---|\n| **Search API** | 30 req/min | `search_repos`, `search_code`, `find_symbol` |\n| **Core API** | 5,000 req/hr | `get_file`, `repo_tree`, `list_tags` |\n| **External** | No GitHub limit | `search_packages` (hits PyPI/npm directly) |\n\nRetries 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.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/)\n\n### Setup\n\n```bash\ngit clone https://github.com/Lipdog/fossick-mcp.git\ncd fossick-mcp\nuv sync\n```\n\n### Run\n\nLaunch the MCP server on stdio (for manual testing or local MCP-client config):\n\n```bash\nuv run fossick-mcp\n```\n\n### Test\n\nUnit and registration tests — no network, runs in seconds:\n\n```bash\nuv run pytest\n```\n\nLive integration tests — hits real GitHub against pinned `modelcontextprotocol/python-sdk@v1.14.0`:\n\n```bash\nuv run pytest -m live\n```\n\n### Build\n\n```bash\nuv build\n```\n\nProduces `dist/fossick_mcp-<version>.tar.gz` and the corresponding wheel.\n\n### Architecture\n\nSee [`CLAUDE.md`](./CLAUDE.md) for the full architecture tour, key patterns, and the recipe for adding new tools.\n\n---\n\n## Star history\n\n<a href=\"https://star-history.com/#Lipdog/fossick-mcp&Date\">\n  <img alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=Lipdog/fossick-mcp&type=Date\" width=\"600\" />\n</a>\n\n---\n\n## License\n\n[MIT](./LICENSE) — fossick away.\n\n<!-- mcp-name: io.github.Lipdog/fossick -->\n\n",
  "bytes": 17232,
  "sha": "25a1dbda82b7115c6438502232967f66b5ccfd068c589ac7a485a2910d4fef2a",
  "repo_slug": "lipdog/fossick-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lipdog_fossick_158faeea/readme"
}