MCPHost

⚠️ MCPHost ya no se mantiene activamente

El desarrollo activo de MCPHost se ha detenido. Este proyecto ha sido sucedido por Kit, que se basa en los cimientos de MCPHost con una arquitectura más potente y extensible.

👉 Recomendamos a todos los usuarios migrar a Kit.

Este repositorio ahora está archivado y no recibirá más actualizaciones ni correcciones de errores.

---

MCPHost 🤖

Una aplicación CLI host que permite a los Modelos de Lenguaje de Gran Escala (LLMs) interactuar con herramientas externas a través del Protocolo de Contexto de Modelo (MCP). Actualmente es compatible con modelos de Claude, OpenAI, Google Gemini y Ollama.

Discute el proyecto en Discord

Tabla de Contenidos

• Descripción General
• Características
• Requisitos
• Configuración del Entorno
• Instalación
• Uso del SDK
• Configuración
  • Servidores MCP
  • Sustitución de Variables de Entorno
  • Esquema de Configuración Simplificado
  • Filtrado de Herramientas
  • Soporte de Configuración Legada
  • Tipos de Transporte
  • Prompt del Sistema
• Uso
  • Modo Interactivo
  • Modo Script
  • Sistema de Hooks
  • Modo No Interactivo
  • Parámetros de Generación del Modelo
  • Modelos Disponibles
  • Ejemplos
  • Banderas
  • Subcomandos de Autenticación
  • Soporte de Archivos de Configuración
  • Comandos Interactivos
• Automatización y Scripting
• Compatibilidad con Servidores MCP
• Contribuciones
• Licencia
• Agradecimientos

Descripción General 🌟

MCPHost actúa como host en la arquitectura cliente-servidor de MCP, donde:

• Hosts (como MCPHost) son aplicaciones LLM que gestionan conexiones e interacciones
• Clientes mantienen conexiones 1:1 con servidores MCP
• Servidores proporcionan contexto, herramientas y capacidades a los LLMs

Esta arquitectura permite que los modelos de lenguaje:

• Accedan a herramientas externas y fuentes de datos 🛠️
• Mantengan un contexto consistente entre interacciones 🔄
• Ejecuten comandos y recuperen información de forma segura 🔒

Actualmente es compatible con:

• Modelos Anthropic Claude (Claude 3.5 Sonnet, Claude 3.5 Haiku, etc.)
• Modelos OpenAI (GPT-4, GPT-4 Turbo, GPT-3.5, etc.)
• Modelos Google Gemini (Gemini 2.0 Flash, Gemini 1.5 Pro, etc.)
• Cualquier modelo compatible con Ollama que tenga soporte de llamada a funciones
• Cualquier endpoint de API compatible con OpenAI

Características ✨

• Conversaciones interactivas con múltiples modelos de IA
• Modo no interactivo para scripting y automatización
• Modo script para scripts de automatización ejecutables basados en YAML
• Soporte para múltiples servidores MCP concurrentes
• Filtrado de herramientas con allowedTools y excludedTools por servidor
• Descubrimiento e integración dinámica de herramientas
• Capacidades de llamada a herramientas en todos los modelos compatibles
• Ubicaciones y argumentos de servidores MCP configurables
• Interfaz de comandos consistente entre tipos de modelos
• Ventana de historial de mensajes configurable para la gestión del contexto
• Soporte de autenticación OAuth para Anthropic (alternativa a las claves API)
• Sistema de hooks para integraciones personalizadas y políticas de seguridad
• Sustitución de variables de entorno en configuraciones y scripts
• Servidores integrados para funcionalidades comunes (filesystem, bash, todo, http)

Requisitos 📋

• Go 1.23 o posterior
• Para OpenAI/Anthropic: clave API del proveedor correspondiente
• Para Ollama: instalación local de Ollama con los modelos deseados
• Para Google/Gemini: clave API de Google (ver https://aistudio.google.com/app/apikey)
• Uno o más servidores de herramientas compatibles con MCP

Configuración del Entorno 🔧

1. Claves API:

# For all providers (use --provider-api-key flag or these environment variables)
export OPENAI_API_KEY='your-openai-key'        # For OpenAI
export ANTHROPIC_API_KEY='your-anthropic-key'  # For Anthropic
export GOOGLE_API_KEY='your-google-key'        # For Google/Gemini

2. Configuración de Ollama:

• Instala Ollama desde https://ollama.ai
• Descarga tu modelo deseado:

ollama pull mistral

• Asegúrate de que Ollama esté en ejecución:

ollama serve

También puedes configurar el cliente de Ollama usando variables de entorno estándar, como OLLAMA_HOST para la URL base de Ollama.

3. Clave API de Google (para Gemini):

export GOOGLE_API_KEY='your-api-key'

4. Configuración compatible con OpenAI:

• Obtén la URL base de tu servidor API, la clave API y el nombre del modelo
• Usa las banderas --provider-url y --provider-api-key o establece variables de entorno

5. Certificados Autofirmados (TLS): Si tu proveedor usa certificados autofirmados (por ejemplo, Ollama local con HTTPS), puedes omitir la verificación de certificados:

mcphost --provider-url https://192.168.1.100:443 --tls-skip-verify

⚠️ ADVERTENCIA: Usa --tls-skip-verify solo para desarrollo o cuando te conectes a servidores de confianza con certificados autofirmados. Esto desactiva la verificación de certificados TLS y es inseguro para uso en producción.

Instalación 📦

go install github.com/mark3labs/mcphost@latest

Uso del SDK 🛠️

MCPHost también proporciona un SDK de Go para acceso programático sin generar procesos del sistema operativo. El SDK mantiene un comportamiento idéntico al CLI, incluyendo la carga de configuración, variables de entorno y valores predeterminados.

Ejemplo Rápido

package main

import (
    "context"
    "fmt"
    "github.com/mark3labs/mcphost/sdk"
)

func main() {
    ctx := context.Background()
    
    // Create MCPHost instance with default configuration
    host, err := sdk.New(ctx, nil)
    if err != nil {
        panic(err)
    }
    defer host.Close()
    
    // Send a prompt and get response
    response, err := host.Prompt(ctx, "What is 2+2?")
    if err != nil {
        panic(err)
    }
    
    fmt.Println(response)
}

Características del SDK

• ✅ Acceso programático sin generar procesos
• ✅ Comportamiento de configuración idéntico al CLI
• ✅ Gestión de sesiones (guardar/cargar/limpiar)
• ✅ Callbacks de ejecución de herramientas para monitoreo
• ✅ Soporte de streaming
• ✅ Compatibilidad total con todos los proveedores y servidores MCP

Para documentación detallada del SDK, ejemplos y referencia de API, consulta el README del SDK.

Configuración ⚙️

Servidores MCP

MCPHost creará automáticamente un archivo de configuración en tu directorio de inicio si no existe. Busca archivos de configuración en este orden:

• .mcphost.yml o .mcphost.json (preferido)
• .mcp.yml o .mcp.json (compatibilidad hacia atrás)

Ubicaciones de archivos de configuración por sistema operativo:

• Linux/macOS: ~/.mcphost.yml, ~/.mcphost.json, ~/.mcp.yml, ~/.mcp.json
• Windows: %USERPROFILE%\.mcphost.yml, %USERPROFILE%\.mcphost.json, %USERPROFILE%\.mcp.yml, %USERPROFILE%\.mcp.json

También puedes especificar una ubicación personalizada usando la bandera --config.

Sustitución de Variables de Entorno

MCPHost admite la sustitución de variables de entorno tanto en archivos de configuración como en frontmatter de scripts usando la sintaxis:

• ${env://VAR} - Variable de entorno requerida (falla si no está establecida)
• ${env://VAR:-default} - Variable de entorno opcional con valor predeterminado

Esto te permite mantener información sensible como claves API en variables de entorno mientras mantienes una configuración flexible.

Ejemplo:

mcpServers:
  github:
    type: local
    command: ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"]
    environment:
      DEBUG: "${env://DEBUG:-false}"
      LOG_LEVEL: "${env://LOG_LEVEL:-info}"

model: "${env://MODEL:-anthropic/claude-sonnet-4-5-20250929}"
provider-api-key: "${env://OPENAI_API_KEY}"  # Required - will fail if not set

Uso:

# Set required environment variables
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"

# Optionally override defaults
export DEBUG="true"
export MODEL="openai/gpt-4"

# Run mcphost
mcphost

Esquema de Configuración Simplificado

MCPHost ahora admite un esquema de configuración simplificado con tres tipos de servidores:

Servidores Locales

Para servidores MCP locales que ejecutan comandos en tu máquina:

{
  "mcpServers": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "${env://WORK_DIR:-/tmp}"],
      "environment": {
        "DEBUG": "${env://DEBUG:-false}",
        "LOG_LEVEL": "${env://LOG_LEVEL:-info}",
        "API_TOKEN": "${env://FS_API_TOKEN}"
      },
      "allowedTools": ["read_file", "write_file"],
      "excludedTools": ["delete_file"]
    },
    "github": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"],
      "environment": {
        "DEBUG": "${env://DEBUG:-false}"
      }
    },
    "sqlite": {
      "type": "local",
      "command": ["uvx", "mcp-server-sqlite", "--db-path", "${env://DB_PATH:-/tmp/foo.db}"],
      "environment": {
        "SQLITE_DEBUG": "${env://DEBUG:-0}",
        "DATABASE_URL": "${env://DATABASE_URL:-sqlite:///tmp/foo.db}"
      }
    }
  }
}

Cada entrada de servidor local requiere:

• type: Debe establecerse en "local"
• command: Matriz que contiene el comando y todos sus argumentos
• environment: (Opcional) Objeto con variables de entorno como pares clave-valor
• allowedTools: (Opcional) Matriz de nombres de herramientas a incluir (lista blanca)
• excludedTools: (Opcional) Matriz de nombres de herramientas a excluir (lista negra)

Servidores Remotos

Para servidores MCP remotos accesibles vía HTTP:

{
  "mcpServers": {
    "websearch": {
      "type": "remote",
      "url": "${env://WEBSEARCH_URL:-https://api.example.com/mcp}",
      "headers": ["Authorization: Bearer ${env://WEBSEARCH_TOKEN}"]
    },
    "weather": {
      "type": "remote", 
      "url": "${env://WEATHER_URL:-https://weather-mcp.example.com}"
    }
  }
}

Cada entrada de servidor remoto requiere:

• type: Debe establecerse en "remote"
• url: La URL donde el servidor MCP es accesible
• headers: (Opcional) Matriz de encabezados HTTP para autenticación y encabezados personalizados

Los servidores remotos usan automáticamente el transporte StreamableHTTP para un rendimiento óptimo.

Servidores Integrados

Para servidores MCP integrados que se ejecutan en proceso para un rendimiento óptimo:

{
  "mcpServers": {
    "filesystem": {
      "type": "builtin",
      "name": "fs",
      "options": {
        "allowed_directories": ["${env://WORK_DIR:-/tmp}", "${env://HOME}/documents"]
      },
      "allowedTools": ["read_file", "write_file", "list_directory"]
    },
    "filesystem-cwd": {
      "type": "builtin",
      "name": "fs"
    }
  }
}

Cada entrada de servidor integrado requiere:

• type: Debe establecerse en "builtin"
• name: Nombre interno del servidor integrado (por ejemplo, "fs" para filesystem)
• options: Opciones de configuración específicas del servidor integrado

Servidores Integrados Disponibles:

• fs (filesystem): Acceso seguro al sistema de archivos con directorios permitidos configurables
  • allowed_directories: Matriz de rutas de directorios a los que el servidor puede acceder (por defecto, el directorio de trabajo actual si no se especifica)
• bash: Ejecuta comandos bash con restricciones de seguridad y controles de tiempo de espera
  • No se requieren opciones de configuración
• todo: Gestiona listas de tareas efímeras para el seguimiento de tareas durante las sesiones
  • No se requieren opciones de configuración (las tareas se almacenan en memoria y se restablecen al reiniciar)
• http: Obtiene contenido web y lo convierte a formatos de texto, markdown o HTML
  • Herramientas: fetch (obtener y convertir contenido web), fetch_summarize (obtener y resumir contenido web usando IA), fetch_extract (obtener y extraer datos específicos usando IA), fetch_filtered_json (obtener JSON y filtrar usando sintaxis de ruta gjson)
  • No se requieren opciones de configuración

Ejemplos de Servidores Integrados

{
  "mcpServers": {
    "filesystem": {
      "type": "builtin",
      "name": "fs",
      "options": {
        "allowed_directories": ["/tmp", "/home/user/documents"]
      }
    },
    "bash-commands": {
      "type": "builtin", 
      "name": "bash"
    },
    "task-manager": {
      "type": "builtin",
      "name": "todo"
    },
    "web-fetcher": {
      "type": "builtin",
      "name": "http"
    }
  }
}

Filtrado de Herramientas

Todos los tipos de servidores MCP admiten el filtrado de herramientas para restringir qué herramientas están disponibles:

• allowedTools: Lista blanca: solo las herramientas especificadas están disponibles desde el servidor
• excludedTools: Lista negra: todas las herramientas excepto las especificadas están disponibles

{
  "mcpServers": {
    "filesystem-readonly": {
      "type": "builtin",
      "name": "fs",
      "allowedTools": ["read_file", "list_directory"]
    },
    "filesystem-safe": {
      "type": "local", 
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "excludedTools": ["delete_file"]
    }
  }
}

Nota: allowedTools y excludedTools son mutuamente excluyentes: solo puedes usar uno por servidor.

Soporte de Configuración Legada

MCPHost mantiene compatibilidad total hacia atrás con el formato de configuración anterior. Nota: Una corrección de errores reciente mejoró la fiabilidad del transporte stdio legado para servidores MCP externos (Docker, NPX, etc.).

Formato STDIO Legado

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/tmp/foo.db"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Formato SSE Legado

{
  "mcpServers": {
    "server_name": {
      "url": "http://some_host:8000/sse",
      "headers": ["Authorization: Bearer my-token"]
    }
  }
}

Formato Docker/Contenedor Legado

{
  "mcpServers": {
    "phalcon": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mark3labs/phalcon-mcp:latest",
        "serve"
      ]
    }
  }
}

Formato Streamable HTTP Legado

{
  "mcpServers": {
    "websearch": {
      "transport": "streamable",
      "url": "https://api.example.com/mcp",
      "headers": ["Authorization: Bearer your-api-token"]
    }
  }
}

Tipos de Transporte

MCPHost admite cuatro tipos de transporte:

• stdio: Lanza un proceso local y se comunica vía stdin/stdout (usado por servidores "local")
• sse: Se conecta a un servidor usando Server-Sent Events (formato legado)
• streamable: Se conecta a un servidor usando el protocolo Streamable HTTP (usado por servidores "remote")
• inprocess: Ejecuta servidores integrados en proceso para un rendimiento óptimo (usado por servidores "builtin")

El esquema simplificado mapea automáticamente:

• Tipo "local" → transporte stdio
• Tipo "remote" → transporte streamable
• Tipo "builtin" → transporte inprocess

Prompt del Sistema

Puedes especificar un prompt del sistema personalizado usando la bandera --system-prompt. Puedes:

1. Pasar el prompt directamente como texto:

   mcphost --system-prompt "You are a helpful assistant that responds in a friendly tone."
   

2. Pasar una ruta a un archivo de texto que contenga el prompt:

   mcphost --system-prompt ./prompts/assistant.md
   

   Ejemplo de archivo assistant.md:

   You are a helpful coding assistant. 
   
   Please:
   - Write clean, readable code
   - Include helpful comments
   - Follow best practices
   - Explain your reasoning
   

Uso 🚀

MCPHost es una herramienta CLI que te permite interactuar con varios modelos de IA a través de una interfaz unificada. Admite varias herramientas a través de servidores MCP y puede ejecutarse tanto en modo interactivo como no interactivo.

Modo Interactivo (Predeterminado)

Inicia una sesión de conversación interactiva:

mcphost

Modo Script

Ejecuta scripts de automatización ejecutables basados en YAML con soporte de sustitución de variables:

# Using the script subcommand
mcphost script myscript.sh

# With variables
mcphost script myscript.sh --args:directory /tmp --args:name "John"

# Direct execution (if executable and has shebang)
./myscript.sh

Formato de Script

Los scripts combinan configuración YAML con prompts en un solo archivo ejecutable. La configuración debe estar envuelta en delimitadores de frontmatter (---). Puedes incluir el prompt en la configuración YAML o colocarlo después del delimitador de cierre de frontmatter:

#!/usr/bin/env -S mcphost script
---
# This script uses the container-use MCP server from https://github.com/dagger/container-use
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
prompt: |
  Create 2 variations of a simple hello world app using Flask and FastAPI. 
  Each in their own environment. Give me the URL of each app
---

O alternativamente, omite el campo prompt: y coloca el prompt después del frontmatter:

#!/usr/bin/env -S mcphost script
---
# This script uses the container-use MCP server from https://github.com/dagger/container-use
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
---
Create 2 variations of a simple hello world app using Flask and FastAPI. 
Each in their own environment. Give me the URL of each app

Sustitución de Variables

Los scripts admiten tanto la sustitución de variables de entorno como la sustitución de argumentos de script:

1. Variables de Entorno: ${env://VAR} y ${env://VAR:-default} - Se procesan primero
2. Argumentos de Script: ${variable} y ${variable:-default} - Se procesan después de las variables de entorno

Las variables se pueden proporcionar mediante argumentos de línea de comandos:

# Script with variables
mcphost script myscript.sh --args:directory /tmp --args:name "John"

Sintaxis de Variables

MCPHost admite las siguientes sintaxis de variables:

1. Variables de entorno requeridas: ${env://VAR} - Deben estar definidas en el entorno
2. Variables de entorno opcionales: ${env://VAR:-default} - Usa un valor predeterminado si no están definidas
3. Argumentos de script requeridos: ${variable} - Deben proporcionarse mediante --args:variable value
4. Argumentos de script opcionales: ${variable:-default} - Usa un valor predeterminado si no se proporcionan

Ejemplo de script con variables de entorno y argumentos de script mixtos:

#!/usr/bin/env -S mcphost script
---
mcpServers:
  github:
    type: "local"
    command: ["gh", "api"]
    environment:
      GITHUB_TOKEN: "${env://GITHUB_TOKEN}"
      DEBUG: "${env://DEBUG:-false}"
  
  filesystem:
    type: "local"
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "${env://WORK_DIR:-/tmp}"]

model: "${env://MODEL:-anthropic/claude-sonnet-4-5-20250929}"
---
Hello ${name:-World}! Please list ${repo_type:-public} repositories for user ${username}.
Working directory is ${env://WORK_DIR:-/tmp}.
Use the ${command:-gh} command to fetch ${count:-10} repositories.

Ejemplos de Uso

# Set environment variables first
export GITHUB_TOKEN="ghp_your_token_here"
export DEBUG="true"
export WORK_DIR="/home/user/projects"

# Uses env vars and defaults: name="World", repo_type="public", command="gh", count="10"
mcphost script myscript.sh

# Override specific script arguments
mcphost script myscript.sh --args:name "John" --args:username "alice"

# Override multiple script arguments  
mcphost script myscript.sh --args:name "John" --args:username "alice" --args:repo_type "private"

# Mix of env vars, provided args, and default values
mcphost script myscript.sh --args:name "Alice" --args:command "gh api" --args:count "5"

Características de Valores Predeterminados

• Valores predeterminados vacíos: ${var:-} - Usa una cadena vacía si no se proporciona
• Valores predeterminados complejos: ${path:-/tmp/default/path} - Admite rutas, URLs, etc.
• Espacios en valores predeterminados: ${msg:-Hello World} - Admite espacios en valores predeterminados
• Compatibilidad hacia atrás: La sintaxis existente ${variable} sigue funcionando sin cambios

Importante:

• Las variables de entorno sin valores predeterminados (por ejemplo, ${env://GITHUB_TOKEN}) son requeridas y deben estar definidas en el entorno
• Los argumentos de script sin valores predeterminados (por ejemplo, ${username}) son requeridos y deben proporcionarse mediante la sintaxis --args:variable value
• Las variables con valores predeterminados son opcionales y usarán su valor predeterminado si no se proporcionan
• Las variables de entorno se procesan primero, luego los argumentos de script

Características de Scripts

• Ejecutable: Usa la línea shebang para ejecución directa (#!/usr/bin/env -S mcphost script)
• Configuración YAML: Define servidores MCP directamente en el script
• Prompts integrados: Incluye el prompt en el YAML
• Sustitución de variables: Usa la sintaxis ${variable} y ${variable:-default} con --args:variable value
• Validación de variables: Las variables requeridas faltantes hacen que el script termine con un error útil
• Modo interactivo: Si el prompt está vacío, entra en modo interactivo (útil para scripts de configuración)
• Respaldo de configuración: Si no se define mcpServers, usa la configuración predeterminada
• Filtrado de herramientas: Admite allowedTools/excludedTools por servidor
• Salida limpia: Sale automáticamente después de completarse

Nota: La línea shebang requiere env -S para manejar el comando de múltiples palabras mcphost script. Esto es compatible con la mayoría de los sistemas modernos tipo Unix.

Ejemplos de Scripts

Consulta examples/scripts/ para ver scripts de ejemplo:

• example-script.sh - Script con servidores MCP personalizados
• simple-script.sh - Script que usa el respaldo de configuración predeterminada

Sistema de Hooks

MCPHost admite un potente sistema de hooks que te permite ejecutar comandos personalizados en puntos específicos durante la ejecución. Esto permite políticas de seguridad, registro de actividades, integraciones personalizadas y flujos de trabajo automatizados.

Inicio Rápido

1. Inicializa una configuración de hooks:

   mcphost hooks init
   

2. Visualiza los hooks activos:

   mcphost hooks list
   

3. Valida tu configuración:

   mcphost hooks validate
   

Configuración

Los hooks se configuran en archivos YAML con la siguiente precedencia (de mayor a menor):

• .mcphost/hooks.yml (hooks específicos del proyecto)
• $XDG_CONFIG_HOME/mcphost/hooks.yml (hooks globales del usuario, por defecto ~/.config/mcphost/hooks.yml)

Ejemplo de configuración:

hooks:
  PreToolUse:
    - matcher: "bash"
      hooks:
        - type: command
          command: "/usr/local/bin/validate-bash.py"
          timeout: 5
  
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "~/.mcphost/hooks/log-prompt.sh"

Eventos de Hook Disponibles

• PreToolUse: Antes de cualquier ejecución de herramienta (bash, fetch, todo, herramientas MCP)
• PostToolUse: Después de que la ejecución de la herramienta se complete
• UserPromptSubmit: Cuando el usuario envía un prompt
• Stop: Cuando el agente termina de responder
• SubagentStop: Cuando un subagente (herramienta Task) termina
• Notification: Cuando MCPHost envía notificaciones

Seguridad

⚠️ ADVERTENCIA: Los hooks ejecutan comandos arbitrarios en tu sistema. Solo usa hooks de fuentes confiables y siempre revisa los comandos de los hooks antes de habilitarlos.

Para deshabilitar temporalmente todos los hooks, usa la bandera --no-hooks:

mcphost --no-hooks

Consulta los scripts de hook de ejemplo en examples/hooks/:

• bash-validator.py - Valida y bloquea comandos bash peligrosos
• prompt-logger.sh - Registra todos los prompts de usuario con marcas de tiempo
• mcp-monitor.py - Monitorea y aplica políticas sobre el uso de herramientas MCP

Modo No Interactivo

Ejecuta un solo prompt y sal - perfecto para scripting y automatización:

# Basic non-interactive usage
mcphost -p "What is the weather like today?"

# Quiet mode - only output the AI response (no UI elements)
mcphost -p "What is 2+2?" --quiet

# Use with different models
mcphost -m ollama/qwen2.5:3b -p "Explain quantum computing" --quiet

Parámetros de Generación del Modelo

MCPHost admite el ajuste fino del comportamiento del modelo mediante varios parámetros:

# Control response length
mcphost -p "Explain AI" --max-tokens 1000

# Adjust creativity (0.0 = focused, 1.0 = creative)
mcphost -p "Write a story" --temperature 0.9

# Control diversity with nucleus sampling
mcphost -p "Generate ideas" --top-p 0.8

# Limit token choices for more focused responses
mcphost -p "Answer precisely" --top-k 20

# Set custom stop sequences
mcphost -p "Generate code" --stop-sequences "```","END"

Estos parámetros funcionan con todos los proveedores compatibles (OpenAI, Anthropic, Google, Ollama) donde el modelo subyacente lo admita.

Modelos Disponibles

Los modelos se pueden especificar usando la bandera --model (-m):

• Anthropic Claude (predeterminado): anthropic/claude-sonnet-4-5-20250929, anthropic/claude-3-5-sonnet-latest, anthropic/claude-3-5-haiku-latest
• OpenAI: openai/gpt-4, openai/gpt-4-turbo, openai/gpt-3.5-turbo
• Google Gemini: google/gemini-2.0-flash, google/gemini-1.5-pro
• Modelos Ollama: ollama/llama3.2, ollama/qwen2.5:3b, ollama/mistral
• Compatible con OpenAI: Cualquier modelo mediante endpoint personalizado con --provider-url

Ejemplos

Modo Interactivo

# Use Ollama with Qwen model
mcphost -m ollama/qwen2.5:3b

# Use OpenAI's GPT-4
mcphost -m openai/gpt-4

# Use OpenAI-compatible model with custom URL and API key
mcphost --model openai/<your-model-name> \
--provider-url <your-base-url> \
--provider-api-key <your-api-key>

Modo No Interactivo

# Single prompt with full UI
mcphost -p "List files in the current directory"

# Compact mode for cleaner output without fancy styling
mcphost -p "List files in the current directory" --compact

# Quiet mode for scripting (only AI response output, no UI elements)
mcphost -p "What is the capital of France?" --quiet

# Use in shell scripts
RESULT=$(mcphost -p "Calculate 15 * 23" --quiet)
echo "The answer is: $RESULT"

# Pipe to other commands
mcphost -p "Generate a random UUID" --quiet | tr '[:lower:]' '[:upper:]'

Banderas

• --provider-url string: URL base para la API del proveedor (aplica a OpenAI, Anthropic, Ollama y Google)
• --provider-api-key string: Clave API para el proveedor (aplica a OpenAI, Anthropic y Google)
• --tls-skip-verify: Omitir verificación de certificado TLS (ADVERTENCIA: inseguro, úsalo solo para certificados autofirmados)
• --config string: Ubicación del archivo de configuración (predeterminado es $HOME/.mcphost.yml)
• --system-prompt string: Ubicación del archivo de prompt del sistema
• --debug: Habilitar registro de depuración
• --max-steps int: Número máximo de pasos del agente (0 para ilimitado, predeterminado: 0)
• -m, --model string: Modelo a usar (formato: proveedor/modelo) (predeterminado "anthropic/claude-sonnet-4-5-20250929")
• -p, --prompt string: Ejecutar en modo no interactivo con el prompt dado
• --quiet: Suprimir toda la salida excepto la respuesta de IA (solo funciona con --prompt)
• --compact: Habilitar modo de salida compacta sin estilos elegantes (ideal para scripting y automatización)
• --stream: Habilitar respuestas en streaming (predeterminado: true, usa --stream=false para deshabilitar)

Subcomandos de Autenticación

• mcphost auth login anthropic: Autenticarse con Anthropic usando OAuth (alternativa a las claves API)
• mcphost auth logout anthropic: Eliminar credenciales OAuth almacenadas
• mcphost auth status: Mostrar estado de autenticación

Nota: Las credenciales OAuth (cuando están presentes) tienen prioridad sobre las claves API de las variables de entorno y las banderas --provider-api-key.

Parámetros de Generación del Modelo

• --max-tokens int: Número máximo de tokens en la respuesta (predeterminado: 4096)
• --temperature float32: Controla la aleatoriedad en las respuestas (0.0-1.0, predeterminado: 0.7)
• --top-p float32: Controla la diversidad mediante muestreo de núcleo (0.0-1.0, predeterminado: 0.95)
• --top-k int32: Controla la diversidad limitando los K tokens principales a muestrear (predeterminado: 40)
• --stop-sequences strings: Secuencias de detención personalizadas (separadas por comas)

Soporte de Archivos de Configuración

Todas las banderas de línea de comandos se pueden configurar mediante el archivo de configuración. MCPHost buscará la configuración en este orden:

1. ~/.mcphost.yml o ~/.mcphost.json (preferido)
2. ~/.mcp.yml o ~/.mcp.json (compatibilidad hacia atrás)

Ejemplo de archivo de configuración (~/.mcphost.yml):

# MCP Servers - New Simplified Format
mcpServers:
  filesystem-local:
    type: "local"
    command: ["npx", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    environment:
      DEBUG: "true"
  filesystem-builtin:
    type: "builtin"
    name: "fs"
    options:
      allowed_directories: ["/tmp", "/home/user/documents"]
  websearch:
    type: "remote"
    url: "https://api.example.com/mcp"

# Application settings
model: "anthropic/claude-sonnet-4-5-20250929"
max-steps: 20
debug: false
system-prompt: "/path/to/system-prompt.txt"

# Model generation parameters
max-tokens: 4096
temperature: 0.7
top-p: 0.95
top-k: 40
stop-sequences: ["Human:", "Assistant:"]

# Streaming configuration
stream: false  # Disable streaming (default: true)

# API Configuration
provider-api-key: "your-api-key"      # For OpenAI, Anthropic, or Google
provider-url: "https://api.openai.com/v1"  # Custom base URL
tls-skip-verify: false  # Skip TLS certificate verification (default: false)

Nota: Las banderas de línea de comandos tienen prioridad sobre los valores del archivo de configuración.

Comandos Interactivos

Mientras chateas, puedes usar:

• /help: Mostrar comandos disponibles
• /tools: Listar todas las herramientas disponibles
• /servers: Listar servidores MCP configurados
• /history: Mostrar historial de conversación
• /quit: Salir de la aplicación
• Ctrl+C: Salir en cualquier momento

Comandos de Autenticación

Autenticación OAuth opcional para Anthropic (alternativa a las claves API):

• mcphost auth login anthropic: Autenticarse usando OAuth
• mcphost auth logout anthropic: Eliminar credenciales OAuth almacenadas
• mcphost auth status: Mostrar estado de autenticación

Banderas Globales

• --config: Especificar ubicación personalizada del archivo de configuración

Automatización y Scripting 🤖

El modo no interactivo de MCPHost lo hace perfecto para automatización, scripting e integración con otras herramientas.

Casos de Uso

Scripts de Shell

#!/bin/bash
# Get weather and save to file
mcphost -p "What's the weather in New York?" --quiet > weather.txt

# Process files with AI
for file in *.txt; do
    summary=$(mcphost -p "Summarize this file: $(cat $file)" --quiet)
    echo "$file: $summary" >> summaries.txt
done

Integración CI/CD

# Code review automation
DIFF=$(git diff HEAD~1)
mcphost -p "Review this code diff and suggest improvements: $DIFF" --quiet

# Generate release notes
COMMITS=$(git log --oneline HEAD~10..HEAD)
mcphost -p "Generate release notes from these commits: $COMMITS" --quiet

Procesamiento de Datos

# Process CSV data
mcphost -p "Analyze this CSV data and provide insights: $(cat data.csv)" --quiet

# Generate reports
mcphost -p "Create a summary report from this JSON: $(cat metrics.json)" --quiet

Integración de API

# Use as a microservice
curl -X POST http://localhost:8080/process \
  -d "$(mcphost -p 'Generate a UUID' --quiet)"

Consejos para Scripting

• Usa la bandera --quiet para obtener salida limpia adecuada para análisis (solo respuesta de IA, sin interfaz)
• Usa la bandera --compact para salida simplificada sin estilos elegantes (cuando quieras ver elementos de interfaz)
• Nota: --compact y --quiet son mutuamente excluyentes - --compact no tiene efecto con --quiet
• Usa variables de entorno para datos sensibles como claves API en lugar de codificarlos
• Usa la sintaxis ${env://VAR} en archivos de configuración y scripts para sustitución de variables de entorno
• Combina con herramientas Unix estándar (grep, awk, sed, etc.)
• Establece tiempos de espera apropiados para operaciones de larga duración
• Maneja errores apropiadamente en tus scripts
• Usa variables de entorno para claves API en producción

Mejores Prácticas para Variables de Entorno

# Set sensitive variables in environment
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"
export DATABASE_URL="postgresql://user:pass@localhost/db"

# Use in config files
mcpServers:
  github:
    environment:
      GITHUB_TOKEN: "${env://GITHUB_TOKEN}"
      DEBUG: "${env://DEBUG:-false}"

# Use in scripts
mcphost script my-script.sh --args:username alice

Compatibilidad con Servidores MCP 🔌

MCPHost puede funcionar con cualquier servidor compatible con MCP. Para ejemplos e implementaciones de referencia, consulta el Repositorio de Servidores MCP.

Contribuciones 🤝

¡Las contribuciones son bienvenidas! Siéntete libre de:

• Enviar informes de errores o solicitudes de funciones a través de issues
• Crear pull requests para mejoras
• Compartir tus servidores MCP personalizados
• Mejorar la documentación

Asegúrate de que tus contribuciones sigan buenas prácticas de codificación e incluyan pruebas apropiadas.

Licencia 📄

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

Agradecimientos 🙏

• Gracias al equipo de Anthropic por Claude y la especificación MCP
• Gracias al equipo de Ollama por su runtime local de LLM
• Gracias a todos los contribuyentes que han ayudado a mejorar esta herramienta