Metadata-Version: 2.4
Name: fossick-mcp
Version: 0.1.2
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

# Fossick MCP

**Help your AI agent pick the right dependency — and learn from real code on GitHub.**

Fossick is an MCP server that gives Claude, Cursor, and other LLM agents a focused toolkit for **discovering libraries, evaluating them, and finding real-world code patterns** across all 200M+ GitHub repos plus PyPI and npm. Seven read-only tools that answer two questions agents constantly run into: _"what should I install for this?"_ and _"how do real projects actually use this API?"_

```
You: "I need a Rust TUI library — something newer than ratatui."

Agent: → search_repos(queries=["rust tui terminal", "rust terminal ui framework"],
                     language="Rust", stars="100..5000", pushed=">2026-02-01")
       → list_tags(repo=<top candidate>)        # still maintained?
       → repo_tree(repo=<top candidate>)        # what does it look like?
       → get_file(repo=<top candidate>, path="README.md")
       → search_code(query="<library>::App", language="Rust")  # real usage in the wild

       Here are 3 actively-maintained options with star counts, last release,
       and example usage from real repos…
```

Fossick is **not** for code archaeology — git history, blame, PR review, version diffing. Reach for `git` and `gh` CLI for that. Fossick exists for the moment you're starting something new and need to pick well.

## Why Fossick

- **Discovery-shaped, not search-shaped.** Tools are designed around the workflow ("find candidate → check if it's alive → read the API → see how others use it"), not around exposing every GitHub endpoint.
- **Hint chaining.** Every response ends with suggested next steps (`→ try repo_tree on this candidate`), so the agent has a clear path forward without guessing.
- **Multi-query search.** `search_repos` accepts a list of phrasings in one call and reranks the merged results — better recall than running the same query three times.
- **Tree-sitter symbol search.** `find_symbol` runs real AST queries on fetched files instead of substring-matching, so "where is `class Foo` defined" actually returns the definition.
- **Honest about rate limits.** Tracks the GitHub Search and Core buckets separately, sleeps on exhaustion, retries with exponential backoff.
- **Zero install for `gh` users.** If you already have GitHub CLI authenticated, Fossick uses your token automatically.

## Install

You'll need [uv](https://docs.astral.sh/uv/) and Python 3.11+.

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

Then add Fossick to your MCP client. The `command` is the same everywhere — just point `--directory` at your clone.

<details open>
<summary><b>Claude Code</b></summary>

Add to your project's `.mcp.json` (or `~/.claude.json` for global):

```json
{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "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": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}
```
</details>

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

Add to `~/.cursor/mcp.json` or `.cursor/mcp.json` in your project:

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

### Authentication

Fossick resolves a GitHub token automatically, in this order:

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": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}
```

A token only needs the public read scope (no scopes selected is fine for public repos).

## Tools

Seven 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. Accepts a list of query phrasings for better recall. |
| **`search_packages`** | Direct lookup on PyPI or npm when you already know the package name. Returns version, description, links, GitHub repo. |

### 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 (READMEs, examples, the main module). |
| **`find_symbol`** | Goto-definition via tree-sitter — find where a class, function, or type is actually declared. |
| **`list_tags`** | View tags and recent releases. The fastest "is this still maintained?" check. |

### Search real code across GitHub

| Tool | What it does |
|---|---|
| **`search_code`** | Search the contents of every public file on GitHub. Full search syntax (`repo:`, `language:`, `path:`, boolean operators, regex). Use it to find real-world examples of an API, locate config patterns (`filename:Dockerfile FROM python`), or scope a search to a single repo. The "show me how people actually do this" tool. |

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

## A typical session

> _"Find me a small, modern alternative to Pydantic for runtime validation in Python."_

```
1. search_repos(queries=[
     "pydantic alternative validation",
     "dataclass runtime type validation",
     "lightweight schema validation python"
   ], language="Python", stars="100..5000")
   → ranked candidates with stars, descriptions, last-push dates

2. list_tags(repo=<top candidate>)
   → recent release dates — confirms it's actively maintained

3. get_file(repo=<top candidate>, path="README.md")
   → positioning, install instructions, code samples

4. search_code(query="from <pkg> import …", language="Python")
   → real adoption signal — who else is using it

5. find_symbol(repo=<top candidate>, name="Struct")
   → goto-definition for the core API — read it before adopting it
```

The agent can run the full evaluation in one turn without you context-switching to a browser.

Or, when you just want a code pattern:

> _"Show me how people set up structured logging with `structlog` and `asyncio` in production."_

```
1. search_code(query="structlog configure_once asyncio", language="Python")
   → matches with surrounding context, ranked by file relevance

2. get_file(repo=<best match>, path=<file>)
   → read the full setup in context, not just the snippet
```

## Rate limits

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

- **Search API** — 30/min: `search_repos`, `search_code`, `find_symbol`
- **Core API** — 5,000/hr: `get_file`, `repo_tree`, `list_tags`
- **External APIs** — `search_packages` hits PyPI / npm directly, no GitHub limit

Retries use exponential backoff on `403`, `429`, `502`, `503`. Search results are cached for 120s, branch content for 300s, SHA-pinned content for 1h.

## Development

```bash
git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync
uv run pytest                   # unit + registration (no network)
uv run pytest -m live           # integration tests against real GitHub
uv run fossick-mcp              # launch the server on stdio
```

The codebase is small and easy to navigate — see [`CLAUDE.md`](./CLAUDE.md) for an architecture tour and the recipe for adding a new tool.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- A GitHub token, or [`gh`](https://cli.github.com/) authenticated locally

## License

[MIT](./LICENSE) © 2026 Hayden Lipsky
