AI导哈

MCP服务器自愈代理

Hydra是一个为AI辅助开发设计的MCP服务器故障容忍代理，能够在服务器崩溃时保持AI会话连接，实现快速重启和状态恢复。

  • by proxikal
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 proxikal/hydra-mcp

使用说明

九头蛇：自愈MCP监督员

“砍掉一个头，再砍两个头。”

Hydra是一个容错的 主管和代理人 用于模型上下文协议（MCP）服务器。它是专门为 人工智能辅助开发，确保崩溃、语法错误和“嘈杂”日志永远不会中断AI Agent（Claude、Gemini等）和开发服务器之间的连接。

🛑 问题

当AI代理为MCP服务器编写代码时（例如，向Python脚本添加工具）：

  1. AI保存文件。
  2. 服务器因语法错误而崩溃。
  3. 连接已死。 AI失去了会话上下文、历史和修复错误的能力。
  4. 钱包流血了。 您支付代币以向AI重新解释上下文。

🐉 Hydra解决方案

Hydra位于AI客户端和MCP服务器之间。它 永不消逝，即使子服务器这样做。

graph LR
    AI["AI Agent"] <-->|"Stdio (Safe)"| Hydra["Hydra Proxy"]
    Hydra <-->|"Stdio (Raw)"| Child["MCP Server"]
    
    style Hydra fill:#e6fffa,stroke:#2c7a7b,stroke-width:2px,color:#234e52
    style Child fill:#fff5f5,stroke:#e53e3e,stroke-width:2px,stroke-dasharray: 5 5,color:#742a2a
    style AI fill:#ebf8ff,stroke:#3182ce,stroke-width:2px,color:#2c5282

核心能力

  • 🛡️ 会话持久性： AI会话在服务器崩溃后幸存下来。Hydra将错误报告为JSON-RPC消息，允许AI读取堆栈跟踪并修复代码 没有 断开连接。
  • 🔇 标准消毒： Hydra过滤器 stdout。如果您的服务器打印 console.log("Debug") 或者对原始堆栈跟踪感到恐慌，Hydra会捕获它，将其封装在日志消息中，并防止它损坏JSON-RPC管道。
  • ⚡ 乐观热重载： 文件保存后立即重新启动服务器（<500ms）。无“飞行前”检查；崩溃 是 反馈。
  • 🧠 会话状态跟踪： 当服务器重新启动时，Hydra会保留并可以回放：
    • initialize 请求（自动）
    • resources/subscribe 请求（跟踪的订阅）
  • 💰 钱包保护： 防止象征性炸弹。
    • 将工具输出限制在50KB，以防止意外转储。
    • 速率限制日志消息（最大10/秒）。
    • 可配置的大小限制和编辑模式。
  • 📊 适应性学习： 监控服务器运行状况（0-100分），并根据观察到的模式建议配置优化。
  • 💾 状态持久性： 指标和会话状态保存到 ~/.hydra/state/ 用于恢复和分析。
  • 📈 普罗米修斯出口： 用于监控仪表板和警报的可选指标端点。

✨ 为什么是九头蛇？

在九头蛇之前：

AI: "Let me add that new tool..."
[Server crashes due to syntax error]
AI: "I've lost the connection. Can you tell me what we were working on?"
You: [Re-explaining everything, burning tokens]

九头蛇：

AI: "Let me add that new tool..."
[Server crashes]
Hydra: "Server crashed with SyntaxError on line 42. Restarted in 320ms."
AI: "I see the issue - missing comma. Let me fix that..."
[No context lost, no reconnection needed]

区别： Hydra使AI会话保持活力，将崩溃转化为 调试消息 而不是 切断.

运作原理

  1. AI客户端连接到Hydra （不直接发送到您的服务器）
  2. Hydra生成您的服务器 作为一个孩子的过程
  3. 所有MCP消息都通过Hydra传输 （透明代理）
  4. Hydra捕获会话状态 （工具、订阅、文件状态）
  5. 服务器崩溃？ 九头蛇：
    • 保持AI连接活跃
    • 重新启动服务器（<500ms）
    • 回放会话状态
    • 将错误作为JSON-RPC日志消息转发
  6. AI读取错误并修复代码 -没有上下文丢失

🚀 入门指南

安装

来源：

git clone https://github.com/proxikal/hydra.git
cd hydra
go build -o bin/hydra cmd/hydra/main.go
sudo mv bin/hydra /usr/local/bin/

或使用Make：

git clone https://github.com/proxikal/hydra.git
cd hydra
make install

验证安装：

hydra --version

注： Homebrew安装将在v1.0版本中发布

快速开始

1.为您的AI客户端初始化Hydra

hydra init --client claude
# Follow prompts to select which MCP servers to supervise

这将创建/更新您的Claude Desktop配置，以通过Hydra路由服务器。

2.启动受监控的服务器

hydra run --name my-python-server

3.检查状态

hydra status my-python-server

4.查看日志

hydra logs my-python-server --follow

5.手动重启（如需要）

hydra restart my-python-server

真实世界示例

脚本： 您正在构建一个Python MCP服务器，并希望在开发过程中进行热重新加载。

第一步： 将您的服务器添加到Hydra

hydra add my-tools \
  --command python3 \
  --args server.py \
  --cwd ~/projects/my-mcp-server \
  --watch-path ~/projects/my-mcp-server \
  --watch-ext .py

第二步： 配置Claude Desktop以使用Hydra

hydra init --client claude
# Select "my-tools" from the list

步骤3： 开始编码

  • 编辑 server.py 并保存
  • Hydra检测到变化并重新启动（<500ms）
  • Claude桌面会话保持活动状态
  • 你看到克劳德的错误，立即修复
  • 无需手动重启，无需重新连接

检查服务器运行状况：

$ hydra inspect my-tools

Server: my-tools
Health: 95/100 ✓
Uptime: 2h 15m
Requests: 247 (245 success, 2 failed)
Latency: P50=42ms, P95=118ms
Restarts: 12 (11 file_change, 1 crash)

配置

Hydra使用两层配置系统：

全局注册表： ~/.hydra/config.json

{
  "servers": {
    "my-python-server": {
      "command": "python",
      "args": ["server.py"],
      "env_file": ".env",
      "watch": {
        "paths": ["./src"],
        "ignore_files": [".gitignore"]
      },
      "max_restarts": 5,
      "restart_window_seconds": 60
    }
  }
}

本地覆盖（可选）： ./hydra.json

{
  "watch": {
    "paths": ["./src", "./lib"]
  }
}

看 docs/CONFIGURATION.md 对于完整模式。

🛠️ 建筑

九头蛇的设计严格 人工智能原生 原则：

  1. 运输不可知： 自动检测 Content-Length 头文件（LSP样式）与NDJSON。
  2. 跨平台： 使用强大的进程组管理（Tree Kill）来处理Windows、Linux和macOS上的僵尸。
  3. 可注射工具： Hydra将自己的工具注入MCP会话：
    • hydra_restart：AI可以手动触发重启。
    • hydra_logs：AI可以读取最后50行 stderr.
    • hydra_status：检查主管的健康状况（包括健康评分）。
    • hydra_force_restart：覆盖碰撞回路保护。
  4. 健康监测： 5个维度的实时健康评分（0-100）：
    • 正常运行时间稳定性（30%）
    • 错误率（25%）
    • 响应延迟（20%）
    • 队列深度（15%）
    • 重启频率（10%）
  5. 适应性学习： 分析运行时模式并提出配置优化建议（例如，调整 max_restarts, queue_size, debounce_ms).

🗺️ 项目状态

所有实施阶段均已完成：

  • ✅ 第一阶段：基础 -运输、配置、消毒器
  • ✅ 第二阶段：核心逻辑 -主管、StateStore、观察者
  • ✅ 第3阶段：编排 -代理、工具注入、流量记录器
  • ✅ 第4阶段：CLI -命令，Bootstrap
  • ✅ 第5阶段：硬化 -混沌测试，基准

当前版本： 测试版（接近v1.0）

v1.0路线图

  • [x] 使用Claude Desktop进行真实世界验证
  • [x] 综合测试套件（35个集成测试，共325+个）
  • [x] 状态持久性和度量系统
  • [x] 适应性学习和健康评分
  • [x] 文件（11份指南中6200多行）
  • []生产工作负载的性能验证
  • []社区反馈和错误修复
  • []Homebrew安装包

⚡ 演出

Hydra的设计旨在将开销降至最低：

度量 目标 实际
代理延迟（P50） <50ms 0.053ms
代理延迟（P99） <200ms 0.141ms
重启时间（P50） <500ms 101ms
内存（1000次重启） <100MB 无泄漏（GC稳定）
CPU（空闲） <1% <0.5%

自适应学习开销： 可忽略不计（<1MB RAM）

看 docs/BENCHARK_RESULTS.md 进行详细的性能分析。

🆘 故障排除

服务器无法启动：

# Check Hydra logs
hydra logs my-server --follow

# Verify config is valid
cat ~/.hydra/config.json | jq .

健康评分低：

# Get detailed breakdown
hydra inspect my-server

# Check what's failing (uptime, latency, errors, etc.)
# Adjust config accordingly

会话仍然在崩溃时死亡：

  • 确保您正在使用 hydra run，不直接运行服务器
  • 通过Hydra检查Claude Desktop配置路由
  • 配置更改后重新启动Claude Desktop

看 测试/验证/VALIDATA_GUIDE.md 获取全面的测试说明。

🤝 贡献

我们欢迎捐款！请参阅 贡献.md 作为指导方针。

关键标准：

  • 不 fmt.Println 生产代码（使用 internal/logger)
  • 接口优先模式（所有组件）
  • 文件<250行（罕见复杂性时最多300行）
  • 80%+测试覆盖率
  • TDD强制性

发展：

git clone https://github.com/proxikal/hydra.git
cd hydra
make test        # Run tests
make lint        # Lint code
make coverage    # Check coverage

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

📚 文档

🙏 致谢

内置于❤️ MCP社区。

特别感谢所有帮助Hydra生产准备就绪的贡献者。

相关 MCP