Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
Initial commit: betterBinaryMCP - Enhanced MCP server for Hopper Disassembler
morluto729d3e927cbc
diff --git a/.gitignore b/.gitignorenew file mode 100644index 000000000..53cf3d840--- /dev/null+++ b/.gitignore@@ -0,0 +1,31 @@+# Byte-compiled+__pycache__/+*.py[cod]+*$py.class++# Distribution+dist/+build/+*.egg-info/+*.egg++# Virtual environments+.venv/+venv/+env/++# IDE+.idea/+.vscode/+*.swp+*.swo+*~++# Testing+.pytest_cache/+htmlcov/+.coverage++# OS+.DS_Store+Thumbs.dbdiff --git a/LICENSE b/LICENSEnew file mode 100644index 000000000..2d476d24f--- /dev/null+++ b/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 morluto++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/README.md b/README.mdnew file mode 100644index 000000000..c99c97d0a--- /dev/null+++ b/README.md@@ -0,0 +1,115 @@+# betterBinaryMCP++An enhanced MCP (Model Context Protocol) server for [Hopper Disassembler](https://www.hopperapp.com/) that wraps the official Hopper 6 MCP server and adds reverse engineering–specific analysis tools.++**No Python injection or plugins needed** — just Hopper open with a binary.++## Architecture++```+MCP Client ←STDIO→ betterBinaryMCP ←STDIO→ Official HopperMCPServer ←XPC→ Hopper.app+```++- Wraps the official `HopperMCPServer` binary as a subprocess+- Proxies all 31 official tools unchanged+- Adds 8 RE-specific tools built on top of official operations++## Tools++### 31 Official Tools (proxied)++| Tool | Description |+|------|-------------|+| `address_name` | Get/set name (label) at an address |+| `comment` / `inline_comment` | Get/set comments |+| `current_address` / `current_procedure` / `current_document` | Cursor state |+| `goto_address` / `next_address` / `prev_address` | Navigation |+| `list_segments` / `list_procedures` / `list_strings` / `list_names` / `list_documents` / `list_bookmarks` | Listing |+| `search_procedures` / `search_strings` | Regex search |+| `procedure_pseudo_code` / `procedure_assembly` | Decompilation |+| `procedure_callees` / `procedure_callers` | Call relationships |+| `procedure_info` / `procedure_address` | Procedure metadata |+| `set_address_name` / `set_addresses_names` | Rename labels |+| `set_comment` / `set_inline_comment` | Write comments |+| `set_bookmark` / `unset_bookmark` | Bookmarks |+| `set_current_document` | Switch active document |+| `xrefs` | Cross-references |++### 8 RE-Specific Tools (added)++| Tool | Description |+|------|-------------|+| `binary_overview()` | Segment layout, procedure/string counts, document info |+| `swift_classes(pattern)` | Swift class hierarchy from mangled `_TtC` names |+| `get_objc_classes(pattern)` | Objective-C class names from labels |+| `get_objc_protocols()` | Objective-C protocol names from labels |+| `batch_decompile(addresses)` | Decompile up to 20 procedures at once |+| `get_call_graph(address, direction, depth)` | Recursive call graph traversal (forward/backward) |+| `analyze_swift_types()` | Categorize all Swift mangled names by module/type/method |+| `find_xrefs_to_name(name)` | Find references by name lookup |++## Requirements++- **Hopper Disassembler** v6+ (ships the official MCP server)+- **Python** 3.10++- **Hopper open** with a binary loaded and analyzed++## Installation++```bash+pip install fastmcp+```++## Usage++### As an MCP Server (recommended)++Add to your MCP client configuration (Claude Desktop, Cursor, etc.):++```json+{+ "mcpServers": {+ "betterBinaryMCP": {+ "command": "python3",+ "args": ["/path/to/betterBinaryMCP/server.py"]+ }+ }+}+```++### Command Line++```bash+python3 server.py+```++### Test Connection++```bash+python3 hopper_client.py+```++## Testing++```bash+pip install pytest pytest-asyncio+python -m pytest tests/ -v+```++## How It Works++1. On startup, the server launches the official `HopperMCPServer` binary as a subprocess+2. Communicates via NDJSON (newline-delimited JSON) over STDIO — no HTTP, no Content-Length framing+3. Proxied tools forward calls directly to the official server+4. RE tools compose multiple official calls (e.g., `swift_classes` calls `list_procedures` and parses `_TtC` mangled names)++## Limitations++- Requires Hopper 6+ (the official MCP server binary must exist)+- The official server connects to Hopper via XPC — Hopper must be running with a document open+- `batch_decompile` is limited to 20 procedures per call+- `get_call_graph` is limited to depth 5++## License++MITdiff --git a/hopper_client.py b/hopper_client.pynew file mode 100644index 000000000..2832c0ae7--- /dev/null+++ b/hopper_client.py@@ -0,0 +1,149 @@+#!/usr/bin/env python3+"""+NDJSON client for the official HopperMCPServer subprocess.++Handles STDIO communication using NDJSON (newline-delimited JSON) protocol.+Each message is a single JSON object followed by a newline.+"""++import json+import subprocess+import select+import threading+import time+from typing import Any, Optional+++class HopperMCPSubprocessClient:+ """Client for communicating with HopperMCPServer via STDIO/NDJSON."""++ def __init__(self, server_path: str = "/Applications/Hopper Disassembler.app/Contents/MacOS/HopperMCPServer"):+ self.server_path = server_path+ self._proc: Optional[subprocess.Popen] = None+ self._next_id = 1+ self._lock = threading.Lock()+ self._server_info: dict = {}++ def start(self) -> dict:+ """Start the subprocess and initialize the connection."""+ if self._proc is not None:+ return self._server_info++ self._proc = subprocess.Popen(+ [self.server_path],+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ bufsize=0+ )++ self._stderr_thread = threading.Thread(target=self._drain_stderr, daemon=True)+ self._stderr_thread.start()++ time.sleep(0.5)++ self._send({+ "jsonrpc": "2.0",+ "method": "initialize",+ "params": {+ "protocolVersion": "2024-11-05",+ "capabilities": {},+ "clientInfo": {"name": "hopper-proxy", "version": "1.0"}+ }+ })+ response = self._recv(timeout=10.0)+ if response and "result" in response:+ self._server_info = response.get("result", {}).get("serverInfo", {})+ else:+ raise RuntimeError(f"Failed to initialize server: {response}")++ time.sleep(1.0)++ return self._server_info++ def _drain_stderr(self):+ """Drain stderr in background thread."""+ while self._proc and self._proc.poll() is None:+ try:+ ready = select.select([self._proc.stderr], [], [], 0.5)+ if ready[0]:+ line = self._proc.stderr.readline()+ if not line:+ break+ except Exception:+ break++ def stop(self):+ """Stop the subprocess."""+ if self._proc:+ self._proc.terminate()+ self._proc.wait(timeout=5)+ self._proc = None++ def _send(self, msg: dict) -> int:+ """Send a JSON-RPC message."""+ with self._lock:+ self._next_id += 1+ msg["id"] = self._next_id+ line = json.dumps(msg) + "\n"+ self._proc.stdin.write(line.encode("utf-8"))+ self._proc.stdin.flush()+ return self._next_id++ def _recv(self, timeout: float = 30.0) -> Optional[dict]:+ """Receive a JSON-RPC response."""+ ready = select.select([self._proc.stdout], [], [], timeout)+ if ready[0]:+ line = self._proc.stdout.readline()+ if line:+ try:+ return json.loads(line.decode("utf-8"))+ except json.JSONDecodeError:+ return None+ return None++ def call_tool(self, tool_name: str, arguments: dict = None) -> Any:+ """Call a tool on the server."""+ arguments = arguments or {}+ self._send({+ "jsonrpc": "2.0",+ "method": "tools/call",+ "params": {+ "name": tool_name,+ "arguments": arguments+ }+ })+ response = self._recv(timeout=30.0)+ if response and "error" in response:+ error_msg = response["error"].get("message", str(response["error"]))+ raise RuntimeError(f"Tool '{tool_name}' error: {error_msg}")+ if response and "result" in response:+ content = response["result"].get("content", [])+ for c in content:+ if c.get("type") == "text":+ try:+ return json.loads(c["text"])+ except (json.JSONDecodeError, TypeError):+ return c["text"]+ return response["result"]+ return response++ @property+ def server_info(self) -> dict:+ return self._server_info+++def test_connection():+ """Test connection to the official server."""+ client = HopperMCPSubprocessClient()+ info = client.start()+ print(f"Connected to {info.get('name', '?')} v{info.get('version', '?')}")++ docs = client.call_tool("list_documents", {})+ print(f"Documents: {docs}")++ client.stop()+++if __name__ == "__main__":+ test_connection()diff --git a/pyproject.toml b/pyproject.tomlnew file mode 100644index 000000000..c239ba543--- /dev/null+++ b/pyproject.toml@@ -0,0 +1,21 @@+[project]+name = "betterBinaryMCP"+version = "0.1.0"+description = "Enhanced MCP server for Hopper Disassembler with reverse engineering tools"+requires-python = ">=3.10"+dependencies = [+ "fastmcp>=0.1.0",+]++[project.optional-dependencies]+test = [+ "pytest>=7.0",+ "pytest-asyncio>=0.21",+]++[project.scripts]+better-binary-mcp = "HopperProxyMCP.server:main"++[build-system]+requires = ["setuptools>=64"]+build-backend = "setuptools.backends._legacy:_Backend"diff --git a/requirements.txt b/requirements.txtnew file mode 100644index 000000000..24f02d9de--- /dev/null+++ b/requirements.txt@@ -0,0 +1,3 @@+fastmcp+pytest+pytest-asynciodiff --git a/server.py b/server.pynew file mode 100644index 000000000..78e0427bb--- /dev/null+++ b/server.py@@ -0,0 +1,644 @@+#!/usr/bin/env python3+"""+HopperProxyMCP - Proxy server that wraps the official HopperMCPServer and adds RE-specific tools.++Architecture:+ MCP Client ←STDIO→ Our Proxy Server ←STDIO→ Official HopperMCPServer ←XPC→ Hopper.app+"""++import asyncio+import json+from contextlib import asynccontextmanager+from typing import Any, Optional++from fastmcp import FastMCP, Context+from pydantic import Field++try:+ from hopper_client import HopperMCPSubprocessClient+except ImportError:+ from .hopper_client import HopperMCPSubprocessClient+++OFFICIAL_SERVER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/HopperMCPServer"++_client: Optional[HopperMCPSubprocessClient] = None+++def get_client() -> HopperMCPSubprocessClient:+ global _client+ if _client is None:+ _client = HopperMCPSubprocessClient(OFFICIAL_SERVER_PATH)+ _client.start()+ return _client+++@asynccontextmanager+async def lifespan(server: FastMCP):+ global _client+ _client = HopperMCPSubprocessClient(OFFICIAL_SERVER_PATH)+ _client.start()+ yield+ if _client:+ _client.stop()+ _client = None+++mcp = FastMCP(+ name="HopperProxyMCP",+ instructions=(+ "This server provides reverse engineering tools for analyzing binaries in Hopper Disassembler. "+ "It wraps the official Hopper MCP server and adds Swift/ObjC-specific analysis tools. "+ "Use binary_overview() first to understand the loaded binary, then swift_classes() or "+ "analyze_swift_types() to explore the type hierarchy, and batch_decompile() or "+ "get_call_graph() for deeper analysis."+ ),+ version="1.0.0",+ mask_error_details=True,+ on_duplicate_tools="error",+ lifespan=lifespan,+)+++def _call_official(tool_name: str, arguments: dict = None) -> Any:+ return get_client().call_tool(tool_name, arguments or {})++[email protected](name="address_name")+async def address_name_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to get the name for"),+) -> str:+ result = _call_official("address_name", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="comment")+async def comment_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to get the comment for"),+) -> str:+ result = _call_official("comment", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="current_address")+async def current_address_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("current_address", {"document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="current_procedure")+async def current_procedure_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("current_procedure", {"document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="current_document")+async def current_document_tool() -> str:+ result = _call_official("current_document", {})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="goto_address")+async def goto_address_tool(+ address: str = Field(description="The address to go to"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("goto_address", {"address": address, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="inline_comment")+async def inline_comment_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to get the inline comment for"),+) -> str:+ result = _call_official("inline_comment", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_bookmarks")+async def list_bookmarks_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("list_bookmarks", {"document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_documents")+async def list_documents_tool() -> str:+ result = _call_official("list_documents", {})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_names")+async def list_names_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to start from"),+) -> str:+ result = _call_official("list_names", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_procedures")+async def list_procedures_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("list_procedures", {"document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_segments")+async def list_segments_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("list_segments", {"document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="list_strings")+async def list_strings_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to start from"),+) -> str:+ result = _call_official("list_strings", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="next_address")+async def next_address_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The current address"),+) -> str:+ result = _call_official("next_address", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="prev_address")+async def prev_address_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The current address"),+) -> str:+ result = _call_official("prev_address", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_address")+async def procedure_address_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_address", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_assembly")+async def procedure_assembly_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_assembly", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_callees")+async def procedure_callees_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_callees", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ elif isinstance(result, list):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_callers")+async def procedure_callers_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_callers", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ elif isinstance(result, list):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_info")+async def procedure_info_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_info", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="procedure_pseudo_code")+async def procedure_pseudo_code_tool(+ procedure: str = Field(description="The procedure name or address"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("procedure_pseudo_code", {"procedure": procedure, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="search_procedures")+async def search_procedures_tool(+ pattern: str = Field(description="The regex pattern to search for"),+ case_sensitive: bool = Field(default=False, description="Whether to match case"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("search_procedures", {"pattern": pattern, "case_sensitive": case_sensitive, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="search_strings")+async def search_strings_tool(+ pattern: str = Field(description="The regex pattern to search for"),+ case_sensitive: bool = Field(default=False, description="Whether to match case"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("search_strings", {"pattern": pattern, "case_sensitive": case_sensitive, "document": document})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="set_address_name")+async def set_address_name_tool(+ address: str = Field(description="The address to name"),+ name: str = Field(description="The name to set"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("set_address_name", {"address": address, "name": name, "document": document})+ return "OK" if result else "OK"++[email protected](name="set_addresses_names")+async def set_addresses_names_tool(+ names: dict = Field(description="A dictionary mapping addresses to names"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("set_addresses_names", {"names": names, "document": document})+ return "OK" if result else "OK"++[email protected](name="set_bookmark")+async def set_bookmark_tool(+ address: str = Field(description="The address to bookmark"),+ name: Optional[str] = Field(default=None, description="The bookmark name"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("set_bookmark", {"address": address, "name": name, "document": document})+ return "OK" if result else "OK"++[email protected](name="set_comment")+async def set_comment_tool(+ address: str = Field(description="The address to comment on"),+ comment: str = Field(description="The comment text"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("set_comment", {"address": address, "comment": comment, "document": document})+ return "OK" if result else "OK"++[email protected](name="set_current_document")+async def set_current_document_tool(+ document: str = Field(description="The document name to set as current"),+) -> str:+ result = _call_official("set_current_document", {"document": document})+ return "OK" if result else "OK"++[email protected](name="set_inline_comment")+async def set_inline_comment_tool(+ address: str = Field(description="The address to inline comment on"),+ comment: str = Field(description="The inline comment text"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("set_inline_comment", {"address": address, "comment": comment, "document": document})+ return "OK" if result else "OK"++[email protected](name="unset_bookmark")+async def unset_bookmark_tool(+ address: str = Field(description="The address to remove bookmark from"),+ document: Optional[str] = Field(default=None, description="The document name"),+) -> str:+ result = _call_official("unset_bookmark", {"address": address, "document": document})+ return "OK" if result else "OK"++[email protected](name="xrefs")+async def xrefs_tool(+ document: Optional[str] = Field(default=None, description="The document name"),+ address: Optional[str] = Field(default=None, description="The address to get xrefs for"),+) -> str:+ result = _call_official("xrefs", {"document": document, "address": address})+ if isinstance(result, dict):+ return json.dumps(result, indent=2, default=str)+ elif isinstance(result, list):+ return json.dumps(result, indent=2, default=str)+ return str(result) if result else "OK"++[email protected](name="swift_classes")+async def swift_classes_tool(+ pattern: str = Field(default="", description="Optional pattern to filter class names"),+) -> str:+ all_procs = _call_official("list_procedures", {}) or {}+ if isinstance(all_procs, dict):+ all_procs = all_procs.get("procedures", all_procs)++ swift_classes = []+ for addr, name in list(all_procs.items())[:5000] if isinstance(all_procs, dict) else []:+ if not isinstance(name, str):+ continue+ if name.startswith("_TtC") or "_TtC" in name:+ if pattern and pattern not in name:+ continue+ swift_classes.append({"address": addr, "name": name})++ result = {+ "count": len(swift_classes),+ "classes": swift_classes[:100],+ }+ return json.dumps(result, indent=2, default=str)++[email protected](name="get_objc_classes")+async def get_objc_classes_tool(+ pattern: str = Field(default="", description="Optional pattern to filter class names"),+) -> str:+ names = _call_official("list_names", {}) or {}+ if isinstance(names, dict):+ names = names.get("names", names)++ objc_classes = []+ seen = set()++ for item in names if isinstance(names, list) else []:+ if not isinstance(item, dict):+ continue+ name = item.get("name", "")+ if not isinstance(name, str):+ continue+ if "OBJC_CLASS" in name or "OBJC_$_CLASS" in name or name.startswith("_OBJC_"):+ if pattern and pattern not in name:+ continue+ addr = item.get("address", "")+ if name not in seen:+ seen.add(name)+ objc_classes.append({"address": addr, "name": name})++ result = {+ "count": len(objc_classes),+ "classes": objc_classes[:100],+ }+ return json.dumps(result, indent=2, default=str)++[email protected](name="get_objc_protocols")+async def get_objc_protocols_tool() -> str:+ names = _call_official("list_names", {}) or {}+ if isinstance(names, dict):+ names = names.get("names", names)++ protocols = []+ seen = set()++ for item in names if isinstance(names, list) else []:+ if not isinstance(item, dict):+ continue+ name = item.get("name", "")+ if not isinstance(name, str):+ continue+ if "OBJC_PROTOCOL" in name or "_TtP" in name:+ if name not in seen:+ seen.add(name)+ protocols.append({"address": item.get("address", ""), "name": name})++ result = {+ "count": len(protocols),+ "protocols": protocols[:100],+ }+ return json.dumps(result, indent=2, default=str)++[email protected](name="batch_decompile")+async def batch_decompile_tool(+ addresses: list[str] = Field(default=[], description="List of procedure addresses to decompile"),+) -> str:+ if not addresses:+ return json.dumps({"error": "No addresses provided"}, indent=2)++ addresses = addresses[:20]++ results = {}+ for addr in addresses:+ try:+ pseudo = _call_official("procedure_pseudo_code", {"procedure": addr})+ results[addr] = pseudo if pseudo else "No output"+ except Exception as e:+ results[addr] = f"Error: {str(e)}"++ return json.dumps(results, indent=2, default=str)++[email protected](name="get_call_graph")+async def get_call_graph_tool(+ address: str = Field(description="Starting address for call graph traversal"),+ direction: str = Field(default="forward", description="Traversal direction: 'forward' (callees) or 'backward' (callers)"),+ depth: int = Field(default=2, description="Maximum traversal depth (1-5)"),+) -> str:+ depth = min(max(1, depth), 5)++ visited = set()+ queue = [(address, 0)]+ graph = {}++ while queue:+ current, current_depth = queue.pop(0)++ if current in visited or current_depth >= depth:+ continue+ visited.add(current)++ if current_depth not in graph:+ graph[current_depth] = []++ tool_name = "procedure_callees" if direction == "forward" else "procedure_callers"+ try:+ callees = _call_official(tool_name, {"procedure": current}) or []+ if isinstance(callees, dict):+ callees = callees.get("callees", callees.get("callers", []))+ graph[current_depth].append({"address": current, "calls": callees})++ if current_depth + 1 < depth:+ for callee in callees if isinstance(callees, list) else []:+ if callee not in visited:+ queue.append((callee, current_depth + 1))+ except Exception as e:+ graph[current_depth].append({"address": current, "error": str(e)})++ return json.dumps(graph, indent=2, default=str)++[email protected](name="analyze_swift_types")+async def analyze_swift_types_tool() -> str:+ all_procs = _call_official("list_procedures", {}) or {}+ if isinstance(all_procs, dict):+ all_procs = all_procs.get("procedures", all_procs)++ swift_symbols = {+ "classes": [],+ "structs": [],+ "enums": [],+ "protocols": [],+ "extensions": [],+ "other": [],+ }++ seen = set()++ for addr, name in list(all_procs.items())[:5000] if isinstance(all_procs, dict) else []:+ if not isinstance(name, str) or "_Tt" not in name:+ continue+ if name in seen:+ continue+ seen.add(name)++ entry = {"address": addr, "name": name}++ if name.startswith("_TtC"):+ swift_symbols["classes"].append(entry)+ elif name.startswith("_TtV"):+ swift_symbols["structs"].append(entry)+ elif name.startswith("_TtO"):+ swift_symbols["enums"].append(entry)+ elif name.startswith("_TtP"):+ swift_symbols["protocols"].append(entry)+ elif name.startswith("_TtE"):+ swift_symbols["extensions"].append(entry)+ else:+ swift_symbols["other"].append(entry)++ result = {+ "total": sum(len(v) for v in swift_symbols.values()),+ "categories": {k: {"count": len(v), "items": v[:50]} for k, v in swift_symbols.items()},+ }+ return json.dumps(result, indent=2, default=str)++[email protected](name="find_xrefs_to_name")+async def find_xrefs_to_name_tool(+ name: str = Field(description="Name to search for and get xrefs to"),+) -> str:+ addr_result = _call_official("address_name", {"address": name})+ addr = None++ if isinstance(addr_result, dict):+ addr = addr_result.get("address", addr_result.get("name"))+ elif isinstance(addr_result, str):+ addr = addr_result++ if not addr:+ return json.dumps({"error": f"Could not resolve name: {name}"})++ xrefs = _call_official("xrefs", {"address": addr})++ if isinstance(xrefs, dict):+ pass+ elif isinstance(xrefs, list):+ xrefs = {"xrefs": xrefs}++ return json.dumps(xrefs, indent=2, default=str)++[email protected](name="binary_overview")+async def binary_overview_tool() -> str:+ segments = _call_official("list_segments", {}) or {}+ if isinstance(segments, dict):+ segments = segments.get("segments", segments)++ documents = _call_official("list_documents", {}) or []+ if isinstance(documents, dict):+ documents = documents.get("documents", documents)++ procedures = _call_official("list_procedures", {}) or {}+ if isinstance(procedures, dict):+ procedures = procedures.get("procedures", procedures)+ proc_count = len(procedures) if isinstance(procedures, dict) else "unknown"++ strings = _call_official("list_strings", {}) or {}+ if isinstance(strings, dict):+ strings = strings.get("strings", strings)+ string_count = len(strings) if isinstance(strings, list) else "unknown"++ doc_name = documents[0] if documents else "unknown"++ result = {+ "document": doc_name,+ "segments": [{"name": s.get("name", ""), "start": s.get("start", ""), "end": s.get("end", "")} for s in segments[:10]],+ "segment_count": len(segments) if isinstance(segments, list) else "unknown",+ "procedure_count": proc_count,+ "string_count": string_count,+ }+ return json.dumps(result, indent=2, default=str)+++def main():+ mcp.run()+++if __name__ == "__main__":+ main()diff --git a/tests/__init__.py b/tests/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/tests/test_server.py b/tests/test_server.pynew file mode 100644index 000000000..dea8f2e68--- /dev/null+++ b/tests/test_server.py@@ -0,0 +1,298 @@+#!/usr/bin/env python3+"""+Tests for HopperProxyMCP server with mocked subprocess.+"""++import asyncio+import json+import os+import sys+import pytest+from unittest.mock import MagicMock, patch, AsyncMock++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))+++class MockHopperClient:+ def __init__(self, server_path=None):+ self._server_info = {"name": "HopperMCPServer", "version": "0.1.0"}+ self._started = False+ self._call_history = []++ def start(self):+ self._started = True+ return self._server_info++ def stop(self):+ self._started = False++ def call_tool(self, tool_name, arguments=None):+ arguments = arguments or {}+ self._call_history.append({"tool": tool_name, "args": arguments})++ if tool_name == "list_documents":+ return ["test_binary"]+ elif tool_name == "list_segments":+ return [{"name": "__TEXT", "start": "0x100000000", "end": "0x1000e0000"}]+ elif tool_name == "list_procedures":+ return {+ "0x1040f4124": "-[_TtC6Signal29AccountSettingsViewController viewDidLoad]",+ "0x1040f4150": "_TtC6Signal29AccountSettingsViewController"+ }+ elif tool_name == "procedure_pseudo_code":+ return "func viewDidLoad() { self.setup() }"+ elif tool_name == "search_procedures":+ return {"0x1040f4124": "-[_TtC6Signal29AccountSettingsViewController viewDidLoad]"}+ elif tool_name == "procedure_callees":+ return ["0x1040f4160", "0x1040f4170"]+ elif tool_name == "procedure_callers":+ return ["0x1040f4100"]+ elif tool_name == "list_names":+ return [+ {"address": "0x1000a0000", "name": "_OBJC_CLASS_$_SignalAppDelegate"},+ {"address": "0x1000a0010", "name": "_TtC6Signal11AppDelegate"}+ ]+ elif tool_name == "address_name":+ return {"address": "0x1040f4124", "name": "viewDidLoad"}+ elif tool_name == "xrefs":+ return ["0x1040f4100", "0x1040f4110"]+ elif tool_name == "list_strings":+ return [{"address": "0x100020000", "value": "Hello World"}]+ elif tool_name == "set_comment":+ return "OK"+ elif tool_name == "set_address_name":+ return "OK"+ else:+ return {"result": "ok"}++ @property+ def server_info(self):+ return self._server_info+++def mock_client():+ return MockHopperClient()+++def server_module(mock_client):+ with patch("HopperProxyMCP.hopper_client.HopperMCPSubprocessClient") as mock_class:+ mock_instance = MagicMock()+ mock_instance.start.return_value = {"name": "HopperMCPServer", "version": "0.1.0"}+ mock_instance.stop.return_value = None+ mock_instance.call_tool.side_effect = mock_client.call_tool+ mock_class.return_value = mock_instance++ from fastmcp import Client+ import importlib+ import HopperProxyMCP.server as server_mod+ importlib.reload(server_mod)+ yield server_mod+++class TestProxyTools:+ @pytest.mark.asyncio+ async def test_binary_overview(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("binary_overview", {})+ assert "test_binary" in result.data+ assert "__TEXT" in result.data++ @pytest.mark.asyncio+ async def test_swift_classes(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("swift_classes", {"pattern": ""})+ data = json.loads(result.data)+ assert data["count"] >= 1+ assert any("_TtC" in c["name"] for c in data["classes"])++ @pytest.mark.asyncio+ async def test_get_objc_classes(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("get_objc_classes", {"pattern": ""})+ data = json.loads(result.data)+ assert data["count"] >= 1++ @pytest.mark.asyncio+ async def test_get_objc_protocols(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("get_objc_protocols", {})+ data = json.loads(result.data)+ assert "count" in data++ @pytest.mark.asyncio+ async def test_batch_decompile(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("batch_decompile", {+ "addresses": ["0x1040f4124", "0x1040f4150"]+ })+ data = json.loads(result.data)+ assert "0x1040f4124" in data++ @pytest.mark.asyncio+ async def test_get_call_graph_forward(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("get_call_graph", {+ "address": "0x1040f4124",+ "direction": "forward",+ "depth": 2+ })+ data = json.loads(result.data)+ assert "0" in data or 0 in data++ @pytest.mark.asyncio+ async def test_get_call_graph_backward(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("get_call_graph", {+ "address": "0x1040f4124",+ "direction": "backward",+ "depth": 2+ })+ data = json.loads(result.data)+ assert "0" in data or 0 in data++ @pytest.mark.asyncio+ async def test_analyze_swift_types(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("analyze_swift_types", {})+ data = json.loads(result.data)+ assert "total" in data+ assert "categories" in data++ @pytest.mark.asyncio+ async def test_find_xrefs_to_name(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("find_xrefs_to_name", {+ "name": "viewDidLoad"+ })+ data = json.loads(result.data)+++class TestOfficialToolProxying:+ @pytest.mark.asyncio+ async def test_list_documents(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("list_documents", {})+ assert "test_binary" in result.data++ @pytest.mark.asyncio+ async def test_list_segments(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("list_segments", {})+ assert "__TEXT" in result.data++ @pytest.mark.asyncio+ async def test_list_procedures(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("list_procedures", {})+ assert "_TtC" in result.data++ @pytest.mark.asyncio+ async def test_procedure_pseudo_code(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("procedure_pseudo_code", {+ "procedure": "0x1040f4124"+ })+ assert "viewDidLoad" in result.data++ @pytest.mark.asyncio+ async def test_search_procedures(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("search_procedures", {+ "pattern": "viewDidLoad",+ "case_sensitive": False+ })+ assert "viewDidLoad" in result.data++ @pytest.mark.asyncio+ async def test_procedure_callees(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("procedure_callees", {+ "procedure": "0x1040f4124"+ })+ assert "0x1040f4160" in result.data or "0x1040f4170" in result.data++ @pytest.mark.asyncio+ async def test_procedure_callers(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("procedure_callers", {+ "procedure": "0x1040f4124"+ })+ assert "0x1040f4100" in result.data++ @pytest.mark.asyncio+ async def test_list_names(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("list_names", {})+ assert "_OBJC_CLASS_" in result.data or "_TtC" in result.data++ @pytest.mark.asyncio+ async def test_address_name(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("address_name", {+ "address": "0x1040f4124"+ })+ assert "viewDidLoad" in result.data++ @pytest.mark.asyncio+ async def test_xrefs(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("xrefs", {+ "address": "0x1040f4124"+ })+ assert "0x1040f4100" in result.data++ @pytest.mark.asyncio+ async def test_set_comment(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("set_comment", {+ "address": "0x1040f4124",+ "comment": "Test comment",+ "document": "test_binary"+ })+ assert result.data in ["OK", '{"result": "ok"}']++ @pytest.mark.asyncio+ async def test_set_address_name(self, server_module, mock_client):+ from fastmcp import Client+ async with Client(server_module.mcp) as client:+ result = await client.call_tool("set_address_name", {+ "address": "0x1040f4124",+ "name": "myFunction",+ "document": "test_binary"+ })+ assert result.data in ["OK", '{"result": "ok"}']+++class TestMockClient:+ def test_call_history(self, mock_client):+ mock_client.call_tool("list_documents")+ mock_client.call_tool("list_segments")+ assert len(mock_client._call_history) == 2+ assert mock_client._call_history[0]["tool"] == "list_documents"+ assert mock_client._call_history[1]["tool"] == "list_segments"+++if __name__ == "__main__":+ pytest.main([__file__, "-v"])