Um servidor MCP leve baseado em stdio para operações no sistema de arquivos local — leitura, escrita, edição, pesquisa, exec para assistentes de IA. Especialmente otimizado para o Chatbox: bat-bypass para exec (CVE-2026-6130), codificação b64 para eliminar problemas de escape e regex de múltiplos padrões para direcionamento preciso de blocos de código.
Servidor MCP sem dependências para operações de arquivos locais. 13 ferramentas de sistema de arquivos + 3 meta-ferramentas para descoberta progressiva — sem SDKs, sem frameworks, sem necessidade de npm install.
Protocolo MCP: 2024-11-05 · Transporte: stdio + HTTP Streamable · Runtime: Node.js ≥ 22.0.0
local-mcp.mjs — 595 linhas, 13 ferramentas, ponto de entrada
lib/mcp-core.mjs — 229 linhas, transporte stdio + HTTP, 9 métodos MCP
lib/config.mjs — 31 linhas, configuração de ambiente MCP_WORKSPACE/DATA com validação
Total: ~855 linhas, zero dependências em tempo de execução.
| Ferramenta | Descrição | Anotação |
|---|---|---|
read | Ler arquivo com números de linha, truncamento opcional head/tail | readOnlyHint |
search | Pesquisar arquivo por nome (glob) e depois por conteúdo (grep) | readOnlyHint |
ls | Listagem compacta de diretório com stat preguiçoso | readOnlyHint |
exec | Execução de comando em streaming com suporte a stdin e timeout | destructiveHint |
diff | Diff de dois arquivos ou strings de texto (Myers O(ND)) | readOnlyHint |
copy | Copiar arquivo ou diretório | destructiveHint |
move | Mover ou renomear arquivo/diretório | destructiveHint |
batch | Executar múltiplas operações sequencialmente; rollback atômico, referências $prev | destructiveHint |
file | Unificado: ler, escrever, editar, anexar, excluir, info, mkdir, mover | — |
block | Ler/substituir/inserir/excluir blocos de código por intervalo ou nome de função | — |
bookmark | Aliases de caminho persistentes (adicionar/obter/listar/excluir) | — |
grep | Formato compacto arquivo:linha:conteúdo com concorrência adaptativa | readOnlyHint |
watch | Observar arquivo/diretório para alterações; max 20 observadores simultâneos | — |
| Ferramenta | Descrição |
|---|---|
search_tools | Pesquisar ferramentas disponíveis por palavra-chave — economiza ~90% de tokens em comparação com listar todas |
describe_tool | Obter esquema de entrada completo para uma ferramenta específica (carregado sob demanda) |
call_tool | Executar qualquer ferramenta pelo nome com argumentos |
Em vez de enviar todos os 13 esquemas de ferramentas (~3.000 tokens) em cada requisição, a descoberta progressiva com estas 3 meta-ferramentas reduz para ~50 tokens — ~90% de economia de tokens.
| # | Otimização | Impacto |
|---|---|---|
| A | Leitura stream head/tail | streamHead() evita ler arquivos inteiros. Logs de 500MB: 3s → 5ms, memória: 500MB → poucos KB |
| B | Stat preguiçoso no ls | Chama statSync apenas quando sort=size. Diretório com 1000 arquivos: 50ms → 2ms |
| C | Concorrência adaptativa no grep | os.availableParallelism() (max 16, min 4) em vez de 16 workers fixos |
| D | Despejo de cache LRU | LRU por ordem de inserção do Map — arquivos pequenos quentes não são mais despejados por arquivos grandes frios |
| E | Proteção de bytes do grep | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 protegem contra OOM |
| F | Notificação de progresso | Passagem de _meta.progressToken para a especificação MCP 2025 (TODO: eventos para execuções longas) |
| Área | Detalhe |
|---|---|
| Cache de leitura | Despejo ciente de tamanho (max 50 itens, 10 MB) + TTL de 5s |
| Myers diff | Algoritmo O(ND), usado por edit, block e diff |
| Pontuação de busca | Correspondência de nome primeiro (sem I/O), depois stat apenas dos 50 principais candidatos |
| Formato de saída | grep: arquivo:linha:conteúdo, ls: colunas compactas, read: números de linha + dica de truncamento |
| Protocolo | Despacho O(1) do Map, curto-circuito de handler síncrono |
# Instalação zero — sem dependências
node local-mcp.mjs
# Com configuração
MCP_WORKSPACE=D:/projects node local-mcp.mjs
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
node local-mcp.mjs --http
node local-mcp.mjs --http --port 3456
Suporta JSON-RPC 2.0 POST, streaming SSE (Accept: text/event-stream), CORS e GET /tools.
node local-mcp.mjs --help # Mostrar uso + variáveis de ambiente
node local-mcp.mjs --list-tools # Exibir ferramentas disponíveis e sair
node local-mcp.mjs --http # Iniciar modo HTTP
node local-mcp.mjs --http --port 3456
| Variável | Padrão | Descrição |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Raiz do diretório de trabalho (limite de segurança) |
MCP_DATA | {WORKSPACE}/.mcp-data | Diretório de dados (marcadores, arquivos temporários) |
MCP_DIR | {WORKSPACE} | Diretório padrão para comandos tree/ls |
MCP_PORT | 3100 | Porta do servidor HTTP (ao usar --http) |
MCP_READONLY | false | Defina como true para bloquear todas as operações de escrita |
MCP_EXCLUDE | — | Diretórios extras separados por vírgula para excluir da pesquisa |
MCP_WORKSPACE e subdiretórios__proto__/constructor/prototype).gitignore e diretórios de exclusão comuns (node_modules, .git, etc.) respeitadosZero dependências em tempo de execução. Usa apenas módulos nativos do Node.js:
| Módulo | Finalidade |
|---|---|
fs | Sistema de arquivos + glob (Node 22) |
child_process | Execução de shell em streaming |
http | Transporte HTTP (sem necessidade de Express) |
path | Resolução de caminho |
os | availableParallelism() para concorrência adaptativa |
readline | Processamento streaming linha por linha |
availableParallelism()streamHead — done definido fora do callback Promise# Executar testes
node --test test/*.test.mjs
# Adicionando uma ferramenta
# 1. Defina esquema + handler em local-mcp.mjs
# 2. Registre com server.tool()
# 3. Adicione testes
MIT