ida-re-mcp

# ida-re-mcp `ida-re-mcp` is an IDA Pro 9.3+ headless stdio MCP service for AI Agents. It provides Native static reverse engineering, Unity IL2CPP native annotations, transactional IDB write-back, and Windows native x64 dynamic debugging, based on explicit workspaces, immutable revisions, and process-isolated workers. The current version is `1.0.0.dev0`. The service uses the standard lifecycle and stdio transport of the official Python MCP SDK. The tool directory is fixed at startup, advertising only tools and immutable resources. The project does not implement its own protocol negotiation, JSON-RPC parser, tasks, prompts, sampling, completions, or interactive approval. ## Environment Requirements - Python `3.13`; - `uv`; - IDA Pro `9.3+` and corresponding license; - Windows x64 for dynamic debugging; - LLVM/LLD `22.1.8`, required only for rebuilding test fixtures. Development virtual environments and runtime data must be located outside the Git working tree: ```powershell $env:UV_PROJECT_ENVIRONMENT = "$env:LOCALAPPDATA\ida-re-mcp\dev-venv" uv python install 3.13 uv sync --locked ``` The IDA installation directory is resolved by the `idapro` runtime environment. On development machines, set `IDADIR` according to IDA installation requirements and execute: ```powershell ida-re-mcp doctor ``` ## CLI ```powershell ida-re-mcp serve ida-re-mcp serve --config C:\path\to\config.toml ida-re-mcp doctor ida-re-mcp gc --dry-run ida-re-mcp gc --apply ``` Configurations use a strict TOML schema; an example is provided in [config.example.toml](config.example.toml). Workspaces, logs, artifacts, checkouts, staging, temporary files, and virtual environments are all located outside the working tree. Only one Supervisor can occupy the same data root at a time. If multiple MCP hosts need to be enabled simultaneously, they must use `IDA_RE_MCP_DATA_ROOT` to specify non-overlapping absolute paths; `IDA_RE_MCP_LOG_ROOT` can be used to specify the log directory separately. Neither override can point to the file system root, nor can they be located within the working tree or contain the working tree. ## Agent Workflow `workspace.create` creates a private candidate copy of the user-provided file and performs strict PE/ELF Native format checks on the copy. The caller must provide a Native image that can be directly loaded by IDA; shell scripts, gzexe, and other compressed wrappers stably return `unsupported`. The service does not unpack or execute candidate files. 1. Call `workspace.create`, saving `workspace_id` and `analysis_operation_id`. 2. Wait for the initial analysis using `operation.wait`, obtaining an immutable revision. 3. Perform static queries using the explicit `workspace_id` and `revision`. 4. Check the `coverage` and `provenance` in the results; do not infer analysis gaps as facts. 5. Perform transactional write-back using `change.prepare` and `change.apply`. 6. Generate an immutable artifact using `report.build` or `workspace.export` and read it through the `ida-re://...` resource URI. 7. When dynamically debugging, save `debug_session_id` and read registers, threads, stacks, and memory only on the current suspended `stop_id`. The text fields of `program.search` are `function`, `name`, and `string`; an explicit empty `text_query=""` represents deterministic enumeration. The `bytes` field uses a separate `bytes_query`. ## Security and Consistency - Original samples are read-only; `workspace.create` copies and verifies the SHA-256, and all format identifications occur on private candidate copies. - AnalysisWorker and DebugWorker use private checkouts that are not saved when closed. - All IDB writes are completed in staging, published as new revisions after read-back, cold verification, and CAS. - Mutation failures, cancellations, or worker crashes must not change old revisions, HEAD, or sample digests. - Debugging executes the target program; Job Object is responsible for recycling the process tree started by the service, but it is not a malicious sample sandbox. - `expert.execute` is not registered by default. When enabled, it is still an open-world IDAPython that can access files, networks, and subprocesses. The project does not provide process memory writing, remote debugging, regular .NET/Mono workspaces, general call capture, or external analyzer execution chains. See [Architecture](docs/Architecture.md) for complete boundaries, [Capability Matrix](docs/Capability%20Matrix.md) for capability status, and [Verification Records](docs/Verification%20Records.md) for reproducible checkpoints.