Vivekpatil200320/CyberRescue

**Give Claude eyes and hands inside your broken Docker containers.**
---
📺 Live Triage Demonstration (33s)
https://github.com/user-attachments/assets/0ee0f583-b8c1-4abe-9dd4-4b59ec25fd49
---
Overview
A locally-hosted MCP (Model Context Protocol) server that gives Claude real tools to debug Docker containers — fetch logs, inspect memory/CPU, and run diagnostic commands inside a container, all from a chat with Claude Desktop. Instead of writing bespoke glue code for every diagnostic endpoint you want an AI agent to reach (logs API, stats API, exec API, each with its own auth, sanitization, and error handling), CyberRescue exposes them once through MCP: register the server, and any MCP-capable client gets all three capabilities with validation, retry, and output caps already handled.
Results
- **Per-endpoint integration time cut from ~2 hours to under 30 minutes.** Wiring an agent to a new container-diagnostic capability previously meant hand-rolling the client call, input validation, output truncation, and failure handling. With the MCP tool pattern established here (validate → semaphore-gated daemon call → retry with back-off → sanitized errors → capped output), adding an endpoint is a single decorated function.
- **42 passing unit tests** (30 for the core MCP server/security/retry logic, 12 for the public demo backend) covering input validation, command-safety blocklists, retry behavior, and the public-demo allowlist — run on every push via GitHub Actions CI.
- Verified **A-Grade Quality** on Glama and listed on global MCP indexes.
Live Demo
*(Link goes here once deployed — backend setup: infra/README.md; frontend: deploy web/ to Vercel with its root directory set to web/.)*
A public demo of the real tool running against 3 intentionally broken sandboxed containers
(broken-flask, leaking-node, crashed-nginx). It's the same stream_container_logs /
inspect_memory_dump /
execute_isolated_script logic used by the local MCP server, exposed over a small FastAPI
backend that's locked to those 3 containers with a fixed diagnostic-command menu (no arbitrary
containers, no freeform shell input) — see SECURITY.md for the
full threat model. The local MCP path (this README, below) and the public demo are two
different deployment contexts sharing one core (src/cyberrescue/core.py).
What it does
CyberRescue exposes three tools to Claude:
- **stream_container_logs** — fetch stdout/stderr logs from a container by ID or name (tail, since-timestamp, keyword filter; 50KB hard cap with truncation flag).
- **inspect_memory_dump** — live CPU/memory snapshot via docker stats, plus top processes via ps aux --sort=-%mem.
- **execute_isolated_script** — run a shell command inside a container via docker exec, with input validation, a command blocklist, and a hard asyncio timeout.
Everything runs locally over stdio — no network ports, no cloud service, no API keys beyond what you already use for Claude Desktop.
Architecture
Read-only telemetry calls (logs, stats) retry up to 3 times with exponential back-off (0.5s → 1s) on transient daemon failures; docker exec is deliberately never retried, since it isn't idempotent. Raw Docker exceptions are logged server-side and never leaked to the client — they can contain host socket paths and usernames.
Requirements
- macOS (Apple Silicon) **or** Windows 10/11 with WSL2
- Docker Desktop (running)
- uv (Python package/project manager)
- Claude Desktop
---
Setup — macOS
1. System tools
Open Docker Desktop from Applications and let it finish starting (steady whale icon in the menu bar). Then install Claude Desktop from claude.ai → Download for Mac.