GhydraMCP

https://github.com/starsong-consulting/ghydramcp
Admin
GhydraMCP is a bridge between Ghidra and AI assistants, enabling AI-assisted reverse engineering...
Tokens:7,828
Snippets:52
Trust Score:3.9
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Conventional Commit Message

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This example demonstrates the conventional commits format for a new feature, including the type, a concise description, an optional body explaining the change in detail, and a footer referencing an issue.

```text
feat: Add support for string listing in binary files

This adds a new endpoint to list all defined strings in the binary
with pagination and filtering by content.

Closes #123
```

--------------------------------

### Example Output for Discovering Ghidra Instances (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet represents the expected output when the `discover_instances` command is executed. It shows the number of found instances and details for each, including their port, URL, and the registration result, indicating successful discovery of active Ghidra instances.

```JSON
{
  "found": 2,
  "instances": [
    {
      "port": 8192,
      "url": "http://localhost:8192",
      "result": "Registered instance on port 8192 at http://localhost:8192"
    },
    {
      "port": 8193,
      "url": "http://localhost:8193",
      "result": "Registered instance on port 8193 at http://localhost:8193"
    }
  ]
}
```

--------------------------------

### Example Output for Listing Registered Ghidra Instances (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet illustrates the output from a `list_instances` command, providing details about currently registered Ghidra instances. It includes the port, URL, the Ghidra project name, and the file being analyzed for each instance, offering a snapshot of active analysis sessions.

```JSON
{
  "instances": [
    {
      "port": 8192,
      "url": "http://localhost:8192",
      "project": "TestProject",
      "file": "application.exe"
    },
    {
      "port": 8193,
      "url": "http://localhost:8193",
      "project": "FirmwareAnalysis",
      "file": "firmware.bin"
    }
  ]
}
```

--------------------------------

### Installing Python Bridge Dependencies - uv

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This command installs the required Python dependencies for the MCP bridge using uv, providing an alternative to pip for dependency management.

```bash
uv pip install mcp==1.6.0 requests==2.32.3
```

--------------------------------

### Example Response for Listing Strings (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet illustrates the expected response format when querying the `/strings` endpoint. It shows an array of string objects, each containing address, value, length, type, and name, along with pagination links.

```json
// Example Response
"result": [
  {
    "address": "0x00401234",
    "value": "Hello, world!",
    "length": 14,
    "type": "string",
    "name": "aHelloWorld"
  },
  {
    "address": "0x00401250",
    "value": "Error: could not open file",
    "length": 26,
    "type": "string",
    "name": "aErrorCouldNotO"
  }
],
"_links": {
  "self": { "href": "/strings?offset=0&limit=10" },
  "next": { "href": "/strings?offset=10&limit=10" }
}
```

--------------------------------

### Adding New GhydraMCP HTTP API Test - Python

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

This Python example demonstrates how to add a new test method to the `GhydraMCPHttpApiTests` class. It uses the `requests` library to make an HTTP GET request to a new endpoint and asserts the status code, JSON validity, and presence of required fields in the response.

```Python
def test_new_endpoint(self):
    """Test the /new_endpoint endpoint"""
    response = requests.get(f"{BASE_URL}/new_endpoint")
    self.assertEqual(response.status_code, 200)
    
    # Verify response is valid JSON
    data = response.json()
    
    # Check required fields in the standard response format
    self.assertIn("success", data)
    self.assertTrue(data["success"])
    self.assertIn("timestamp", data)
    self.assertIn("port", data)
```

--------------------------------

### Installing Python Bridge Dependencies - pip

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This command installs the required Python dependencies for the MCP bridge using pip, ensuring the correct versions of 'mcp' and 'requests' are available for the bridge's operation.

```bash
pip install mcp==1.6.0 requests==2.32.3
```

--------------------------------

### Example Response for Reading Memory (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet demonstrates the response structure for reading raw memory bytes from the `/memory/{address}` endpoint. It includes the address, length, format, and the hexadecimal representation of the bytes read.

```json
// Example Response Fragment for GET /programs/proj%3A%2Ffile.bin/memory/0x402000?length=16&format=hex
"result": {
  "address": "0x402000",
  "length": 16,
  "format": "hex",
  "bytes": "48656C6C6F20576F726C642100000000" // "Hello World!...."
}
```

--------------------------------

### Listing Functions API Response - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Example JSON response fragment when listing functions. It shows an array of function objects, each containing its name, address, and a self-referencing link.

```JSON
// Example Response Fragment
"result": [
  { "name": "FUN_08000004", "address": "08000004", "_links": { "self": { "href": "/functions/08000004" } } },
  { "name": "init_peripherals", "address": "08001cf0", "_links": { "self": { "href": "/functions/08001cf0" } } }
]
```

--------------------------------

### Retrieving Current Plugin Instance Information (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet shows the response from the `GET /info` endpoint, detailing the current Ghidra plugin instance. It includes information such as the loaded file, architecture, processor, project details, and server specifics. The `_links` section provides navigation to related resources like instances and program.

```json
{
  "id": "req-info",
  "instance": "http://localhost:8192",
  "success": true,
  "result": {
    "isBaseInstance": true,
    "file": "example.exe",
    "architecture": "x86:LE:64:default",
    "processor": "x86",
    "addressSize": 64,
    "creationDate": "2023-01-01T12:00:00Z",
    "executable": "/path/to/example.exe",
    "project": "MyProject",
    "projectLocation": "/path/to/MyProject",
    "serverPort": 8192,
    "serverStartTime": 1672531200000,
    "instanceCount": 1
  },
  "_links": {
    "self": { "href": "/info" },
    "root": { "href": "/" },
    "instances": { "href": "/instances" },
    "program": { "href": "/program" }
  }
}
```

--------------------------------

### Requesting Function List for Another Ghidra Instance (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet is another example of requesting a function list, targeting a different Ghidra instance by specifying its `port`. This shows how to interact with multiple Ghidra instances independently to retrieve their respective function lists.

```JSON
{"port": 8193}
```

--------------------------------

### Retrieving All Active Plugin Instances (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet represents the response from the `GET /instances` endpoint, listing all active GhydraMCP plugin instances. Each instance entry includes its port, URL, type, associated project, and file. The `_links` section offers navigation to individual instance details and actions like registration/unregistration.

```json
{
  "id": "req-instances",
  "instance": "http://localhost:8192",
  "success": true,
  "result": [
    {
      "port": 8192,
      "url": "http://localhost:8192",
      "type": "base",
      "project": "MyProject",
      "file": "example.exe",
      "_links": {
        "self": { "href": "/instances/8192" },
        "info": { "href": "http://localhost:8192/info" },
        "connect": { "href": "http://localhost:8192" }
      }
    },
    {
      "port": 8193,
      "url": "http://localhost:8193",
      "type": "standard",
      "project": "MyProject",
      "file": "library.dll",
      "_links": {
        "self": { "href": "/instances/8193" },
        "info": { "href": "http://localhost:8193/info" },
        "connect": { "href": "http://localhost:8193" }
      }
    }
  ],
  "_links": {
    "self": { "href": "/instances" },
    "register": { "href": "/registerInstance", "method": "POST" },
    "unregister": { "href": "/unregisterInstance", "method": "POST" },
    "programs": { "href": "/programs" }
  }
}
```

--------------------------------

### Retrieving Plugin Version and API Information (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet illustrates the expected response from the `GET /plugin-version` endpoint. It provides details on the Ghidra plugin's build version and its ordinal API version, crucial for client compatibility checks. The `_links` section includes self-referential and root links.

```json
{
  "id": "req-meta-ver",
  "instance": "http://localhost:8192",
  "success": true,
  "result": {
    "plugin_version": "v2.0.0",
    "api_version": 2
  },
  "_links": {
    "self": { "href": "/plugin-version" },
    "root": { "href": "/" }
  }
}
```

--------------------------------

### Disassembling Function API Response - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Example JSON response fragment for retrieving the assembly listing of a function. It provides an array of instruction objects, each with its address, mnemonic, operands, and bytes.

```JSON
// Example Response Fragment
"result": [
  { "address": "0x4010a0", "mnemonic": "PUSH", "operands": "RBP", "bytes": "55" },
  { "address": "0x4010a1", "mnemonic": "MOV", "operands": "RBP, RSP", "bytes": "4889E5" },
  // ... more instructions
]
```

--------------------------------

### Performing Ghidra Data Flow Analysis (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This endpoint executes data flow analysis from a specified starting address. It allows control over the analysis direction (forward/backward) and the maximum number of steps, providing a sequence of instructions and descriptions.

```JSON
"result": {
  "start_address": "0x401050",
  "direction": "forward",
  "max_steps": 50,
  "steps": [
    {
      "address": "0x401050",
      "instruction": "MOV EAX, [RBP+0x8]",
      "description": "Starting point of data flow analysis"
    }
  ]
}
```

--------------------------------

### Retrieving Program Metadata (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON fragment demonstrates the `result` and `_links` sections of the response from the `GET /program` endpoint. It provides comprehensive metadata about the currently loaded binary in Ghidra, including its ID, name, language, compiler, image base, memory size, and analysis status. The links facilitate navigation to related program resources like functions, symbols, and memory.

```json
{
  "id": "req-program",
  "instance": "http://localhost:8192",
  "success": true,
  "result": {
    "programId": "myproject:/path/to/mybinary.exe",
    "name": "mybinary.exe",
    "isOpen": true,
    "languageId": "x86:LE:64:default",
    "compilerSpecId": "gcc",
    "imageBase": "0x400000",
    "memorySize": 1048576,
    "analysisComplete": true
  },
  "_links": {
    "self": { "href": "/program" },
    "project": { "href": "/project" },
    "functions": { "href": "/functions" },
    "symbols": { "href": "/symbols" },
    "data": { "href": "/data" },
    "segments": { "href": "/segments" },
    "memory": { "href": "/memory" },
    "xrefs": { "href": "/xrefs" },
    "analysis": { "href": "/analysis" }
  }
}
```

--------------------------------

### Using GhydraMCP Client for Program Analysis and Operations - Python

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This snippet demonstrates how to interact with GhydraMCP using the Python MCP SDK. It shows examples of calling various tools like `decompile_function`, `get_function`, `get_callgraph` for program analysis, `read_memory`, `get_disassembly` for memory operations, and `list_strings` for string analysis, including pagination and filtering. It also illustrates how to modify function signatures and add comments.

```Python
# Program analysis
client.use_tool("ghydra", "decompile_function", {"name": "main"})
client.use_tool("ghydra", "get_function", {"address": "0x00401000"})
client.use_tool("ghydra", "get_callgraph", {"address": "0x00401000"})

# Memory and disassembly operations
client.use_tool("ghydra", "read_memory", {"address": "0x00401000", "length": 16})
client.use_tool("ghydra", "get_disassembly", {"address": "0x00401000", "length": 32})

# String analysis
client.use_tool("ghydra", "list_strings")  # List all strings in the binary
client.use_tool("ghydra", "list_strings", {"limit": 100, "offset": 0})  # Pagination
client.use_tool("ghydra", "list_strings", {"filter": "password"})  # Search for strings containing "password"

# Function operations
client.use_tool("ghydra", "set_function_signature", {"address": "0x00401000", "signature": "int main(int argc, char **argv)"})
client.use_tool("ghydra", "set_comment", {"address": "0x00401100", "comment": "This instruction initializes the counter", "comment_type": "plate"})
```

--------------------------------

### Decompiling Function API Response - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Example JSON response fragment for retrieving the decompiled C-like code of a function. It includes the function's address and the decompiled source code.

```JSON
// Example Response Fragment (without syntax tree)
"result": {
  "address": "0x4010a0",
  "ccode": "int process_data(char *param_1, int param_2)\n{\n  // ... function body ...\n  return result;\n}\n"
}
```

--------------------------------

### Retrieving Function Details API Response - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Example JSON response fragment when retrieving details for a specific function. It includes comprehensive information such as name, address, signature, size, stack depth, calling convention, and various related links.

```JSON
// Example Response Fragment for GET /functions/0x4010a0
"result": {
  "name": "process_data",
  "address": "0x4010a0",
  "signature": "int process_data(char * data, int size)",
  "size": 128,
  "stack_depth": 16,
  "has_varargs": false,
  "calling_convention": "__stdcall"
  // ... other details
},
"_links": {
  "self": { "href": "/functions/0x4010a0" },
  "decompile": { "href": "/functions/0x4010a0/decompile" },
  "disassembly": { "href": "/functions/0x4010a0/disassembly" },
  "variables": { "href": "/functions/0x4010a0/variables" },
  "xrefs_to": { "href": "/xrefs?to_addr=0x4010a0" },
  "xrefs_from": { "href": "/xrefs?from_addr=0x4010a0" }
}
```

--------------------------------

### Modifying Function API Request Payload - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Example JSON payload for modifying a function using the PATCH method. It demonstrates how to update the function's name and signature.

```JSON
{ "name": "calculate_checksum", "signature": "uint32_t calculate_checksum(uint8_t* buffer, size_t length)" }
```

--------------------------------

### Retrieving Current Cursor Position (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet illustrates the expected response from the `GET /address` endpoint, providing the current cursor position within Ghidra's CodeBrowser. It includes the address and the program name. The `_links` section offers navigation to related resources like the program, memory at the address, and the function containing the address.

```json
{
  "id": "req-address",
  "instance": "http://localhost:8192",
  "success": true,
  "result": {
    "address": "0x401000",
    "program": "mybinary.exe"
  },
  "_links": {
    "self": { "href": "/address" },
    "program": { "href": "/program" },
    "memory": { "href": "/memory/0x401000?length=16" },
    "function": { "href": "/functions/0x401000" },
    "decompile": { "href": "/functions/0x401000/decompile" }
  }
}
```

--------------------------------

### Retrieving Ghidra Function Call Graph (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This endpoint fetches the function call graph for the loaded program. It supports query parameters to specify a starting function and a maximum depth for the graph traversal, returning nodes and edges representing calls.

```JSON
"result": {
  "root": "main",
  "root_address": "0x401000",
  "max_depth": 3,
  "nodes": [
    {
      "id": "0x401000",
      "name": "main",
      "address": "0x401000",
      "_links": {
        "self": { "href": "/functions/0x401000" }
      }
    }
  ],
  "edges": [
    {
      "from": "0x401000",
      "to": "0x401100",
      "type": "call",
      "call_site": "0x401050"
    }
  ]
}
```

--------------------------------

### Retrieving Current Function Information (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This JSON snippet shows the expected response from the `GET /function` endpoint, detailing the function at the current cursor position in Ghidra. It includes the function's name, address, signature, and size. The `_links` section provides navigation to related resources such as the program, decompiler output, disassembly, variables, and cross-references.

```json
{
  "id": "req-function",
  "instance": "http://localhost:8192",
  "success": true,
  "result": {
    "name": "main",
    "address": "0x401000",
    "signature": "int main(int argc, char** argv)",
    "size": 256
  },
  "_links": {
    "self": { "href": "/function" },
    "program": { "href": "/program" },
    "function": { "href": "/functions/0x401000" },
    "decompile": { "href": "/functions/0x401000/decompile" },
    "disassembly": { "href": "/functions/0x401000/disassembly" },
    "variables": { "href": "/functions/0x401000/variables" },
    "xrefs": { "href": "/xrefs?to_addr=0x401000" }
  }
}
```

--------------------------------

### Adding New GhydraMCP MCP Bridge Test - Python

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

This Python example illustrates how to add a new test method to the `MCPBridgeTests` class for an MCP tool. It uses the `send_mcp_request` method to call a tool with specific arguments and then asserts the basic response structure, content type, and content length.

```Python
def test_new_tool(self):
    """Test the new_tool tool"""
    response = self.send_mcp_request("call_tool", {
        "name": "new_tool",
        "arguments": {
            "param1": "value1",
            "param2": "value2"
        }
    })
    
    # Check basic response structure
    self.assertIn("result", response)
    self.assertIn("content", response["result"])
    
    # Parse the content
    content = response["result"]["content"]
    self.assertIsInstance(content, list)
    self.assertGreaterEqual(len(content), 1)
```

--------------------------------

### Building All GhydraMCP Artifacts - Maven

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This Maven command builds both the Ghidra plugin and the complete GhydraMCP package, generating `target/GhydraMCP-[version].zip` and `target/GhydraMCP-Complete-[version].zip` respectively. It performs a clean build before packaging.

```bash
mvn clean package
```

--------------------------------

### Building GhydraMCP from Source - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This snippet provides the commands to clone the GhydraMCP repository and build the project using Maven. It generates a Ghidra plugin ZIP and a complete package ZIP.

```bash
git clone https://github.com/starsong-consulting/GhydraMCP.git
cd GhydraMCP

mvn clean package
```

--------------------------------

### Configuring GhydraMCP Server for Claude Desktop (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON configuration snippet defines how the GhydraMCP server, specifically the 'ghydra' tool, is set up within the Claude Desktop environment. It specifies the command to run the bridge script (`uv run`), its arguments, and optional environment variables like `GHIDRA_HYDRA_HOST` for host configuration.

```JSON
{
  "mcpServers": {
    "ghydra": {
      "command": "uv",
      "args": [
        "run",
        "/ABSOLUTE_PATH_TO/bridge_mcp_hydra.py"
      ],
      "env": {
        "GHIDRA_HYDRA_HOST": "localhost"
      }
    }
  }
}
```

--------------------------------

### Registering Ghidra Instances with GhydraMCP (Python)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This snippet shows how to register Ghidra instances with GhydraMCP using the `register_instance` command. It allows specifying the port and an optional URL for the Ghidra instance, enabling the system to manage multiple Ghidra instances.

```Python
client.use_tool("ghydra", "register_instance", {"port": 8192, "url": "http://localhost:8192/"})
client.use_tool("ghydra", "register_instance", {"port": 8193})
```

--------------------------------

### Building Complete GhydraMCP Package Only - Maven

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This Maven command builds only the complete GhydraMCP package, `target/GhydraMCP-Complete-[version].zip`, by activating the `complete-only` profile. It performs a clean build before packaging the combined artifact.

```bash
mvn clean package -P complete-only
```

--------------------------------

### Discovering Ghidra Instances with GhydraMCP (Python)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This snippet illustrates how to automatically discover active Ghidra instances using the `discover_instances` command. It can be used without parameters to discover on the default host or with a `host` parameter to specify a custom IP address for discovery.

```Python
client.use_tool("ghydra", "discover_instances")  # Default host
client.use_tool("ghydra", "discover_instances", {"host": "192.168.1.10"})  # Custom host
```

--------------------------------

### Building Ghidra Plugin Only - Maven

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This Maven command builds only the Ghidra plugin artifact, `target/GhydraMCP-[version].zip`, by activating the `plugin-only` profile. It ensures a clean build before packaging the plugin.

```bash
mvn clean package -P plugin-only
```

--------------------------------

### Running Project Tests - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This command executes the test suite for the GhydraMCP project. It is typically used to verify changes before creating a pull request or during the release preparation phase. The `run_tests.py` script orchestrates the various tests, including HTTP API tests for Java and MCP Bridge tests for Python.

```bash
python run_tests.py
```

--------------------------------

### Running GhydraMCP HTTP API Tests - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

This command executes the dedicated script for testing the GhydraMCP plugin's HTTP API. It verifies connectivity, response format, JSON structure, and error handling of the exposed endpoints.

```Bash
python test_http_api.py
```

--------------------------------

### Requesting Function List for a Specific Ghidra Instance (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet demonstrates a request to list functions from a specific Ghidra instance. It specifies the `port` of the target Ghidra instance, indicating which active session's functions should be retrieved.

```JSON
{"port": 8192}
```

--------------------------------

### Standard API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet illustrates the standard HATEOAS-driven response format for the GhydraMCP API, including a unique request ID, instance URL, success status, result payload, timestamp, and HATEOAS links for self and related resources.

```json
{
  "id": "req-123",
  "instance": "http://localhost:8192",
  "success": true,
  "result": "...",
  "timestamp": 1712159482123,
  "_links": {
    "self": {"href": "/endpoint/current"},
    "related": [
      {"href": "/endpoint/related1", "name": "Related Resource 1"},
      {"href": "/endpoint/related2", "name": "Related Resource 2"}
    ]
  }
}
```

--------------------------------

### Performing Data Manipulation with GhydraMCP (Python)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This snippet demonstrates various data manipulation operations using the `client.use_tool` method with the 'ghydra' tool. It covers creating, setting data types, renaming, updating, and deleting data entries by specifying an address, data type, or name. These operations interact with Ghidra's data management capabilities.

```Python
client.use_tool("ghydra", "create_data", {"address": "0x00401234", "data_type": "int"})
client.use_tool("ghydra", "set_data_type", {"address": "0x00401238", "data_type": "char *"})
client.use_tool("ghydra", "rename_data", {"address": "0x00401234", "name": "my_variable"})
client.use_tool("ghydra", "update_data", {"address": "0x00401238", "name": "ptr_var", "data_type": "char *"})
client.use_tool("ghydra", "delete_data", {"address": "0x0040123C"})
```

--------------------------------

### Running All GhydraMCP Tests - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

This command executes the main test runner script, which orchestrates both HTTP API and MCP bridge tests for the GhydraMCP plugin. It provides a consolidated summary of all test results.

```Bash
python run_tests.py
```

--------------------------------

### Running Specific GhydraMCP Test Suites - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

These commands allow users to execute specific test suites for the GhydraMCP plugin. The `--http` flag runs only the HTTP API tests, while `--mcp` runs only the MCP bridge tests, enabling focused testing.

```Bash
# Run only the HTTP API tests
python run_tests.py --http

# Run only the MCP bridge tests
python run_tests.py --mcp
```

--------------------------------

### Paginated List API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet demonstrates the HATEOAS-driven response format for list operations in the GhydraMCP API, incorporating pagination details such as total size, offset, limit, and HATEOAS links for self, next, and previous pages.

```json
{
  "id": "req-123",
  "instance": "http://localhost:8192",
  "success": true,
  "result": [ ... objects ... ],
  "size": 150,
  "offset": 0,
  "limit": 50,
  "_links": {
    "self": { "href": "/functions?offset=0&limit=50" },
    "next": { "href": "/functions?offset=50&limit=50" },
    "prev": { "href": "/functions?offset=0&limit=50" }
  }
}
```

--------------------------------

### Defining Ghidra Plugin Version - Java

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This Java snippet shows how the plugin's version string is defined as a constant within the `ApiConstants.java` file. This version is updated for all changes to the Java plugin.

```java
public static final String PLUGIN_VERSION = "v2.0.0-beta.1";
```

--------------------------------

### Defining Ghidra Plugin API Version - Java

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This Java snippet defines the integer API version for the Ghidra plugin in `ApiConstants.java`. This version is incremented only when breaking changes are introduced to the API.

```java
public static final int API_VERSION = 2;
```

--------------------------------

### Running GhydraMCP Bridge Tests - Bash

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/TESTING.md

This command executes the script for testing the GhydraMCP bridge functionality. It verifies MCP protocol communication, tool availability, response formats, and the ability to call tools and handle mutating operations.

```Bash
python test_mcp_client.py
```

--------------------------------

### Retrieving Ghidra Analysis Status and Analyzers (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This endpoint retrieves the current analysis status of the loaded program and lists all available Ghidra analyzers. It provides details such as the program name, whether analysis is enabled, and a list of analysis modules.

```JSON
"result": {
  "program": "mybinary.exe",
  "analysis_enabled": true,
  "available_analyzers": [
    "Function Start Analyzer",
    "Basic Block Model Analyzer",
    "Reference Analyzer",
    "Call Convention Analyzer",
    "Data Reference Analyzer",
    "Decompiler Parameter ID",
    "Stack Analyzer"
  ]
},
"_links": {
  "self": { "href": "/analysis" },
  "program": { "href": "/program" },
  "analyze": { "href": "/analysis", "method": "POST" },
  "callgraph": { "href": "/analysis/callgraph" }
}
```

--------------------------------

### Triggering Ghidra Program Re-analysis (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

This endpoint allows users to initiate a full or partial re-analysis of the currently loaded Ghidra program. The response confirms whether the analysis process has been successfully triggered.

```JSON
"result": {
  "program": "mybinary.exe",
  "analysis_triggered": true,
  "message": "Analysis initiated on program"
}
```

--------------------------------

### Paginated List API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Illustrates the structure for API responses that return lists of resources, extending the standard format with pagination details such as total size, offset, limit, and navigation links (next/prev) for traversing results. The 'result' field contains an array of objects.

```json
{
  "id": "req-123",
  "instance": "http://localhost:8192",
  "success": true,
  "result": [ ... objects ... ],
  "size": 150, // Total number of items matching the query across all pages
  "offset": 0,
  "limit": 50,
  "_links": {
    "self": { "href": "/functions?offset=0&limit=50" },
    "next": { "href": "/functions?offset=50&limit=50" }, // Present if more items exist
    "prev": { "href": "/functions?offset=0&limit=50" }  // Present if not the first page
  }
}
```

--------------------------------

### Standard API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Defines the common structure for all successful non-error API responses, including a correlation ID, the instance URL, a success flag, the main data payload, and optional HATEOAS links for resource discovery. The 'result' field can be a single object or an array of objects.

```json
{
  "id": "[correlation identifier]",
  "instance": "[instance url]",
  "success": true,
  "result": Object | Array<Object>,
  "_links": { // Optional: HATEOAS links
    "self": { "href": "/path/to/current/resource" },
    "related_resource": { "href": "/path/to/related" }
    // ... other relevant links
  }
}
```

--------------------------------

### Requesting Another Decompiled Function from Ghidra Instance (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet is similar to the previous one, demonstrating a request to decompile a function from a different Ghidra instance. It specifies the `port` and the `name` of the function, `handle_message`, to retrieve its decompiled representation for analysis.

```JSON
{"port": 8193, "name": "handle_message"}
```

--------------------------------

### Error API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet outlines the HATEOAS-driven error response format for the GhydraMCP API, providing details like a unique request ID, instance URL, failure status, an error object with code and message, HTTP status code, timestamp, and a self-referencing HATEOAS link.

```json
{
  "id": "req-123",
  "instance": "http://localhost:8192",
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Function 'main' not found in current program"
  },
  "status_code": 404,
  "timestamp": 1712159482123,
  "_links": {
    "self": {"href": "/functions/main"}
  }
}
```

--------------------------------

### Defining Required API Version for Bridge - Python

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This Python snippet specifies the required API version that the MCP bridge expects from the Ghidra plugin. The bridge verifies this version at runtime to ensure compatibility.

```python
REQUIRED_API_VERSION = 2
```

--------------------------------

### Defining MCP Bridge Version - Python

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/CONTRIBUTING.md

This Python snippet illustrates how the bridge's version string is defined as a constant in `bridge_mcp_hydra.py`. This version is updated when the bridge script is modified.

```python
BRIDGE_VERSION = "v2.0.0-beta.1"
```

--------------------------------

### Requesting Decompiled Function from Ghidra Instance (JSON)

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/README.md

This JSON snippet shows a request to retrieve the decompiled code for a specific function from a Ghidra instance. It requires both the `port` of the target instance and the `name` of the function to be decompiled, enabling detailed analysis of individual functions.

```JSON
{"port": 8192, "name": "process_command"}
```

--------------------------------

### Error API Response Format - JSON

Source: https://github.com/starsong-consulting/ghydramcp/blob/main/GHIDRA_HTTP_API.md

Outlines the structure for API error responses, which use appropriate HTTP status codes (e.g., 4xx, 5xx) and include a 'success' flag set to false, along with an 'error' object containing a machine-readable code and a human-readable message describing the issue.

```json
{
  "id": "[correlation identifier]",
  "instance": "[instance url]",
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND", // Optional: Machine-readable code
    "message": "Descriptive error message"
    // Potentially other details like invalid parameters
  }
}
```
Tokens:
Raw