MCPHost

⚠️ MCPHost não é mais mantido ativamente

O desenvolvimento ativo do MCPHost foi interrompido. Este projeto foi sucedido pelo Kit, que se baseia nos fundamentos do MCPHost com uma arquitetura mais poderosa e extensível.

👉 Recomendamos que todos os usuários migrem para o Kit.

Este repositório agora está arquivado e não receberá mais atualizações ou correções de bugs.

---

MCPHost 🤖

Um aplicativo host de CLI que permite que Modelos de Linguagem de Grande Porte (LLMs) interajam com ferramentas externas por meio do Protocolo de Contexto de Modelo (MCP). Atualmente suporta modelos Claude, OpenAI, Google Gemini e Ollama.

Discuta o projeto no Discord

Sumário

• Visão Geral
• Recursos
• Requisitos
• Configuração do Ambiente
• Instalação
• Uso do SDK
• Configuração
  • Servidores MCP
  • Substituição de Variáveis de Ambiente
  • Esquema de Configuração Simplificado
  • Filtragem de Ferramentas
  • Suporte a Configuração Legada
  • Tipos de Transporte
  • Prompt do Sistema
• Uso
  • Modo Interativo
  • Modo de Script
  • Sistema de Hooks
  • Modo Não Interativo
  • Parâmetros de Geração do Modelo
  • Modelos Disponíveis
  • Exemplos
  • Flags
  • Subcomandos de Autenticação
  • Suporte a Arquivo de Configuração
  • Comandos Interativos
• Automação e Scripts
• Compatibilidade com Servidores MCP
• Contribuindo
• Licença
• Agradecimentos

Visão Geral 🌟

O MCPHost atua como host na arquitetura cliente-servidor do MCP, onde:

• Hosts (como o MCPHost) são aplicações LLM que gerenciam conexões e interações
• Clientes mantêm conexões 1:1 com servidores MCP
• Servidores fornecem contexto, ferramentas e capacidades aos LLMs

Essa arquitetura permite que os modelos de linguagem:

• Acessem ferramentas externas e fontes de dados 🛠️
• Mantenham contexto consistente entre interações 🔄
• Executem comandos e recuperem informações com segurança 🔒

Atualmente suporta:

• 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.)
• Qualquer modelo compatível com Ollama com suporte a chamada de funções
• Qualquer endpoint de API compatível com OpenAI

Recursos ✨

• Conversas interativas com múltiplos modelos de IA
• Modo não interativo para scripts e automação
• Modo de script para scripts de automação executáveis baseados em YAML
• Suporte a múltiplos servidores MCP simultâneos
• Filtragem de ferramentas com allowedTools e excludedTools por servidor
• Descoberta e integração dinâmicas de ferramentas
• Capacidades de chamada de ferramentas em todos os modelos suportados
• Locais e argumentos de servidor MCP configuráveis
• Interface de comando consistente entre tipos de modelo
• Janela de histórico de mensagens configurável para gerenciamento de contexto
• Suporte a autenticação OAuth para Anthropic (alternativa às chaves de API)
• Sistema de hooks para integrações personalizadas e políticas de segurança
• Substituição de variáveis de ambiente em configurações e scripts
• Servidores integrados para funcionalidades comuns (filesystem, bash, todo, http)

Requisitos 📋

• Go 1.23 ou posterior
• Para OpenAI/Anthropic: chave de API do respectivo provedor
• Para Ollama: instalação local do Ollama com os modelos desejados
• Para Google/Gemini: chave de API do Google (veja https://aistudio.google.com/app/apikey)
• Um ou mais servidores de ferramentas compatíveis com MCP

Configuração do Ambiente 🔧

1. Chaves de 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. Configuração do Ollama:

• Instale o Ollama a partir de https://ollama.ai
• Baixe o modelo desejado:

ollama pull mistral

• Certifique-se de que o Ollama está em execução:

ollama serve

Você também pode configurar o cliente Ollama usando variáveis de ambiente padrão, como OLLAMA_HOST para a URL base do Ollama.

3. Chave de API do Google (para Gemini):

export GOOGLE_API_KEY='your-api-key'

4. Configuração compatível com OpenAI:

• Obtenha a URL base do servidor de API, a chave de API e o nome do modelo
• Use as flags --provider-url e --provider-api-key ou defina variáveis de ambiente

5. Certificados Autoassinados (TLS): Se o seu provedor usa certificados autoassinados (ex.: Ollama local com HTTPS), você pode pular a verificação de certificado:

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

⚠️ AVISO: Use --tls-skip-verify apenas para desenvolvimento ou ao conectar a servidores confiáveis com certificados autoassinados. Isso desativa a verificação de certificados TLS e é inseguro para uso em produção.

Instalação 📦

go install github.com/mark3labs/mcphost@latest

Uso do SDK 🛠️

O MCPHost também fornece um SDK Go para acesso programático sem gerar processos do sistema operacional. O SDK mantém comportamento idêntico ao CLI, incluindo carregamento de configuração, variáveis de ambiente e padrões.

Exemplo 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)
}

Recursos do SDK

• ✅ Acesso programático sem gerar processos
• ✅ Comportamento de configuração idêntico ao CLI
• ✅ Gerenciamento de sessão (salvar/carregar/limpar)
• ✅ Callbacks de execução de ferramentas para monitoramento
• ✅ Suporte a streaming
• ✅ Compatibilidade total com todos os provedores e servidores MCP

Para documentação detalhada do SDK, exemplos e referência de API, consulte o README do SDK.

Configuração ⚙️

Servidores MCP

O MCPHost criará automaticamente um arquivo de configuração no seu diretório inicial se ele não existir. Ele procura arquivos de configuração nesta ordem:

• .mcphost.yml ou .mcphost.json (preferido)
• .mcp.yml ou .mcp.json (compatibilidade com versões anteriores)

Locais do arquivo de configuração por SO:

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

Você também pode especificar um local personalizado usando a flag --config.

Substituição de Variáveis de Ambiente

O MCPHost suporta substituição de variáveis de ambiente em arquivos de configuração e frontmatter de scripts usando a sintaxe:

• ${env://VAR} - Variável de ambiente obrigatória (falha se não estiver definida)
• ${env://VAR:-default} - Variável de ambiente opcional com valor padrão

Isso permite manter informações sensíveis, como chaves de API, em variáveis de ambiente enquanto mantém uma configuração flexível.

Exemplo:

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 Configuração Simplificado

O MCPHost agora suporta um esquema de configuração simplificado com três tipos de servidor:

Servidores Locais

Para servidores MCP locais que executam comandos na sua 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 requer:

• type: Deve ser definido como "local"
• command: Array contendo o comando e todos os seus argumentos
• environment: (Opcional) Objeto com variáveis de ambiente como pares chave-valor
• allowedTools: (Opcional) Array de nomes de ferramentas a incluir (whitelist)
• excludedTools: (Opcional) Array de nomes de ferramentas a excluir (blacklist)

Servidores Remotos

Para servidores MCP remotos acessíveis via 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 requer:

• type: Deve ser definido como "remote"
• url: A URL onde o servidor MCP está acessível
• headers: (Opcional) Array de cabeçalhos HTTP para autenticação e cabeçalhos personalizados

Servidores remotos usam automaticamente o transporte StreamableHTTP para desempenho ideal.

Servidores Integrados

Para servidores MCP integrados que executam em processo para desempenho ideal:

{
  "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 requer:

• type: Deve ser definido como "builtin"
• name: Nome interno do servidor integrado (ex.: "fs" para filesystem)
• options: Opções de configuração específicas do servidor integrado

Servidores Integrados Disponíveis:

• fs (filesystem): Acesso seguro ao sistema de arquivos com diretórios permitidos configuráveis
  • allowed_directories: Array de caminhos de diretório que o servidor pode acessar (padrão: diretório de trabalho atual se não especificado)
• bash: Executa comandos bash com restrições de segurança e controles de timeout
  • Nenhuma opção de configuração necessária
• todo: Gerencia listas de tarefas efêmeras para acompanhamento de tarefas durante sessões
  • Nenhuma opção de configuração necessária (as tarefas são armazenadas em memória e redefinidas na reinicialização)
• http: Busca conteúdo da web e converte para formatos de texto, markdown ou HTML
  • Ferramentas: fetch (busca e converte conteúdo da web), fetch_summarize (busca e resume conteúdo da web usando IA), fetch_extract (busca e extrai dados específicos usando IA), fetch_filtered_json (busca JSON e filtra usando sintaxe de caminho gjson)
  • Nenhuma opção de configuração necessária

Exemplos 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"
    }
  }
}

Filtragem de Ferramentas

Todos os tipos de servidor MCP suportam filtragem de ferramentas para restringir quais ferramentas estão disponíveis:

• allowedTools: Whitelist - apenas as ferramentas especificadas estão disponíveis no servidor
• excludedTools: Blacklist - todas as ferramentas, exceto as especificadas, estão disponíveis

{
  "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 e excludedTools são mutuamente exclusivos - você só pode usar um por servidor.

Suporte a Configuração Legada

O MCPHost mantém compatibilidade total com versões anteriores do formato de configuração. Nota: Uma correção de bug recente melhorou a confiabilidade do 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/Container 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

O MCPHost suporta quatro tipos de transporte:

• stdio: Inicia um processo local e comunica via stdin/stdout (usado por servidores "local")
• sse: Conecta a um servidor usando Server-Sent Events (formato legado)
• streamable: Conecta a um servidor usando o protocolo Streamable HTTP (usado por servidores "remote")
• inprocess: Executa servidores integrados em processo para desempenho ideal (usado por servidores "builtin")

O esquema simplificado mapeia automaticamente:

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

Prompt do Sistema

Você pode especificar um prompt de sistema personalizado usando a flag --system-prompt. Você pode:

1. Passar o prompt diretamente como texto:

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

2. Passar um caminho para um arquivo de texto contendo o prompt:

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

   Exemplo de arquivo assistant.md:

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

Uso 🚀

O MCPHost é uma ferramenta CLI que permite interagir com vários modelos de IA por meio de uma interface unificada. Ele suporta várias ferramentas por meio de servidores MCP e pode ser executado em modos interativo e não interativo.

Modo Interativo (Padrão)

Inicie uma sessão de conversa interativa:

mcphost

Modo de Script

Execute scripts de automação executáveis baseados em YAML com suporte a substituição de variáveis:

# 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 do Script

Os scripts combinam configuração YAML com prompts em um único arquivo executável. A configuração deve ser envolvida em delimitadores de frontmatter (---). Você pode incluir o prompt na configuração YAML ou colocá-lo após o delimitador de frontmatter de fechamento:

#!/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
---

Ou, alternativamente, omita o campo prompt: e coloque o prompt após o 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

Substituição de Variáveis

Os scripts suportam tanto a substituição de variáveis de ambiente quanto a substituição de argumentos de script:

1. Variáveis de Ambiente: ${env://VAR} e ${env://VAR:-default} - Processadas primeiro
2. Argumentos de Script: ${variable} e ${variable:-default} - Processados após as variáveis de ambiente

As variáveis podem ser fornecidas via argumentos de linha de comando:

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

Sintaxe de Variáveis

O MCPHost suporta estas sintaxes de variáveis:

1. Variáveis de Ambiente Obrigatórias: ${env://VAR} - Devem ser definidas no ambiente
2. Variáveis de Ambiente Opcionais: ${env://VAR:-default} - Usa o padrão se não for definida
3. Argumentos de Script Obrigatórios: ${variable} - Devem ser fornecidos via --args:variable value
4. Argumentos de Script Opcionais: ${variable:-default} - Usa o padrão se não for fornecido

Exemplo de script com variáveis de ambiente e argumentos de script misturados:

#!/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.

Exemplos 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"

Recursos de Valores Padrão

• Padrões vazios: ${var:-} - Usa string vazia se não for fornecido
• Padrões complexos: ${path:-/tmp/default/path} - Suporta caminhos, URLs, etc.
• Espaços em padrões: ${msg:-Hello World} - Suporta espaços em valores padrão
• Compatibilidade retroativa: A sintaxe existente ${variable} continua funcionando sem alterações

Importante:

• Variáveis de ambiente sem padrão (ex.: ${env://GITHUB_TOKEN}) são obrigatórias e devem ser definidas no ambiente
• Argumentos de script sem padrão (ex.: ${username}) são obrigatórios e devem ser fornecidos via sintaxe --args:variable value
• Variáveis com padrão são opcionais e usarão seu valor padrão se não forem fornecidas
• Variáveis de ambiente são processadas primeiro, depois os argumentos de script

Recursos de Script

• Executável: Use a linha shebang para execução direta (#!/usr/bin/env -S mcphost script)
• Configuração YAML: Defina servidores MCP diretamente no script
• Prompts Incorporados: Inclua o prompt no YAML
• Substituição de Variáveis: Use a sintaxe ${variable} e ${variable:-default} com --args:variable value
• Validação de Variáveis: Variáveis obrigatórias ausentes fazem o script sair com erro útil
• Modo Interativo: Se o prompt estiver vazio, entra em modo interativo (útil para scripts de configuração)
• Fallback de Configuração: Se nenhum mcpServers for definido, usa a configuração padrão
• Filtragem de Ferramentas: Suporta allowedTools/excludedTools por servidor
• Saída Limpa: Sai automaticamente após a conclusão

Nota: A linha shebang requer env -S para lidar com o comando de múltiplas palavras mcphost script. Isso é suportado na maioria dos sistemas Unix-like modernos.

Exemplos de Script

Consulte examples/scripts/ para scripts de exemplo:

• example-script.sh - Script com servidores MCP personalizados
• simple-script.sh - Script usando fallback de configuração padrão

Sistema de Hooks

O MCPHost suporta um poderoso sistema de hooks que permite executar comandos personalizados em pontos específicos durante a execução. Isso possibilita políticas de segurança, registro de logs, integrações personalizadas e fluxos de trabalho automatizados.

Início Rápido

1. Inicialize uma configuração de hooks:

   mcphost hooks init
   

2. Visualize hooks ativos:

   mcphost hooks list
   

3. Valide sua configuração:

   mcphost hooks validate
   

Configuração

Os hooks são configurados em arquivos YAML com a seguinte precedência (da maior para a menor):

• .mcphost/hooks.yml (hooks específicos do projeto)
• $XDG_CONFIG_HOME/mcphost/hooks.yml (hooks globais do usuário, padrão para ~/.config/mcphost/hooks.yml)

Exemplo de configuração:

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 Disponíveis

• PreToolUse: Antes de qualquer execução de ferramenta (bash, fetch, todo, ferramentas MCP)
• PostToolUse: Após a conclusão da execução da ferramenta
• UserPromptSubmit: Quando o usuário envia um prompt
• Stop: Quando o agente termina de responder
• SubagentStop: Quando um subagente (ferramenta Task) termina
• Notification: Quando o MCPHost envia notificações

Segurança

⚠️ AVISO: Os hooks executam comandos arbitrários no seu sistema. Use apenas hooks de fontes confiáveis e sempre revise os comandos dos hooks antes de ativá-los.

Para desativar temporariamente todos os hooks, use o sinalizador --no-hooks:

mcphost --no-hooks

Consulte os scripts de hook de exemplo em examples/hooks/:

• bash-validator.py - Valida e bloqueia comandos bash perigosos
• prompt-logger.sh - Registra todos os prompts do usuário com carimbos de data/hora
• mcp-monitor.py - Monitora e aplica políticas no uso de ferramentas MCP

Modo Não Interativo

Execute um único prompt e saia - perfeito para scripts e automação:

# 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 Geração do Modelo

O MCPHost suporta ajuste fino do comportamento do modelo através de vários 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"

Esses parâmetros funcionam com todos os provedores suportados (OpenAI, Anthropic, Google, Ollama) onde suportados pelo modelo subjacente.

Modelos Disponíveis

Os modelos podem ser especificados usando o sinalizador --model (-m):

• Anthropic Claude (padrão): 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
• Compatível com OpenAI: Qualquer modelo via endpoint personalizado com --provider-url

Exemplos

Modo Interativo

# 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 Não Interativo

# 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:]'

Sinalizadores

• --provider-url string: URL base para a API do provedor (aplica-se a OpenAI, Anthropic, Ollama e Google)
• --provider-api-key string: Chave de API para o provedor (aplica-se a OpenAI, Anthropic e Google)
• --tls-skip-verify: Ignorar verificação de certificado TLS (AVISO: inseguro, use apenas para certificados autoassinados)
• --config string: Localização do arquivo de configuração (padrão é $HOME/.mcphost.yml)
• --system-prompt string: Localização do arquivo de prompt do sistema
• --debug: Ativar registro de depuração
• --max-steps int: Número máximo de etapas do agente (0 para ilimitado, padrão: 0)
• -m, --model string: Modelo a usar (formato: provedor/modelo) (padrão "anthropic/claude-sonnet-4-5-20250929")
• -p, --prompt string: Executar em modo não interativo com o prompt fornecido
• --quiet: Suprimir toda a saída exceto a resposta da IA (funciona apenas com --prompt)
• --compact: Ativar modo de saída compacta sem estilos sofisticados (ideal para scripts e automação)
• --stream: Ativar respostas em streaming (padrão: true, use --stream=false para desativar)

Subcomandos de Autenticação

• mcphost auth login anthropic: Autenticar com Anthropic usando OAuth (alternativa às chaves de API)
• mcphost auth logout anthropic: Remover credenciais OAuth armazenadas
• mcphost auth status: Mostrar status de autenticação

Nota: Credenciais OAuth (quando presentes) têm precedência sobre chaves de API de variáveis de ambiente e sinalizadores --provider-api-key.

Parâmetros de Geração do Modelo

• --max-tokens int: Número máximo de tokens na resposta (padrão: 4096)
• --temperature float32: Controla a aleatoriedade nas respostas (0.0-1.0, padrão: 0.7)
• --top-p float32: Controla a diversidade via amostragem de núcleo (0.0-1.0, padrão: 0.95)
• --top-k int32: Controla a diversidade limitando os K tokens principais para amostragem (padrão: 40)
• --stop-sequences strings: Sequências de parada personalizadas (separadas por vírgula)

Suporte a Arquivo de Configuração

Todos os sinalizadores de linha de comando podem ser configurados via arquivo de configuração. O MCPHost procurará a configuração nesta ordem:

1. ~/.mcphost.yml ou ~/.mcphost.json (preferido)
2. ~/.mcp.yml ou ~/.mcp.json (compatibilidade retroativa)

Exemplo de arquivo de configuração (~/.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: Sinalizadores de linha de comando têm precedência sobre valores do arquivo de configuração.

Comandos Interativos

Durante a conversa, você pode usar:

• /help: Mostrar comandos disponíveis
• /tools: Listar todas as ferramentas disponíveis
• /servers: Listar servidores MCP configurados
• /history: Exibir histórico da conversa
• /quit: Sair do aplicativo
• Ctrl+C: Sair a qualquer momento

Comandos de Autenticação

Autenticação OAuth opcional para Anthropic (alternativa às chaves de API):

• mcphost auth login anthropic: Autenticar usando OAuth
• mcphost auth logout anthropic: Remover credenciais OAuth armazenadas
• mcphost auth status: Mostrar status de autenticação

Sinalizadores Globais

• --config: Especificar localização personalizada do arquivo de configuração

Automação e Scripts 🤖

O modo não interativo do MCPHost o torna perfeito para automação, scripts e integração com outras ferramentas.

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

Integração 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

Processamento de Dados

# 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

Integração de API

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

Dicas para Scripts

• Use o sinalizador --quiet para obter saída limpa adequada para análise (apenas resposta da IA, sem interface)
• Use o sinalizador --compact para saída simplificada sem estilos sofisticados (quando quiser ver elementos da interface)
• Nota: --compact e --quiet são mutuamente exclusivos - --compact não tem efeito com --quiet
• Use variáveis de ambiente para dados sensíveis como chaves de API em vez de codificá-los
• Use a sintaxe ${env://VAR} em arquivos de configuração e scripts para substituição de variáveis de ambiente
• Combine com ferramentas Unix padrão (grep, awk, sed, etc.)
• Defina timeouts apropriados para operações de longa duração
• Trate erros adequadamente em seus scripts
• Use variáveis de ambiente para chaves de API em produção

Melhores Práticas para Variáveis de Ambiente

# 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

Compatibilidade com Servidores MCP 🔌

O MCPHost pode trabalhar com qualquer servidor compatível com MCP. Para exemplos e implementações de referência, consulte o Repositório de Servidores MCP.

Contribuindo 🤝

Contribuições são bem-vindas! Sinta-se à vontade para:

• Enviar relatórios de bugs ou solicitações de recursos através de issues
• Criar pull requests para melhorias
• Compartilhar seus servidores MCP personalizados
• Melhorar a documentação

Por favor, garanta que suas contribuições sigam boas práticas de codificação e incluam testes apropriados.

Licença 📄

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos 🙏

• Agradecimentos à equipe Anthropic por Claude e a especificação MCP
• Agradecimentos à equipe Ollama por seu runtime LLM local
• Agradecimentos a todos os contribuidores que ajudaram a melhorar esta ferramenta