check pt

Author: matteius

BINARY_COMPARISON_USAGE_GUIDE.md

@@ -1,13 +1,15 @@
-# Binary Comparison Usage Guide
+# Binary Ninja Usage Guide
 
 ## Overview
 
-smartdiff now supports binary comparison through integration with Binary Ninja MCP servers. This enables AI agents to:
+smartdiff uses Binary Ninja MCP servers for binary inspection. This enables AI agents to:
 
 1. **Discover binaries** loaded in Binary Ninja
 2. **List functions** in binaries
 3. **Decompile functions** to see high-level code
-4. **Compare binaries** (coming in Phase 3)
+
+Binary-to-binary comparison is intentionally hidden in the default build. It
+requires the explicit `binary-comparison` Cargo feature.
 
 ## Architecture
 
@@ -26,15 +28,15 @@ Binary Ninja (GUI with Personal License)
 ### 1. Binary Ninja
 
 - Binary Ninja installed (Personal License or higher)
-- Binary Ninja MCP plugin installed (from `/home/matteius/codediff/binary_ninja_mcp/`)
+- Binary Ninja MCP plugin installed (from `/home/matteius/smartdiff/binary_ninja_mcp/`)
 
 ### 2. Binary Ninja MCP Server
 
-Located at: `/home/matteius/codediff/binary_ninja_mcp/`
+Located at: `/home/matteius/smartdiff/binary_ninja_mcp/`
 
 **Installation**:
 ```bash
-cd /home/matteius/codediff/binary_ninja_mcp
+cd /home/matteius/smartdiff/binary_ninja_mcp
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
@@ -47,12 +49,13 @@ pip install -r requirements.txt
 
 ### 3. smartdiff MCP Server
 
-Located at: `/home/matteius/codediff/`
+Located at: `/home/matteius/smartdiff/`
 
 **Build**:
 ```bash
-cd /home/matteius/codediff
+cd /home/matteius/smartdiff
 cargo build --release -p smart-diff-mcp-server
+cargo build --release -p smart-diff-cli
 ```
 
 ## Setup Workflow
@@ -73,36 +76,51 @@ cargo build --release -p smart-diff-mcp-server
    - Server will start on port 9010
    - You'll see: "MCP Server started on port 9010"
 
-### Step 2: Start Binary Ninja MCP Bridge (Optional)
+### Step 2: Verify Direct Rust Access
+
+The preferred smartdiff path is the Rust client talking directly to the
+Binary Ninja GUI plugin server:
+
+```bash
+cd /home/matteius/smartdiff
+cargo run --release -p smart-diff-cli -- binja servers
+cargo run --release -p smart-diff-cli -- binja functions port_9009 --limit 25
+cargo run --release -p smart-diff-cli -- binja decompile port_9009 main
+```
+
+This avoids headless Binary Ninja entirely and works with a Personal license
+because the licensed GUI process owns the analysis.
+
+### Step 3: Start Binary Ninja MCP Bridge (Optional)
 
 If you want to use Binary Ninja MCP directly with Claude:
 
 ```bash
-cd /home/matteius/codediff/binary_ninja_mcp
+cd /home/matteius/smartdiff/binary_ninja_mcp
 source .venv/bin/activate
 python bridge/bn_mcp_bridge_multi_http.py
 ```
 
 This bridge connects to Claude Desktop and routes requests to Binary Ninja servers.
 
-### Step 3: Start smartdiff MCP Server
+### Step 4: Start smartdiff MCP Server
 
 ```bash
-cd /home/matteius/codediff
+cd /home/matteius/smartdiff
 cargo run --release --bin smart-diff-mcp
 ```
 
 The server will start and listen on stdio for MCP requests.
 
-### Step 4: Configure Claude Desktop
+### Step 5: Configure Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
 
 ```json
 {
   "mcpServers": {
     "smartdiff": {
-      "command": "/path/to/codediff/target/release/smart-diff-mcp",
+      "command": "/home/matteius/smartdiff/target/release/smart-diff-mcp",
       "args": []
     }
   }
@@ -115,7 +133,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 {
   "mcpServers": {
     "smartdiff": {
-      "command": "/path/to/codediff/target/release/smart-diff-mcp",
+      "command": "/home/matteius/smartdiff/target/release/smart-diff-mcp",
       "args": []
     },
     "binary_ninja": {
@@ -126,7 +144,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
-### Step 5: Restart Claude Desktop
+### Step 6: Restart Claude Desktop
 
 Restart Claude Desktop to load the new MCP server configuration.
 
@@ -262,23 +280,6 @@ Agent:
 5. Reports findings
 ```
 
-### Workflow 3: Compare Two Binaries (Manual - Phase 3 will automate)
-
-```
-User: "I have two versions of a binary. What changed between them?"
-
-Agent:
-1. Calls list_binja_servers() to see both binaries
-2. Calls list_binary_functions() for both binaries
-3. Compares function lists to find:
-   - Added functions (in v2 but not v1)
-   - Deleted functions (in v1 but not v2)
-   - Common functions (in both)
-4. For common functions, decompiles both versions
-5. Compares decompiled code to identify changes
-6. Reports significant changes
-```
-
 ## Troubleshooting
 
 ### No servers found
@@ -310,49 +311,24 @@ Agent:
 3. Restart the MCP server in Binary Ninja
 4. Check firewall settings (localhost should be allowed)
 
-## Next Steps (Phase 3)
-
-Phase 3 will add automated binary comparison:
-
-### New Tools (Coming Soon)
+## Rust CLI Shortcuts
 
-#### `compare_binaries_via_binja`
+The same path is available without MCP:
 
-Compare two binaries and identify matching functions.
-
-```
-compare_binaries_via_binja(
-    binary_a_id="port_9009",
-    binary_b_id="port_9010",
-    options={
-        "use_decompiled_code": true,
-        "similarity_threshold": 0.7
-    }
-)
-```
-
-#### `list_binary_function_matches`
-
-List matched functions sorted by similarity.
-
-```
-list_binary_function_matches(
-    comparison_id="uuid",
-    sort_by="similarity_asc",
-    limit=50
-)
+```bash
+cargo run --release -p smart-diff-cli -- binja servers
+cargo run --release -p smart-diff-cli -- binja functions port_9009 --limit 25
+cargo run --release -p smart-diff-cli -- binja decompile port_9009 main
 ```
 
-#### `get_binary_function_diff`
+## Feature-Gated Comparison
 
-Get detailed diff for a specific function match.
+The comparison commands and MCP tools are not exposed by default. To enable
+them deliberately, build with:
 
-```
-get_binary_function_diff(
-    comparison_id="uuid",
-    function_a="process_data",
-    function_b="process_data_v2"
-)
+```bash
+cargo build --release -p smart-diff-cli --features binary-comparison
+cargo build --release -p smart-diff-mcp-server --features binary-comparison
 ```
 
 ## Technical Details
@@ -376,12 +352,12 @@ The MCP server (`crates/mcp-server/`) now includes:
   - `get_function_diff`
   - `get_comparison_summary`
 
-- **Binary comparison tools** (new):
+- **Binary inspection tools**:
   - `list_binja_servers`
   - `list_binary_functions`
   - `decompile_binary_function`
 
-All tools are available to AI agents through the MCP protocol.
+Only these binary tools are available to AI agents in the default build.
 
 ## License
 
@@ -393,4 +369,3 @@ AGPL-3.0-only
 - [Binary Ninja Client Library](crates/binary-ninja-client/README.md)
 - [smartdiff MCP Server](crates/mcp-server/README.md)
 - [Binary Ninja](https://binary.ninja/)
-