Installing `comprehensive-test` `ferroscope` executables

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install ferroscope

It will make comprehensive-test ferroscope commands available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall ferroscope uninstalls.

Back to the crate overview.

Readme

Ferroscope

MCP server that enables AI assistants to debug Rust programs using LLDB and GDB.

Quick Start

1. Install

cargo install ferroscope

Alternative: Build from source

git clone https://github.com/douglance/ferroscope.git
cd ferroscope
cargo install --path .

2. Configure Your AI Assistant

Add this to your AI assistant's MCP settings:

{
  "mcpServers": {
    "ferroscope": {
      "command": "ferroscope",
      "args": [],
      "env": {},
      "description": "Rust debugging via LLDB/GDB"
    }
  }
}

3. Add Custom Instructions

Copy this snippet to your AI assistant's custom instructions:

When debugging Rust programs, use ferroscope with this workflow:
1. Load program: debug_run /path/to/project
2. Set breakpoints: debug_break main or debug_break src/main.rs:25
3. Start execution: debug_continue
4. At breakpoints: debug_eval variable_name to inspect values
5. Step through: debug_step (over), debug_step_into (into), debug_step_out (out)
6. Check state: debug_state to see current status
7. View stack: debug_backtrace when errors occur

Always start with debug_run, then set breakpoints before debug_continue.

For advanced debugging with optimized context usage, append our best practices to your CLAUDE.md:

curl -s https://raw.githubusercontent.com/douglance/ferroscope/main/best-practices.md >> CLAUDE.md

4. Start Debugging

Ask your AI assistant: "Debug this Rust program" and it will use ferroscope automatically.

Configuration by AI Assistant

Claude Code

The configuration above works for Claude Code. Add it to Settings → MCP Servers, then restart.

Cursor

Add to .cursor/config.json:

{"tools": {"ferroscope": {"command": "ferroscope", "description": "Debug Rust programs"}}}

Windsurf

Add to tools configuration:

{"customTools": [{"name": "ferroscope", "command": "ferroscope", "type": "mcp"}]}

Zed

Add to ~/.config/zed/settings.json:

{"assistant": {"tools": {"ferroscope": {"command": "ferroscope", "args": []}}}}

Other AI Assistants

For any MCP-compatible AI assistant, the command is ferroscope. Check your assistant's documentation for "MCP tools" or "external tools".

Available Tools

debug_run - Load and prepare Rust programs for debugging
debug_break - Set breakpoints at functions or lines
debug_continue - Launch/continue program execution
debug_step - Step through code line by line
debug_step_into - Step into function calls
debug_step_out - Step out of current function
debug_eval - Evaluate expressions and inspect variables
debug_backtrace - Show call stack
debug_list_breakpoints - List all breakpoints
debug_state - Get current debugging session state

Requirements

Rust toolchain
LLDB (macOS) or GDB (Linux)
Windows not currently supported (WinDbg integration planned)

Verification

Check ferroscope is installed and working:

# Verify installation
which ferroscope

# Test basic functionality
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ferroscope

# Run test suite (if built from source)
cargo run --bin comprehensive-test
# Expected output:
# 🧪 FERROSCOPE COMPREHENSIVE TEST SUITE
# ✅ MCP Protocol Test: PASSED
# ✅ Program Loading Test: PASSED
# ✅ Breakpoint Test: PASSED
# ... (more tests)
# 🎉 ALL TESTS PASSED! Ferroscope functionality verified!

Limitations

Security: Currently runs with full user privileges without sandboxing. Only use with trusted code.
Platform Support: Windows is not supported (WinDbg integration planned)
Performance: No connection pooling or resource limits for concurrent debugging sessions
Error Recovery: Limited error handling for malformed debugger output
Binary Types: Only supports Rust binaries compiled with debug symbols
Debugger Versions: Tested with LLDB 15+ and GDB 12+

Development and Releases

Ferroscope uses automated semantic versioning based on conventional commits. New versions are automatically published to crates.io when:

Fixes are merged (patch release: 0.1.1 → 0.1.2)
Features are added (minor release: 0.1.1 → 0.2.0)
Breaking changes occur (major release: 0.1.1 → 1.0.0)

See CONTRIBUTING.md for contribution guidelines and release process details.

Ready to debug Rust programs with AI! 🦀

Installing comprehensive-test ferroscope executables

Installing `comprehensive-test` `ferroscope` executables