@justmpm/token-counter

MCP Server para estimativa de tokens de arquivos e diretorios.

Descricao

Este servidor MCP (Model Context Protocol) estima a quantidade de tokens que arquivos e diretorios consomem. Util para:

• Avaliar se um projeto cabe no context window de um modelo
• Estimar custos de uso de LLMs por projeto
• Identificar quais arquivos sao os maiores consumidores de tokens
• Planejar estrategias de RAG (qual parte do projeto enviar)

Como funciona: Le arquivos recursivamente, ignora binarios automaticamente e estima tokens usando ~4 caracteres por token.

Por que usar?

• Sem dependencias externas: Usa apenas APIs nativas do Node.js (fs, path)
• Sem API key: Nao precisa de nenhuma chave ou configuracao
• Inteligente: Ignora automaticamente node_modules, .git, lock files e outros arquivos irrelevantes
• Rapido: Leitura em chunks para arquivos grandes (>1MB)
• Integracao MCP: Funciona com Claude Desktop, OpenCode e outros clientes MCP

Instalacao

Opcao 1 - Via npx (sem instalar)

Basta configurar no seu cliente MCP -- ele baixa automaticamente:

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

Opcao 2 - Instalacao global

npm install -g @justmpm/token-counter

Depois configure no cliente MCP:

{
  "mcpServers": {
    "token-counter": {
      "command": "token-counter"
    }
  }
}

Opcao 3 - Desenvolvimento local

git clone https://github.com/justmpm/token-counter-mcp
cd token-counter-mcp
npm install
npm run build

Configure apontando para o build:

{
  "mcpServers": {
    "token-counter": {
      "command": "node",
      "args": ["D:\\caminho\\para\\token-counter\\dist\\index.js"]
    }
  }
}

Configuracao

Claude Desktop

Edite o arquivo claude_desktop_config.json:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Reinicie o Claude Desktop apos salvar.

OpenCode

Adicione ao arquivo de configuracao do OpenCode:

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

Cursor / Windsurf / outros clientes MCP

Siga o padrao de configuracao do seu cliente usando npx -y @justmpm/token-counter como comando.

Tools Disponiveis

token_count - Conta tokens de arquivos e diretorios

Estima a quantidade de tokens de arquivos e diretorios, retornando uma tabela ordenada por maior consumo.

Parametros:

| Parametro | Tipo | Obrigatorio | Descricao | |-----------|------|-------------|-----------| | paths | string[] | Sim | Caminhos dos arquivos ou diretorios (relativos ao cwd) | | ext | string | Nao | Filtrar por extensoes separadas por virgula (ex: .ts,.tsx) | | cwd | string | Sim | Diretorio de trabalho para resolver caminhos relativos |

Exemplo -- Contar diretorio inteiro:

{
  "paths": ["src/"],
  "cwd": "D:\\Pictures\\MeuProjeto"
}

Exemplo -- Filtrar por extensao:

{
  "paths": ["src/", "lib/"],
  "ext": ".ts,.tsx",
  "cwd": "D:\\Pictures\\MeuProjeto"
}

Exemplo -- Arquivo especifico:

{
  "paths": ["package.json", "tsconfig.json"],
  "cwd": "D:\\Pictures\\MeuProjeto"
}

Retorno:

--------------------------------------------------------------------
Arquivo                          Bytes       Tokens
--------------------------------------------------------------------
src/components/Dashboard.tsx    12.450      3.113
src/hooks/useAuth.ts             8.200      2.050
src/utils/format.ts              3.100        775
--------------------------------------------------------------------
TOTAL (3 arquivos)              23.750      5.938
--------------------------------------------------------------------

  Pulados: 15 arquivo(s) (12 binarios, 3 filtrados)

Metodo de Contagem

| Aspecto | Detalhe | |---------|---------| | Formula | tokens = Math.ceil(caracteres / 4) | | Ratio | ~4 caracteres por token | | Precisao | Estimativa (nao e contagem exata via tokenizer) | | Arquivos grandes | Leitura em chunks de 64KB (>1MB) | | Binarios | Ignorados automaticamente |

Nota: Esta e uma estimativa generica. Tokenizers reais (como o do Claude ou GPT) podem variar. Para decisoes criticas de custo, use o tokenizer oficial do modelo.

Arquivos Ignorados Automaticamente

Diretorios

node_modules, .git, .next, .turbo, .nuxt, .output, dist, build, out, coverage, target, .cache, .tmp, .vercel, .netlify, .firebase, .analyze, .claude, .github, .vscode, .idea, .cursor

Arquivos

package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, bun.lock, composer.lock, Gemfile.lock, cargo.lock, .DS_Store, Thumbs.db

Extensoes reconhecidas como texto

.ts, .tsx, .js, .jsx, .mjs, .cjs, .json, .md, .mdx, .txt, .yaml, .yml, .toml, .xml, .html, .css, .scss, .less, .py, .rb, .go, .rs, .java, .kt, .swift, .sh, .bash, .zsh, .ps1, .sql, .graphql, .gql, .vue, .svelte, .astro

Arquivos sem extensao reconhecidos

Makefile, Dockerfile, Jenkinsfile, Vagrantfile, LICENSE, README, CHANGELOG, CONTRIBUTING, CNAME, .gitignore, .dockerignore, .editorconfig, .env, .npmrc, .nvmrc, .gitattributes

Casos de Uso

Verificar se o projeto cabe no context window

Projeto: 45.000 tokens
Claude 3.5 Sonnet: ~200k tokens -> Cabe tranquilamente
GPT-4o: ~128k tokens -> Cabe
Gemini 1.5 Pro: ~1M tokens -> Cabe com folga

Estimar custo por chamada

Projeto: 50.000 tokens
Modelo: Claude 3.5 Sonnet ($3/MTok input)
Custo: 50.000 / 1.000.000 * $3 = $0.15 por chamada

Identificar arquivos pesados

A tabela ja vem ordenada por maior consumo, facilitando identificar quais arquivos merecem atencao (refatoracao, split, etc).

Estrutura do Projeto

token-counter/
├── src/
│   ├── index.ts           # Servidor MCP principal
│   ├── types.ts           # Tipos TypeScript (FileResult, CountOptions)
│   ├── constants.ts       # Constantes (ratios, extensoes, filtros)
│   ├── utils/
│   │   ├── fs.ts          # Resolucao recursiva de caminhos
│   │   ├── estimate.ts    # Contagem de chars e estimativa de tokens
│   │   └── format.ts      # Formatacao da tabela ASCII
│   └── tools/
│       └── count.ts       # Tool token_count
├── dist/                  # Build compilado
├── package.json
├── tsconfig.json
├── README.md              # Este arquivo
└── AGENTS.md              # Guia para subagents

Desenvolvimento

# Clonar repositorio
git clone https://github.com/justmpm/token-counter-mcp
cd token-counter-mcp

# Instalar dependencias
npm install

# Build
npm run build

# Desenvolvimento com watch
npm run dev

# Testes
npm test

# Executar localmente
npm start

Testar com MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Abre uma interface visual no navegador para testar as tools.

Documentacao Adicional

AGENTS.md

Guia simplificado para subagents sobre como usar as tools. Inclui referencia rapida, exemplos de uso e dicas.

Para Subagents: Consulte AGENTS.md para orientacoes rapidas.

Troubleshooting

"Nenhum arquivo encontrado"

Verifique se cwd esta correto e se os caminhos em paths existem dentro desse diretorio.

"Caminho nao encontrado"

O path informado em paths nao existe no diretorio de trabalho (cwd). Verifique a ortografia.

"Erro de validacao"

Falta algum parametro obrigatorio. paths (array) e cwd (string) sao obrigatorios.

Tokens menores que o esperado

Arquivos binarios (imagens, fontes, etc) e lock files sao ignorados automaticamente. Arquivos dentro de node_modules, .git, dist e outras pastas tambem sao ignorados.

O MCP nao inicia no Claude Desktop

1. Verifique se o Claude Desktop foi reiniciado apos a configuracao
2. Confirme se o Node.js esta instalado (node --version)
3. Teste manualmente: npx -y @justmpm/token-counter --version

Licenca

MIT - Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• Model Context Protocol: https://modelcontextprotocol.io/
• Repositorio: https://github.com/justmpm/token-counter-mcp