Skip to content

development.md

Latest commit

 

History

History
104 lines (66 loc) · 2.19 KB

development.md

File metadata and controls

104 lines (66 loc) · 2.19 KB

Development

Tests

python -m pytest -q bridge/tests/unit bridge/tests/contract bridge/tests/golden

Java Development

Use this path when you need IDE support or want to iterate on the Ghidra extension outside the Docker builder.

Prerequisites

  • JDK 21
  • Maven 3.6+
  • Ghidra 11.4.2 (or set GHIDRA_DIR to your local installation)

Build Steps

  1. Fetch Ghidra dependencies:

    python scripts/fetch_ghidra_jars.py

    This downloads the required Ghidra JARs into lib/. Alternatively, if you have a local Ghidra installation:

    export GHIDRA_DIR=/path/to/ghidra_11.4.2_PUBLIC

  2. Build the extension:

    mvn -DskipTests package

    To include tests:

    mvn package

Output Location

The build produces:

target/GhidraMCP-1.0-SNAPSHOT.jar

Installation

Option 1: Manual copy

cp target/GhidraMCP-1.0-SNAPSHOT.jar $GHIDRA_INSTALL_DIR/Extensions/Ghidra/

Option 2: Ghidra GUI

  1. Open Ghidra
  2. Go to File → Install Extensions
  3. Click the + button
  4. Select target/GhidraMCP-1.0-SNAPSHOT.jar
  5. Restart Ghidra

Verify installation:

After restarting Ghidra, the extension should appear in File → Configure → Miscellaneous → GhidraMCP.

Plan workflow

  • Edit .plan/TODO.md, .plan/tasks.manifest.json, .plan/state.json
  • Keep them in sync with python3 bin/plan_check.py
  • Use .plan/sync_state.sh after each task

CI

GitHub Actions runs:

  • Plan check
  • Python tests
  • Maven packaging (only when Java changes)

Ghidra-API Quicklinks

Additional design notes and roadmap context live in docs/ROADMAP.md.

Utilities

aggregate_transcripts (in bridge.orchestrator)

Parses transcript records to extract the first JSON object per record, validates each object against a JSON schema (default: envelope.v1.json), and produces a summary dict:

  • total: number of records processed
  • ok: records whose first JSON object matched the schema
  • failed: records that did not match

Use this when you need a quick quality check on logged transcripts.