ollama-handoff

Descarregue trabalho barato do seu agente de IA para um modelo local Ollama — resumos, rascunhos, extrações, revisões iniciais — com custo zero de nuvem.

GitHub

Experimente este MCPPatrocinado

Documentação

Ollama Handoff

Resumos locais, extrações, revisões de código e rascunhos de commits para o seu cliente MCP.

O Ollama Handoff permite que seu agente envie tarefas rotineiras de texto para um modelo executado na sua máquina. Oito ferramentas MCP fornecem prompts focados, descoberta de modelos e verificações de configuração.

A inferência local não incorre em cobranças de API de modelos em nuvem. Seu agente chamador ainda pode usar tokens pagos para planejar tarefas e ler resultados. Velocidade, uso de memória e qualidade dependem do seu modelo e hardware.

Início rápido

1. Prepare o Ollama

Instale Ollama e uv. Python 3.11 ou mais recente é necessário; o uv pode gerenciar o Python para você.

ollama pull llama3.1:8b
ollama list

Mantenha o Ollama em execução. Se o aplicativo de desktop ou serviço não estiver em execução, inicie ollama serve em outro terminal.

Estes exemplos selecionam llama3.1:8b. Você pode substituir por outro modelo instalado. Sem uma substituição, o pacote usa por padrão qwen2.5-coder:14b, que deve ser baixado separadamente.

2. Registre o servidor

Para Claude Code:

claude mcp add --transport stdio --env OLLAMA_DEFAULT_MODEL=llama3.1:8b ollama-handoff -- uvx ollama-handoff@0.1.3

Para um cliente que aceita uma configuração JSON mcpServers:

{
  "mcpServers": {
    "ollama-handoff": {
      "command": "uvx",
      "args": ["ollama-handoff@0.1.3"],
      "env": {
        "OLLAMA_DEFAULT_MODEL": "llama3.1:8b"
      }
    }
  }
}

Adicione esta entrada usando as configurações de MCP do seu cliente e, em seguida, reconecte ou reinicie-o. Se o cliente não encontrar uvx, use o caminho absoluto relatado por where.exe uvx no Windows ou command -v uvx no macOS e Linux.

A versão 0.1.3 declara a restrição de compatibilidade MCP automaticamente. Este servidor usa a API MCP 1 FastMCP, que o MCP 2 removeu. Se você permanecer na versão 0.1.2, adicione --with "mcp<2" ao comando uvx.

Para pip, instale em um ambiente virtual e configure seu cliente para executar o executável ollama-handoff desse ambiente:

python -m pip install "ollama-handoff==0.1.3"

3. Verifique a conexão

Pergunte ao seu agente:

Chame server_info e list_models do Ollama Handoff. Confirme que o modelo configurado está instalado. Em seguida, chame summarize_local com o seguinte texto, focando no teste que falhou:
10:00:01 INFO Starting build
10:00:02 INFO Compiled 12 modules
10:00:03 ERROR tests/test_checkout.py::test_total expected 42.00, got 40.00
10:00:03 ERROR Build stopped because one test failed

Verifique se o resumo identifica test_total, o total esperado de 42.00 e o total real de 40.00. A redação varia conforme o modelo. As ferramentas aceitam texto, não caminhos de arquivo: seu agente deve fornecer o conteúdo dos arquivos quando necessário.

Execute a demonstração sem um agente

A demonstração inicia o servidor MCP real via stdio, descobre suas ferramentas, verifica a configuração, lista os modelos instalados e resume o log sintético acima. Ela requer Ollama local, mas nenhuma chave de API em nuvem.

git clone https://github.com/Michael-WhiteCapData/ollama-handoff.git
cd ollama-handoff
uv venv
uv pip install -e .
uv run --no-project python examples/demo.py --model llama3.1:8b

Uma execução bem-sucedida descobre 8 ferramentas, lista seu modelo e retorna o resumo. Cada chamada imprime seu tempo decorrido. Verificado no Windows com Python 3.14, MCP 1.30.0 e llama3.1:8b. O tempo não é um benchmark; o primeiro carregamento do modelo pode demorar mais.

Ferramentas

Ferramenta	Use para
`ask_local`	Um único prompt com uma instrução de sistema opcional
`chat_local`	Uma conversa com histórico explícito de mensagens
`summarize_local`	Resumos do texto fornecido, opcionalmente focados em um tópico
`code_review_local`	Revisão inicial do código fornecido ou de um diff
`draft_commit_message_local`	Uma mensagem de commit a partir de um diff fornecido
`extract_local`	Extração de itens como URLs, nomes ou códigos de erro
`list_models`	Descoberta de modelos Ollama instalados
`server_info`	Inspeção da configuração efetiva do servidor

Resumos e revisões gerados precisam de verificação. O servidor não lê arquivos, prepara alterações ou cria commits para você.

Configuração

Defina estas variáveis no seu registro MCP:

Variável	Padrão	Descrição
`OLLAMA_URL`	`http://localhost:11434`	URL do servidor Ollama
`OLLAMA_DEFAULT_MODEL`	`qwen2.5-coder:14b`	Modelo usado quando uma chamada de ferramenta omite um modelo
`OLLAMA_NUM_CTX`	`32768`	Janela de contexto em tokens
`OLLAMA_KEEP_ALIVE`	`30m`	Tempo para manter o modelo carregado
`OLLAMA_TIMEOUT_S`	`600`	Tempo limite de geração e solicitação de chat em segundos

Para uma tarefa pequena em uma máquina com memória limitada, tente OLLAMA_NUM_CTX=4096 e um modelo menor.

O endpoint Ollama selecionado recebe o texto enviado a essas ferramentas. Um endpoint remoto envia esse texto para outra máquina. A execução local não impede que seu cliente chamador envie prompts ou resultados ao seu próprio provedor de nuvem.

Solução de problemas

Sintoma	O que verificar
`No module named mcp.server.fastmcp`	Atualize para a versão 0.1.3 e reinicie o cliente MCP
`uvx` não encontrado	Reinicie o cliente após instalar o uv, ou configure o caminho absoluto do executável
Conexão recusada	Confirme que o Ollama está em execução e que `OLLAMA_URL` aponta para ele
Modelo não encontrado	Corresponda ao nome completo de `ollama list`, ou baixe o modelo com `ollama pull`
Resposta lenta ou tempo limite	Permita o carregamento do modelo; tente um modelo ou contexto menor
Servidor parece ocioso em um terminal	Este servidor stdio aguarda um cliente MCP; não é um CLI de chat interativo

server_info verifica a configuração sem contatar o Ollama. list_models verifica a conectividade. Uma chamada bem-sucedida de summarize_local também confirma a geração.

Docker

O Dockerfile incluído compila o pacote de origem. Mantenha o stdin aberto para MCP:

docker build -t ollama-handoff .
docker run --rm -i -e OLLAMA_URL=http://host.docker.internal:11434 -e OLLAMA_DEFAULT_MODEL=llama3.1:8b ollama-handoff

No Linux sem Docker Desktop, use --network=host com OLLAMA_URL=http://localhost:11434. Não adicione -t quando um cliente MCP iniciar o contêiner.

Desenvolvimento

uv venv
uv pip install -e ".[dev]"
uv run --no-project ruff check .
uv run --no-project pytest

Os testes de unidade usam httpx.MockTransport e não precisam do Ollama. A demonstração usa inferência real. Veja CONTRIBUTING.md.