ida-pro-mcp-xjoker 1.0.1__tar.gz → 1.0.2__tar.gz

ida_pro_mcp_xjoker-1.0.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: ida-pro-mcp-xjoker
+Version: 1.0.2
+Summary: Vibe reversing with IDA Pro (enhanced fork)
+Author: mrexodia, can1357, IDA Pro MCP Contributors
+Maintainer: xjoker
+Project-URL: Repository, https://github.com/xjoker/ida-pro-mcp
+Project-URL: Issues, https://github.com/xjoker/ida-pro-mcp/issues
+Keywords: ida,mcp,llm,plugin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: idapro>=0.0.7
+Requires-Dist: tomli-w>=1.0.0
+Dynamic: license-file
+
+# IDA Pro MCP (Enhanced Fork)
+
+[中文文档](https://github.com/xjoker/ida-pro-mcp/blob/main/README_zh.md) | English
+
+[![PyPI](https://img.shields.io/pypi/v/ida-pro-mcp-xjoker)](https://pypi.org/project/ida-pro-mcp-xjoker/)
+[![Python](https://img.shields.io/pypi/pyversions/ida-pro-mcp-xjoker)](https://pypi.org/project/ida-pro-mcp-xjoker/)
+
+An enhanced fork of [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) - MCP Server for LLM-assisted reverse engineering in IDA Pro.
+
+## What's Different from Original
+
+| Feature | Original | This Fork |
+|---------|----------|-----------|
+| **Multi-instance Support** | ❌ Port conflict crashes | ✅ Auto port increment (13337→13346) |
+| **Web Configuration** | ❌ None | ✅ Bilingual UI at `/config.html` |
+| **API Key Auth** | ❌ None | ✅ Bearer token + env var support |
+| **Server Startup** | Manual hotkey | ✅ Auto-start on IDA launch |
+| **Hotkey Conflicts** | Occupies Ctrl+Alt+M | ✅ No hotkey, menu-only |
+| **Config Persistence** | None | ✅ Saved per IDB database |
+
+### Key Enhancements
+
+- **Port Conflict Auto-Retry**: Multiple IDA instances automatically use different ports
+- **Web Config UI**: `http://localhost:13337/config.html` with English/中文 interface
+- **API Key Authentication**: Secure remote access with Bearer token
+- **Bug Fixes**: Thread safety, regex handling, type parsing errors fixed
+
+## Installation
+
+```bash
+pip install ida-pro-mcp-xjoker
+ida-pro-mcp --install
+```
+
+Restart IDA Pro completely after installation.
+
+## Quick Start
+
+1. Open a binary in IDA Pro
+2. MCP server starts automatically on `http://127.0.0.1:13337`
+3. Configure your MCP client:
+
+```bash
+# Claude Code
+claude mcp add ida-pro-mcp http://127.0.0.1:13337/mcp
+
+# With API Key authentication
+claude mcp add --transport http ida-pro-mcp http://127.0.0.1:13337/mcp \
+  --header "Authorization: Bearer your-api-key"
+```
+
+4. Open web config at `http://127.0.0.1:13337/config.html` to customize settings
+
+## Requirements
+
+- Python 3.11+
+- IDA Pro 8.3+ (9.0 recommended), **IDA Free not supported**
+- Any [MCP-compatible client](https://modelcontextprotocol.io/clients)
+
+## API Overview
+
+**71 MCP Tools** including:
+
+| Category | Tools |
+|----------|-------|
+| Analysis | `decompile`, `disasm`, `xrefs_to`, `callees`, `callers`, `basic_blocks` |
+| Memory | `get_bytes`, `get_string`, `get_int`, `patch` |
+| Types | `declare_type`, `set_type`, `infer_types`, `read_struct` |
+| Modify | `set_comments`, `rename`, `patch_asm` |
+| Search | `find_bytes`, `find_insns`, `find_regex` |
+| Debug | `dbg_*` (20+ debugger tools, enable with `?ext=dbg`) |
+| Python | `py_eval` - execute Python in IDA context |
+
+**24 MCP Resources** for read-only access:
+- `ida://idb/metadata`, `ida://cursor`, `ida://structs`, `ida://xrefs/from/{addr}`, etc.
+
+## Headless Mode
+
+```bash
+# SSE transport
+ida-pro-mcp --transport http://127.0.0.1:8744/sse
+
+# With idalib (no GUI)
+idalib-mcp --host 127.0.0.1 --port 8745 /path/to/binary
+```
+
+## Links
+
+- [Original Project](https://github.com/mrexodia/ida-pro-mcp) by mrexodia
+- [Changelog](https://github.com/xjoker/ida-pro-mcp/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/xjoker/ida-pro-mcp/issues)
+
+## License
+
+MIT - Same as original project

ida_pro_mcp_xjoker-1.0.2/README.md

@@ -0,0 +1,95 @@
+# IDA Pro MCP (Enhanced Fork)
+
+[中文文档](https://github.com/xjoker/ida-pro-mcp/blob/main/README_zh.md) | English
+
+[![PyPI](https://img.shields.io/pypi/v/ida-pro-mcp-xjoker)](https://pypi.org/project/ida-pro-mcp-xjoker/)
+[![Python](https://img.shields.io/pypi/pyversions/ida-pro-mcp-xjoker)](https://pypi.org/project/ida-pro-mcp-xjoker/)
+
+An enhanced fork of [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) - MCP Server for LLM-assisted reverse engineering in IDA Pro.
+
+## What's Different from Original
+
+| Feature | Original | This Fork |
+|---------|----------|-----------|
+| **Multi-instance Support** | ❌ Port conflict crashes | ✅ Auto port increment (13337→13346) |
+| **Web Configuration** | ❌ None | ✅ Bilingual UI at `/config.html` |
+| **API Key Auth** | ❌ None | ✅ Bearer token + env var support |
+| **Server Startup** | Manual hotkey | ✅ Auto-start on IDA launch |
+| **Hotkey Conflicts** | Occupies Ctrl+Alt+M | ✅ No hotkey, menu-only |
+| **Config Persistence** | None | ✅ Saved per IDB database |
+
+### Key Enhancements
+
+- **Port Conflict Auto-Retry**: Multiple IDA instances automatically use different ports
+- **Web Config UI**: `http://localhost:13337/config.html` with English/中文 interface
+- **API Key Authentication**: Secure remote access with Bearer token
+- **Bug Fixes**: Thread safety, regex handling, type parsing errors fixed
+
+## Installation
+
+```bash
+pip install ida-pro-mcp-xjoker
+ida-pro-mcp --install
+```
+
+Restart IDA Pro completely after installation.
+
+## Quick Start
+
+1. Open a binary in IDA Pro
+2. MCP server starts automatically on `http://127.0.0.1:13337`
+3. Configure your MCP client:
+
+```bash
+# Claude Code
+claude mcp add ida-pro-mcp http://127.0.0.1:13337/mcp
+
+# With API Key authentication
+claude mcp add --transport http ida-pro-mcp http://127.0.0.1:13337/mcp \
+  --header "Authorization: Bearer your-api-key"
+```
+
+4. Open web config at `http://127.0.0.1:13337/config.html` to customize settings
+
+## Requirements
+
+- Python 3.11+
+- IDA Pro 8.3+ (9.0 recommended), **IDA Free not supported**
+- Any [MCP-compatible client](https://modelcontextprotocol.io/clients)
+
+## API Overview
+
+**71 MCP Tools** including:
+
+| Category | Tools |
+|----------|-------|
+| Analysis | `decompile`, `disasm`, `xrefs_to`, `callees`, `callers`, `basic_blocks` |
+| Memory | `get_bytes`, `get_string`, `get_int`, `patch` |
+| Types | `declare_type`, `set_type`, `infer_types`, `read_struct` |
+| Modify | `set_comments`, `rename`, `patch_asm` |
+| Search | `find_bytes`, `find_insns`, `find_regex` |
+| Debug | `dbg_*` (20+ debugger tools, enable with `?ext=dbg`) |
+| Python | `py_eval` - execute Python in IDA context |
+
+**24 MCP Resources** for read-only access:
+- `ida://idb/metadata`, `ida://cursor`, `ida://structs`, `ida://xrefs/from/{addr}`, etc.
+
+## Headless Mode
+
+```bash
+# SSE transport
+ida-pro-mcp --transport http://127.0.0.1:8744/sse
+
+# With idalib (no GUI)
+idalib-mcp --host 127.0.0.1 --port 8745 /path/to/binary
+```
+
+## Links
+
+- [Original Project](https://github.com/mrexodia/ida-pro-mcp) by mrexodia
+- [Changelog](https://github.com/xjoker/ida-pro-mcp/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/xjoker/ida-pro-mcp/issues)
+
+## License
+
+MIT - Same as original project

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ida-pro-mcp-xjoker"
-version = "1.0.1"
+version = "1.0.2"
 description = "Vibe reversing with IDA Pro (enhanced fork)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,6 +9,9 @@ authors = [
     { name = "can1357" },
     { name = "IDA Pro MCP Contributors" },
 ]
+maintainers = [
+    { name = "xjoker" },
+]
 keywords = ["ida", "mcp", "llm", "plugin"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -50,7 +53,7 @@ dev = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.0.1"
+version = "1.0.2"
 version_files = [
     "pyproject.toml:^version"
 ]

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/api_analysis.py

@@ -13,6 +13,7 @@ import ida_idaapi
 import ida_xref
 import ida_ua
 import ida_name
+import ida_idp
 from .rpc import tool
 from .sync import idasync, tool_timeout
 from .cache import decompile_cache, xrefs_cache
@@ -503,7 +504,8 @@ def callees(
                         break
                     current_ea = next_ea
                     continue
-                if insn.itype in [idaapi.NN_call, idaapi.NN_callfi, idaapi.NN_callni]:
+                # Use architecture-independent call instruction detection
+                if ida_idp.is_call_insn(insn):
                     op0 = insn.ops[0]
                     if op0.type in (ida_ua.o_mem, ida_ua.o_near, ida_ua.o_far):
                         target = op0.addr

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/api_core.py

@@ -10,7 +10,7 @@ import ida_nalt
 
 from .rpc import tool
 from .sync import idasync
-from .cache import function_cache, string_cache
+from .cache import function_cache
 
 # Cached strings list: [(ea, text), ...]
 _strings_cache: list[tuple[int, str]] | None = None

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/auth.py

@@ -3,11 +3,14 @@
 Provides authentication middleware for MCP server with support for:
 - Bearer token authentication (Authorization: Bearer <key>)
 - X-API-Key header authentication
+- Environment variable expansion (${ENV_VAR} syntax)
 - Timing-attack resistant comparison
 """
 
 import hmac
 import logging
+import os
+import re
 from typing import Optional, Callable
 
 logger = logging.getLogger(__name__)
@@ -18,6 +21,33 @@ AUTH_EXEMPT_PATHS = frozenset({
     "/config.html",
 })
 
+# Pattern to match ${ENV_VAR} syntax
+_ENV_VAR_PATTERN = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
+
+
+def resolve_env_var(value: Optional[str]) -> Optional[str]:
+    """Resolve environment variable reference in ${VAR} format.
+
+    Args:
+        value: The value to resolve, may be a literal or ${ENV_VAR} reference
+
+    Returns:
+        The resolved value (from environment) or the original value if not a reference
+    """
+    if not value:
+        return value
+
+    match = _ENV_VAR_PATTERN.match(value.strip())
+    if match:
+        env_name = match.group(1)
+        env_value = os.environ.get(env_name)
+        if env_value:
+            return env_value
+        else:
+            logger.warning(f"Environment variable '{env_name}' not found, using literal value")
+            return None  # Env var not set, disable auth
+    return value
+
 
 def check_api_key(provided_key: Optional[str], expected_key: Optional[str]) -> bool:
     """Compare API keys using constant-time comparison to prevent timing attacks.
@@ -100,23 +130,29 @@ class AuthMiddleware:
 
         Args:
             api_key: The expected API key (None = no authentication)
+                     Supports ${ENV_VAR} syntax to reference environment variables
             enabled: Whether authentication is enabled
         """
-        self._api_key = api_key
+        self._api_key_raw = api_key  # Store original value (may be ${ENV_VAR})
         self._enabled = enabled and api_key is not None
 
     @property
     def enabled(self) -> bool:
         return self._enabled
 
+    @property
+    def _api_key(self) -> Optional[str]:
+        """Get the resolved API key (expands ${ENV_VAR} references)."""
+        return resolve_env_var(self._api_key_raw)
+
     def update_key(self, api_key: Optional[str], enabled: bool = True) -> None:
         """Update the API key configuration.
 
         Args:
-            api_key: New API key
+            api_key: New API key (supports ${ENV_VAR} syntax)
             enabled: Whether to enable authentication
         """
-        self._api_key = api_key
+        self._api_key_raw = api_key
         self._enabled = enabled and api_key is not None
 
     def authenticate(self, path: str, headers: dict) -> bool:
@@ -160,6 +196,7 @@ __all__ = [
     "check_api_key",
     "extract_api_key_from_headers",
     "is_path_exempt",
+    "resolve_env_var",
     "AuthMiddleware",
     "create_auth_check",
     "AUTH_EXEMPT_PATHS",

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/framework.py

@@ -340,6 +340,7 @@ def get_functions_with_calls() -> list[str]:
     """
     import idaapi
     import idautils
+    import ida_idp
 
     result = []
     for func_ea in idautils.Functions():
@@ -352,7 +353,8 @@ def get_functions_with_calls() -> list[str]:
         for head in idautils.Heads(func.start_ea, func.end_ea):
             insn = idaapi.insn_t()
             if idaapi.decode_insn(insn, head) > 0:
-                if insn.itype in [idaapi.NN_call, idaapi.NN_callfi, idaapi.NN_callni]:
+                # Use architecture-independent call instruction detection
+                if ida_idp.is_call_insn(insn):
                     has_call = True
                     break
 

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/server_manager.py

@@ -11,7 +11,7 @@ import threading
 from dataclasses import dataclass, field
 from typing import Optional, Callable, TYPE_CHECKING
 
-from .config import ServerInstanceConfig, McpConfig, get_config, save_config
+from .config import ServerInstanceConfig, McpConfig, get_config
 from .auth import AuthMiddleware
 from .port_utils import try_serve_with_port_retry
 

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/sync.py

@@ -107,11 +107,14 @@ def _sync_wrapper(ff):
             raise IDASyncError(error_str)
 
         call_stack.put((ff.__name__))
+        # Enable batch mode for all synchronized operations
+        old_batch = idc.batch(1)
         try:
             res_container.put(ff())
         except Exception as x:
             res_container.put(x)
         finally:
+            idc.batch(old_batch)
             call_stack.get()
 
     idaapi.execute_sync(runned, idaapi.MFF_WRITE)
@@ -132,21 +135,14 @@ def _normalize_timeout(value: object) -> float | None:
 
 
 def sync_wrapper(ff, timeout_override: float | None = None):
-    """Wrapper to enable batch mode during IDA synchronization."""
+    """Wrapper to enable timeout and cancellation during IDA synchronization.
+
+    Note: Batch mode is handled in _sync_wrapper to ensure it's always
+    applied consistently for all synchronized operations.
+    """
     # Capture cancel event from thread-local before execute_sync
     cancel_event = get_current_cancel_event()
 
-    def _run_with_batch(inner_ff):
-        def _wrapped():
-            old_batch = idc.batch(1)
-            try:
-                return inner_ff()
-            finally:
-                idc.batch(old_batch)
-
-        _wrapped.__name__ = inner_ff.__name__
-        return _wrapped
-
     timeout = timeout_override
     if timeout is None:
         timeout = _get_tool_timeout_seconds()
@@ -172,8 +168,8 @@ def sync_wrapper(ff, timeout_override: float | None = None):
                 sys.setprofile(old_profile)
 
         timed_ff.__name__ = ff.__name__
-        return _sync_wrapper(_run_with_batch(timed_ff))
-    return _sync_wrapper(_run_with_batch(ff))
+        return _sync_wrapper(timed_ff)
+    return _sync_wrapper(ff)
 
 
 def idasync(f):

ida_pro_mcp_xjoker-1.0.2/src/ida_pro_mcp/ida_mcp/tests/__init__.py

@@ -0,0 +1,14 @@
+"""IDA Pro MCP Test Package.
+
+This package contains test modules for each API module.
+Tests are registered via the @test decorator from the framework module.
+"""
+
+# Import all test modules to register tests when the package is imported
+from . import test_api_core as test_api_core
+from . import test_api_analysis as test_api_analysis
+from . import test_api_memory as test_api_memory
+from . import test_api_modify as test_api_modify
+from . import test_api_types as test_api_types
+from . import test_api_stack as test_api_stack
+from . import test_api_resources as test_api_resources

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/tests/test_api_resources.py

@@ -145,7 +145,7 @@ def test_resource_struct_name():
 def test_resource_struct_name_not_found():
     """struct_name_resource handles non-existent structure"""
     try:
-        result = struct_name_resource("NonExistentStruct12345")
+        struct_name_resource("NonExistentStruct12345")
         # Should return error or empty
     except IDAError:
         pass  # Expected for non-existent struct

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/ui.py

@@ -10,7 +10,6 @@ from typing import Optional, TYPE_CHECKING
 
 from .config import (
     ServerInstanceConfig,
-    McpConfig,
     get_config,
     save_config,
     reload_config,
@@ -34,9 +33,9 @@ class ServerConfigForm(idaapi.Form):
         instance_id = "" if is_new else config.instance_id
         host = "127.0.0.1" if is_new else config.host
         port = 13337 if is_new else config.port
-        auth_enabled = False if is_new else config.auth_enabled
+        _ = False if is_new else config.auth_enabled  # Reserved for future use
         api_key = "" if is_new else (config.api_key or "")
-        auto_start = False if is_new else config.auto_start
+        _ = False if is_new else config.auto_start  # Reserved for future use
 
         form_template = r"""STARTITEM 0
 BUTTON YES* Save

{ida_pro_mcp_xjoker-1.0.1 → ida_pro_mcp_xjoker-1.0.2}/src/ida_pro_mcp/ida_mcp/utils.py

@@ -22,6 +22,7 @@ from typing import (
 
 import ida_funcs
 import ida_hexrays
+import ida_idp
 import ida_kernwin
 import ida_nalt
 import ida_typeinf
@@ -1022,7 +1023,8 @@ def get_callees(addr: str) -> list[dict]:
         while current_ea < func_end:
             insn = idaapi.insn_t()
             idaapi.decode_insn(insn, current_ea)
-            if insn.itype in [idaapi.NN_call, idaapi.NN_callfi, idaapi.NN_callni]:
+            # Use architecture-independent call instruction detection
+            if ida_idp.is_call_insn(insn):
                 target = idc.get_operand_value(current_ea, 0)
                 target_type = idc.get_operand_type(current_ea, 0)
                 if target_type in [idaapi.o_mem, idaapi.o_near, idaapi.o_far]:
@@ -1064,11 +1066,8 @@ def get_callers(addr: str, limit: int = 50) -> list[Function]:
                 continue
             insn = idaapi.insn_t()
             idaapi.decode_insn(insn, caller_addr)
-            if insn.itype not in [
-                idaapi.NN_call,
-                idaapi.NN_callfi,
-                idaapi.NN_callni,
-            ]:
+            # Use architecture-independent call instruction detection
+            if not ida_idp.is_call_insn(insn):
                 continue
             callers[func["addr"]] = func