Como adicionar uma extensão MCP de resolvedor de CAPTCHA ao Goose

Resumo rápido

• Adicione um resolvedor de CAPTCHA ao Goose como uma extensão MCP local usando o servidor oficial em Python.
• Informe ao Goose o caminho absoluto para o ambiente Python que contém o servidor; um pacote instalado em outro ambiente não será encontrado automaticamente.
• Comece com get_supported_captchas como a única ferramenta disponível e então inspecione o menu de ferramentas do Goose para confirmar a conexão.
• O Goose exibe a ferramenta selecionada como capsolver__get_supported_captchas quando a extensão se chama capsolver.
• Uma conexão de extensão funcionando não significa que uma tarefa de CAPTCHA paga ou um fluxo de trabalho de navegador tenha sido concluído.

Goose é um agente de IA open source para desenvolvedores que pode trabalhar com ferramentas externas por meio de extensões MCP. Uma extensão de resolvedor de CAPTCHA do Goose adiciona uma capacidade específica: acesso às operações documentadas do resolvedor a partir do agente que você já usa. Isso é útil quando você está adicionando tratamento de CAPTCHA a uma tarefa de navegador autorizada e precisa estabelecer que o Goose realmente consegue encontrar as ferramentas necessárias.

A CapSolver fornece o servidor MCP usado abaixo. O guia se concentra na instalação, na configuração do Goose e em uma verificação de conexão que não envia um CAPTCHA. Ele também explica o que você precisa adicionar antes de usar as ferramentas de resolução. Você pode concluir a configuração sem escrever um servidor MCP personalizado ou um adaptador de framework.

O que a extensão de CAPTCHA do Goose adiciona?

A extensão de CAPTCHA do Goose expõe as ferramentas do servidor oficial por meio do suporte MCP já existente no Goose. O Goose continua sendo o cliente agente; o processo Python fornece as operações de CAPTCHA. O guia de extensões do Goose oferece suporte a servidores MCP personalizados mesmo quando eles não estão listados em seu diretório de extensões.

Essa distinção é importante se você já tiver uma ferramenta de navegador conectada. Uma ferramenta de navegador controla sua própria sessão de navegador, enquanto uma ferramenta de resolução executa a operação descrita pelo seu schema de entrada. Instalar o resolvedor não o acopla automaticamente a uma aba do Chrome aberta nem transfere o estado da página de outra extensão.

A referência oficial de ferramentas MCP distingue a resolução orientada a token das ferramentas de navegador baseadas em URL. Escolha a interface que corresponde ao seu fluxo de trabalho existente. Para esta primeira configuração, use a consulta de tipos suportados: ela verifica as capacidades anunciadas pelo servidor sem criar uma tarefa de desafio paga.

Prepare o Goose e o servidor em Python

Prepare um Goose CLI instalado e um ambiente Python separado para o servidor MCP. Use Python 3.10 ou mais recente; o pacote MCP fixado exige isso. A configuração abaixo foi verificada com Goose 1.55.0, Python 3.12.14, capsolver-mcp 0.1.3 e capsolver-core 0.1.1 no macOS. Essas versões identificam a combinação testada; não são uma promessa de que todas as versões posteriores se comportem de forma idêntica.

Se o Goose é novo para você, use as instruções oficiais de instalação para o seu sistema operacional e configure um provedor de modelo. A inspeção de permissões de ferramenta usada mais adiante espera que o Goose tenha um provedor e um modelo selecionados. A configuração de provedor é separada de uma chave de conta CapSolver.

Instale o resolvedor em um único ambiente

Em um diretório de projeto novo no macOS ou Linux, execute:

python3 -m venv py
py/bin/python -m pip install capsolver-core==0.1.1 capsolver-mcp==0.1.3
py/bin/python -c 'import sys; print(sys.executable)'

Guarde o caminho do interpretador impresso pelo último comando. O Goose iniciará esse interpretador diretamente, para que o servidor possa usar os pacotes que você acabou de instalar. Isso evita uma falha comum em que o terminal usa um ambiente virtual, mas o agente inicia uma instalação diferente de Python.

A instalação básica é suficiente para a verificação de conexão deste artigo. As ferramentas baseadas em navegador do servidor têm dependências adicionais; instalar apenas o pacote base não prepara o Chromium. Não é necessário instalar um navegador apenas para inspecionar a ferramenta de tipos suportados.

Encontre a configuração que o Goose realmente usa

Execute o comando a seguir para localizar a configuração do Goose:

goose info

Use o caminho de configuração exibido pela sua instalação. O local padrão e qualquer substituição de caminho configurada podem ser diferentes, então verificar o CLI em execução é mais confiável do que presumir um local. Preserve suas configurações existentes de provedor e outras extensões ao editar o arquivo.

Adicione o servidor de CAPTCHA à configuração do Goose

Adicione o servidor sob o mapeamento extensions existente no arquivo YAML de configuração do Goose. Não cole uma segunda chave de nível superior extensions em um arquivo que já contém uma.

Substitua o caminho de interpretador de exemplo abaixo pelo caminho absoluto impresso durante a instalação. Este é um modelo de configuração; o caminho é o único valor de máquina local que você precisa substituir para a verificação inicial de descoberta.

extensions:
  capsolver:
    name: capsolver
    type: stdio
    enabled: true
    cmd: /absolute/path/to/project/py/bin/python
    args: ["-m", "capsolver_mcp"]
    envs:
      CAPSOLVER_API_KEY: ""
    env_keys: []
    timeout: 60
    available_tools: ["get_supported_captchas"]

A chave de conta vazia é intencional para esta verificação inicial. A ferramenta de tipos suportados não exige uma solicitação de resolução paga. Um valor vazio não é uma credencial utilizável para operações pagas.

A referência de configuração do Goose documenta stdio, cmd, args e available_tools. Aqui, stdio significa que o Goose inicia o processo local e troca mensagens MCP por sua entrada e saída padrão. Você não precisa expor uma porta de rede.

Entenda o filtro de ferramentas

A entrada available_tools torna apenas get_supported_captchas disponível a partir dessa extensão. No Goose, uma lista vazia significa todas as ferramentas, então apagar o nome deixando [] amplia o conjunto de ferramentas disponíveis.

Mantenha o filtro inicial restrito enquanto confirma que o interpretador e o servidor são iniciados corretamente. Quando tiver uma conexão funcionando, ajuste a lista para a operação específica de que seu fluxo de trabalho precisa. Use os nomes de ferramenta remotos da referência oficial em vez de adivinhar a partir de um rótulo em outro cliente.

O timeout é expresso em segundos. O valor de 60 segundos do exemplo é uma escolha de configuração para a verificação de instalação, não um tempo medido de resolução de CAPTCHA nem uma garantia do serviço.

Verifique se o Goose descobre a ferramenta de CAPTCHA

Verifique a descoberta pelo menu de permissões de ferramentas do Goose antes de pedir ao agente para executar uma tarefa de navegador. Execute:

goose configure

Selecione goose settings → Tool Permission → capsolver. O Goose se conecta à extensão configurada e apresenta suas ferramentas. Com o filtro acima, o menu deve conter capsolver__get_supported_captchas, descrita como listando os tipos de CAPTCHA suportados pela instância.

Essa entrada com namespace apareceu na verificação de conexão real do Goose para este guia. O sublinhado duplo separa o nome da extensão configurada do nome da ferramenta do servidor. O filtro YAML usa get_supported_captchas; o menu do Goose exibe capsolver__get_supported_captchas.

Você pode cancelar no menu de seleção de ferramenta após inspecionar a entrada. Visualizar a ferramenta descoberta não exige alterar sua permissão. Os controles de permissões de ferramenta do Goose permitem decidir separadamente como um agente pode invocá-la.

Se a ferramenta estiver ausente, corrija a descoberta antes de adicionar um prompt longo ou uma URL de destino. Um modelo não pode chamar uma ferramenta que o cliente não carregou. Também reinicie ou reconecte após mudar configurações de extensão; uma configuração salva para novas sessões pode não alterar as ferramentas em uma conversa existente.

Resgate seu código de bônus CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para obter 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Painel CapSolver

Passe da descoberta de ferramenta para uma tarefa de CAPTCHA

Passe para uma tarefa de CAPTCHA somente após escolher a operação e preparar suas entradas documentadas. A verificação de conexão estabelece que o Goose consegue carregar o servidor MCP real e descobrir a ferramenta filtrada. Ela não testa seleção de modelo, resolução paga ou conclusão de página.

Com um provedor de modelo funcionando, um próximo pedido útil é: “Use a ferramenta de tipos suportados da extensão de CAPTCHA e resuma suas capacidades retornadas. Não envie uma tarefa de resolução.” Este é um prompt de acompanhamento sugerido, não uma afirmação de que uma chamada dirigida por modelo foi executada para este guia. Inspecione a invocação da ferramenta e seus dados retornados em vez de aceitar apenas uma resposta conversacional.

Para um fluxo orientado a token, habilite solve_captcha quando estiver pronto para fornecer o tipo de CAPTCHA suportado e os parâmetros de site exigidos. Configure uma chave de conta válida nas configurações de ambiente da extensão e mantenha os controles normais de aprovação para chamadas de ferramenta. Mantenha credenciais reais fora de exemplos de configuração compartilhados e de controle de versão.

Para detect_captchas ou solve_on_page, siga primeiro as etapas de instalação de extras de navegador e Chromium na referência oficial de ferramentas. Essas operações aceitam uma URL de página; elas não reutilizam automaticamente a sessão de navegador possuída por uma extensão diferente do Goose. Essa fronteira de sessão é especialmente importante para uma página cujo estado de formulário já foi alterado.

A interface de página do SDK core é uma superfície de integração separada a ser examinada quando sua aplicação precisa trabalhar com um objeto de página que já controla. Escolha com base nesse requisito concreto em vez de presumir que todas as ferramentas MCP de navegador compartilham uma aba.

Uma chamada de API e uma ação de aplicação concluída são resultados distintos. Quando você eventualmente testar um fluxo de trabalho de CAPTCHA autorizado, verifique a resposta do resolvedor e então o resultado esperado na página. Mantenha a verificação de configuração deste artigo separada desse teste de aceitação de aplicação.

Corrija problemas comuns de configuração de extensão no Goose

Corrija problemas de configuração na etapa que está falhando: inicialização do interpretador, importação de pacote, descoberta de ferramenta ou a chamada de tarefa posterior. As verificações a seguir geralmente tornam a falha mais fácil de localizar.

Não substitua uma configuração local stdio funcionando por um endpoint HTTP arbitrário para resolver um erro de importação. O comando de inicialização e o ambiente do pacote são as verificações relevantes. O tutorial oficial de instalação pelo registry fornece contexto adicional para localizar e iniciar o pacote suportado.

Ao pedir ajuda, registre a versão do Goose, a versão do Python, as versões dos pacotes e a etapa que falhou. Um caminho de inicialização e mensagem de erro redigidos são mais úteis do que uma captura de tela contendo uma chave de API. Evite reenviar tarefas pagas apenas para determinar se a extensão está instalada.

Mantenha o próximo passo ligado à sua tarefa de navegador

Mantenha o próximo passo focado na operação de CAPTCHA de que sua aplicação realmente precisa. Uma entrada de ferramenta visível oferece um ponto de partida verificado; ela não substitui um teste com as entradas corretas, credenciais, estado de navegador e asserção final da aplicação.

Use a CapSolver para essa etapa específica de resolução e mantenha claro o papel do Goose: descobrir a ferramenta, solicitar a operação permitida e inspecionar seu resultado. Prepare sua conta pelo painel da CapSolver quando estiver pronto para um teste de resolução separado em um fluxo de trabalho que você possua ou esteja autorizado a operar.

FAQ

P: Posso adicionar este servidor se ele estiver ausente do diretório de extensões do Goose?

Sim. O Goose oferece suporte a extensões MCP personalizadas. A configuração local stdio aponta o Goose para o servidor Python oficial instalado.

P: Uma chave CapSolver é obrigatória para a verificação de descoberta?

Não. O exemplo carrega a ferramenta de tipos suportados com uma chave vazia. Operações de CAPTCHA pagas precisam de uma chave de conta válida e dos insumos de tarefa exigidos.

P: Por que o Goose mostra um sublinhado duplo no nome da ferramenta?

O Goose prefixa a ferramenta remota com o nome da extensão. Nesta configuração, capsolver e get_supported_captchas produzem capsolver__get_supported_captchas.

P: Por que as ferramentas de resolução estão ausentes?

O exemplo seleciona deliberadamente apenas get_supported_captchas. Atualize available_tools para os nomes de ferramenta documentados necessários quando estiver pronto para testar essas operações.

P: Esta extensão vai assumir minha aba de navegador existente?

Não. Nenhuma transferência automática é estabelecida por esta configuração. Verifique as entradas da ferramenta escolhida e o comportamento de sessão de navegador antes de combiná-la com outra extensão de navegador ou aplicação.

P: Ver a ferramenta prova que a resolução de CAPTCHA funciona?

Não. Isso apenas verifica a conexão cliente-servidor e a descoberta. Uma resolução paga e o resultado na aplicação exigem testes separados com credenciais válidas e as entradas corretas de fluxo de trabalho.