whichlib

whichlib

O seletor de dependências para agentes de codificação. Pergunte qual biblioteca usar e obtenha uma resposta pontuada e verificada em vez de um palpite.

whichlib é um servidor MCP com três ferramentas (recommend_repos, compare_repos, trending_repos) e um painel gratuito, Fresh Repos, que mostra os repositórios GitHub mais estrelados criados no último dia, semana e mês. Cada repositório recebe uma pontuação transparente de 0 a 100 baseada em momentum, manutenção, adoção (estrelas, forks, downloads npm e PyPI) e licença, além de um veredito de uma linha.

Início rápido

Agentes: veja servidor MCP abaixo para a instalação em uma linha.

Painel:

1. Clone ou baixe este repositório.
2. Clique duas vezes em whichlib/dashboard/index.html.

Isso é tudo. A página é um único arquivo HTML que chama a API de Busca do GitHub diretamente do seu navegador. Sem etapa de build, sem servidor, sem conta.

Opcional: cole um token do GitHub em Configurações na página para aumentar o limite da API de 10 para 30 requisições por minuto. Um token de granularidade fina sem permissões é suficiente. Ele permanece no armazenamento local do seu navegador.

O que você obtém

• Três abas: Hoje, Esta semana, Este mês. Cada uma lista os 100 repositórios mais estrelados criados nesse período.
• Ordene por qualquer coluna: estrelas, estrelas por dia, forks, issues abertas, data de criação, último push, linguagem, licença ou nome. Clique novamente para inverter.
• Filtre por linguagem (17 linguagens) ou por texto livre sobre nome, descrição e tópicos.
• A coluna de classificação sempre mostra a classificação por estrelas, então após ordenar por forks você ainda vê onde um repositório está.
• Os resultados são armazenados em cache no navegador por 60 minutos por aba e linguagem.
• Temas claro e escuro seguem a configuração do seu sistema.

Como os números são definidos

• Em alta aqui significa "criado no período, classificado por estrelas". Isso é o que a API de Busca do GitHub suporta. A própria página de tendências do GitHub classifica por estrelas ganhas no período, o que não tem API pública. Os snapshots noturnos neste repositório tornarão isso possível mais tarde.
• Downloads não existem para repositórios no GitHub, apenas para arquivos de release. Forks são mostrados como o sinal público mais próximo.
• Estrelas/dia é estrelas dividido pela idade do repositório, com mínimo de uma hora.

Pontuação

Cada repositório recebe uma pontuação de 0 a 100, um nível e um veredito de uma linha. A análise detalhada é sempre retornada para que uma pessoa ou agente possa ver o motivo. O mesmo arquivo, whichlib/lib/score.js, roda no painel e no Node, então os dois nunca podem discordar.

Parte	Peso	Sinal
Momentum	40%	Estrelas ganhas nos últimos 7 dias a partir de nossas contagens diárias de estrelas (top 1.000 repositórios por linguagem mais novos repositórios em alta). Sem histórico, estrelas por dia desde a criação vezes 7, com idade mínima de um dia, escalado pela tendência de downloads npm/PyPI quando conhecida (última semana contra as três semanas anteriores, limitado a 0,5–2x). Escala logarítmica: 50 por semana já é bom, 5.000 é o máximo.
Manutenção	25%	Dias desde o último push: pontuação total até 30 dias, zero em 365, linear entre eles. Menos 0,2 quando issues abertas excedem um décimo das estrelas. Proteção de estabilidade: um repositório com 10k+ estrelas ou 100k+ downloads semanais, com push no último ano e não arquivado, nunca cai abaixo de 0,5 aqui. Uso intenso mais silêncio é estabilidade, não decadência.
Adoção	25%	Com downloads semanais conhecidos: 50% estrelas (máx 100k), 20% forks (máx 20k), 30% downloads (máx 1M). Caso contrário, 70% estrelas, 30% forks. Tudo em escala logarítmica.
Licença	10%	Permissiva 1.0, copyleft fraco 0.75, copyleft forte 0.5, não reconhecida 0.5, nenhuma 0.

Níveis: Forte 75 e acima, Sólido 50, Observar 25, Evitar abaixo de 25. Os nomes são escolhidos para ler corretamente tanto para um projeto de seis semanas quanto para uma biblioteca de seis anos. Repositórios arquivados são limitados a 20 e recebem o veredito "Arquivado, evite." Uma licença ausente é sempre mencionada no veredito.

Vereditos parecem com "Crescendo rápido, 10,6k downloads/sem, push há 2 dias, MIT", "Ganhando de forma constante, 145M downloads/sem, quieto por 6 meses, amplamente usado, BSD-3-CLAUSE" ou "Crescimento lento, sem push em 60 dias, GPL-3.0".

Downloads

O GitHub não tem contagem de downloads para repositórios, mas os registros de pacotes têm. Após cada snapshot, a etapa de enriquecimento mapeia repositórios JavaScript e TypeScript para npm e repositórios Python para PyPI, então busca os downloads da última semana:

• Um pacote conta como do repositório apenas quando os metadados do próprio registro apontam de volta para github.com/<owner>/<repo>. Um nome correspondente sozinho nunca é suficiente, então um novo repositório chamado widget não é creditado com os downloads de um pacote widget não relacionado.
• Candidatos tentados: <repo> e @<owner>/<repo> no npm, <repo> no PyPI.
• Mapeamentos são armazenados em cache em registry-map.json no branch data. Negativos são re-verificados após 7 dias, positivos mantidos, downloads atualizados diariamente.
• Na primeira execução, 63 de 858 repositórios elegíveis mapearam para um pacote. A maioria dos repositórios com menos de um mês ainda não foi publicada, o que é esperado.

Outras linguagens (Rust, Go, Java...) são ignoradas por enquanto. Cargo, Go e Maven podem seguir o mesmo padrão.

Ressalva: aberto do disco, o painel não tem histórico de snapshots, então o momentum usa o fallback. Pontuações na aba Hoje são portanto provisórias; o relatório e o servidor MCP usam números reais de estrelas ganhas quando há dois ou mais dias de snapshots.

cd whichlib
npm run score      # top 25 repos from the latest snapshot with score and verdict

Servidor MCP

A mesma pontuação, servida a agentes de codificação. Três ferramentas via stdio:

Ferramenta	Entrada	O que retorna
recommend_repos	need em palavras simples, opcional language, limit (1–10, padrão 5)	Os melhores repositórios para a necessidade, classificados por adequação (pontuação × relevância), com downloads npm/PyPI e um veredito cada. Candidatos vêm da ordem de relevância do GitHub, sua ordem de estrelas e uma consulta de tópicos; veja "Como recommend encontra e classifica candidatos" abaixo.
compare_repos	repos: 2–10 nomes como owner/repo	Os repositórios lado a lado, melhores primeiro, mesma análise detalhada.
trending_repos	period dia/semana/mês, opcional language, limit (padrão 20), withDownloads	Repositórios mais estrelados criados no período, pontuados.

Cada resultado carrega texto legível e structuredContent (JSON) com a pontuação, nível, veredito, as quatro subpontuações, flags, pacotes e downloads.

Requer Node 22 ou mais novo. Instale no Claude Code (-s user o torna disponível em todos os projetos):

claude mcp add whichlib -s user -- npx -y whichlib

Ou como um plugin do Claude Code, que adiciona uma habilidade que faz o Claude verificar uma biblioteca com whichlib antes de adicioná-la:

/plugin marketplace add josifb/whichlib
/plugin install whichlib@whichlib

Cursor, Windsurf, Claude Desktop e outros aceitam o mesmo comando em sua configuração MCP:

{ "mcpServers": { "whichlib": { "command": "npx", "args": ["-y", "whichlib"] } } }

Para rodar a partir de um clone em vez disso: node whichlib/mcp/server.mjs.

Variáveis de ambiente, ambas opcionais:

• GITHUB_TOKEN aumenta os limites do GitHub (busca de 10 para 30 por minuto). Um token de granularidade fina sem permissões é suficiente. Recommend faz três buscas por chamada, então sem token ele permite cerca de três recomendações por minuto.
• Histórico de estrelas: momentum usa estrelas reais ganhas por semana para os top 1.000 repositórios por linguagem mais novos repositórios em alta, a partir de contagens diárias de estrelas no branch data. Instalado do npm, o servidor mantém os últimos 10 dias em ~/.whichlib/stars/ e os atualiza em segundo plano no máximo a cada 12 horas a partir de raw.githubusercontent.com (arquivos públicos, sem token, nada enviado). WHICHLIB_HISTORY=off desliga o download; repositórios sem histórico caem para estrelas por dia desde a criação. Em um clone, npm run pull-data preenche whichlib/data/stars em vez disso, e FRESH_REPOS_DATA_DIR aponta para qualquer pasta de arquivos diários.
• WHICHLIB_TELEMETRY=off ou DO_NOT_TRACK=1 desativa a contagem anônima de chamadas. O que é contado: nome da ferramenta, um ID de instalação aleatório, versão, plataforma e versão principal do Node. Nunca consultas, nomes de repositórios ou resultados. O coletor é um pequeno Cloudflare Worker em telemetry/, e seus números agregados são públicos em https://whichlib-telemetry.todorovskijosif.workers.dev/stats.

Experimente sem um cliente:

cd whichlib
npm run mcp:smoke   # starts the server over stdio, lists tools, calls each one

Viés conhecido, reduzido: manutenção costumava cair a zero em 90 dias sem push, o que colocava httpx (145M downloads semanais, seis meses quietos) em "Observar". A curva agora vai até um ano e a proteção de estabilidade mantém repositórios amplamente usados em 0,5 ou melhor; httpx cai em "Sólido". Cadência de releases da API de releases do GitHub é o sinal adequado de longo prazo e ainda está por vir.

Avaliação de recomendação

mcp/eval/needs.json contém 20 necessidades ("parser de pdf" em Python, "gerenciamento de estado" em TypeScript, ...) cada uma com um conjunto de respostas aceitas que um engenheiro sênior consideraria razoáveis. npm run eval as executa através de recommend_repos ao vivo e relata com que frequência um repositório aceito aparece na posição 1, 3 e 5, para nossa classificação e para linhas de base construídas a partir do mesmo pool de candidatos. Relatórios vão para mcp/eval/results/.

Resultado em 2026-09-27, após expansão de consulta (segundo relatório em results/):

Classificação	hit@1	hit@3	hit@5	MRR
nossa (adequação, veja abaixo)	75%	95%	100%	0.85
ordem de relevância do GitHub	65%	80%	95%	0.76
ordem de estrelas	45%	65%	75%	0.56
apenas pontuação, sem relevância	30%	65%	70%	0.46

O primeiro relatório, antes da expansão, tinha as mesmas taxas de hit para nossa classificação (75 / 95 / 100, MRR 0.86) em um pool menor. A expansão aumentou o recall de 53 para 74 repositórios aceitos nos 20 pools, nunca menos em nenhuma necessidade, e as linhas de base caíram nesse pool mais ruidoso enquanto a nossa se manteve. As regras de adequação são o que mantém o ruído fora.

Como recommend encontra e classifica candidatos

Recuperação, três buscas no GitHub por necessidade:

1. Busca de texto na ordem de relevância do GitHub, com sinônimos conhecidos combinados com OU (async OR asynchronous runtime), para que diferenças de vocabulário parem de esconder bibliotecas como tokio.
2. A mesma busca de texto em ordem de estrelas, para os grandes nomes cuja descrição só menciona o assunto.
3. Uma consulta de tópicos ordenada por estrelas (topic:cli, topic:image-processing), que traz o que mantenedores marcaram eles mesmos. A palavra principal é usada quando é específica (pdf, cli, orm) e a frase hifenizada quando é ampla (image-processing, state-management). O GitHub rejeita OR entre tópicos, então é um por requisição.

Filtros de linguagem usam famílias: JavaScript inclui TypeScript e Python inclui Jupyter, porque muitas bibliotecas migraram para TypeScript.

Chave de classificação é fit = score × relevance:

• relevância é 1.0 na posição 1 de relevância do GitHub caindo para 0.5 na posição 25, 0.75 quando encontrado apenas através da consulta de tópicos, 0.4 quando encontrado apenas na ordem de estrelas;
• ×0.75 quando o repositório nomeia o assunto apenas em suas tags de tópicos e ×0.5 quando em nenhum lugar de seu nome, descrição ou tópicos (correspondeu apenas ao texto do README);
• ×0.8 quando você pediu um framework, biblioteca, parser ou cliente e o repositório parece uma aplicação em vez de um bloco de construção.

Tanto score quanto fit são retornados, com a posição de relevância, as fontes de onde o repositório veio e os dois sinais, para que um agente possa ver o motivo.

node mcp/eval/inspect.mjs "<need>" [language] [wanted/repo ...] imprime todo o pool de candidatos para uma necessidade com esses valores.

Trabalho de snapshot noturno

whichlib/snapshot/ é um script Node 22 sem dependências que armazena os top 100 repositórios para 3 períodos vezes 9 linguagens em whichlib/data/snapshots/YYYY-MM-DD.json. Snapshots consecutivos são o que uma pontuação de momentum precisa.

cd whichlib
npm test          # 16 unit tests, no network
npm run snapshot  # about 3 minutes without a token, 1 minute with GITHUB_TOKEN

Um workflow do GitHub Actions (.github/workflows/snapshot.yml) executa o trabalho todos os dias às 06:17 UTC e faz commit do resultado no branch data, para que o histórico se acumule sem inchar main. Acione manualmente pela aba Actions ou com gh workflow run snapshot. Baixe os arquivos localmente com:

cd whichlib
npm run pull-data  # copies new snapshots from origin/data into data/snapshots/
npm run score      # now with real 7-day stars gained once there are 2+ days

Uma alternativa do Agendador de Tarefas do Windows está em whichlib/README.md.

Layout do repositório

whichlib/             the npm package: MCP server, score, dashboard, jobs, eval, tests
whichlib/dashboard/   Fresh Repos, one HTML file
whichlib/lib/         score.js, shared by browser and Node
whichlib/mcp/         MCP server: recommend_repos, compare_repos, trending_repos
whichlib/snapshot/    snapshot job, enrichment, history builder, score report
whichlib/server.json  MCP registry manifest
telemetry/            call counter: Cloudflare Worker + Analytics Engine
RELEASING.md          release steps

Roadmap

1. Concluído: painel, snapshots noturnos, pontuação transparente com níveis e veredictos, downloads npm e PyPI, servidor MCP com ferramentas de recomendação, comparação e tendências.
2. Nomeado whichlib. Formato do pacote, server.json para o registro MCP e o contador de chamadas estão prontos; restante: implantar o contador, tornar o repositório público, npm publish, mcp-publisher publish, listar no marketplace de plugins do Claude Code e nas listas awesome-mcp.
3. Depois, aguarde quatro semanas e leia instalações ativas semanais e chamadas por instalação. Isso decide se o nível de equipe com regras de política será construído.
4. Mais tarde: adoção em Cargo, Go e Maven; cadência de lançamentos na manutenção; downloads no painel; expandir a avaliação além de 20 necessidades do uso real.

Licença

MIT.