# ghidra-docsbox-mcp

> Streamable-HTTP MCP server bridging agent clients to LaurieWired's GhidraMCP plugin for reverse-engineering Ghidra programs.

This server is **plumbing**. Decompilation, xref analysis, and program introspection happen inside Ghidra; this MCP service shapes those calls into discoverable, schema-typed MCP tools.

## Endpoint

- MCP: `POST /mcp` (streamable HTTP)
- Health: `GET /health`
- Public host: `https://ghidra-mcp.afterrealism.com`

## Tool families

- **Reference** (always available, no Ghidra needed): `list_sections`, `get_documentation`, `ghidra_help`, `summarize_corpus`, `run_locally`.
- **Bridge status**: `bridge_status` — probes the configured Ghidra plugin URL.
- **Program (read-only)**: `list_methods`, `list_classes`, `list_segments`, `list_imports`, `list_exports`, `list_namespaces`, `list_data_items`, `list_functions`, `list_strings`, `search_functions_by_name`.
- **Decompile / disassemble**: `decompile_function`, `decompile_function_by_address`, `disassemble_function`.
- **Inspect**: `get_function_by_address`, `get_current_address`, `get_current_function`.
- **Xrefs**: `get_xrefs_to`, `get_xrefs_from`, `get_function_xrefs`.
- **Mutating** (gated by `GHIDRA_DOCSBOX_ACCESS_MODE=read_write`): `rename_function`, `rename_data`, `rename_variable`, `set_decompiler_comment`, `set_disassembly_comment`, `rename_function_by_address`, `set_function_prototype`, `set_local_variable_type`.

## Modes

| Env config | Behaviour |
|---|---|
| `GHIDRA_DOCSBOX_BRIDGE_URL` unset | Docs-only; bridge tools return `{"ok": false, "error": "not_configured"}`. |
| Bridge set, mode = `read_only` (default) | All read tools live; mutating tools stubbed. |
| Bridge set, mode = `read_write` | All 28 tools live. |

## Trust boundary

`run_locally` is **plan-only** — it returns a list of shell steps for the calling agent's host to execute. The MCP service never executes shell commands itself.

Bridge calls go to a single configured URL (`GHIDRA_DOCSBOX_BRIDGE_URL`). The MCP server does not auto-discover or scan for plugin instances.

## Upstream

Built against [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP). The plugin embeds an HTTP server inside Ghidra; this MCP server bridges that HTTP surface to MCP tool calls.