diff --git a/README.md b/README.md index fad77f1..1ace548 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ This project provides a Model-Context Protocol (MCP) integration for LLDB, allow The integration consists of two main components: -1. **server.py** - An MCP server that communicates with Claude (or other MCP clients) -2. **lldb_plugin.py** - A plugin that runs inside LLDB and exposes debugger functionality via JSON-RPC +1. **lldb_mcp.py** - An MCP server that communicates with Claude (or other MCP clients) +2. **lisa.py** - A plugin that runs inside LLDB and exposes debugger functionality via JSON-RPC This architecture allows Claude to help you debug code by directly interacting with LLDB through natural language. The MCP server acts as a bridge, translating Claude's requests into LLDB commands and returning results in a structured format. @@ -23,8 +23,8 @@ This architecture allows Claude to help you debug code by directly interacting w 1. Clone this repository: ``` - git clone https://github.com/ant4g0nist/lldb-mcp.git - cd lldb-mcp + git clone https://github.com/ant4g0nist/lisa.py.git + cd lisa.py ``` 2. Install required dependencies: @@ -55,7 +55,7 @@ This architecture allows Claude to help you debug code by directly interacting w "command": "/path/to/your/.local/bin/uv", "args": [ "--directory", - "/path/to/your/lldb-mcp/llmcp", + "/path/to/your/lisa.py", "run", "lldb_mcp.py" ] @@ -89,6 +89,80 @@ If you prefer to use the plugin directly from LLDB without Claude for Desktop: 3. The server will be available at http://localhost:13338 for any MCP client to connect to. +### Method 3: Using with Roo Code + +This section details how to set up and use the LLDB MCP server with Roo Code. + +**Initial One-Time Setup:** + +1. **Clone the Repository (if not already done):** + ```bash + git clone https://github.com/ant4g0nist/lldb-mcp.git # Or your fork/project path + cd lldb-mcp + ``` + +2. **Install `capstone` for LLDB's Internal Python Environment:** + The LLDB plugin (`lldb_plugin.py` after installation) also requires `capstone`. LLDB often uses its own Python interpreter (e.g., bundled with Xcode), which is separate from your project's environment. + * **Identify LLDB's Python:** Start `lldb` and run: + ```lldb + (lldb) script import sys; print(sys.path) + ``` + Look for a path like `/Applications/Xcode.app/.../Python3.framework/.../bin/python3.x`. + For example, it might be `/Applications/Xcode.app/Contents/Developer/Library/Frameworks/Python3.framework/Versions/3.9/bin/python3.9`. + * **Install `capstone` into LLDB's Python:** Use the Python executable identified above. + ```bash + # Replace with the actual path you found: + /Applications/Xcode.app/Contents/Developer/usr/bin/python3.9 -m pip install capstone==4.0.2 + ``` + *(Note: This command might install to your user's site-packages for that Python version, e.g., `~/Library/Python/3.9/lib/python/site-packages/`, which should be in LLDB's `sys.path`.)* + +3. **Configure Roo Code MCP Settings:** + Add or verify the `lldb` server configuration in your Roo Code MCP settings file. On macOS, this is typically at `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`. + ```json + { + "mcpServers": { + "lldb": { + "command": "/opt/homebrew/bin/uv", // Or your system's `uv` path, e.g., /Users/dante/.local/bin/uv + "args": [ + "--directory", + "/path/to/your/lldb-mcp", // IMPORTANT: Absolute path to this project + "run", + "lldb_mcp.py" + ], + "disabled": false, + "alwaysAllow": [] // Keep empty or customize as needed + } + // ... other servers if any ... + } + } + ``` + **Important:** + * Replace `/path/to/your/lldb-mcp` with the **actual absolute path** to this cloned `lldb-mcp` project directory. + * Ensure the `command` path for `uv` (or `python3` if not using `uv` for the MCP server) is correct for your system. + +**Manual Steps for Each Debugging Session with Roo Code:** + +The `lldb_mcp.py` server (run by Roo Code) needs to connect to a JSON-RPC server that you manually start within an LLDB session. **You must perform these steps each time you want to use LLDB with Roo Code:** + +1. **Open a new terminal window.** +2. **Start LLDB:** + ```bash + lldb + ``` +3. **Import the LLDB plugin and start the MCP server:** + Inside the `(lldb)` prompt, run the following commands: + ```lldb + (lldb) command script import lldb_plugin.py + ``` + You should see output like "Manual loaded for architecture..." and the prompt might change to `(lisa:>)`. Then, start the server: + ```lldb + (lisa:>) mcp start + ``` + You should see: `LLDB JSON-RPC server started on port 13338` and `Started LLDB JSON-RPC server on http://localhost:13338/mcp`. + +4. **Keep this LLDB terminal session running in the background.** Do not close it while using the LLDB tools with Roo Code. + + ## Available LLDB Tools The MCP server exposes the following methods for AI assistants: