Hoverfly MCP Server

Hoverfly MCP Server

Um servidor Model Context Protocol (MCP) baseado em Spring Boot que expõe o Hoverfly como uma ferramenta programável para assistentes de IA como Cursor, Claude Desktop, GitHub Copilot ou qualquer outro assistente que suporte MCP. Ele permite a simulação dinâmica de APIs de terceiros para desbloquear o desenvolvimento e os testes quando serviços externos estão indisponíveis.

---

🛠️ Instalação

Nota: Os pré-requisitos e as etapas de build a seguir são necessários apenas se você quiser contribuir ou compilar a partir do código-fonte. Para a maioria dos usuários, usar a imagem Docker é suficiente.

Pré-requisitos

• Java 17
• Maven 3.6+

Build e Execução

git clone <repository-url>
cd hoverfly-mcp-server
mvn clean package
java -jar target/hoverfly-mcp-server-<version>.jar

Substitua <version> pela versão real do JAR que você compilou.

---

⚙️ Configuração como Servidor MCP (com Docker)

Para usar este servidor com um assistente de IA que suporte Model Context Protocol (MCP), adicione o seguinte ao seu .mcp.json ou mcp.config.json:

{
  "mcpServers": {
    "hoverfly-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p 8500:8500",
        "-p 8888:8888",
        "-v /path/to/your/data:/opt/hoverfly-mcp/simulation-data",
        "docker.io/kapish88/hoverfly-mcp-server"
      ]
    }
  }
}

• 8500: Porta do proxy Hoverfly (serviços simulados)
• 8888: Porta administrativa do Hoverfly (API de controle de simulação)
• -v /path/to/your/data:/opt/hoverfly-mcp/simulation-data: Monte um volume para persistência da simulação

Certifique-se de que o Docker esteja instalado. A imagem será baixada automaticamente se não estiver disponível localmente.

---

🔧 Ferramentas MCP Expostas

Nome da Ferramenta	Descrição
get_hoverfly_status	Verifica se o Hoverfly está em execução
start_hoverfly_web_server	Inicia o Hoverfly no modo simulação como um servidor web. Por padrão, ele carrega automaticamente a simulação mais recente de /opt/hoverfly-mcp/simulation-data se disponível, a menos que o carregamento automático esteja desabilitado.
stop_hoverfly_server	Para o Hoverfly e limpa as simulações
fetch_hoverfly_version	Retorna a versão do Hoverfly
list_hoverfly_mocks	Lista todas as APIs simuladas ativas (pares de requisição-resposta)
add_hoverfly_mock	Adiciona uma API simulada usando uma definição JSON de RequestResponsePair
clear_hoverfly_mocks	Remove todas as APIs simuladas existentes
show_hoverfly_endpoints_info	Retorna os principais endpoints do Hoverfly e exemplos de uso
get_hoverfly_documentation	Retorna a documentação do Hoverfly para um tópico específico
suggest_hoverfly_matchers	Sugere opções de correspondência para um JSON de par requisição-resposta
get_hoverfly_debug_logs	Busca logs recentes do Hoverfly para depuração (o limite é opcional)
download_hoverfly_simulation	Baixa a simulação atual para /opt/hoverfly-mcp/simulation-data (diretório de simulação persistente)

Essas ferramentas podem ser invocadas programaticamente por assistentes de IA por meio do host do Assistente de IA.

---

💾 Persistência da Simulação

O servidor suporta persistência de simulação por meio de um volume fixo e montado:

Carregamento Automático na Inicialização

Ao iniciar o Hoverfly com start_hoverfly_web_server, o servidor, por padrão:

• Carrega o arquivo de simulação mais recente de /opt/hoverfly-mcp/simulation-data (se disponível)
• Inicia com um estado limpo se nenhum arquivo de simulação for encontrado

Você pode desabilitar o carregamento automático definindo o parâmetro apropriado.

Dados Persistentes e Montagem de Volume

Para persistir os dados da simulação entre reinicializações, você deve montar um diretório do host em /opt/hoverfly-mcp/simulation-data dentro do contêiner.
Este é o único local suportado para dados persistentes.

Nota: O diretório do host deve ser gravável pelo usuário do contêiner.

Os arquivos de simulação são salvos apenas neste diretório quando você invoca explicitamente a ferramenta de download.

🤝 Contribuindo

1. Faça um fork deste repositório
2. Crie um branch de funcionalidade
3. Envie um Pull Request

---

📜 Licença

Consulte o arquivo LICENSE para os termos de licenciamento.