Depverse

Depverse

📖 Documentação completa → Guias de instalação, referência de ferramentas e configuração para Claude Code, Claude Desktop, Cursor, Cline, Windsurf e Copilot.

Depverse é um servidor MCP (Model Context Protocol) que expõe o npm Registry público como 39 ferramentas estruturadas que o Claude (ou qualquer cliente compatível com MCP) pode chamar — versões, dependências, changelogs, avisos de segurança, tendências de download e muito mais — sem nunca sair do editor.

O servidor fala o transporte stdio do MCP, então ele se conecta diretamente ao Claude Code, Claude Desktop, Cursor, Cline, Windsurf e Copilot Chat. Nenhuma chave de API necessária — o cliente traz sua própria autenticação.

---

Recursos

O Depverse expõe 58 ferramentas agrupadas em dez categorias.

Ferramentas de versão

Ferramenta	O que faz
get_latest_version	String da versão estável mais recente de um pacote.
get_all_versions	Todas as versões publicadas (mais uma contagem).
get_version_info	Manifesto para uma versão específica (deps, licença, engines, …).
get_dist_tags	Todas as dist-tags (latest, beta, next, …) e as versões para as quais apontam.
get_changelog	Notas de lançamento do GitHub Releases (se uma versão for fornecida) ou CHANGELOG.md do repositório vinculado.
check_version_exists	Verificação booleana: pkg@version está publicado?

Ferramentas de informações do pacote

Ferramenta	O que faz
get_package_info	Cartão de metadados de alto nível: nome, descrição, autor, licença, homepage, mantenedores, datas de criação/modificação.
get_package_readme	README em markdown para a versão mais recente (truncado em 20.000 caracteres).
get_package_keywords	Palavras-chave / tags declaradas em package.json.
get_package_repository	URL do repositório de origem, mais um slug owner/repo analisado quando o repositório está no GitHub.
get_package_homepage	URL da homepage + URL da página npm como fallback.
get_package_license	Licença declarada (string, SPDX ou formato legado de array).
get_package_size	Tamanho descompactado (bytes + legível) e contagem de arquivos para uma versão específica.

Ferramentas de dependências

Ferramenta	O que faz
get_dependencies	dependencies de tempo de execução para uma versão.
get_peer_dependencies	peerDependencies + peerDependenciesMeta (marca peers opcionais).
get_dev_dependencies	devDependencies (apenas tempo de build/teste).
get_dependency_tree	Percorre o grafo de dependências transitivas. Resolve nós em paralelo, remove duplicatas e limita em max_depth (padrão 2, limite rígido em 4).
check_peer_compatibility	Dado {peer_name: installed_version}, relata por-peer yes / no / unknown / missing / missing-optional. Inclui um pequeno matcher semver que lida com ^, ~, >=, <=, >, <, =, *, `

Ferramentas de segurança e saúde

Ferramenta	O que faz
check_vulnerabilities	Verifica um pacote + versão contra o banco de dados OSV.dev. Retorna todos os avisos correspondentes (GHSA, CVE) com gravidade e referências.
get_deprecation_status	Informa se um pacote ou versão específica está obsoleto, além da mensagem de deprecação. Verifica todas as versões quando nenhum version é fornecido.
check_maintainer_activity	Data da última publicação, contagem de publicações, cadência média e um rótulo de status (active / slowing / stale / abandoned).
get_download_stats	Contagens de download semanais / mensais da API pública de downloads do npm, além de um nível simples de popularidade.
check_typosquat_risk	Sinaliza nomes suspeitamente próximos de pacotes populares via distância de Levenshtein — detecta erros de digitação comuns em supply-chain.
get_download_trend	Contagens de download dia a dia em um intervalo (last-month, last-year ou datas personalizadas) com um rótulo de tendência growing / declining / flat.
compare_popularity	Contagens de download lado a lado para 2–10 pacotes. Retorna um ranking além da participação de cada pacote no total combinado.
get_download_by_version	Detalhamento de downloads por versão na última semana — mostra quais versões os usuários estão realmente instalando, além da linha principal mais popular.
get_vulnerability_details	Detalhes completos para um ID de aviso específico (GHSA, CVE, OSV) — resumo, gravidade, pacotes npm afetados, versões corrigidas.
audit_all_dependencies	Auditoria de vulnerabilidades em uma única chamada de um package.json inteiro via endpoint em lote do OSV. Relata contagens de vulnerabilidades por dependência.
check_supply_chain_risk	Resolve as dependências diretas de um pacote, audita todas e retorna um nível de risco clean / low / medium / high.
get_patched_version	Dado um ID CVE/GHSA/OSV, retorna a primeira versão corrigida por pacote npm afetado — para o que você precisa atualizar.

Ferramentas de compatibilidade e atualização

Ferramenta	O que faz
check_node_compatibility	Retorna o campo engines (restrições de node / npm / yarn) declarado por uma versão de pacote.
compare_versions	Compara dois dependencies, devDependencies, peerDependencies e engines de versões — relata adicionados / removidos / intervalo alterado.
get_breaking_changes	Verifica um diff de versão from → to para dependências diretas ou peers cujo intervalo declarado cruzou um limite de major version.
resolve_semver	Resolve um intervalo npm (^18.0.0, ~4.17.20, >=2 <3, 1.x, *) para a versão publicada mais alta que o satisfaz.
check_outdated	Dado {package_name: installed_version}, retorna o sinalizador outdated por pacote e o nível de lacuna (major / minor / patch). Fan-out paralelo.

Ferramentas de busca e descoberta

Ferramenta	O que faz
search_packages	Busca de texto livre no npm Registry com pontuações de relevância / qualidade / popularidade / manutenção.
get_similar_packages	Encontra alternativas para um pacote pesquisando em suas palavras-chave declaradas — filtra o próprio pacote de origem.
get_packages_by_author	Todos os pacotes publicados por um nome de usuário npm (via qualificador author:).
get_organization_packages	Todos os pacotes sob um escopo como @babel ou @vue. Over-fetch + filtro de prefixo estrito para confiabilidade.

Ferramentas utilitárias

Ferramenta	O que faz
batch_get_versions	Consulta /latest em paralelo para uma lista de pacotes — uma ida e volta por pacote em vez de sequencial.
validate_package_json	Verifica se os intervalos de dependência em um package.json resolvem para pelo menos uma versão publicada. Sinaliza erros de digitação como lodash@999.0.0.
generate_install_command	Constrói comandos de instalação para npm / pnpm / yarn / bun com dialetos de sinalização --dev e --exact tratados por gerenciador.
resolve_cdn_url	URLs fixadas jsDelivr, unpkg e esm.sh para um pacote + caminho de arquivo opcional. Resolve automaticamente "latest" quando nenhuma versão é fornecida.

Ferramentas de tamanho de bundle (via bundlephobia.com)

Ferramenta	O que faz
get_bundle_size	Tamanho minificado + gzip de um pacote (com uma versão específica ou a mais recente), além da contagem de dependências e disponibilidade ESM.
get_bundle_size_history	Histórico de tamanho entre versões recentes. Relata tendência growing / stable / shrinking e delta percentual.
check_treeshakeable	Retorna true quando o pacote entrega módulos ES E declara "sideEffects": false — as duas condições necessárias para tree-shaking do bundler.
compare_bundle_sizes	Consulta de tamanho em paralelo para 2–10 pacotes. Classifica por tamanho gzip (mais leve primeiro).
get_bundle_size_impact	Estruturado para revisão de PR: "adicionar X adicionará Y KB gzip com Z dependências transitivas" — além de um nível impact (minúsculo / pequeno / moderado / pesado).

Ferramentas de módulo e compatibilidade

Ferramenta	O que faz
check_esm_support	O pacote entrega módulos ES? Lê exports.import, campo module, type: "module".
check_cjs_support	Suporta CommonJS? Lê main, exports.require e as regras padrão quando não há marcadores ESM.
check_typescript_support	Tipos integrados (types/typings/exports .d.ts) ou um pacote @types/<name> DefinitelyTyped — informa qual, ou nenhum.
get_exports_map	Retorna o campo exports bruto além de uma lista plana de subcaminhos (ex.: ., ./router).
check_browser_compatible	yes / likely / unlikely / no com base no campo browser, exports.browser, arquivos .node nativos e bin de CLI.
check_deno_compatible	yes / likely / unknown / no — analisa ESM/CJS, módulos nativos e presença no JSR.
get_package_on_jsr	Verifica se um pacote com escopo também está no JSR (o registro moderno focado em TypeScript usado pelo Deno).

Ferramentas de migração e atualização

Ferramenta	O que faz
suggest_upgrade_path	Percorre da-versão → para-versão em saltos por-major, recomendando a versão estável mais alta em cada linha major e chamando get_breaking_changes para cada salto.
find_replacement_package	Detecta deprecação e extrai a substituição recomendada da mensagem de deprecação (padrões: "use X instead", "moved to X", "see X"…).
check_migration_guide	Busca MIGRATION.md / UPGRADING.md / UPGRADE.md do repositório GitHub do pacote. Recorre à verificação do conteúdo do repositório para nomes de arquivos relacionados à migração.

Todas as ferramentas retornam JSON. Erros se tornam ValueErrors com uma mensagem clara (ex.: "npm package 'foo' was not found."), que o MCP apresenta ao cliente como um erro de ferramenta.

---

Estrutura do projeto

Depverse/
├── mcp_server.py       # The MCP server — all 39 npm tools live here
├── mcp_client.py       # Thin MCP client wrapper (stdio transport)
├── test_npm_tool.py    # Manual end-to-end test for the server
├── pyproject.toml
├── uv.lock
├── .mcp.json           # Example MCP server config for external clients
├── docs/               # Documentation site (GitHub Pages)
│
│   # --- Optional: bundled CLI chat (main.py) ---
├── main.py             # Entrypoint for the optional CLI chat
└── core/
    ├── chat.py         # Tool-using chat loop
    ├── cli_chat.py     # CLI-flavoured chat (supports @docs and /commands)
    ├── cli.py          # prompt-toolkit UI (autocompletion, history, key bindings)
    ├── claude.py       # Anthropic API wrapper
    └── tools.py        # Bridges MCP tool calls into Anthropic tool_use blocks

---

Pré-requisitos

• Python 3.10+
• uv (recomendado) ou pip simples
• Acesso de rede a registry.npmjs.org, api.osv.dev, api.npmjs.org e (para changelogs) api.github.com / raw.githubusercontent.com

Nenhuma chave de API Anthropic necessária. O Claude Code (ou qualquer cliente MCP) traz sua própria autenticação. Uma chave só é necessária se você também quiser usar o chat CLI opcional incluído (main.py).

---

Instalação

git clone https://github.com/yash-neural/Depverse.git
cd Depverse
uv venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
uv pip install -e .

Ou sem uv:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Verifique se o servidor inicia corretamente:

uv run test_npm_tool.py   # spawns the server, lists tools, calls each once

---

Usando o Depverse de outros clientes MCP

O Depverse é um servidor MCP stdio padrão — você pode conectá-lo ao Claude Desktop, Claude Code ou qualquer outro cliente MCP apontando a configuração deles para mcp_server.py.

Exemplo (.mcp.json / Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "Depverse": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Depverse",
        "run",
        "mcp_server.py"
      ],
      "env": {}
    }
  }
}

Use "command": "python" e remova "run" de args se você não estiver usando uv.

---

Teste manual de ponta a ponta

test_npm_tool.py inicia o servidor, lista suas ferramentas e chama cada uma com uma entrada realista. Útil para verificar alterações sem o loop completo do Claude:

uv run test_npm_tool.py

Ele imprime cada chamada de ferramenta e a resposta JSON (truncada), para que você possa inspecionar a saída.

---

Como funciona

1. mcp_server.py registra cada ferramenta com FastMCP (do SDK Python do MCP). Cada ferramenta é uma função async que fala com o npm Registry, OSV.dev ou a API de downloads do npm via httpx, com um helper compartilhado _fetch_json que impõe um timeout de 10 s e mensagens consistentes de 404 / erro.
2. mcp_client.py envolve mcp.ClientSession com uma pequena classe gerenciada por contexto — usada apenas por test_npm_tool.py e pelo chat CLI opcional.
3. O cliente MCP (Claude Code, Claude Desktop, Cursor, etc.) inicia mcp_server.py como um subprocesso via stdio. Quadros JSON-RPC fluem em ambas as direções; chamadas de ferramenta retornam JSON estruturado sobre o qual o modelo pode raciocinar. O servidor MCP é o ponto central — tudo em core/ é apenas a estrutura para o chat CLI opcional incluído, que você pode ignorar se estiver apenas conectando o Depverse ao Claude Code.

---

Licença

Nenhum arquivo de licença foi commitado ainda — adicione um (MIT é um padrão sensato) antes de publicar ou aceitar contribuições externas.