ollama-handoff

ollama-handoff

Un servidor MCP que descarga trabajo barato de tu agente LLM en la nube a un modelo local de Ollama.

Tu modelo de frontera (Claude, GPT, etc.) es brillante y medido. Gran parte del trabajo que recibe — resumir un registro, redactar un mensaje de commit, extraer todas las URLs de un archivo, una revisión rápida de código de primera pasada — no necesita razonamiento de frontera en absoluto. ollama-handoff expone tu instancia local de Ollama como un puñado de herramientas MCP diseñadas para un propósito, para que tu agente pueda enrutar ese trabajo a un modelo en tu propia GPU — a costo de nube cero — y gastar su presupuesto de razonamiento (pagado) en las cosas que realmente lo necesitan.

Este no es un servidor genérico de "envolver la API de Ollama". Cada herramienta incluye un prompt de sistema integrado y una descripción escrita para el agente que llama, para que el agente sepa cuándo delegar y obtenga un resultado ajustado sin tener que reafirmar instrucciones en cada llamada.

---

Por qué querrías esto

• 💸 Gasta menos. Las descargas rutinarias se ejecutan localmente y no facturan nada.
• ⚡ Mantén el modelo grande enfocado. Los resúmenes, extracciones y borradores no consumen su contexto ni tu presupuesto.
• 🧠 Ajustado, no crudo. summarize_local, code_review_local, draft_commit_message_local y extract_local vienen con prompts de sistema de revisor/resumidor/extractor ya calibrados.
• 🔌 Integración directa. Un registro MCP; funciona con Claude Code, Claude Desktop, Cursor y cualquier cliente MCP.
• 🪶 Pequeño y auditable. Dos dependencias (mcp, httpx), completamente tipado, probado con unit tests, sin telemetría.

Requisitos

• Ollama ejecutándose localmente (ollama serve) con al menos un modelo descargado, por ejemplo ollama pull qwen2.5-coder:14b.
• Python 3.11+ (o simplemente uvx, que lo gestiona por ti).

Instalación

El camino más rápido es uv — sin necesidad 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 (bloque de configuración mcp)

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

Ejecutar con Docker

Se incluye un Dockerfile. El servidor habla MCP sobre stdio, así que ejecútalo de forma interactiva (-i) y apúntalo a tu instancia de Ollama:

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

En Linux nativo (sin Docker Desktop), usa --network=host con OLLAMA_URL=http://localhost:11434.

Herramientas

Herramienta	Qué hace	Cuándo debería usarla el agente
ask_local	Prompt de una sola vez al modelo local	Cualquier delegación que no necesite razonamiento de frontera
chat_local	Chat local de múltiples turnos	Delegaciones que necesiten más de un turno de contexto
summarize_local	Resumen estructurado (titular + viñetas)	Archivos largos, registros, transcripciones, documentos
code_review_local	Revisión rápida de primera pasada de un diff/código	Prefiltro barato antes de una revisión profunda
draft_commit_message_local	Mensaje de commit convencional a partir de un diff	Commits rutinarios
extract_local	Extraer elementos estructurados de texto no estructurado	URLs, nombres de funciones, códigos de error, TODOs
list_models	Listar modelos de Ollama disponibles localmente	Descubrimiento / elección de modelo
server_info	Informar la configuración efectiva	Depuración de configuración

Configuración

Toda la configuración se realiza mediante variables de entorno establecidas en tu registro MCP:

Variable	Predeterminado	Descripción
OLLAMA_URL	http://localhost:11434	URL base del servidor Ollama
OLLAMA_DEFAULT_MODEL	qwen2.5-coder:14b	Modelo predeterminado para delegaciones
OLLAMA_NUM_CTX	32768	Ventana de contexto en tokens
OLLAMA_KEEP_ALIVE	30m	Cuánto tiempo mantener el modelo residente en VRAM
OLLAMA_TIMEOUT_S	600	Tiempo de espera por solicitud, en segundos

Ejemplo

Una vez registrado, no llamas a las herramientas tú mismo — lo hace tu agente. Un intercambio típico:

Tú: Resume los errores en build.log y redacta un commit para la corrección en stage.

Agente: (llama a summarize_local(build.log, focus="errors and stack traces") y draft_commit_message_local(git diff --staged) — ambos se ejecutan en tu GPU, sin facturar nada) → devuelve el resumen + el mensaje de commit.

Desarrollo

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

Consulta CONTRIBUTING.md. Las contribuciones son bienvenidas — especialmente nuevas herramientas de delegación especializadas.

Licencia

MIT © Michael Tierney