# ghidra-docsbox-mcp — full reference

## Overview

This is one of five sibling MCP servers (`python-docsbox-mcp`, `postgres-postgis-docsbox-mcp`, `duckdb-spatial-docsbox-mcp`, `rust-docsbox-mcp`, `ghidra-docsbox-mcp`). They share a common skeleton: streamable-HTTP transport, FastMCP wiring, custom routes for landing/health/llms, a corpus loader, and per-tool dependency injection.

This sibling specialises in reverse-engineering: it bridges to LaurieWired's GhidraMCP plugin, which embeds an HTTP server inside Ghidra and exposes program introspection / decompilation / mutation endpoints.

## Architecture

```
agent → POST /mcp → ghidra-docsbox-mcp (Python) → GhidraBridge (httpx) → http://<plugin-host>:<port>/ → Ghidra plugin (Java)
```

- **`server.py`** — assembles the FastMCP instance, builds `TransportSecuritySettings`, wires custom routes, and registers each tool module.
- **`bridge.py`** — `GhidraBridge` is the only place that talks HTTP to the plugin. It has a `configured` flag (false when `GHIDRA_DOCSBOX_BRIDGE_URL` is unset) and bounded responses (4 MiB cap).
- **`corpus.py`** — TOML/SQLite-backed read-only doc corpus.
- **`tools/`** — one module per concern, each with a `register(mcp, …)` entrypoint.

## Environment

| Var | Default | Purpose |
|---|---|---|
| `GHIDRA_DOCSBOX_BIND` | `127.0.0.1:7822` | Listen address. |
| `GHIDRA_DOCSBOX_BRIDGE_URL` | (unset) | URL of the GhidraMCP plugin's embedded HTTP server, e.g. `http://127.0.0.1:8080`. |
| `GHIDRA_DOCSBOX_ACCESS_MODE` | `read_only` | `read_only` blocks 8 mutating tools; `read_write` enables them. |
| `GHIDRA_DOCSBOX_CORPUS_DIR` | (unset → bundled) | Path to a custom corpus dir. |
| `GHIDRA_DOCSBOX_LOG` | `info` | Python `logging` level. |
| `GHIDRA_DOCSBOX_ALLOWED_HOSTS` | (unset) | Extra `Host:` allow-list entries (comma-separated). |
| `GHIDRA_DOCSBOX_ALLOWED_ORIGINS` | (unset) | Extra `Origin:` allow-list entries (comma-separated). |
| `GHIDRA_DOCSBOX_DISABLE_DNS_PROTECTION` | (unset) | Set to `1` only in tests. |

## Tool catalogue

### Reference

- `list_sections(package?)` → manifest entries, optionally filtered by package.
- `get_documentation(section_id)` → fetch a single section's body or live URL.
- `ghidra_help(section?)` → quick-reference cheatsheet for Ghidra concepts.
- `summarize_corpus(focus?)` → MCP Prompt primitive that produces a guided summary.
- `run_locally()` → plan-only shell steps to install GhidraMCP and configure this server.

### Bridge

- `bridge_status()` → probe the plugin, return reachability + access mode.

### Program introspection (read-only)

- `list_methods()` / `list_functions(offset, limit)` — paginated function names.
- `list_classes(offset, limit)`
- `list_segments(offset, limit)`
- `list_imports(offset, limit)` / `list_exports(offset, limit)`
- `list_namespaces(offset, limit)`
- `list_data_items(offset, limit)`
- `list_strings(offset, limit, filter?)`
- `search_functions_by_name(query, offset, limit)`

### Decompilation / disassembly

- `decompile_function(name)` — POST to `/decompile`.
- `decompile_function_by_address(address)` — GET `/decompile_function`.
- `disassemble_function(address)` — GET `/disassemble_function`.

### Address-cursor inspection

- `get_function_by_address(address)`
- `get_current_address()`
- `get_current_function()`

### Cross-references

- `get_xrefs_to(address, offset, limit)`
- `get_xrefs_from(address, offset, limit)`
- `get_function_xrefs(name, offset, limit)`

### Mutating (read_write only)

- `rename_function(old_name, new_name)`
- `rename_data(address, new_name)`
- `rename_variable(function, old_name, new_name)`
- `set_decompiler_comment(address, comment)`
- `set_disassembly_comment(address, comment)`
- `rename_function_by_address(address, new_name)`
- `set_function_prototype(address, prototype)`
- `set_local_variable_type(function, variable, type)`

In `read_only` mode, each mutating tool is registered as a stub returning `{"ok": false, "error": "read_only_mode", ...}`.

## Upstream

- Plugin: [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)
- Ghidra: [NSA/ghidra](https://github.com/NationalSecurityAgency/ghidra)
- API docs: [ghidra.re/ghidra_docs/api](https://ghidra.re/ghidra_docs/api/)