Metadata-Version: 2.4
Name: fossick-mcp
Version: 0.1.4
Summary: MCP server — search code, find libraries, and evaluate dependencies across all of GitHub, PyPI, and npm
Project-URL: Homepage, https://github.com/Lipdog/fossick-mcp
Project-URL: Repository, https://github.com/Lipdog/fossick-mcp
Project-URL: Issues, https://github.com/Lipdog/fossick-mcp/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,code-search,github,library-discovery,mcp,mcp-server
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.26
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tree-sitter-language-pack>=1.5.0
Requires-Dist: tree-sitter>=0.25.2
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo.png" alt="Fossick" width="220" />

  <h3>Prospect across all of GitHub from your AI agent.</h3>

  <p><strong>Find libraries, discover gems, search code patterns, and read real production code — across 200M+ repos, PyPI, and npm.</strong></p>

  <p>
    <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>
    <a href="https://pypi.org/project/fossick-mcp/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/fossick-mcp?color=blue"></a>
    <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>
    <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>
    <a href="./LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-green"></a>
    <a href="https://www.python.org/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11+-blue"></a>
    <a href="https://modelcontextprotocol.io/"><img alt="MCP Protocol" src="https://img.shields.io/badge/MCP-1.0-orange"></a>
  </p>

  <p>
    <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>
    <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>
  </p>
</div>

---

## Contents

- [What is Fossick](#what-is-fossick)
- [Examples](#examples)
- [Installation](#installation)
- [Tools](#tools)
- [Why Fossick](#why-fossick)
- [FAQ](#faq)
- [Configuration](#configuration)
- [Development](#development)
- [License](#license)

---

## 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](https://docs.astral.sh/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](https://code.claude.com/docs/en/mcp)).

#### Global (recommended for personal use)

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

```bash
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.

```bash
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.

```bash
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

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

### Other clients

<details>
<summary><b>Cursor</b></summary>

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=fossick&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmb3NzaWNrLW1jcCJdfQ%3D%3D)

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

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

</details>

<details>
<summary><b>VS Code</b></summary>

[![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)

Or via CLI:

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

</details>

<details>
<summary><b>Claude Desktop</b></summary>

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

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

Restart Claude Desktop after saving.

</details>

<details>
<summary><b>Windsurf</b></summary>

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

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

</details>

<details>
<summary><b>Cline</b></summary>

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

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

</details>

<details>
<summary><b>Codex</b></summary>

```bash
codex mcp add fossick -- uvx fossick-mcp
```

Or edit `~/.codex/config.toml`:

```toml
[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]
```

</details>

<details>
<summary><b>From source (development)</b></summary>

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

Then point your MCP config at the local clone:

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

</details>

---

## 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](https://github.com/github/github-mcp-server) when you also need to act on your own repos (issues, PRs, Actions).

---

## FAQ

<details>
<summary><b>Do I need a GitHub token?</b></summary>

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](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.

</details>

<details>
<summary><b>Why <code>uvx</code> instead of <code>pip install</code>?</b></summary>

`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.

</details>

<details>
<summary><b>Does Fossick use my GitHub API quota?</b></summary>

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.

</details>

<details>
<summary><b>Will it work with MCP client X?</b></summary>

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](#installation) section for client-specific snippets.

</details>

<details>
<summary><b>Does Fossick search private repos?</b></summary>

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.

</details>

<details>
<summary><b>Why doesn't it do <code>git blame</code> / PR history / version diffs?</b></summary>

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.

</details>

<details>
<summary><b>How fresh is the data?</b></summary>

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.

</details>

---

## 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](https://cli.github.com/) — **no config needed if you're already logged in**

To pass a token explicitly:

```json
{
  "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](https://docs.astral.sh/uv/)

### Setup

```bash
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):

```bash
uv run fossick-mcp
```

### Test

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

```bash
uv run pytest
```

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

```bash
uv run pytest -m live
```

### Build

```bash
uv build
```

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

### Architecture

See [`CLAUDE.md`](./CLAUDE.md) for the full architecture tour, key patterns, and the recipe for adding new tools.

---

## Star history

<a href="https://star-history.com/#Lipdog/fossick-mcp&Date">
  <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Lipdog/fossick-mcp&type=Date" width="600" />
</a>

---

## License

[MIT](./LICENSE) — fossick away.

<!-- mcp-name: io.github.Lipdog/fossick -->

