MCP y herramientas

zqagent puede inyectar herramientas externas mediante MCP (Model Context Protocol); el OCR integrado funciona de inmediato y /tool add permite crear herramientas de comando.

Instalar servidores MCP

Comando	Descripción
/mcp	Lista servidores, estado de conexión y número de herramientas
/mcp add	Instalación interactiva: elegir plantilla → rellenar parámetros → conectar y guardar
/mcp add <name> stdio <cmd...>	Añadir manualmente un proceso local
/mcp add <name> http|sse <url>	Añadir manualmente un endpoint remoto
/mcp import [file]	Importar configuración; sin archivo, pega el JSON y termina con EOF
/mcp rm|enable|disable|refresh [name]	Eliminar / activar / desactivar / actualizar la lista de herramientas

Plantillas integradas: Filesystem, Memory, Sequential Thinking, GitHub, Fetch, PostgreSQL, OCR.

Importar configuración existente

/mcp import admite un array simple, { "servers": [...] } y el formato de objeto mcpServers de Claude Desktop / Cursor:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

• Si se omite type, se deduce de builtin / url / command; si url termina en /sse, se deduce SSE.
• command puede ser una cadena y se combina con el array args; también admite expansión de variables ${VAR} / ${env:VAR}.
• Al guardar se escribe como array en .agent/mcp.json (viaja con el proyecto y puede confirmarse en git). Al importar entradas con el mismo nombre se pregunta una a una si sobrescribir u omitir.

OCR integrado

El OCR integrado está activado por defecto ({ "name": "ocr", "type": "builtin", "builtin": "ocr" }); la herramienta se llama mcp__ocr__recognize.

• Entrada: imagePath (recomendado, ruta dentro del espacio de trabajo), imageBase64, imageUrl; los PDF se reconocen página a página (maxPages por defecto 5, dpi por defecto 150).
• Los motores se degradan automáticamente: macOS Vision (requiere Xcode Command Line Tools) → tesseract + pdftoppm → modelo multimodal configurado.
• Si no hay ninguno disponible, devuelve error y how_to_fix, sin bloquear el arranque ni otras herramientas.
• Para desactivarlo: /mcp disable ocr.

La imagen de servidor Linux incluye tesseract-ocr, tesseract-ocr-chi-sim y poppler-utils; en local puedes instalarlos con el gestor de paquetes:

# macOS
brew install tesseract tesseract-lang poppler
# Debian / Ubuntu
apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

Carga bajo demanda

Cuando hay muchas herramientas MCP (por defecto ≥16 o schema total ≥24000 caracteres) se cambia automáticamente a carga bajo demanda:

• Ya no se envían todos los mcp__*; se usan mcp_search_tools (búsqueda) y mcp_call_tool (llamada).
• El modelo busca primero y las herramientas encontradas se cargan en el siguiente turno (máximo 40 por conversación); también puede llamarlas directamente con la metaherramienta.
• En escenarios pequeños se siguen inyectando todas, sin cambios de comportamiento; ZQAGENT_MCP_LAZY=1|0 permite forzarlo.

Herramientas de comando

Comando	Descripción
/tool add <name> <cmd...>	Añadir una herramienta de comando (ejecuta un comando de shell)
/tool rm|disable|enable <name>	Eliminar / desactivar / activar una herramienta

Efecto inmediato y persistencia

Añadir / eliminar / desactivar / reemplazar herramientas surte efecto en la siguiente conversación, sin reiniciar.

La configuración de servidores MCP y herramientas de comando se guarda con el proyecto y puede confirmarse en git y compartirse con el equipo. Las herramientas inyectadas por MCP (incluido el OCR integrado) se tratan como de alto riesgo por defecto y requieren aprobación en cada uso en modo interactivo.

Siguiente paso

• Herramientas integradas
• Uso de la CLI