Fossick

Explore todo o GitHub a partir do seu agente de IA.

Encontre bibliotecas, descubra gems, pesquise padrões de código e leia código de produção real — em mais de 200 milhões de repositórios, PyPI e npm.

Conteúdo

• O que é o Fossick
• Exemplos
• Instalação
• Ferramentas
• Por que Fossick
• FAQ
• Configuração
• Desenvolvimento
• Licença

O que é o Fossick

fossick /ˈfɒsɪk/ verbo (australiano/nova-zelandês) — prospectar ou vasculhar em busca de gemas, especialmente o tipo de mineração em pequena escala em que você peneira leitos de riachos e rejeitos antigos procurando o que os operadores maiores deixaram para trás.

É exatamente isso que esta ferramenta faz — mas para código.

O Fossick dá ao seu agente de IA sete ferramentas somente leitura para explorar todo o GitHub, PyPI e npm, cobrindo o ciclo completo de descoberta de ponta a ponta:

1. Pesquise e descubra. Peneire mais de 200 milhões de repositórios com ranqueamento de relevância multi-consulta, encontre as bibliotecas pequenas, mas boas, que ferramentas maiores enterram, consulte pacotes no PyPI e npm.
2. Aprofunde-se em qualquer repositório sem clonar. Navegue pela árvore de um repositório remoto com filtros de profundidade e glob, leia qualquer arquivo em qualquer branch/tag/commit e vá para a definição de qualquer classe, função ou tipo — tudo no GitHub remoto, sem necessidade de checkout local.
3. Pesquise padrões de código em todo o GitHub. Busca em texto completo, regex e com reconhecimento de qualificadores em todos os arquivos públicos — descubra como uma API é realmente usada em produção, não apenas na documentação.

Útil sempre que você quiser que seu agente alcance o maior corpus de código do mundo:

• Escolha a biblioteca certa. Encontre uma opção pequena, focada e mantida ativamente para qualquer tarefa — não apenas a mais popular.
• Descubra joias escondidas. Traga à tona a biblioteca de 500 estrelas que ranqueia mais alto em relevância do que a atual de 50.000 estrelas.
• Aprofunde-se em um repositório que você encontrou. Explore sua estrutura, leia o README, descubra onde sua API principal é definida — sem git clone.
• Encontre padrões de uso em código real. Pesquise como uma API é chamada em produção e depois leia os arquivos correspondentes no contexto.
• Inspire-se. Veja como outros estruturaram projetos semelhantes, quais padrões usaram e quais trade-offs fizeram.
• Mantenha-se atualizado. Descubra o que está em alta, acabou de ser lançado ou é novo em um ecossistema — além do corte de treinamento do seu modelo.

Ele não faz arqueologia de código — git blame, histórico de PRs, diffs de versões. Para isso, use git e gh.

Exemplos

Depois que o Fossick estiver conectado, aqui está o tipo de coisa que você pode pedir ao seu agente.

Descubra bibliotecas e pacotes

• "Encontre uma biblioteca TUI em Rust pequena e mantida ativamente — algo mais novo que o ratatui."
• "O que as pessoas estão usando no lugar do LangChain atualmente?"
• "Mostre-me frameworks web em Python em alta lançados nos últimos 90 dias."
• "Qual é uma boa alternativa leve ao Pydantic para validação em tempo de execução?"

Aprofunde-se em um repositório específico

• "Explore a estrutura de astral-sh/uv — o que há em crates/?"
• "Leia o __init__.py principal de pydantic/pydantic."
• "Onde a classe Stream está definida em anthropics/anthropic-sdk-python?"
• "Qual é a versão mais recente de modelcontextprotocol/python-sdk e quando ela foi lançada?"

Encontre padrões de código no mundo real

• "Como aplicativos FastAPI em produção realmente configuram logging estruturado com structlog e asyncio?"
• "Mostre-me exemplos reais de tokio::select! sendo usado com cancelamento por timeout."
• "Encontre Dockerfiles que criam imagens Python multi-estágio com uv."
• "Como as pessoas estão chamando o endpoint de streaming da API da OpenAI a partir do Go?"

Avalie uma dependência antes de adotá-la

• "A biblioteca requests ainda é mantida?"
• "Compare a atualização de httpx vs aiohttp — datas do último lançamento, atividade recente."
• "Quem realmente usa msgspec? Mostre-me uso real em codebases de produção."
• "Encontre o repositório GitHub por trás do pacote polars no PyPI e verifique seu último lançamento."

Instalação

Pré-requisito: uv — instale com curl -LsSf https://astral.sh/uv/install.sh | sh. Em seguida, uvx baixará e executará o Fossick sob demanda. Sem necessidade de clone.

Claude Code

Três escopos de instalação. Escolha o que corresponde a como você quer que o Fossick esteja disponível — globalmente, compartilhado com sua equipe ou apenas para você em um projeto. A flag de escopo controla onde a configuração é gravada (Escopos MCP do Claude Code).

Global (recomendado para uso pessoal)

Disponível em todos os projetos na sua máquina. Armazenado em ~/.claude.json, privado para sua conta de usuário.

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

Compartilhado com a equipe (commitado no git)

Armazenado em .mcp.json na raiz do projeto, verificado no controle de versão. Qualquer pessoa que clonar o repositório recebe o mesmo servidor MCP. Use isso quando toda a equipe deve ter o Fossick.

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

Apenas neste projeto (padrão)

Escopo local é o padrão. Habilitado apenas no projeto atual, apenas para você. Armazenado em ~/.claude.json no caminho deste projeto — não commitado, não compartilhado com colaboradores.

claude mcp add fossick uvx fossick-mcp

Instalação manual

Se preferir pular a CLI, escreva a configuração você mesmo. A estrutura JSON é a mesma independentemente do escopo — apenas o arquivo muda:

• ~/.claude.json para escopo de usuário / local
• .mcp.json (raiz do projeto) para escopo de projeto

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

Outros clientes

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

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

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

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

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

codex mcp add fossick -- uvx fossick-mcp

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

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

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

Ferramentas

Sete ferramentas somente leitura, organizadas pelo papel delas no fluxo de trabalho de descoberta.

Encontre candidatos

Avalie um candidato

Pesquise código no GitHub

Todas as ferramentas são somente leitura, idempotentes e seguras para aprovação automática. Cada resposta termina com próximos passos encadeados por dicas para que o agente saiba o que fazer em seguida.

Por que Fossick

• Feito para o fluxo de trabalho de descoberta. As ferramentas seguem a forma natural: encontre candidato → aprofunde-se → leia a API → veja como outros usam. Sugestões de próximos passos encadeadas por dicas mantêm seu agente no caminho certo durante todo o ciclo.
• Aprofunde-se em qualquer repositório público sem clonar. Navegue por árvores de repositórios remotos com filtros de profundidade + glob, leia qualquer arquivo em qualquer branch/tag/commit e execute busca real de símbolos baseada em AST para ir à definição de qualquer classe, função ou tipo — tudo no GitHub remoto.
• Busca multi-consulta com ranqueamento inteligente. search_repos aceita uma lista de formulações em uma única chamada e aplica ranqueamento de relevância composto que prioriza correspondência literal sobre popularidade bruta — traz à tona a joia de 500 estrelas que supera a atual de 50.000 estrelas.
• Econômico em tokens por design. 7 ferramentas focadas (não 30+), saídas em Markdown formatado (não dumps JSON), cache com TTL, encadeamento de dicas que reduz as rodadas de raciocínio do agente e busca multi-consulta que agrupa N requisições em 1. Cada descrição de ferramenta e resposta é dimensionada para manter seu orçamento de contexto livre para o trabalho real.
• Ciente de limites de taxa. Rastreia os buckets da API de Pesquisa e da API Principal do GitHub separadamente, pausa na exaustão e tenta novamente com backoff exponencial.
• Zero configuração para usuários de gh. Já tem a CLI do GitHub autenticada? Nada para configurar.
• Integra-se bem com outros. Somente leitura, idempotente, seguro para aprovação automática. Combine o Fossick com github-mcp-server quando você também precisar agir nos seus próprios repositórios (issues, PRs, Actions).

FAQ

Configuração

Autenticação

O Fossick resolve um token do GitHub automaticamente:

1. Variáveis de ambiente GH_TOKEN, GITHUB_TOKEN ou GITHUB_PERSONAL_ACCESS_TOKEN
2. gh auth token da GitHub CLI — nenhuma configuração necessária se você já estiver conectado

Para passar um token explicitamente:

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

Um token só precisa de acesso de leitura a repositórios públicos (nenhum escopo selecionado é suficiente).

Limites de taxa

O Fossick monitora ambos os buckets da API do GitHub e pausa automaticamente quando qualquer um deles é esgotado.

As tentativas usam backoff exponencial em erros de limite de taxa e erros transitórios. Os resultados são armazenados em cache brevemente para evitar chamadas de API redundantes, com TTLs mais longos para conteúdo fixado a um SHA de commit específico.

Desenvolvimento

Pré-requisitos

• Python 3.11+
• uv

Configuração

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

Executar

Inicie o servidor MCP no stdio (para testes manuais ou configuração local do cliente MCP):

uv run fossick-mcp

Testar

Testes de unidade e registro — sem rede, executa em segundos:

uv run pytest

Testes de integração ao vivo — acessa o GitHub real contra modelcontextprotocol/python-sdk@v1.14.0 fixado:

uv run pytest -m live

Compilar

uv build

Produz dist/fossick_mcp-<version>.tar.gz e o wheel correspondente.

Arquitetura

Consulte CLAUDE.md para o tour completo da arquitetura, padrões principais e a receita para adicionar novas ferramentas.

Histórico de estrelas

Licença

MIT — explore à vontade.