Hoverfly MCP Server

Hoverfly MCP Server

Un servidor Model Context Protocol (MCP) basado en Spring Boot que expone Hoverfly como una herramienta programable para asistentes de IA como Cursor, Claude Desktop, GitHub Copilot, o cualquier otro asistente que soporte MCP. Permite el mockeo dinámico de APIs de terceros para desbloquear el desarrollo y las pruebas cuando los servicios externos no están disponibles.

---

🛠️ Instalación

Nota: Los siguientes requisitos previos y pasos de compilación solo son necesarios si deseas contribuir o compilar desde el código fuente. Para la mayoría de los usuarios, usar la imagen de Docker es suficiente.

Requisitos previos

• Java 17
• Maven 3.6+

Compilar y ejecutar

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

Reemplaza <version> con la versión real del JAR que compilaste.

---

⚙️ Configuración como servidor MCP (con Docker)

Para usar este servidor con un asistente de IA que soporte Model Context Protocol (MCP), agrega lo siguiente a tu .mcp.json o 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: puerto proxy de Hoverfly (servicios simulados)
• 8888: puerto de administración de Hoverfly (API de control de simulaciones)
• -v /path/to/your/data:/opt/hoverfly-mcp/simulation-data: Monta un volumen para la persistencia de simulaciones

Asegúrate de que Docker esté instalado. La imagen se descargará automáticamente si no está disponible localmente.

---

🔧 Herramientas MCP expuestas

Nombre de la herramienta	Descripción
get_hoverfly_status	Comprueba si Hoverfly está en ejecución
start_hoverfly_web_server	Inicia Hoverfly en modo simulación como servidor web. Por defecto, cargará automáticamente la simulación más reciente desde /opt/hoverfly-mcp/simulation-data si está disponible, a menos que la carga automática esté deshabilitada.
stop_hoverfly_server	Detiene Hoverfly y limpia las simulaciones
fetch_hoverfly_version	Devuelve la versión de Hoverfly
list_hoverfly_mocks	Lista todas las APIs simuladas activas (pares solicitud-respuesta)
add_hoverfly_mock	Agrega una API simulada usando una definición JSON de RequestResponsePair
clear_hoverfly_mocks	Elimina todas las APIs simuladas existentes
show_hoverfly_endpoints_info	Devuelve los endpoints clave de Hoverfly y ejemplos de uso
get_hoverfly_documentation	Devuelve la documentación de Hoverfly para un tema específico
suggest_hoverfly_matchers	Sugiere opciones de coincidencia para un JSON de par solicitud-respuesta dado
get_hoverfly_debug_logs	Obtiene los registros recientes de Hoverfly para depuración (el límite es opcional)
download_hoverfly_simulation	Descarga la simulación actual a /opt/hoverfly-mcp/simulation-data (directorio de simulación persistente)

Estas herramientas pueden ser invocadas programáticamente por asistentes de IA a través del host del asistente de IA.

---

💾 Persistencia de simulaciones

El servidor soporta la persistencia de simulaciones a través de un volumen fijo montado:

Carga automática al inicio

Al iniciar Hoverfly con start_hoverfly_web_server, el servidor por defecto:

• Cargará el archivo de simulación más reciente desde /opt/hoverfly-mcp/simulation-data (si está disponible)
• Iniciará con un estado limpio si no se encuentra ningún archivo de simulación

Puedes deshabilitar la carga automática configurando el parámetro adecuado.

Datos persistentes y montaje de volúmenes

Para persistir los datos de simulación entre reinicios, debes montar un directorio del host en /opt/hoverfly-mcp/simulation-data dentro del contenedor.
Esta es la única ubicación compatible para datos persistentes.

Nota: El directorio del host debe ser escribible por el usuario del contenedor.

Los archivos de simulación solo se guardan en este directorio cuando invocas explícitamente la herramienta de descarga.

🤝 Contribuciones

1. Haz un fork de este repositorio
2. Crea una rama de características
3. Envía un Pull Request

---

📜 Licencia

Consulta el archivo LICENSE para conocer los términos de licencia.