NPMLens MCP

NPMLens MCP

npmlens-mcp permite que seu agente de codificação (como Claude, Cursor, Copilot, Gemini ou Codex) pesquise o registro npm e obtenha contexto do pacote (README, downloads, informações do GitHub, trechos de uso). Ele atua como um servidor Model‑Context‑Protocol (MCP), dando ao seu assistente de IA uma maneira estruturada de descobrir bibliotecas e integrá-las rapidamente.

Changelog | Contribuindo | Solução de problemas | Referência de ferramentas

Principais recursos

• Pesquisa estruturada no npm com pesos de classificação opcionais.
• Busca direta de README (opcionalmente truncado).
• Informações enriquecidas do pacote (downloads + detalhes do GitHub).
• Extração de trechos de uso do README.
• Transporte MCP Stdio, pronto para clientes compatíveis com MCP.

Avisos

npmlens-mcp realiza requisições de rede para npm e GitHub quando as ferramentas são usadas. Evite compartilhar segredos em prompts; defina GITHUB_TOKEN apenas se você quiser limites de taxa mais altos do GitHub.

Requisitos

• Node.js v18.17 ou mais recente
• npm (ou pnpm)

Começando

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "npmlens": {
      "command": "npx",
      "args": ["-y", "npmlens-mcp@latest"]
    }
  }
}

[!NOTE] Usar npmlens-mcp@latest garante que seu cliente MCP sempre execute a versão publicada mais recente.

Configuração do cliente MCP

amp mcp add npmlens -- npx npmlens-mcp@latest

claude mcp add npmlens npx npmlens-mcp@latest

codex mcp add npmlens -- npx npmlens-mcp@latest

copilot

/mcp add

code --add-mcp '{"name":"npmlens","command":"npx","args":["-y","npmlens-mcp@latest"]}'

gemini mcp add npmlens npx npmlens-mcp@latest

gemini mcp add -s user npmlens npx npmlens-mcp@latest

Seu primeiro prompt

Digite um dos seguintes prompts no seu cliente MCP para verificar se tudo funciona:

Pesquisa básica e informações:

Find 5 React debounce hook libraries, include weekly downloads, and
fetch the README for the top result.

Comparar pacotes:

Compare react-query, swr, and apollo-client. Show me their weekly
downloads, GitHub stars, and licenses.

Histórico de versões:

Show me all TypeScript versions released in the last 6 months with
their publish dates.

Dependências:

What are the dependencies of express? Include dev dependencies.

Uso Avançado e Local

Procurando exemplos JSON‑RPC, esquemas de ferramentas, a CLI de desenvolvimento local, solução de problemas ou configuração de contribuidor?

• Veja docs/advanced.md para todos os detalhes técnicos.
• Veja CONTRIBUTING.md para diretrizes de contribuição.

Ferramentas

Abaixo estão as ferramentas expostas pelo NPMLens MCP. Para esquemas JSON completos, veja a Referência de ferramentas.

Pesquisa e Informações Principais

• search_npm

  • Pesquise o registro npm com pesos de classificação opcionais.
  • Args: query (string, obrigatório), size (1..250), from (offset), weights (objeto com quality, popularity, maintenance).
  • Retorna: { total, results[] } onde cada resultado inclui name, version, description, links, score, etc.

• search_by_keywords

  • Pesquise pacotes npm por palavras-chave/tags específicas com operadores AND/OR.
  • Args: keywords (array de strings, obrigatório), operator (AND | OR, padrão AND), size (1..250).
  • Retorna: O mesmo que search_npm.
  • Exemplo: Encontre pacotes com "react" AND "hooks" AND "typescript".

• get_readme

  • Busque o markdown do README de um pacote (opcionalmente por versão).
  • Args: name (string, obrigatório), version (string), truncateAt (número).
  • Retorna: metadados JSON (name, version, repository, homepage) e o README como conteúdo de texto.

• get_package_info

  • Informações enriquecidas do pacote combinando metadados do registro, downloads do npm e detalhes do GitHub.
  • Args: name (string, obrigatório), version (string), includeReadme (booleano).
  • Retorna: name, version, repository, homepage, github{ fullName, url, stars, forks, license }, downloadsLastWeek, e opcional readme.

• get_usage_snippet

  • Extraia um trecho de uso provável do README de um pacote.
  • Args: name (string, obrigatório), version (string).
  • Retorna: { snippet: { language, code, heading } }.

Análise de Versão e Dependências

• get_package_versions

  • Liste todas as versões disponíveis de um pacote com datas de publicação e tags dist.
  • Args: name (string, obrigatório), limit (número), since (string - data ISO ou relativa como "6 meses").
  • Retorna: { name, versions[] } onde cada versão inclui version, date, tags[].
  • Exemplo: "Mostre-me todas as versões do React do último ano".

• get_package_dependencies

  • Obtenha a árvore de dependências de um pacote.
  • Args: name (string, obrigatório), version (string), depth (1-3, padrão 1), includeDevDependencies (booleano).
  • Retorna: { name, version, dependencies[], devDependencies[] } com nome e faixa de versão para cada dependência.
  • Exemplo: "Quais dependências o express tem?".

Métricas e Comparação

• get_downloads

  • Busque downloads do npm para os últimos day/week/month.
  • Args: name (string, obrigatório), period (day | week | month, padrão week).
  • Retorna: { downloads, start, end, package }.

• compare_packages

  • Compare vários pacotes npm lado a lado.
  • Args: packages (array de 1-10 nomes de pacotes, obrigatório).
  • Retorna: Array de dados de comparação com name, version, description, downloads, stars, forks, license, repository, homepage, e opcional error.
  • Busca todos os pacotes em paralelo para desempenho.
  • Exemplo: "Compare react-query, swr e apollo-client".

Exemplos de consultas de uso

Abaixo estão exemplos de consultas que você pode usar com seu assistente de IA para testar todas as 9 ferramentas do NPMLens:

search_npm

Search npm for react testing libraries

Find packages related to "typescript validation" and show me the top 5 results

get_readme

Show me the README for express

Get the README for react version 18.0.0

get_package_info

Get detailed information about the lodash package

Tell me about the vite package including GitHub stats and download numbers

get_downloads

How many downloads does react have in the last week?

Show me download statistics for next for the last month

get_usage_snippet

Show me a usage example for axios

How do I use the commander package? Give me a code snippet.

get_package_versions

List all versions of React from the last year

Show me the version history of TypeScript since 6 months ago

get_package_dependencies

What dependencies does express have?

Show me the dependency tree for next with depth 2

compare_packages

Compare react, vue, and angular

Compare the packages axios, fetch, and node-fetch and help me decide which to use

search_by_keywords

Find packages with keywords "react" AND "hooks" AND "typescript"

Search for packages with keywords "cli" OR "terminal"

Consultas combinadas

Você também pode pedir ao seu assistente de IA para usar várias ferramentas juntas:

Compare react-query, swr, and apollo-client, then show me usage examples for the most popular one

Search for typescript validation libraries, then show me the README and dependencies for the top result

Find the package "zod", show me its download stats, version history, and a usage example

Licença e Contribuição

NPMLens MCP é licenciado sob MIT. Contribuições são bem-vindas! Por favor, veja CONTRIBUTING.md para diretrizes.

Encontrou um bug ou tem uma solicitação de recurso? Abra uma issue no GitHub.

Feito com ❤️ para a comunidade de vibe coding. Boa codificação!