Skip to main content
Glama
resc
by zney295

resc — MCP data recovery engine and AI recovery skills

resc is an open-source, read-only disk-image recovery toolkit for MCP-compatible AI assistants. It combines a Rust JSON-RPC engine, Python command-line tools and five recovery skills for Codex and Antigravity/Gemini. It inspects disk images, tests filesystem repairs in a durable virtual overlay, and exports supported files with SHA-256 provenance.

Tiếng Việt: Bộ skill cứu dữ liệu cho AI: chẩn đoán ảnh đĩa USB/SSD/HDD, thử sửa metadata trong overlay và xuất file NTFS/FAT vào vị trí riêng.

What resc does and FAQ · Download Windows toolkit · Installation guide · Current capabilities

Implementation status: See implemented capabilities and limitations for the hardened engine's actual behavior: 512/4096-byte sectors, durable overlay WAL, asynchronous extraction, paginated hits and SHA-256 provenance manifests. Native NTFS/FAT reads use the overlay; unsupported features return explicit errors. Historical feature claims below are not a substitute for this capability reference or the live MCP tool schema.

🛡️ resc

Low-Level Disk Forensics & Data Recovery MCP Engine in Rust

Rust MCP Safety License: Apache 2.0

Use an MCP agent to inspect disk images and test recovery patches in a virtual overlay.

Reviewed v5 additions: unified CLI, installer, header/driver diagnostics and limitations.

Architecture • Safety Guarantee • Quick Start • MCP Tools • Forensic Playbooks


Illustrated resc recovery workflow

This animation is a simulated illustration, not a recorded recovery session. Consult the capability reference for implemented operations.

Related MCP server: Forensics MCP Server

Setup and recovery workbench

Read the Vietnamese step-by-step recovery guide for installation, selecting raw source images, diagnosing multiple failure types, MP4/MOV box analysis, exact byte-range reconstruction and FFmpeg verification. The workbench does not require choosing a failure hypothesis in advance. The recovery skills route 17 case types, including USB No Media, reader disagreement, 00/FF-dominant images, zero-hit and persistence failures. They include a streaming read-only image audit/comparison helper; they do not claim to repair hardware or create bytes missing from a source. For a computer that cannot boot its OS, start with the two-computer / Linux Live rescue guide. scripts/rescue.py adds Linux device inventory, GNU ddrescue acquisition with resume/retry, an existing-Live-USB toolkit bundle, authenticated SSH control and resumable hash-verified transfer of sealed acquisitions. SSH acquisition stages the image on a healthy destination disk at the source computer before transfer; it does not make a powered-off computer accessible through an ordinary USB cable. Read the professional literature review and research roadmap for 14 examined works and the distinction between implemented capabilities and proposed metadata-, codec- and validation-guided reconstruction. The controlled deep-evidence study records reproducible negative cases: two structurally valid PNG candidates can conflict, and an MP4 can probe/decode all frames while containing wrong video data. See the three-case integration guide and independently researched implementations for partition/boot damage, deleted FAT32 metadata and fragmented content. Added tools include analyze_partition_recovery and analyze_file_candidate; FAT32 deleted-entry discovery is an asynchronous job.

bash scripts/setup.sh
python scripts/recovery.py doctor
python scripts/recovery.py triage /path/to/source.img --deep
python scripts/recovery.py mcp-config --session-root /path/to/persistent-state

New MCP tools: diagnose_recovery, analyze_video_candidate. Scan jobs include ISO_BMFF_BOX_SCAN and METADATA_WITHOUT_VBR. Open a Windows raw-device session with storage_diagnostics: true to report capacity and write state. New export mode: CARVE_BY_BYTE_RANGES. These add evidence-led triage and exact extent reconstruction; they do not infer arbitrary fragment order or regenerate missing video metadata. See algorithm provenance.

Why resc?

When a USB drive or hard disk turns RAW, loses its partition table, or suffers from corrupted $MFT / FAT headers, users face a painful choice:

  1. Commercial GUI tools ($70–$100+): Expensive, black-box scanners that often fail on complex structural corruption or fragmented media (moov atom separation in MP4s, broken SQLite B-trees).

  2. Open-source CLI forensics (TestDisk, The Sleuth Kit, ddrescue, Hex Editors): Extremely powerful, but require deep knowledge of LBA offsets, Boot Sector byte structures, and manual hex patching.

resc bridges this gap. However, you cannot simply feed a 500GB raw disk image into an LLM's context window.

resc implements a Hybrid Brain & Muscle Architecture:

  • The Rust engine: Provides read-only image I/O, Windows physical I/O, streaming signature discovery, entropy measurements, MBR/GPT validation, native NTFS/FAT traversal and bounded MP4/MOV structure inspection. Actual throughput depends on the source and hardware.

  • The Brain (AI Agent via MCP): Receives ultra-compact < 5KB JSON Anomaly Reports, diagnoses structural corruption, tests hex patches safely in RAM (Copy-on-Write Overlay), and orchestrates file extraction.


Hybrid "Brain & Muscle" Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                    AI AGENT (Claude / Cursor / Gemini)                  │
│  • Reads Forensic Playbooks (.agents/skills/)                           │
│  • Analyzes <5KB JSON Anomaly Maps & formulates recovery strategies     │
└───────────────────────────────────▲─────────────────────────────────────┘
                                    │ Model Context Protocol (JSON-RPC stdio)
┌───────────────────────────────────▼─────────────────────────────────────┐
│                        resc MCP SERVER (crates/mcp-server)              │
│  • Async Job Queue (Prevents MCP timeouts on multi-terabyte scans)      │
│  • Virtual Disk Overlay (512/4096-byte sectors and durable WAL)        │
└───────────────────────────────────▲─────────────────────────────────────┘
                                    │ Rust Internal API / Zero-Copy Structs
┌───────────────────────────────────▼─────────────────────────────────────┐
│                 NATIVE ENGINE (core-io / disk-parsers)                  │
│  • Layer 0: Read-only image and Windows physical-device I/O            │
│  • Layer 1: Signature scanning and entropy analysis                    │
│  • Layer 2: MBR/GPT and native NTFS/FAT validation                    │
│  • Layer 3: Background image extraction and cloning                    │
└─────────────────────────────────────────────────────────────────────────┘

Safety Architecture: In-Memory Virtual Overlay

Source media are opened read-only by resc. Virtual patches are applied to an in-memory overlay and recorded in a session WAL; they are never written to the source by resc. This is not a hardware write blocker: the OS or another application may still modify shared media. Native NTFS/FAT validation checks root traversal and a file entry; it does not certify the whole filesystem. See capabilities and SECURITY.md for the boundaries.


Quick Start

1. MCP Client Configuration

Copy mcp_config.example.json into your MCP client configuration and replace its placeholders with absolute paths. The launcher requires a locally built or otherwise trusted native binary; it does not download one. It uses RESC_MCP_BIN, or the legacy RECOVERYAI_MCP_BIN fallback, when set.

If resc-mcp is available on npm, the equivalent package-based configuration is:

{
  "mcpServers": {
    "resc": {
      "command": "npx",
      "args": ["-y", "resc-mcp"],
      "env": { "RESC_MCP_BIN": "<absolute-path-to-trusted-mcp-server-binary>" }
    }
  }
}

The npm package is named resc-mcp; its resc, resc-mcp and legacy recoveryai-mcp commands all use bin/resc-mcp.js. To select the resc alias explicitly, use npx --package resc-mcp resc. Bare npx resc resolves the npm package named resc and requires that package to be published separately. Package publication and release availability must be verified separately; the npm package does not include the native binary.

2. Build from Source (Rust Workspace)

Prerequisites: current Rust stable (Cargo), Node >=18, and Python >=3.11. For physical drive access on Windows, run your terminal/client as Administrator.

git clone https://github.com/psy-zney/resc.git
cd resc

# External legacy forensic adapters are currently disabled; no companion downloads are needed.

# Build the release binary
cargo build --release --locked

# Run disposable synthetic corruption / reconstruction tests
python ./tests/test_e2e_recovery.py
python ./tests/test_recovery_workbench.py
python ./tests/test_deleted_recovery.py
python ./tests/test_three_cases.py
python ./tests/test_rescue.py

Windows supports image files and physical-drive inspection. CI also exercises image workflows on Ubuntu; raw devices on non-Windows platforms return NotImplemented. macOS is not covered by CI. Raw-device extraction and cloning are currently unavailable even on Windows. See capabilities.

3. Set up Codex and Antigravity

After building the engine, use Python 3.11+ to preview and apply the configuration and five bundled skills. Use --client codex or --client antigravity for one client, and --root PATH to select a configuration home.

python scripts/setup_clients.py --client both
python scripts/setup_clients.py --client both --apply

The installer stages changed files, creates backups, replaces each file atomically, verifies readback, and rolls back on handled failures. Codex uses .codex/config.toml and .agents/skills/ under the selected home. With the default home, CODEX_HOME can override the Codex config directory. Antigravity uses .gemini/config/mcp_config.json and .gemini/config/skills/. An existing unmanaged Codex resc entry that differs from the proposed settings needs a manual merge.


MCP Tools Catalog

tools/list exposes 18 tools including four legacy aliases. The live schema and AGENTS.md tool matrix are the parameter reference. The server reports MCP protocol version 2024-11-05 at initialization.

The main workflow is open → diagnose → inspect/scan → validate an evidence-based repair or reconstruction → export asynchronously → verify provenance/content. scan_filesystem_journals remains an explicit NotImplemented endpoint. New video box scanning and byte-range exports supplement native NTFS/FAT allocated-file extraction. They do not automatically reconstruct arbitrary fragmented files.


Built-in Forensic Skills & Playbooks

resc ships with five version-4.1 skills (inspired by REA). They route by evidence and distinguish implemented operations from external handoffs; use the capability reference and live MCP schema:

  • disk-forensics/: Device/media and reader checks, MBR/GPT and NTFS/FAT boot proposals, acquisition and unbootable-host workflows.

  • file-carving-and-defrag/: Bounded discovery, heuristic fragment candidates, JPEG/PNG/MP4 validation and external SQLite salvage handoff.

  • filesystem-repair/: Overlay-only NTFS/FAT proposals and explicit limits for deleted records, exFAT and Ext4.

  • mcp-disk-automation/: Actual asynchronous job states, cancellation, cursor pagination, quotas and artifact preservation.

  • recovery-triage/: Seventeen case routes, including No Media, reader disagreement, 00/FF, zero-hit and persistence; regular-image audit/comparison helpers.

For an MBR USB previously formatted outside resc, verify captures made before format (T0), after flush (T1), and after reconnect (T2). Supply separate readback files for the two canary observations and the expected digest of the original canary. The verifier reads regular files and reports which metadata and canary bytes agree. The operator supplies the capture provenance.

Windows USB reuse has a separate preview-first execution path: python scripts/usb_format_verify.py format --drive D: --filesystem exfat or python scripts/usb_format_verify.py write-canary --drive D:. After approving the displayed device identity, pass its --confirm token. Formatting additionally requires --data-loss-accepted and erases the entire selected disk. Both commands enforce USB/system/pagefile guards and require Administrator for execution. Formatting automatically writes four 1 MiB canary files and checks their SHA-256 after flush. External audit manifests are stored under %LOCALAPPDATA%/resc/usb-lab. Reconnect verification and full-capacity testing remain separate observations.

python scripts/usb_format_verify.py --filesystem exfat --t0 t0.img --t1 t1.img --t2 t2.img --canary-t1 t1.bin --canary-t2 t2.bin --canary-sha256 EXPECTED_SHA256

Project Structure

resc/
├── .agents/skills/          # 5 Specialized AI Forensic Skill Modules & 13 Playbooks
├── ai-context/              # Decision trees & tool catalogs for LLM context injection
├── bin/                     # Node.js NPX wrapper (resc-mcp.js) for instant MCP integration
├── crates/
│   ├── core-io/             # 4KB-aligned DMA buffers, SCSI watchdog, RAM Virtual Overlay
│   ├── disk-parsers/        # Zero-copy MBR/GPT/NTFS/FAT structs, SIMD carver, Defrag matcher
│   ├── external-bridges/    # Headless wrappers for The Sleuth Kit, PhotoRec, GNU ddrescue
│   └── mcp-server/          # Tokio JSON-RPC stdio server & Async Job Manager
└── tests/                   # Synthetic disk corruption generator & E2E verification suite

Reliability, Verification & OS Boundaries

resc applies defensive checks when handling untrusted, corrupted disk media:

  • Verified test results: Local Windows validation passed 46 unit tests, 16 synthetic E2E groups, and 1,000,000 deterministic malformed-input cases across MBR, GPT, NTFS boot-sector and FAT32 parsers with no observed panics. This regression corpus is not a completed libFuzzer campaign or proof of safety for every input.

  • Persistent CoW overlay: Patches for 512-byte and 4096-byte logical sectors are synced to a session Write-Ahead Log (.wal) before changing RAM. Retained image sessions can replay verified records after restart when source identity and geometry match. Preserve RESC_SESSION_ROOT; interrupted jobs do not resume automatically.

  • TOCTOU and overwrite protection: Background extraction uses no-follow flags and platform handle identity checks before writes. Exclusive .part files, sync_all, metadata-first publication and rollback protect clone/mapfile and file/manifest pairs. This is a recoverable protocol, not one atomic transaction across power loss. Completed extractions include SHA-256 provenance manifests (.manifest.json).

  • Kernel I/O boundaries: Windows overlapped reads request CancelIoEx after a 500 ms timeout or job cancellation. Buffers remain alive until kernel completion; an unresponsive driver can still delay cancellation. There is no guaranteed hard deadline when the driver does not complete its request.

  • Panic boundaries: Release builds require panic = "unwind"; handler and worker boundaries report caught panics as errors. catch_unwind does not isolate memory corruption, OOM aborts or non-terminating parser execution. Safe Rust and passing tests reduce risk without eliminating these boundaries.

CI runs on Windows and Ubuntu. For commit 19cb436, Ubuntu CI passed release build, unit tests, Clippy and E2E. Local Windows release compilation was blocked by Application Control (OS error 4551); the local E2E results above used the debug binary. See the verification report and implemented capabilities for evidence and limits.

Disclaimer & Safety Notice

Data recovery on failing hardware carries inherent physical risks. If a drive is making mechanical clicking noises, unplug it immediately and seek a cleanroom lab. resc is strictly read-only at the software layer, but scanning a dying NAND flash chip or degraded platter can accelerate hardware failure—always use the DD_RESCUE_CLONE workflow first when bad_sectors_count > 0.

License

Licensed under the Apache License 2.0.

Available Tools

1 tool
inspect_disk_headersC

Limited Python backend: read-only regular-image header evidence. No repair/extraction. Returns at most eight volume samples.

Inputs: target_path (required), sector_size.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusing it with another operation. Its purpose is explicitly limited to read-only disk header inspection, so selection is unambiguous.

    Naming Consistency5/5

    The single tool name inspect_disk_headers follows a clear verb_noun snake_case pattern. There are no competing conventions to create inconsistency.

    Tool Count3/5

    A single tool is defensible for a strictly narrow read-only header-evidence server, but it feels thin for a server named resc and offers no broader lifecycle. The tool count is borderline rather than clearly well-scoped.

    Completeness2/5

    The surface only reads regular-image header evidence and samples at most eight volumes. It explicitly lacks repair, extraction, and broader disk recovery operations, leaving significant gaps for a rescue-oriented domain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform digital forensics analysis including memory analysis, file metadata inspection, and threat-intelligence lookups.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform digital forensics and incident response tasks by dynamically discovering and utilizing host tools for memory analysis, metadata extraction, threat detection, and file dissection.
      5
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect Autopsy forensic cases through read-only MCP tools for case metadata, filesystem and artifact search, timeline and account queries, evidence extraction, and hash-chained audit/seal verification.
      2
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an LLM agent to inventory Windows physical disks, partitions and logical volumes read-only, then plan and execute guarded forensic imaging to E01 format via ewftools, requiring validated plans, explicit execution flags, distinct source/destination disks and attested write blockers. Also verifies image integrity, extracts image metadata, and produces Markdown, JSON, HTML and audit-log reports.
      3
      Apache 2.0