resc
Integrates with GNU ddrescue via headless external bridges, enabling cloning of failing or damaged drives and bad-sector rescue workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@resc scan /dev/sdb for deleted files"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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

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-stateNew 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:
Commercial GUI tools ($70–$100+): Expensive, black-box scanners that often fail on complex structural corruption or fragmented media (
moovatom separation in MP4s, broken SQLite B-trees).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.pyWindows 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 --applyThe 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_SHA256Project 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 suiteReliability, 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. PreserveRESC_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
.partfiles,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
CancelIoExafter 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_unwinddoes 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 toolinspect_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
Scored across 1 tool
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.
The single tool name inspect_disk_headers follows a clear verb_noun snake_case pattern. There are no competing conventions to create inconsistency.
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.
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
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Search and read free, scanned AI agent skills and configs. Read-only, no account.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform digital forensics analysis including memory analysis, file metadata inspection, and threat-intelligence lookups.-
- FlicenseAqualityDmaintenanceEnables 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.51-
- AlicenseNot gradedqualityCmaintenanceEnables 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.2GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables 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.3Apache 2.0