ollama-handoff

Descarga trabajo barato de tu agente de IA a un modelo local de Ollama: resúmenes, borradores, extracciones, revisiones iniciales, sin costo en la nube.

GitHub

Prueba este MCPPatrocinado

Documentación

Ollama Handoff

Resúmenes locales, extracciones, revisiones de código y borradores de commits para tu cliente MCP.

Ollama Handoff permite que tu agente envíe tareas de texto rutinarias a un modelo que se ejecuta en tu máquina. Ocho herramientas MCP proporcionan indicaciones enfocadas, descubrimiento de modelos y comprobaciones de configuración.

La inferencia local no incurre en cargos de API de modelos en la nube. Tu agente llamador aún puede usar tokens pagados para planificar tareas y leer resultados. La velocidad, el uso de memoria y la calidad dependen de tu modelo y hardware.

Inicio rápido

1. Preparar Ollama

Instala Ollama y uv. Se requiere Python 3.11 o más reciente; uv puede gestionar Python por ti.

ollama pull llama3.1:8b
ollama list

Mantén Ollama en ejecución. Si la aplicación de escritorio o el servicio no está ya en ejecución, inicia ollama serve en otra terminal.

Estos ejemplos seleccionan llama3.1:8b. Puedes sustituir otro modelo instalado. Sin una anulación, el paquete usa por defecto qwen2.5-coder:14b, que debe descargarse por separado.

2. Registrar el 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 un cliente que acepte una configuración JSON de mcpServers:

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

Añade esta entrada usando la configuración MCP de tu cliente, luego reconéctate o reinícialo. Si el cliente no puede encontrar uvx, usa la ruta absoluta reportada por where.exe uvx en Windows o command -v uvx en macOS y Linux.

La versión 0.1.3 declara la restricción de compatibilidad MCP automáticamente. Este servidor usa la API de FastMCP de MCP 1, que MCP 2 eliminó. Si permaneces en la versión 0.1.2, añade --with "mcp<2" al comando uvx.

Para pip, instala en un entorno virtual y configura tu cliente para ejecutar el ejecutable ollama-handoff de ese entorno:

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

3. Verificar la conexión

Pregunta a tu agente:

Llama a server_info y list_models desde Ollama Handoff. Confirma que el modelo configurado está instalado. Luego llama a summarize_local con el siguiente texto, enfocándote en la prueba fallida:
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

Comprueba que el resumen identifica test_total, el total esperado de 42.00 y el total real de 40.00. La redacción varía según el modelo. Las herramientas aceptan texto, no rutas de archivos: tu agente debe proporcionar el contenido de los archivos cuando sea necesario.

Ejecutar la demo sin un agente

La demo lanza el servidor MCP real sobre stdio, descubre sus herramientas, comprueba la configuración, lista los modelos instalados y resume el registro sintético anterior. Requiere Ollama local pero no una clave de API en la nube.

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

Una ejecución exitosa descubre 8 herramientas, lista tu modelo y devuelve el resumen. Cada llamada imprime su tiempo transcurrido. Verificado en Windows con Python 3.14, MCP 1.30.0 y llama3.1:8b. El tiempo no es un punto de referencia; la primera carga del modelo puede tardar más.

Herramientas

Herramienta	Úsala para
`ask_local`	Una sola indicación con una instrucción de sistema opcional
`chat_local`	Una conversación con historial de mensajes explícito
`summarize_local`	Resúmenes del texto proporcionado, opcionalmente enfocados en un tema
`code_review_local`	Revisión inicial del código o diff proporcionado
`draft_commit_message_local`	Un mensaje de commit a partir de un diff proporcionado
`extract_local`	Extraer elementos como URLs, nombres o códigos de error
`list_models`	Descubrir modelos de Ollama instalados
`server_info`	Inspeccionar la configuración efectiva del servidor

Los resúmenes y revisiones generados necesitan verificación. El servidor no lee archivos, prepara cambios ni crea commits por ti.

Configuración

Establece estas variables en tu registro MCP:

Variable	Predeterminado	Descripción
`OLLAMA_URL`	`http://localhost:11434`	URL del servidor Ollama
`OLLAMA_DEFAULT_MODEL`	`qwen2.5-coder:14b`	Modelo usado cuando una llamada de herramienta omite un modelo
`OLLAMA_NUM_CTX`	`32768`	Ventana de contexto en tokens
`OLLAMA_KEEP_ALIVE`	`30m`	Tiempo para mantener el modelo cargado
`OLLAMA_TIMEOUT_S`	`600`	Tiempo de espera de generación y solicitud de chat en segundos

Para una tarea pequeña en una máquina con memoria limitada, prueba OLLAMA_NUM_CTX=4096 y un modelo más pequeño.

El endpoint de Ollama seleccionado recibe el texto enviado a estas herramientas. Un endpoint remoto envía ese texto a otra máquina. La ejecución local no impide que tu cliente llamador envíe indicaciones o resultados a su propio proveedor en la nube.

Solución de problemas

Síntoma	Qué comprobar
`No module named mcp.server.fastmcp`	Actualiza a la versión 0.1.3 y reinicia el cliente MCP
`uvx` no encontrado	Reinicia el cliente después de instalar uv, o configura la ruta absoluta del ejecutable
Conexión rechazada	Confirma que Ollama está en ejecución y que `OLLAMA_URL` apunta a él
Modelo no encontrado	Coincide con el nombre completo de `ollama list`, o descarga el modelo con `ollama pull`
Respuesta lenta o tiempo de espera	Permite la carga del modelo; prueba un modelo o contexto más pequeño
El servidor parece inactivo en una terminal	Este servidor stdio espera a un cliente MCP; no es un CLI de chat interactivo

server_info comprueba la configuración sin contactar a Ollama. list_models comprueba la conectividad. Una llamada exitosa a summarize_local también confirma la generación.

Docker

El Dockerfile incluido construye el paquete fuente. Mantén stdin abierto 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

En Linux sin Docker Desktop, usa --network=host con OLLAMA_URL=http://localhost:11434. No añadas -t cuando un cliente MCP lanza el contenedor.

Desarrollo

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

Las pruebas unitarias usan httpx.MockTransport y no necesitan Ollama. La demo usa inferencia real. Consulta CONTRIBUTING.md.