Skip to content

README.md

Latest commit

 

History

History
179 lines (128 loc) · 5.02 KB

README.md

File metadata and controls

179 lines (128 loc) · 5.02 KB

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
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

  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! 🦀