Local Worker MCP

MCP local, agnóstico de cliente. Frontier planeja, delega e revisa. Local executa o trabalho pesado, mecânico e verificável.

O objetivo é reduzir o consumo de tokens das IAs pagas sem jogar o conteúdo bruto no contexto delas.

Codex / Claude / Gemini / Grok
              │
              ▼
       Local Worker MCP
              │
       ┌──────┴───────────────┐
       ▼                      ▼
 Gemma 4 12B QAT          arquivos / PDF
 via Ollama               extração + evidências
       │
       ▼
 resultado compacto e verificável
       │
       ▼
 Frontier revisa

Isso não substitui a IA principal e não é um model router. É delegação real de trabalho.

LOCAL DISPONÍVEL?          NÃO
      │                     │
      ▼                     ▼
   DELEGA                NÃO INSISTE
      │                     │
      ▼                     ▼
   COMPRIME            FRONTIER ASSUME
      │
      ▼
 FRONTIER REVISA

A Gemma é uma otimização. Ela jamais pode virar ponto único de falha.

Princípio

Delegar quando a tarefa for mecânica, repetitiva, verificável ou intensiva em contexto: PDF, logs, CSV, código, extração, classificação, resumo.

Manter na frontier: decisões arquiteturais, segurança, mudanças críticas, julgamento subjetivo, requisitos ambíguos.

Se o worker local estiver offline, a frontier continua. O MCP devolve unavailable rápido e recomenda fallback. O cliente pode registrar:

Worker local indisponível; executei diretamente.

Não exige intervenção do usuário.

Requisitos

• Python 3.10+
• Ollama no mesmo PC ou em outro da LAN
• Um modelo local (recomendado: Gemma 4 12B QAT)

Instalação

git clone https://github.com/CaioAllgayer/Local-Worker-MCP.git
cd Local-Worker-MCP
python -m pip install -e ".[dev]"
copy .env.example .env

Ollama + Gemma

1. Instale e inicie o Ollama.
2. Baixe o modelo. O nome não é hardcoded — use o nome real no seu ollama list:

ollama list
ollama pull <nome-real-do-gemma>

3. Se LOCAL_LLM_MODEL ficar vazio, o worker tenta detectar um modelo cujo nome contém gemma. Senão, usa o primeiro modelo listado.

4. Teste o endpoint:

curl http://127.0.0.1:11434/api/tags
local-worker status

5. Suba o MCP:

local-worker-mcp

Mesmo PC

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://127.0.0.1:11434
LOCAL_LLM_MODEL=

local vs lan é detectado pelo hostname. 127.0.0.1, localhost e ::1 são locais.

Notebook usando o desktop

O worker não assume localhost. O backend pode estar em outro PC da LAN.

No notebook:

LOCAL_LLM_PROVIDER=ollama
LOCAL_LLM_BASE_URL=http://192.168.x.x:11434

Troque 192.168.x.x pelo IP atual do desktop (ipconfig no Windows, ip a no Linux). Não há IP fixo no projeto.

O comportamento é o mesmo: fail-fast, circuit breaker, cache, compressão.

No desktop, o Ollama precisa aceitar conexões da LAN (variável OLLAMA_HOST=0.0.0.0 e firewall liberando a porta 11434).

OpenAI-compatible

LM Studio, llama.cpp server, vLLM e similares:

LOCAL_LLM_PROVIDER=openai_compatible
LOCAL_LLM_BASE_URL=http://127.0.0.1:1234/v1
LOCAL_LLM_MODEL=...
LOCAL_LLM_API_KEY=

Fail-fast e circuit breaker

Defaults:

LOCAL_LLM_CONNECT_TIMEOUT_SECONDS=2
LOCAL_LLM_REQUEST_TIMEOUT_SECONDS=45
LOCAL_LLM_MAX_RETRIES=0
LOCAL_LLM_CIRCUIT_BREAKER_FAILURES=2
LOCAL_LLM_CIRCUIT_BREAKER_COOLDOWN_SECONDS=60

Conexão recusada não entra em retry. Depois de N falhas o circuito abre e as próximas chamadas devolvem unavailable imediatamente. Após o cooldown, uma tentativa é permitida.

{
  "status": "unavailable",
  "fallback_recommended": true,
  "reason": "Local LLM endpoint unreachable"
}

Ferramentas MCP

Ferramenta	Função
local_status	provider, endpoint, local/LAN, latência, modelo, circuit breaker, cache
delegate_task	tarefa genérica → JSON compacto
delegate_batch	tarefas independentes em paralelo (MAX_PARALLEL_WORKERS=4)
delegate_file	TXT, Markdown, CSV, JSON, código, logs
delegate_pdf	extração por página, chunking, síntese hierárquica, evidências
cache_stats	tamanho, entradas, hits, misses, hit rate, expirados
cache_cleanup	GC agora (TTL → não reutilizados → LRU)
cache_clear	apaga entradas descartáveis

O conteúdo bruto do arquivo não precisa entrar no contexto da IA paga. O worker lê, comprime e devolve evidências verificáveis (página, linha, trecho).

Segurança

Default: SECURITY_MODE=READ_ONLY, ENABLE_SHELL=false.

SECURITY_MODE=READ_ONLY
ALLOWED_PATHS=C:\Projects,D:\Research
ENABLE_SHELL=false

• READ_ONLY — só leitura nos paths autorizados; escrita e shell bloqueados
• WORKSPACE_WRITE — leitura/escrita nos paths autorizados; shell só se ENABLE_SHELL=true
• FULL_LOCAL — mais permissivo; ainda bloqueia comandos destrutivos

Path traversal é bloqueado. rm, del, format etc. são recusados.

Cache e logs

Cache persistente em ~/.local-worker-mcp/cache, autolimpante:

CACHE_TTL_DAYS=30
CACHE_MAX_SIZE_GB=10
CACHE_CLEANUP_THRESHOLD_PERCENT=90
CACHE_TARGET_USAGE_PERCENT=80
CACHE_CLEANUP_INTERVAL_HOURS=6

Entradas são descartáveis por padrão. persistent=true preserva artefatos importantes.

Logs rotacionam e expiram:

LOG_RETENTION_DAYS=14
LOG_MAX_SIZE_MB=250

O log não guarda o conteúdo completo dos arquivos.

Benchmark

local-worker benchmark arquivo.pdf

Saída:

Arquivo: arquivo.pdf
Worker: gemma4:12b-qat
Backend: ollama
Endpoint: LAN/local
Tamanho: ...
Tokens originais estimados: ...
Tokens processados localmente: ...
Resultado para frontier: ...
Compressão: ...
Tempo: ...
Cache: HIT/MISS

Codex

~/.codex/config.toml ou o JSON do cliente:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434",
        "ALLOWED_PATHS": "C:\\Projects"
      }
    }
  }
}

Ver examples/codex.json.

Claude Code

claude mcp add local-worker --scope user -- local-worker-mcp

Ou cole examples/claude_code.json em ~/.claude.json.

No CLAUDE.md / AGENTS.md do projeto, ensine a política:

Tarefas mecânicas e leitura de arquivos grandes vão para delegate_pdf / delegate_file / delegate_task. Se local_status ou a ferramenta devolver unavailable, execute diretamente e siga em frente.

Outros clientes MCP

Qualquer cliente stdio funciona. Exemplo genérico em examples/generic.json:

{
  "mcpServers": {
    "local-worker": {
      "command": "local-worker-mcp",
      "env": {
        "LOCAL_LLM_PROVIDER": "ollama",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434"
      }
    }
  }
}

Exemplos

• examples/pdf.md — paper / PDF longo
• examples/code.md — leitura inicial de repositório
• examples/logs.md — extração de erros

Testes

python -m pip install -e ".[dev]"
pytest
ruff check src tests

A suíte não depende de Ollama/Gemma reais. Tudo é mockado.

O que não entra neste MVP

Automação de GUI Windows, Playwright, multiagente complexo, RAG vetorial, dashboard, Kubernetes, roteador ML.

A arquitetura deixa espaço para delegate_repo, delegate_git, delegate_browser etc. na próxima fase.

Licença

MIT.