@justmpm/deps-consult

MCP server que consulta pacotes npm instalados no node_modules diretamente. Extrai API surfaces, JSDoc, exemplos de uso e metadados -- zero config, offline, sem API keys.

Features

• API surface completa -- funcoes, classes, interfaces, tipos, enums e variaveis exportadas com assinaturas TypeScript
• JSDoc rico -- extrai @param, @returns, @example, @deprecated, @since, @see, @throws, @default
• Exemplos de codigo -- coleta de 4 fontes: JSDoc @example, diretorio /examples, blocos de codigo do README e /docs
• Busca inteligente -- match exato, prefixo (Button*), sufixo (*Button), contem (*Button*) e fuzzy matching com scoring
• Zero config -- funciona com qualquer pacote npm, sem internet, sem API keys, sem arquivos de configuracao
• Deduplicacao automatica -- pacotes com multiplos entry points (como es-toolkit) nao geram resultados duplicados
• Cache LRU -- 50 pacotes em cache com TTL de 30 minutos e invalidacao automatica por hash do package.json
• Suporte completo -- pacotes scoped, workspaces, symlinks, conditional exports e fallbacks legados

Instalacao

npx (sem instalar)

{
  "mcpServers": {
    "deps-consult": {
      "command": "npx",
      "args": ["-y", "@justmpm/deps-consult"]
    }
  }
}

Instalacao global

npm install -g @justmpm/deps-consult

{
  "mcpServers": {
    "deps-consult": {
      "command": "deps-consult"
    }
  }
}

Como projeto local

git clone https://github.com/Just-mpm/deps-consult.git
cd deps-consult
npm install && npm run build

{
  "mcpServers": {
    "deps-consult": {
      "command": "node",
      "args": ["D:/caminho/para/deps-consult/build/index.js"]
    }
  }
}

Configuracao MCP

O deps-consult usa transporte stdio (JSON-RPC). Adicione a configuracao acima no arquivo de configuracao do seu cliente:

| Cliente | Arquivo de configuracao | |---------|------------------------| | Claude Desktop | ~/.claude/claude_desktop_config.json | | OpenCode | .opencode/config.json | | Cursor | .cursor/mcp.json |

Referencia das Tools

| Tool | Descricao | Parametros | |------|-----------|------------| | deps_info | Visao geral do pacote: versao, descricao, entry points, dependencias, peer deps, tipos, tamanho | package, projectDir? | | deps_api | API surface completa: todas as funcoes, classes, interfaces, tipos, enums e variaveis com assinaturas | package, entrypoint?, kind?, limit? | | deps_search | Busca simbolos por nome com wildcards e fuzzy matching | package, query, entrypoint?, kind? | | deps_usage | Detalhes de uso de um simbolo: assinatura, JSDoc, parametros, return type, exemplos, imports | package, symbol, entrypoint? | | deps_examples | Exemplos de codigo extraidos de JSDoc, /examples, README e /docs | package, symbol?, entrypoint? |

Parametros em detalhe

deps_info

• package (string, obrigatorio) -- Nome do pacote (ex: zod, @mui/material)
• projectDir (string, opcional) -- Diretorio do projeto. Default: process.cwd()

deps_api

• package (string, obrigatorio)
• entrypoint (string, opcional) -- Subpath do entry point (ex: "hooks", "utils")
• kind (enum, opcional) -- all | functions | classes | interfaces | types | enums | variables. Default: all
• limit (number, opcional) -- Maximo de simbolos por categoria. Range: 1-200. Default: 50

deps_search

• package (string, obrigatorio)
• query (string, obrigatorio) -- Suporta wildcards: Button (exato), Button* (prefixo), *Button (sufixo), *Button* (contem)
• entrypoint (string, opcional)
• kind (enum, opcional) -- Mesmas opcoes do deps_api

deps_usage

• package (string, obrigatorio)
• symbol (string, obrigatorio) -- Nome exato do simbolo. Se nao encontrar, faz busca fuzzy com score > 0.5
• entrypoint (string, opcional)

deps_examples

• package (string, obrigatorio)
• symbol (string, opcional) -- Filtra exemplos por simbolo
• entrypoint (string, opcional)

Exemplos de Uso

Conhecer um pacote novo

deps_info zod

Retorna versao, descricao, entry points, dependencias, se tem tipos e tamanho no disco.

Ver a API completa

deps_api es-toolkit kind=functions limit=30

Lista as primeiras 30 funcoes exportadas com assinaturas TypeScript.

Buscar um simbolo

deps_search @mui/material query="Button*"

Encontra todos os simbolos com prefixo "Button" no MUI.

Entender como usar um simbolo

deps_usage zod symbol="object"

Retorna a assinatura completa, JSDoc (params, returns), exemplos e todos os caminhos de import possiveis.

Ver exemplos de codigo

deps_examples react-hook-form

Coleta exemplos de todas as fontes: JSDoc, diretorio de exemplos, README e docs.

Arquitetura

src/
  index.ts                          MCP server (5 tools registradas)
  pipeline.ts                       Orquestracao: resolvers -> extractors -> cache
  types/index.ts                    Tipos compartilhados
  schemas/package-json.schema.ts    Zod v4 schemas (package.json + inputs)
  cache/package-cache.ts            LRU cache (50 pacotes, 30min TTL)
  resolvers/
    package-resolver.ts             Encontra pacote no node_modules
    exports-resolver.ts             Resolve conditional exports
    types-resolver.ts               5 estrategias para achar .d.ts
  extractors/
    api-extractor.ts                ts-morph: extrai API surface
    jsdoc-extractor.ts              Extrai @param, @returns, @example, etc.
    readme-extractor.ts             Parser manual de markdown
    examples-extractor.ts           4 fontes de exemplos
  formatters/
    markdown-formatter.ts           Output otimizado para contexto de LLM

Fluxo de dados:

Tool call
  -> Cache (hit? retorna)
  -> PackageResolver (acha no node_modules)
  -> ExportsResolver (resolve entry points)
  -> TypesResolver (acha .d.ts com 5 estrategias)
  -> ApiExtractor (ts-morph: funcoes, classes, tipos...)
  -> ReadmeExtractor (parser manual)
  -> Deduplicacao por nome (Set)
  -> Salva no cache
  -> Formatter (markdown para LLM)
  -> Response

Desenvolvimento

# Instalar dependencias
npm install

# Build
npm run build

# Desenvolvimento (watch)
npm run dev

# Lint
npm run lint

# Type check
npm run type-check

# Testes (JSON-RPC real via stdin/stdout)
node test-mcp.ts

Requisitos

• Node.js >= 22.0.0
• npm (ou bun)

Licenca

MIT -- Koda AI Studio