ida-code 0.2.1__py3-none-any.whl

ida_code/undo.py

@@ -0,0 +1,102 @@
+import logging
+
+from fastmcp.exceptions import ToolError
+
+from ida_code import session
+
+log = logging.getLogger(__name__)
+
+
+def get_status() -> dict:
+    """Return current undo/redo availability and action labels."""
+    session.require_open()
+
+    import ida_undo
+
+    undo_label = ida_undo.get_undo_action_label() or ""
+    redo_label = ida_undo.get_redo_action_label() or ""
+
+    return {
+        "can_undo": bool(undo_label),
+        "undo_action": undo_label,
+        "can_redo": bool(redo_label),
+        "redo_action": redo_label,
+    }
+
+
+def perform_undo(steps: int = 1) -> dict:
+    """Undo the last action(s). Returns details of what was undone."""
+    session.require_open()
+
+    if steps < 1:
+        raise ToolError("steps must be at least 1.")
+
+    import ida_undo
+
+    undo_label = ida_undo.get_undo_action_label() or ""
+    if not undo_label:
+        raise ToolError("Nothing to undo.")
+
+    actions: list[str] = []
+    for _ in range(steps):
+        label = ida_undo.get_undo_action_label() or ""
+        if not label:
+            break
+        ida_undo.perform_undo()
+        actions.append(label)
+
+    # Database state changed — reset executor namespace.
+    from ida_code.executor import reset
+    reset()
+
+    undo_next = ida_undo.get_undo_action_label() or ""
+    redo_next = ida_undo.get_redo_action_label() or ""
+
+    log.info("Undo %d/%d steps: %s", len(actions), steps, actions)
+    return {
+        "status": "undone",
+        "steps_requested": steps,
+        "steps_performed": len(actions),
+        "actions": actions,
+        "next_undo": undo_next,
+        "next_redo": redo_next,
+    }
+
+
+def perform_redo(steps: int = 1) -> dict:
+    """Redo the last undone action(s). Returns details of what was redone."""
+    session.require_open()
+
+    if steps < 1:
+        raise ToolError("steps must be at least 1.")
+
+    import ida_undo
+
+    redo_label = ida_undo.get_redo_action_label() or ""
+    if not redo_label:
+        raise ToolError("Nothing to redo.")
+
+    actions: list[str] = []
+    for _ in range(steps):
+        label = ida_undo.get_redo_action_label() or ""
+        if not label:
+            break
+        ida_undo.perform_redo()
+        actions.append(label)
+
+    # Database state changed — reset executor namespace.
+    from ida_code.executor import reset
+    reset()
+
+    undo_next = ida_undo.get_undo_action_label() or ""
+    redo_next = ida_undo.get_redo_action_label() or ""
+
+    log.info("Redo %d/%d steps: %s", len(actions), steps, actions)
+    return {
+        "status": "redone",
+        "steps_requested": steps,
+        "steps_performed": len(actions),
+        "actions": actions,
+        "next_undo": undo_next,
+        "next_redo": redo_next,
+    }

ida_code/variables.py

@@ -0,0 +1,206 @@
+"""Variable inspection and modification (local/decompiler and global)."""
+
+import logging
+
+from fastmcp.exceptions import ToolError
+
+from ida_code import session
+
+log = logging.getLogger(__name__)
+
+
+def _decompile_func(func_ea: int):
+    """Decompile the function at *func_ea*, returning a cfunc_t.
+
+    Raises ToolError if Hex-Rays is unavailable or decompilation fails.
+    """
+    try:
+        import ida_hexrays
+    except ImportError:
+        raise ToolError("Hex-Rays decompiler is not available.")
+
+    import ida_funcs
+
+    pfn = ida_funcs.get_func(func_ea)
+    if pfn is None:
+        raise ToolError(f"Address {func_ea:#x} is not within a recognized function.")
+
+    try:
+        cfunc = ida_hexrays.decompile(pfn.start_ea)
+    except ida_hexrays.DecompilationFailure as e:
+        raise ToolError(f"Decompilation failed: {e}")
+    except Exception as e:
+        raise ToolError(f"{type(e).__name__}: {e}")
+
+    if cfunc is None:
+        raise ToolError("Decompilation returned no result.")
+    return cfunc
+
+
+def _find_lvar(cfunc, name: str):
+    """Find a local variable by name in *cfunc*.lvars.
+
+    Raises ToolError if not found, listing available names.
+    """
+    for lv in cfunc.lvars:
+        if lv.name == name:
+            return lv
+
+    available = [lv.name for lv in cfunc.lvars if lv.name]
+    raise ToolError(
+        f"Local variable '{name}' not found. "
+        f"Available: {available}"
+    )
+
+
+def _lvar_to_dict(lv, func_ea: int) -> dict:
+    """Convert a local variable (lvar_t) to a result dict."""
+    import ida_funcs
+
+    func_name = ida_funcs.get_func_name(func_ea) or f"sub_{func_ea:x}"
+    return {
+        "name": lv.name,
+        "type": str(lv.type()),
+        "width": lv.width,
+        "is_arg": lv.is_arg_var,
+        "function": func_name,
+        "scope": "local",
+    }
+
+
+def _global_to_dict(ea: int) -> dict:
+    """Convert a global address to a result dict."""
+    import ida_name
+    import ida_nalt
+    import ida_typeinf
+    import idc
+
+    name = ida_name.get_name(ea) or f"unk_{ea:x}"
+
+    # Try to get type info.
+    tif = ida_typeinf.tinfo_t()
+    if ida_nalt.get_tinfo(tif, ea):
+        type_str = str(tif)
+    else:
+        type_str = idc.get_type(ea) or ""
+
+    return {
+        "name": name,
+        "type": type_str,
+        "address": f"{ea:#x}",
+        "scope": "global",
+    }
+
+
+def _parse_type(type_str: str):
+    """Parse a C type string into a tinfo_t.
+
+    Raises ToolError if parsing fails.
+    """
+    import ida_typeinf
+
+    tif = ida_typeinf.tinfo_t()
+    til = ida_typeinf.get_idati()
+    decl = f"{type_str} __dummy;"
+    if not ida_typeinf.parse_decl(tif, til, decl, ida_typeinf.PT_SIL):
+        raise ToolError(f"Failed to parse type: '{type_str}'")
+    return tif
+
+
+def get_local_variable(func_ea: int, name: str) -> dict:
+    """Get info about a local (decompiler) variable."""
+    session.require_open()
+
+    cfunc = _decompile_func(func_ea)
+    lv = _find_lvar(cfunc, name)
+    return _lvar_to_dict(lv, func_ea)
+
+
+def get_global_variable(ea: int) -> dict:
+    """Get info about a global variable/name at *ea*."""
+    session.require_open()
+    return _global_to_dict(ea)
+
+
+def set_local_variable(
+    func_ea: int,
+    name: str,
+    new_name: str | None = None,
+    new_type: str | None = None,
+) -> dict:
+    """Rename and/or retype a local (decompiler) variable."""
+    session.require_open()
+
+    import ida_hexrays
+    import ida_funcs
+
+    pfn = ida_funcs.get_func(func_ea)
+    if pfn is None:
+        raise ToolError(f"Address {func_ea:#x} is not within a recognized function.")
+    start_ea = pfn.start_ea
+
+    # Verify the variable exists first.
+    cfunc = _decompile_func(func_ea)
+    _find_lvar(cfunc, name)
+
+    if new_name is not None:
+        ok = ida_hexrays.rename_lvar(start_ea, name, new_name)
+        if not ok:
+            raise ToolError(f"Failed to rename local variable '{name}' to '{new_name}'.")
+        log.info("Renamed local variable '%s' -> '%s' in func at %#x", name, new_name, start_ea)
+
+    if new_type is not None:
+        tif = _parse_type(new_type)
+        lsi = ida_hexrays.lvar_saved_info_t()
+        current_name = new_name if new_name is not None else name
+        lsi.name = current_name
+        lsi.type = tif
+        lsi.size = tif.get_size()
+        lsi.flags = ida_hexrays.LVINF_TYPE
+
+        # Find the lvar to get its location info.
+        cfunc2 = _decompile_func(func_ea)
+        lv = _find_lvar(cfunc2, current_name)
+        lsi.ll = lv.location
+
+        ok = ida_hexrays.modify_user_lvar_info(start_ea, ida_hexrays.MLI_TYPE, lsi)
+        if not ok:
+            raise ToolError(f"Failed to retype local variable '{current_name}' to '{new_type}'.")
+        log.info("Retyped local variable '%s' to '%s' in func at %#x", current_name, new_type, start_ea)
+
+    # Re-decompile and return updated info.
+    final_name = new_name if new_name is not None else name
+    cfunc_final = _decompile_func(func_ea)
+    lv_final = _find_lvar(cfunc_final, final_name)
+    result = _lvar_to_dict(lv_final, func_ea)
+    result["status"] = "modified"
+    return result
+
+
+def set_global_variable(
+    ea: int,
+    new_name: str | None = None,
+    new_type: str | None = None,
+) -> dict:
+    """Rename and/or retype a global variable/name."""
+    session.require_open()
+
+    import ida_name
+    import ida_typeinf
+
+    if new_name is not None:
+        ok = ida_name.set_name(ea, new_name, ida_name.SN_CHECK)
+        if not ok:
+            raise ToolError(f"Failed to rename global at {ea:#x} to '{new_name}'.")
+        log.info("Renamed global at %#x -> '%s'", ea, new_name)
+
+    if new_type is not None:
+        tif = _parse_type(new_type)
+        ok = ida_typeinf.apply_tinfo(ea, tif, ida_typeinf.TINFO_DEFINITE)
+        if not ok:
+            raise ToolError(f"Failed to retype global at {ea:#x} to '{new_type}'.")
+        log.info("Retyped global at %#x to '%s'", ea, new_type)
+
+    result = _global_to_dict(ea)
+    result["status"] = "modified"
+    return result

ida_code-0.2.1.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: ida-code
+Version: 0.2.1
+Summary: MCP server for AI-assisted IDAPython scripting via idalib
+Project-URL: Homepage, https://github.com/Dil4rd/ida-code
+Project-URL: Repository, https://github.com/Dil4rd/ida-code
+Project-URL: Issues, https://github.com/Dil4rd/ida-code/issues
+Project-URL: Changelog, https://github.com/Dil4rd/ida-code/blob/main/CHANGELOG.md
+Author: Dil4rd
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ida,ida-pro,idalib,idapython,mcp,reverse-engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: lief>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ida-code
+
+MCP server that lets AI coding agents interact with IDA Pro. Open binaries, decompile, run IDAPython, search the API docs — all through tool calls.
+
+Built on [idalib](https://docs.hex-rays.com/developer-guide/idalib) for headless in-process operation and [fastmcp](https://github.com/jlowin/fastmcp) for the MCP transport.
+
+> **Requires** a licensed IDA Pro 9.2+ with idalib support. `ida-code` does not install or replace IDA Pro — it loads `idapro` from your existing install at startup.
+
+## Install
+
+```bash
+uv tool install ida-code
+```
+
+This puts the `ida-code` CLI on your `PATH` (via `uv`'s tool dir) so MCP clients can launch it directly. Don't have uv? `pip install ida-code` works too.
+
+Then point `IDA_INSTALL_DIR` at your IDA Pro install (the directory that contains `idalib/python/`):
+
+| OS | Typical path |
+|---|---|
+| Linux | `/opt/ida-pro-9.3` |
+| macOS | `/Applications/IDA Professional 9.3.app/Contents/MacOS` |
+| Windows | `C:\Program Files\IDA Professional 9.3` |
+
+## Use with Claude Code
+
+Add `ida-code` to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ida-code": {
+      "command": "ida-code",
+      "env": {
+        "IDA_INSTALL_DIR": "/opt/ida-pro-9.3"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code; the server is picked up automatically. You can confirm it's wired up by asking Claude to open a binary — it should call `open_database` and report architecture, entry point, and load address.
+
+For other MCP clients, run the server directly:
+
+```bash
+IDA_INSTALL_DIR=/opt/ida-pro-9.3 ida-code   # stdio transport
+```
+
+## Tools (35)
+
+Full parameter docs live in each tool's docstring — surfaced automatically to MCP clients via `tools/list`.
+
+| Domain | Tools |
+|---|---|
+| Database | `open_database`, `close_database`, `get_database_info`, `list_architectures` |
+| Code execution | `execute`, `execute_file` |
+| Navigation | `list_functions`, `decompile`, `get_disassembly`, `get_xrefs_to`, `get_xrefs_from` |
+| Annotation | `rename_function`, `retype_function`, `get_comment`, `set_comment`, `delete_comment`, `get_variable`, `set_variable` |
+| Structures | `list_structures`, `get_structure`, `create_structure`, `edit_structure`, `delete_structure` |
+| Snapshots | `list_snapshots`, `create_snapshot`, `restore_snapshot`, `delete_snapshot` |
+| Undo/redo | `get_undo_status`, `perform_undo`, `perform_redo` |
+| Inventory | `get_strings`, `get_imports`, `get_exports` |
+| Search | `search_docs`, `search_examples` |
+
+## Resources & prompts
+
+| Type | URI / name | Purpose |
+|---|---|---|
+| Resource | `guidelines://standalone_script` | Boilerplate for standalone idalib scripts |
+| Resource | `guidelines://plugin` | Boilerplate for IDA plugins (`plugin_t`) |
+| Resource | `guidelines://idapython_script` | Boilerplate for IDAPython scripts run inside IDA GUI |
+| Prompt | `reverse_engineer` | Five-phase RE workflow (recon, triage, analysis, annotation, iteration) |
+| Prompt | `create_script` | Coding guidelines for a chosen target script type |
+
+## Transport modes
+
+```bash
+ida-code                          # stdio (default)
+ida-code --http                   # streamable-http on 127.0.0.1:8080
+ida-code --http 0.0.0.0:9090      # custom host:port
+ida-code --sse                    # SSE on 127.0.0.1:8080
+ida-code --sse :9090              # SSE on 127.0.0.1:9090
+```
+
+HTTP/SSE require bearer token auth. Set `MCP_AUTH_TOKEN` or let the server generate one (printed to stderr on startup).
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `IDA_INSTALL_DIR` | `/opt/ida-pro-9.3` | IDA Pro installation directory (must contain `idalib/python/`) |
+| `LOG_LEVEL` | `WARNING` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
+| `MCP_AUTH_TOKEN` | (auto-generated) | Bearer token for HTTP/SSE transports |
+
+Doc and example paths are derived from `IDA_INSTALL_DIR` (`docs/`, `python/`, `python/examples/`).
+
+## Install from source
+
+```bash
+git clone https://github.com/Dil4rd/ida-code
+cd ida-code
+uv sync
+uv run ida-code
+```
+
+When wiring a source checkout into `.mcp.json`, use `uv` as the command:
+
+```json
+{
+  "mcpServers": {
+    "ida-code": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ida-code", "ida-code"],
+      "env": { "IDA_INSTALL_DIR": "/opt/ida-pro-9.3" }
+    }
+  }
+}
+```
+
+> **Note:** the `fastmcp` dependency is the [community fastmcp](https://github.com/jlowin/fastmcp) package, not the official `mcp` SDK. Don't install `mcp` by mistake.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+The test suite covers the executor, doc/example search, comments, snapshots, structures, undo, variables, and Mach-O parsing. Tests that need idalib are skipped if it's not available.
+
+## Credits
+
+Thanks to [@p41l](https://github.com/p41l) for ideas and for testing the tool across different LLMs.
+
+## License
+
+MIT — see `LICENSE`.

ida_code-0.2.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+ida_code/__init__.py,sha256=zWUY4fR0EJQx_22ZBPqyIDLdAMmZTbMzLR8PdkHzLZE,125
+ida_code/_search_utils.py,sha256=fCrEc-exNzcRMms-cZMFGezxHUkgXmndWg2MVSk__84,1103
+ida_code/comments.py,sha256=EvNuRIagaLpksg2nJETw4GXclXSAALU-pz-rIgUVKY4,5604
+ida_code/config.py,sha256=lJwGy8F9j7yAS6gQYLsWS39B-KExYGPungzN8AOxbwo,358
+ida_code/doc_search.py,sha256=ZQijMTInq93JvcF9CZv16n3jNI-qpc7iAgH6-qiZFqY,7461
+ida_code/example_search.py,sha256=DCDuVrU2suhfn3hL6GhXTwTvdtXihCNaZJsQ6a87Tt4,17375
+ida_code/executor.py,sha256=Ed_j0tpg4nTENQhT2LOrNRClfgh22MUfTHGbMXQvytM,4327
+ida_code/guidelines.py,sha256=lqWgoPRgMEjamO4ORXaN3oKFo4STKFiBgIog6HtyOSM,10008
+ida_code/macho.py,sha256=n8Ju7kWqTVKwFZAleLOaZupcDsvEHorzJchjSvpiKX8,2077
+ida_code/prompts.py,sha256=UI9Wpy5tXzW9pTl3-UQyZrd0Ry2EhuT9agknqva82v4,8226
+ida_code/server.py,sha256=k_NDC-_bYHk9lR7egiAKOdN-JiqiashnU7xinx1gask,33048
+ida_code/session.py,sha256=7abx4BlX-LF8rYDDorc8Dohy0NfMjkyxuAog8EdN-Zc,8592
+ida_code/snapshots.py,sha256=OxiIXIjuGVXQI1gGLH1s2HDPNW4Qm7CREkZTWJWiXoE,2967
+ida_code/structures.py,sha256=JM3QXUGfLMcEZxhYnL6_RD2E2PG4-3JX_eVI3BpswA4,6370
+ida_code/undo.py,sha256=2wYFpfDqPpqfXjyh1zzYAbULnTPgvdt_FNk4SwFcKGE,2705
+ida_code/variables.py,sha256=orj-3qx5eYhsKV2S4oNoUwclWar0YFKWV5lKS1oj8GY,5980
+ida_code-0.2.1.dist-info/METADATA,sha256=YgFfhCRL2oY8xsn48g4dJvn_r8XA_sdXenF2gnnIUDY,6066
+ida_code-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ida_code-0.2.1.dist-info/entry_points.txt,sha256=PxudvHpujlv2Ww0De7UN78LLjsN5VFHqC13znUTdIqg,50
+ida_code-0.2.1.dist-info/licenses/LICENSE,sha256=6q3O_h5USiWV6W1EycYFMGr1IOeirQ8n37KS022-s6c,1063
+ida_code-0.2.1.dist-info/RECORD,,

ida_code-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ida_code-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ida-code = ida_code.server:main

ida_code-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dil4rd
+
+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.