Ferroscope

CI Crates.io Documentation

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

Quick Start

1. Install

cargo install ferroscope

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

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

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

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

Available Tools

1. debug_run - Load and prepare Rust programs for debugging
2. debug_break - Set breakpoints at functions or lines
3. debug_continue - Launch/continue program execution
4. debug_step - Step through code line by line
5. debug_step_into - Step into function calls
6. debug_step_out - Step out of current function
7. debug_eval - Evaluate expressions and inspect variables
8. debug_backtrace - Show call stack
9. debug_list_breakpoints - List all breakpoints
10. 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! 🦀