Локальный Worker MCP

MCP локальный, агностический к клиенту. Frontier планирует, делегирует и проверяет. Локальный выполняет тяжелую, механическую и проверяемую работу.

Цель — снизить потребление токенов платных ИИ без отправки сырого содержимого в их контекст.

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

Это не заменяет основную ИИ и не является маршрутизатором моделей. Это реальное делегирование работы.

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

Gemma — это оптимизация. Она никогда не должна стать единой точкой отказа.

Принцип

Делегировать, когда задача механическая, повторяющаяся, проверяемая или интенсивная по контексту: PDF, логи, CSV, код, извлечение, классификация, резюмирование.

Оставлять на frontier: архитектурные решения, безопасность, критические изменения, субъективные суждения, неоднозначные требования.

Если локальный worker офлайн, frontier продолжает работу. MCP быстро возвращает unavailable и рекомендует fallback. Клиент может зарегистрировать:

Worker local indisponível; executei diretamente.

Не требует вмешательства пользователя.

Related MCP server: ollama-handoff

Требования

• Python 3.10+

• Ollama на том же ПК или другом в локальной сети

• Локальная модель (рекомендуется: Gemma 4 12B QAT)

Установка

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. Установите и запустите Ollama.

2. Загрузите модель. Имя не жестко закодировано — используйте реальное имя из вашего ollama list:

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

3. Если LOCAL_LLM_MODEL останется пустым, worker попытается обнаружить модель, имя которой содержит gemma. В противном случае используется первая модель из списка.

4. Проверьте endpoint:

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

5. Запустите MCP:

local-worker-mcp

Тот же ПК

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

local vs lan определяется по hostname. 127.0.0.1, localhost и ::1 считаются локальными.

Ноутбук, использующий настольный ПК

Worker не предполагает localhost. Бэкенд может находиться на другом ПК в локальной сети.

На ноутбуке:

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

Замените 192.168.x.x на актуальный IP настольного ПК (ipconfig в Windows, ip a в Linux). В проекте нет фиксированного IP.

Поведение то же самое: fail-fast, circuit breaker, кэш, сжатие.

На настольном ПК Ollama должен принимать соединения из локальной сети (переменная OLLAMA_HOST=0.0.0.0 и брандмауэр, разрешающий порт 11434).

Совместимость с OpenAI

LM Studio, llama.cpp server, vLLM и аналоги:

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 и circuit breaker

Значения по умолчанию:

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

Отказ в соединении не приводит к повторным попыткам. После N сбоев цепь размыкается, и следующие вызовы немедленно возвращают unavailable. После периода охлаждения разрешается одна попытка.

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

Инструменты MCP

Сырое содержимое файла не должно попадать в контекст платной ИИ. Worker читает, сжимает и возвращает проверяемые доказательства (страница, строка, фрагмент).

Безопасность

По умолчанию: SECURITY_MODE=READ_ONLY, ENABLE_SHELL=false.

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

• READ_ONLY — только чтение в разрешенных путях; запись и shell заблокированы

• WORKSPACE_WRITE — чтение/запись в разрешенных путях; shell только если ENABLE_SHELL=true

• FULL_LOCAL — более разрешительный; все еще блокирует разрушительные команды

Path traversal блокируется. rm, del, format и т.д. отклоняются.

Кэш и логи

Постоянный кэш в ~/.local-worker-mcp/cache, самоочищающийся:

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

Записи по умолчанию одноразовые. persistent=true сохраняет важные артефакты.

Логи ротируются и истекают:

LOG_RETENTION_DAYS=14
LOG_MAX_SIZE_MB=250

Лог не хранит полное содержимое файлов.

Бенчмарк

local-worker benchmark arquivo.pdf

Вывод:

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 или JSON клиента:

{
  "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"
      }
    }
  }
}

См. examples/codex.json.

Claude Code

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

Или вставьте examples/claude_code.json в ~/.claude.json.

В CLAUDE.md / AGENTS.md проекта укажите политику:

Механические задачи и чтение больших файлов отправляются в delegate_pdf / delegate_file / delegate_task. Если local_status или инструмент возвращает unavailable, выполняйте напрямую и продолжайте.

Другие клиенты MCP

Любой клиент stdio работает. Общий пример в 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"
      }
    }
  }
}

Примеры

• examples/pdf.md — статья / длинный PDF

• examples/code.md — начальное чтение репозитория

• examples/logs.md — извлечение ошибок

Тесты

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

Набор не зависит от реальных Ollama/Gemma. Всё замокано.

Что не входит в этот MVP

Автоматизация GUI Windows, Playwright, сложный мультиагент, векторный RAG, дашборд, Kubernetes, ML-маршрутизатор.

Архитектура оставляет место для delegate_repo, delegate_git, delegate_browser и т.д. на следующем этапе.

Лицензия

MIT.