npm package: @justmpm/deps-consult
Description: MCP server for querying installed npm packages in node_modules - extract API surfaces, types, documentation and usage examples
Author: Koda AI Studio
Latest version: 1.5.0

# @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.

[![npm version](https://img.shields.io/npm/v/@justmpm/deps-consult.svg)](https://www.npmjs.com/package/@justmpm/deps-consult)
[![license](https://img.shields.io/npm/l/@justmpm/deps-consult.svg)](https://github.com/Just-mpm/deps-consult/blob/main/LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)

## 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)

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

### Instalacao global

```bash
npm install -g @justmpm/deps-consult
```

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

### Como projeto local

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

```json
{
  "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

```bash
# 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](https://github.com/Just-mpm/deps-consult/blob/main/LICENSE) -- Koda AI Studio