ollama-handoff

ollama-handoff

Um servidor MCP que transfere trabalho barato do seu agente LLM na nuvem para um modelo Ollama local.

Seu modelo de fronteira (Claude, GPT, etc.) é brilhante e medido. Muito do trabalho que ele recebe — resumir um log, redigir uma mensagem de commit, extrair todas as URLs de um arquivo, uma revisão rápida de código em primeira passada — não precisa de raciocínio de fronteira. ollama-handoff expõe sua instância local de Ollama como um conjunto de ferramentas MCP criadas para propósitos específicos, para que seu agente possa direcionar esse trabalho para um modelo na sua própria GPU — a custo zero na nuvem — e gastar seu orçamento de raciocínio (pago) nas coisas que realmente precisam dele.

Isto não é um servidor genérico de "envolver a API do Ollama". Cada ferramenta vem com um prompt de sistema embutido e uma descrição escrita para o agente chamador, para que o agente saiba quando fazer a transferência e receba um resultado ajustado sem precisar repetir instruções a cada chamada.

---

Por que você vai querer isso

• 💸 Gaste menos. Transferências rotineiras rodam localmente e não geram cobrança.
• ⚡ Mantenha o modelo grande focado. Resumos, extrações e rascunhos não consomem o contexto dele nem o seu orçamento.
• 🧠 Ajustado, não cru. summarize_local, code_review_local, draft_commit_message_local e extract_local vêm com prompts de sistema de revisor/resumidor/extrator já calibrados.
• 🔌 Plug-and-play. Um único registro MCP; funciona com Claude Code, Claude Desktop, Cursor e qualquer cliente MCP.
• 🪶 Pequeno e auditável. Duas dependências (mcp, httpx), totalmente tipado, com testes unitários, sem telemetria.

Requisitos

• Ollama rodando localmente (ollama serve) com pelo menos um modelo baixado, ex.: ollama pull qwen2.5-coder:14b.
• Python 3.11+ (ou apenas uvx, que gerencia isso para você).

Instalação

O caminho mais rápido é uv — sem necessidade de venv manual:

uvx ollama-handoff          # run directly
# or
pip install ollama-handoff  # then run: ollama-handoff

Claude Code

claude mcp add ollama-handoff -- uvx ollama-handoff

Claude Desktop / Cursor (bloco de configuração mcp)

{
  "mcpServers": {
    "ollama-handoff": {
      "command": "uvx",
      "args": ["ollama-handoff"],
      "env": {
        "OLLAMA_DEFAULT_MODEL": "qwen2.5-coder:14b"
      }
    }
  }
}

Executar com Docker

Um Dockerfile está incluído. O servidor fala MCP via stdio, então execute-o interativamente (-i) e aponte para sua instância do Ollama:

docker build -t ollama-handoff .
docker run --rm -i -e OLLAMA_URL=http://host.docker.internal:11434 ollama-handoff

No Linux nativo (sem Docker Desktop), use --network=host com OLLAMA_URL=http://localhost:11434.

Ferramentas

Ferramenta	O que faz	Quando o agente deve usar
ask_local	Prompt único para o modelo local	Qualquer transferência que não precise de raciocínio de fronteira
chat_local	Chat local de múltiplas turnas	Transferências que precisam de mais de uma turna de contexto
summarize_local	Resumo estruturado (título + tópicos)	Arquivos longos, logs, transcrições, documentos
code_review_local	Revisão rápida de primeira passada de um diff/código	Pré-filtro barato antes de uma revisão profunda
draft_commit_message_local	Mensagem de commit convencional a partir de um diff	Commits rotineiros
extract_local	Extrair itens estruturados de texto não estruturado	URLs, nomes de funções, códigos de erro, TODOs
list_models	Listar modelos Ollama disponíveis localmente	Descoberta / escolha de modelo
server_info	Reportar a configuração efetiva	Depuração da configuração

Configuração

Toda a configuração é feita por variáveis de ambiente definidas no seu registro MCP:

Variável	Padrão	Descrição
OLLAMA_URL	http://localhost:11434	URL base do servidor Ollama
OLLAMA_DEFAULT_MODEL	qwen2.5-coder:14b	Modelo padrão para transferências
OLLAMA_NUM_CTX	32768	Janela de contexto em tokens
OLLAMA_KEEP_ALIVE	30m	Quanto tempo manter o modelo residente na VRAM
OLLAMA_TIMEOUT_S	600	Timeout por requisição, em segundos

Exemplo

Depois de registrado, você não chama as ferramentas diretamente — seu agente faz isso. Um exemplo típico:

Você: Resuma os erros em build.log e redija um commit para a correção em stage.

Agente: (chama summarize_local(build.log, focus="errors and stack traces") e draft_commit_message_local(git diff --staged) — ambos rodam na sua GPU, sem cobrança) → retorna o resumo + mensagem de commit.

Desenvolvimento

git clone https://github.com/Michael-WhiteCapData/ollama-handoff
cd ollama-handoff
uv pip install -e ".[dev]"
ruff check .
pytest          # tests use httpx.MockTransport — no running Ollama required

Veja CONTRIBUTING.md. Contribuições são bem-vindas — especialmente novas ferramentas especializadas de transferência.

Licença

MIT © Michael Tierney