> [!IMPORTANT]
> `--gui` avvia Ghidra tramite `pyghidra-mcp`. Non si collega a un'istanza Ghidra esterna già in esecuzione.

Oppure, esegui come [contenitore Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):```bash
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

Oppure installa con pip:```bash
pip install pyghidra-mcp-cli

2. **Usa la CLI** (in un altro terminale):```bash
# List available binaries
pyghidra-mcp-cli list binaries

# Decompile a function
pyghidra-mcp-cli decompile --binary ls main

# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs

# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10

#### Creazione di progetti personalizzati```bash
# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis

$ tree ~/analysis/ 
/home/vscode/analysis/
└── malware_study
    ├── malware_analysis.gpr
    ├── malware_analysis-pyghidra-mcp
    │   ├── chromadb
    │   └── gzfs
    └── malware_analysis.rep

### Aprire progetti Ghidra esistenti

Se hai progetti Ghidra esistenti (file `.gpr`), puoi aprirli direttamente con `pyghidra-mcp`:

#### Apertura tramite file .gpr```bash
# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr

# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)

La modalità GUI è la scelta giusta quando vuoi:

- aprire o cambiare programmi in CodeBrowser
- navigare nel listing fino a una funzione o un indirizzo
- rinominare funzioni o aggiungere commenti e vedere subito queste modifiche in Ghidra

### Default di avvio e progetti di grandi dimensioni

`pyghidra-mcp` non richiede `--wait-for-analysis` di default. Il server può avviarsi mentre l'analisi e l'indicizzazione lato MCP continuano in background.

Questo è importante per progetti di grandi dimensioni:

- l'avvio di un progetto con molti binari non deve bloccare l'avvio del server
- `--wait-for-analysis` è disponibile quando vuoi un progetto completamente analizzato prima di servire le richieste
- per progetti esistenti di grandi dimensioni, aspettati che la prontezza di analisi e indicizzazione vari da binario a binario

Limitazione attuale:

- lo stato di analisi di Ghidra e lo stato di indicizzazione di MCP sono separati
- un binario può essere completamente analizzato in Ghidra mentre `search_strings` o la ricerca semantica `search_code` attendono ancora l'indicizzazione lato MCP
- questo è più evidente quando si aprono progetti esistenti di grandi dimensioni

In pratica:

- decompilazione, navigazione, rinomina e commenti possono comunque funzionare per un binario mentre le funzionalità di ricerca che dipendono dall'indicizzazione recuperano il ritardo
- se la latenza di avvio conta più della prontezza immediata della ricerca, mantieni il default `--no-wait-for-analysis`
- se la prontezza immediata conta più del tempo di avvio, usa `--wait-for-analysis`

## Sviluppo

Questo progetto usa un `Makefile` per semplificare sviluppo e testing. `ruff` è usato per linting e formattazione, e gli hook `pre-commit` sono usati per garantire la qualità del codice.

### Configurazione

1.  **Installa `uv`**: Se non hai `uv` installato, puoi installarlo usando pip:
    ```bash
    pip install uv
    ```
    Oppure, segui la guida ufficiale all'installazione di `uv`: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)

2.  **Crea un ambiente virtuale e installa le dipendenze**:
    ```bash
    make dev-setup
    source ./.venv/bin/activate
    ```

3.  **Imposta la variabile d'ambiente di Ghidra**: Scarica e installa Ghidra, poi imposta la variabile d'ambiente `GHIDRA_INSTALL_DIR` sulla directory di installazione di Ghidra.
    ```bash
    # For Linux / Mac
    export GHIDRA_INSTALL_DIR="/path/to/ghidra/"

    # For Windows PowerShell
    [System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
    ```

### Test e qualità

Il `Makefile` fornisce diversi target per il testing e la qualità del codice:

- `make run`: Esegue il server MCP.
- `make test`: Esegue la suite di test completa (unit e integrazione).
- `make test-unit`: Esegue i test unitari.
- `make test-integration`: Esegue i test di integrazione.
- `make test-integration-fast`: Esegue lo smoke test di integrazione leggero usato da pre-commit.
- `make test-integration-gui`: Esegue i test di integrazione GUI. Richiede un'installazione di Ghidra funzionante e il supporto GUI.
- `make lint`: Controlla lo stile del codice con `ruff`.
- `make format`: Formatta il codice con `ruff`.
- `make typecheck`: Esegue controlli statici leggeri con `ruff`.
- `make check`: Esegue tutti i controlli di qualità.
- `make dev`: Esegue il flusso di lavoro di sviluppo (formattazione e controllo).
- `make build`: Compila i pacchetti di distribuzione.
- `make clean`: Pulisce gli artefatti di build e la cache.

Suddivisione consigliata:

- pre-commit: `ruff`, `pyright`, test unitari e uno smoke test di integrazione leggero
- GitHub Actions: copertura completa dell'integrazione headless su Linux, GUI Linux sotto `Xvfb`, copertura CLI e smoke test correnti su macOS
- CI pianificata: copertura della compatibilità con versioni precedenti di macOS / Ghidra
- locale/manuale: debug GUI più pesante specifico per ambiente e controlli di sanity pre-rilascio

## API

### Strumenti

Consentono agli LLM di eseguire azioni, fare calcoli deterministici e interagire con servizi esterni.

#### Operazioni batch

`decompile_function` e `list_xrefs` accettano un singolo target o una lista di target, riducendo i round-trip quando si analizzano catene di chiamate o più simboli contemporaneamente.```jsonc
// Decompile three functions in one call, with callees and xrefs attached
{
  "binary_name": "firmware.bin",
  "name_or_address": ["main", "init_hardware", "0x08001234"],
  "include_callees": true,
  "include_xrefs": true
}

// Get cross-references for multiple symbols at once
{
  "binary_name": "firmware.bin",
  "name_or_address": ["malloc", "free", "realloc"]
}

#### Strumenti di lettura / analisi

- `search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0)`: Cerca pseudo-C decompilato usando ricerca vettoriale semantica o corrispondenza letterale.

- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Elenca i riferimenti incrociati a funzioni, simboli o indirizzi. Accetta un singolo target o una lista per la ricerca batch.

- `gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120)`: Genera un grafo delle chiamate MermaidJS per una funzione specificata. Supporta entrambe le direzioni "calling" (funzioni chiamate dal target) e "called" (funzioni che chiamano il target) con più tipi di visualizzazione.

- `decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30)`: Decompila funzioni per nome o indirizzo. Accetta un singolo target o una lista per la decompilazione batch. I flag di risposta estesa collegano callees, stringhe e/o xref a ciascun risultato. `timeout_sec` si applica per target e limita autonomamente ogni tentativo di decompilazione.

- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Elenca tutte le funzioni e i simboli esportati da un binario specificato (regex supportata per la query).

- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Elenca tutte le funzioni e i simboli importati per un binario specificato (regex supportata per la query).

- `read_bytes(binary_name: str, address: str, size: int = 32)`: Legge byte grezzi dalla memoria a un indirizzo specificato. Gli indirizzi esadecimali possono includere o omettere il prefisso `0x`.

- `search_strings(binary_name: str, query: str, limit: int = 100)`: Cerca stringhe all'interno di un binario.

- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Cerca simboli in un binario per nome. Supporta pattern regex (es. `^main$`, `func.*one`) con corrispondenza senza distinzione tra maiuscole e minuscole, o semplici query per sottostringa. Imposta `functions_only=True` per escludere etichette, variabili e altri simboli non funzione.

#### Operazioni di progetto

- `import_binary(binary_path: str)`: Importa un binario da un percorso designato nel progetto Ghidra corrente. Se il percorso è una directory, esegue una scansione ricorsiva e importa tutti i file binari supportati, preservando la struttura delle directory all'interno del progetto Ghidra.

- `list_project_binaries()`: Elenca i binari nel progetto Ghidra corrente. In modalità GUI questo include i binari del progetto presenti su disco anche se non sono attualmente aperti in CodeBrowser.

- `list_project_binary_metadata(binary_name: str)`: Recupera metadati dettagliati per un binario specifico, inclusi architettura, compilatore, formato eseguibile, metriche di analisi e hash dei file.

- `delete_project_binary(binary_name: str)`: Elimina un binario (programma) dal progetto Ghidra.

#### Strumenti di modifica / mutazione

- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Rinomina una funzione per nome o indirizzo. In modalità GUI questa operazione viene eseguita come transazione Ghidra live e aggiorna il programma aperto.

- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Rinomina un parametro di funzione o una variabile locale tramite nome esatto all'interno di una funzione specifica. Se il nome è assente o ambiguo all'interno di quella funzione, lo strumento restituisce un errore anziché fare ipotesi. In modalità GUI questa operazione viene eseguita come transazione Ghidra live e aggiorna il programma aperto.

- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Imposta il tipo di dati per un parametro di funzione o una variabile locale tramite nome esatto all'interno di una funzione specifica. Se il nome è assente o ambiguo all'interno di quella funzione, lo strumento restituisce un errore anziché fare ipotesi. `type_name` viene analizzato tramite il parser dei tipi di dati di Ghidra utilizzando il gestore dei tipi di dati del programma.

- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Imposta un prototipo di funzione da una stringa di firma completa. Lo strumento esegue sempre il prototipo tramite il parser di firme nativo di Ghidra e restituisce l'eventuale errore del parser o dell'applicazione se il prototipo non è valido.

- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Imposta un commento di funzione/decompilatore o un commento al listing. I target dei commenti al listing possono essere indirizzi, simboli o funzioni. I valori supportati per `comment_type` sono `decompiler`, `plate`, `pre`, `eol`, `post` e `repeatable`.

#### Strumenti di controllo GUI (solo `--gui`)

Questi strumenti sono disponibili solo quando `pyghidra-mcp` viene avviato con `--gui` e controllano ciò che la GUI mostra anziché modificare direttamente i dati del progetto:

- `list_open_programs()`: Elenca i programmi attualmente aperti nella GUI di Ghidra.
- `open_program_in_gui(binary_name: str, new_window: bool = True)`: Apre un binario del progetto in CodeBrowser. Di default apre una nuova finestra di CodeBrowser. Imposta `new_window=false` per riutilizzare un CodeBrowser visibile quando possibile.
- `set_current_program(binary_name: str)`: Rende un programma aperto il programma attivo/corrente nel contesto principale degli strumenti GUI.
- `goto(binary_name: str, target: str, target_type: str)`: Naviga nella GUI di Ghidra fino a un indirizzo o una funzione. `target_type` deve essere `address` o `function`.

## Utilizzo

Questo pacchetto Python è pubblicato su PyPI come [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) e può essere installato ed eseguito con [pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package), [pipx](https://pipx.pypa.io/), [uv](https://docs.astral.sh/uv/), [poetry](https://python-poetry.org/), o qualsiasi gestore di pacchetti Python.```text
$ uvx pyghidra-mcp --help
Usage: pyghidra-mcp [OPTIONS] [INPUT_PATHS]...

  PyGhidra Command-Line MCP server

Options:
  -v, --version                       Show version and exit.
  -t, --transport [stdio|streamable-http|sse|http]
                                      Transport protocol. SSE is deprecated;
                                      use streamable-http instead. [default: stdio]
  -p, --port INTEGER                  Port for HTTP-based transports. [default: 8000]
  -o, --host TEXT                     Host for HTTP-based transports. [default: 127.0.0.1]
  --project-path PATH                 Directory for a pyghidra-mcp project or an
                                      existing Ghidra .gpr file. [default: pyghidra_mcp_projects]
  --project-name TEXT                 Ghidra project name. Ignored for .gpr paths.
                                      [default: my_project]
  --threaded / --no-threaded          Allow threaded analysis. [default: threaded]
  --max-workers INTEGER               Number of analysis workers; 0 means CPU count.
                                      [default: 0]
  --wait-for-analysis / --no-wait-for-analysis
                                      Wait for initial analysis before starting.
                                      [default: no-wait-for-analysis]
  --gui / --no-gui                    Launch Ghidra GUI in-process and serve MCP
                                      against GUI-open programs. Cannot attach to
                                      an already-running external Ghidra process.
                                      [default: no-gui]
  --list-project-binaries             List ingested project binaries and exit.
  --delete-project-binary TEXT        Delete a project binary by name and exit.
  --force-analysis / --no-force-analysis
                                      Force a new binary analysis each run.
                                      [default: no-force-analysis]
  --verbose-analysis / --no-verbose-analysis
                                      Verbose logging for analysis. [default: no-verbose-analysis]
  --no-symbols / --with-symbols       Turn off symbols for analysis. [default: with-symbols]
  --sym-file-path PATH                Single PDB symbol file for one binary.
  -s, --symbols-path PATH             Local symbols directory.
  --gdt PATH                          Path to GDT files. May be specified multiple times.
  --program-options PATH              JSON file with Ghidra program options.
  --gzfs-path PATH                    Location to store GZFs of analyzed binaries.
  -h, --help                          Show this message and exit.

### Utilizzo con OpenWeb-UI e MCPO

Puoi integrare `pyghidra-mcp` con [OpenWeb-UI](https://github.com/open-webui/open-webui) utilizzando [MCPO](https://github.com/open-webui/mcpo), un proxy MCP-to-OpenAPI. Questo ti consente di esporre gli strumenti di `pyghidra-mcp` tramite un'API RESTful standard, rendendoli accessibili alle interfacce web e ad altri strumenti.


https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95


#### Con `uvx`

Puoi eseguire `pyghidra-mcp` e `mcpo` insieme usando `uvx`:```bash
uvx mcpo -- \
  pyghidra-mcp /bin/ls

### Input/Output standard (stdio)

Il trasporto stdio consente la comunicazione tramite flussi di input e output standard. Ciò è particolarmente utile per integrazioni locali e strumenti da riga di comando. Vedi la [specifica](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) per maggiori dettagli.

#### Python```bash
pyghidra-mcp

Per impostazione predefinita, il container Docker avvia il server `streamable-http`, quindi includi `-t stdio` dopo il nome dell'immagine ed esegui con `-i` per la modalità stdio [interattiva](https://docs.docker.com/reference/cli/docker/container/run/#interactive).

### Streamable HTTP

Streamable HTTP consente risposte in streaming su JSON RPC tramite richieste HTTP POST. Consulta la [specifica](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) per maggiori dettagli.

Per impostazione predefinita, il server è in ascolto su [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) per le connessioni dei client. Usa `--host` / `--port` o le variabili d'ambiente `MCP_HOST` / `MCP_PORT` per modificare l'indirizzo di bind. _Il server deve essere in esecuzione affinché i client possano connettersi ad esso._

#### Python```bash
pyghidra-mcp -t streamable-http

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

Di default, il pacchetto Python verrà eseguito in modalità `stdio`, quindi dovrai includere `-t sse`.

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

## Ispirazione

L'implementazione e il design di questo progetto sono stati ispirati da questi fantastici progetti:

* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
* [semgrep-mcp](https://github.com/semgrep/mcp)
* [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)
* [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)

---

## Contributi, community ed esecuzione dal sorgente

Crediamo che il futuro del reverse engineering sia agentico, contestuale e scalabile.  
`pyghidra-mcp` è un passo verso quel futuro—rendere i progetti Ghidra completi accessibili ad agenti AI e pipeline di automazione.

Stiamo sviluppando attivamente il progetto e accogliamo volentieri feedback, segnalazioni di problemi e contributi.

> [!NOTE]
> Adoriamo il tuo feedback, le segnalazioni di bug, le richieste di funzionalità e il codice.

### Flusso di lavoro per i contributori

Se stai aggiungendo un nuovo strumento o una nuova integrazione, ecco il flusso di lavoro consigliato:

- Assegna al tuo branch il prefisso `feature/` per indicare una nuova funzionalità.
- Aggiungi il tuo strumento usando lo stesso stile e la stessa struttura degli strumenti esistenti in `pyghidra/tools/`.
- Scrivi un test di integrazione che eserciti il tuo strumento usando un'istanza di `StdioClient`. Posizionalo in `tests/integration/`.
- Estendi i test concorrenti aggiungendo una chiamata al tuo strumento in `tests/integration/test_concurrent_streamable_client.py`.
- Esegui make test e make format per assicurarti che le tue modifiche superino tutti i test e siano conformi alle regole di linting.

Questo garantisce coerenza in tutto il codebase e ci aiuta a mantenere strumenti robusti e scalabili per i flussi di lavoro di reverse engineering.

______________________________________________________________________

Fatto con ❤️ dal [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)