<div align="center"> <img src="./HoverflyMCPServer.png" alt="Hoverfly MCP Server Logo" width="240"/> </div>

Hoverfly MCP Server

一个基于Spring Boot的模型上下文协议（MCP）服务器，它将Hoverfly作为可编程工具提供给像Cursor、Claude Desktop、GitHub Copilot或其他支持MCP的助手。它能够动态模拟第三方API，以便在外部服务不可用时解除开发和测试的阻塞。

---

🛠️ 安装

注意： 下列前置条件和构建步骤仅在您希望贡献或从源码构建时需要。对于大多数用户来说，使用Docker镜像就足够了。

前置条件

• Java 17
• Maven 3.6+

构建与运行

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

将<version>替换为您实际构建的JAR版本。

---

⚙️ 配置为MCP服务器（使用Docker）

要将此服务器与支持模型上下文协议（MCP）的AI助手一起使用，请在您的.mcp.json或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: Hoverfly代理端口（模拟的服务）
• 8888: Hoverfly管理端口（模拟控制API）
• -v /path/to/your/data:/opt/hoverfly-mcp/simulation-data: 挂载卷以持久化模拟数据

确保已安装Docker。如果本地没有该镜像，将会自动拉取。

---

🔧 暴露的MCP工具

工具名称	描述
get_hoverfly_status	检查Hoverfly是否正在运行
start_hoverfly_web_server	在模拟模式下启动Hoverfly作为Web服务器。默认情况下，如果有可用的最新模拟文件，它会自动加载来自/opt/hoverfly-mcp/simulation-data的模拟文件，除非禁用了自动加载。
stop_hoverfly_server	停止Hoverfly并清除模拟
fetch_hoverfly_version	返回Hoverfly版本
list_hoverfly_mocks	列出所有活跃的模拟API（请求-响应对）
add_hoverfly_mock	使用JSON RequestResponsePair定义添加模拟API
clear_hoverfly_mocks	移除所有现有的模拟API
show_hoverfly_endpoints_info	返回关键Hoverfly端点及其示例用法
get_hoverfly_documentation	返回特定主题的Hoverfly文档
suggest_hoverfly_matchers	为给定的请求-响应对JSON建议匹配器选项
get_hoverfly_debug_logs	获取最近的Hoverfly调试日志（可选限制）
download_hoverfly_simulation	将当前模拟下载到/opt/hoverfly-mcp/simulation-data（持久化模拟目录）

这些工具可以通过AI助手主机程序化地调用。

---

💾 模拟持久化

服务器通过固定挂载的卷支持模拟持久化：

启动时自动加载

当使用start_hoverfly_web_server启动Hoverfly时，默认情况下：

• 加载/opt/hoverfly-mcp/simulation-data中的最新模拟文件（如果存在）
• 如果未找到模拟文件，则以干净状态启动

您可以设置相应的参数来禁用自动加载。

持久化数据和卷挂载

为了跨重启持久化模拟数据，您必须将主机目录挂载到容器内的/opt/hoverfly-mcp/simulation-data。 这是唯一支持的持久化数据位置。

注意： 主机目录必须由容器用户可写。

只有在显式调用下载工具时，模拟文件才会保存到此目录。

🤝 贡献

1. 分叉此仓库
2. 创建一个特性分支
3. 提交Pull Request

---

📜 许可证

查看LICENSE文件获取许可条款。