# Changelog - Ghidra MCP Server

Complete version history for the Ghidra MCP Server project.

---

## v2.0.0 - 2026-02-03

### Major Release - Security, Ghidra 12.0.2, Enhanced Documentation

#### 🔒 Security
- **Localhost binding**: HTTP server now binds to `127.0.0.1` instead of `0.0.0.0` in both GUI plugin and headless server — prevents accidental network exposure on shared networks
- Addresses the same concern as [LaurieWired/GhidraMCP#125](https://github.com/LaurieWired/GhidraMCP/issues/125)

#### ⚙️ Configurable Decompile Timeout
- New optional `timeout` parameter on `/decompile_function` endpoint
- Defaults to 60s — no behavior change for existing callers
- Allows longer timeouts for complex functions (e.g., `?timeout=300`)

#### 🏷️ Label Deletion Endpoints
- **New `delete_label` tool**: Delete individual labels at specified addresses
- **New `batch_delete_labels` tool**: Efficiently delete multiple labels in a single atomic operation
- Essential for cleaning up orphan labels after applying array types to pointer tables

#### 🔧 Environment Configuration
- New `.env.template` with `GHIDRA_PATH` and other environment-specific settings
- Deploy script reads `.env` file — no more hardcoded paths
- Auto-detection of Ghidra installation from common paths
- Python bridge respects `GHIDRA_SERVER_URL` environment variable

#### 🚀 Ghidra 12.0.2 Support
- Updated all dependencies and paths for Ghidra 12.0.2
- Updated library dependency documentation (14 required JARs)

#### 🛠️ Tool Count
- **Total MCP Tools**: 110 fully implemented
- **Java REST Endpoints**: 133 (includes internal endpoints)
- **New tools added**: 2 (delete_label, batch_delete_labels)

#### 📚 Documentation
- Complete README rewrite with full tool listing organized by category
- Added architecture overview, library dependency table, and project structure
- Reorganized API documentation by category
- Added comprehensive contributing guidelines

#### 🧪 Testing
- New unit tests for bridge utilities (`test_bridge_utils.py`)
- New unit tests for MCP tools (`test_mcp_tools.py`)
- Updated CI workflow to latest GitHub Actions versions

#### 🧹 Cleanup
- Removed superseded files: `cross_version_matcher.py`, `cross_version_verifier.py` (replaced by hash index system in v1.9.4)
- Removed stale data files: `hash_matches_*.json`, `string_anchors.json`, `docs/KNOWN_ORDINALS.md`
- Refactored workflow engine (`continuous_improvement.py`, `ghidra_manager.py`)

---

## v1.9.4 - 2025-12-03

### Function Hash Index Release

#### 🔗 Cross-Binary Documentation Propagation
- **Function Hash Index System**: Hash-based matching of identical functions across different binaries
- **New Java Endpoints**:
  - `GET /get_function_hash` - Compute SHA-256 hash of normalized function opcodes
  - `GET /get_bulk_function_hashes` - Paginated bulk hashing with filter (documented/undocumented/all)
  - `GET /get_function_documentation` - Export complete function documentation (name, prototype, plate comment, parameters, locals, comments, labels)
  - `POST /apply_function_documentation` - Import documentation to target function
- **New Python MCP Tools**:
  - `get_function_hash` - Single function hash retrieval
  - `get_bulk_function_hashes` - Bulk hashing with pagination
  - `get_function_documentation` - Export function docs as JSON
  - `apply_function_documentation` - Apply docs to target function
  - `build_function_hash_index` - Build persistent JSON index from programs
  - `lookup_function_by_hash` - Find matching functions in index
  - `propagate_documentation` - Apply docs to all matching instances

#### 🧮 Hash Normalization Algorithm
- Normalizes opcodes for position-independent matching across different base addresses
- **Internal jumps**: `REL+offset` (relative to function start)
- **External calls**: `CALL_EXT` placeholder
- **External data refs**: `DATA_EXT` placeholder
- **Small immediates** (<0x10000): Preserved as `IMM:value`
- **Large immediates**: Normalized to `IMM_LARGE`
- **Registers**: Preserved (part of algorithm logic)

#### ✅ Verified Cross-Version Matching
- Tested D2Client.dll 1.07 → 1.08: **1,313 undocumented functions** match documented functions
- Successfully propagated `ConcatenatePathAndWriteFile` documentation across versions
- Identical functions produce matching hashes despite different base addresses

#### 🛠 Tool Count
- **Total MCP Tools**: 118 (112 implemented + 6 ROADMAP v2.0)
- **New tools added**: 7 (4 Java endpoints + 3 Python index management tools)

---

## v1.9.3 - 2025-11-14

### Documentation & Workflow Enhancement Release

#### 📚 Documentation Organization
- **Organized scattered markdown files**: Moved release files to proper `docs/releases/` structure
- **Created comprehensive navigation**: Added `docs/README.md` with complete directory structure
- **Enhanced release documentation**: Added `docs/releases/README.md` with version index
- **Streamlined project structure**: Moved administrative docs to `docs/project-management/`

#### 🔧 Hungarian Notation Improvements
- **Enhanced pointer type coverage**: Added comprehensive double pointer types (`void **` → `pp`, `char **` → `pplpsz`)
- **Added const pointer support**: New rules for `const char *` → `lpcsz`, `const void *` → `pc`
- **Windows SDK integration**: Added mappings for `LPVOID`, `LPCSTR`, `LPWSTR`, `PVOID`
- **Fixed spacing standards**: Corrected `char **` notation (removed spaces)
- **Array vs pointer clarity**: Distinguished stack arrays from pointer parameters

#### 🎯 Variable Renaming Workflow
- **Comprehensive variable identification**: Mandated examining both decompiled and assembly views
- **Eliminated pre-filtering**: Attempt renaming ALL variables regardless of name patterns
- **Enhanced failure handling**: Use `variables_renamed` count as sole reliability indicator
- **Improved documentation**: Better comment examples for non-renameable variables

#### 🛠 Build & Development
- **Fixed Ghidra script issues**: Resolved class name mismatches and deprecated API usage
- **Improved workflow efficiency**: Streamlined function documentation processes
- **Enhanced type mapping**: More precise Hungarian notation type-to-prefix mapping

---

## v1.9.2 - 2025-11-07

### Documentation & Organization Release

**Focus**: Project organization, documentation standardization, and production release preparation

#### 🎯 Major Improvements

**Documentation Organization:**
- ✅ Created comprehensive `PROJECT_STRUCTURE.md` documenting entire project layout
- ✅ Consolidated `DOCUMENTATION_INDEX.md` merging duplicate indexes
- ✅ Enhanced `scripts/README.md` with categorization and workflows  
- ✅ Established markdown naming standards (`MARKDOWN_NAMING.md`)
- ✅ Organized 40+ root-level files into clear categories

**Project Structure:**
- ✅ Categorized all files by purpose (core, build, data, docs, scripts, tools)
- ✅ Created visual directory trees with emoji icons for clarity
- ✅ Defined clear guidelines for adding new files
- ✅ Documented access patterns and usage workflows
- ✅ Prepared 3-phase reorganization plan for future improvements

**Standards & Conventions:**
- ✅ Established markdown file naming best practices (kebab-case)
- ✅ Defined special file naming rules (README.md, CHANGELOG.md, etc.)
- ✅ Created quick reference guides and checklists
- ✅ Documented directory-specific naming patterns
- ✅ Set up migration strategy for existing files

**Release Preparation:**
- ✅ Created comprehensive release checklist (`RELEASE_CHECKLIST_v1.9.2.md`)
- ✅ Verified version consistency across project (pom.xml 1.9.2)
- ✅ Updated all documentation references
- ✅ Prepared release notes and changelog
- ✅ Ensured production-ready state

#### 📚 New Documentation Files

| File | Purpose | Lines |
|------|---------|-------|
| `PROJECT_STRUCTURE.md` | Complete project organization guide | 450+ |
| `DOCUMENTATION_INDEX.md` | Consolidated master index | 300+ |
| `ORGANIZATION_SUMMARY.md` | Documentation of organization work | 350+ |
| `MARKDOWN_NAMING.md` | Quick reference for naming standards | 120+ |
| `.github/MARKDOWN_NAMING_GUIDE.md` | Comprehensive naming guide | 320+ |
| `scripts/README.md` (enhanced) | Scripts directory documentation | 400+ |
| `RELEASE_CHECKLIST_v1.9.2.md` | Release preparation checklist | 300+ |

#### 🔧 Infrastructure Updates

- ✅ Version consistency verification across all files
- ✅ Build configuration validated (Maven 3.9+, Java 21)
- ✅ Plugin deployment verified with Ghidra 11.4.2  
- ✅ Python dependencies current (`requirements.txt`)
- ✅ All core functionality tested and working

#### ✅ Quality Metrics

- **Documentation coverage**: 100% (all directories documented)
- **Version consistency**: Verified (pom.xml 1.9.2 is source of truth)
- **Build success rate**: 100% (clean builds passing)
- **API tool count**: 111 tools (108 analysis + 3 lifecycle)
- **Test coverage**: 53/53 read-only tools verified functional

#### 📊 Organization Achievements

**Before November 2025:**
- 50+ files cluttered in root directory
- 2 separate documentation indexes (duplicate)
- Unclear file categorization
- No scripts directory documentation
- Difficult navigation and discovery

**After November 2025:**
- 40 organized root files with clear categories
- 1 consolidated master documentation index
- Complete project structure documentation
- Comprehensive scripts README with categorization
- Task-based navigation with multiple entry points
- Visual directory trees for clarity
- Established naming conventions and standards

#### 🚀 Production Readiness

- ✅ **Build System**: Maven clean package succeeds
- ✅ **Plugin Deployment**: Loads successfully in Ghidra 11.4.2
- ✅ **API Endpoints**: All 111 tools functional
- ✅ **Documentation**: 100% coverage with cross-references
- ✅ **Testing**: Core functionality verified
- ✅ **Organization**: Well-structured and maintainable

---

## v1.8.4 - 2025-10-26

### Bug Fixes & Improvements - Read-Only Tools Testing

**Critical Fixes:**
- ✅ **Fixed silent failures in `get_xrefs_to` and `get_xrefs_from`**
  - Previously returned empty output when no xrefs found
  - Now returns descriptive message: "No references found to/from address: 0x..."
  - Affects: Java plugin endpoints (lines 3120-3167)

- ✅ **Completed `get_assembly_context` implementation**
  - Replaced placeholder response with actual assembly instruction retrieval
  - Returns context_before/context_after arrays with surrounding instructions
  - Adds mnemonic field and pattern detection (data_access, comparison, arithmetic, etc.)
  - Affects: Java plugin getAssemblyContext() method (lines 7223-7293)

- ✅ **Completed `batch_decompile_xref_sources` usage extraction**
  - Replaced placeholder "usage_line" with actual code line extraction
  - Returns usage_lines array showing how target address is referenced in decompiled code
  - Adds xref_addresses array showing specific instruction addresses
  - Affects: Java plugin batchDecompileXrefSources() method (lines 7362-7411)

**Quality Improvements:**
- ✅ **Improved `list_strings` filtering**
  - Added minimum length filter (4+ characters)
  - Added printable ratio requirement (80% printable ASCII)
  - Filters out single-byte hex strings like "\x83"
  - Returns meaningful message when no quality strings found
  - Affects: Java plugin listDefinedStrings() and new isQualityString() method (lines 3217-3272)

- ✅ **Fixed `list_data_types` category filtering**
  - Previously only matched category paths (file names like "crtdefs.h")
  - Now also matches data type classifications (struct, enum, union, typedef, pointer, array)
  - Added new getDataTypeName() helper to determine type classification
  - Searching for "struct" now correctly returns Structure data types
  - Affects: Java plugin listDataTypes() and getDataTypeName() methods (lines 4683-4769)

### Testing
- Systematically tested all **53 read-only MCP tools** against D2Client.dll
- **100% success rate** across 6 categories:
  - Metadata & Connection (3 tools)
  - Listing (14 tools)
  - Get/Query (10 tools)
  - Analysis (12 tools)
  - Search (5 tools)
  - Advanced Analysis (9 tools)

### Impact
- More robust error handling with descriptive messages instead of silent failures
- Completion of previously stubbed implementations
- Better string detection quality (fewer false positives)
- Type-based data type filtering now works as expected
- All read-only tools verified functional and returning valid data

---

## v1.8.3 - 2025-10-26

### Removed Tools - API Cleanup
- ❌ **Removed 3 redundant/non-functional MCP tools** (108 → 105 tools)
  - `analyze_function_complexity` - Never implemented, returned placeholder JSON only
  - `analyze_data_types` - Superseded by comprehensive `analyze_data_region` tool
  - `auto_create_struct_from_memory` - Low-quality automated output, better workflow exists

### Rationale
- **analyze_function_complexity**: Marked "not yet implemented" for multiple versions, no demand
- **analyze_data_types**: Basic 18-line implementation completely replaced by `analyze_data_region` (200+ lines, comprehensive batch operation with xref mapping, boundary detection, stride analysis)
- **auto_create_struct_from_memory**: Naive field inference produced generic field_0, field_4 names without context; better workflow is `analyze_data_region` → manual `create_struct` with meaningful names

### Impact
- Cleaner API surface with less confusion
- Removed dead code from both Python bridge and Java plugin
- No breaking changes for active users (tools were redundant or non-functional)
- Total MCP tools: **105 analysis + 6 script lifecycle = 111 tools**

---

## v1.8.2 - 2025-10-26

### New External Location Management Tools
- ✅ **Three New MCP Tools** - External location management for ordinal import fixing
  - `list_external_locations()` - List all external locations (imports, ordinal imports)
  - `get_external_location()` - Get details about specific external location
  - `rename_external_location()` - Rename ordinal imports to actual function names
  - Enables mass fixing of broken ordinal-based imports when DLL functions change

### New Documentation
- ✅ **`EXTERNAL_LOCATION_TOOLS.md`** - Complete API reference for external location tools
  - Full tool signatures and parameters
  - Use cases and examples
  - Integration with ordinal restoration workflow
  - Performance considerations and error handling
- ✅ **`EXTERNAL_LOCATION_WORKFLOW.md`** - Quick-start workflow guide
  - Step-by-step workflow (5-15 minutes)
  - Common patterns and code examples
  - Troubleshooting guide
  - Performance tips for large binaries

### Implementation Details
- Added `listExternalLocations()` method to Java plugin (lines 10479-10509)
- Added `getExternalLocationDetails()` method to Java plugin (lines 10511-10562)
- Added `renameExternalLocation()` method to Java plugin (lines 10567-10626)
- Added corresponding HTTP endpoints for each method
- Fixed Ghidra API usage for ExternalLocationIterator and namespace retrieval
- All operations use Swing EDT for thread-safe Ghidra API access

**Impact**: Complete workflow for fixing ordinal-based imports - essential for binary analysis when external DLL functions change or ordinals shift

---

## v1.8.1 - 2025-10-25

### Documentation Reorganization
- ✅ **Project Structure Overhaul** - Cleaned and reorganized entire documentation
  - Consolidated prompts: 12 files → 8 focused workflow files
  - Created `docs/examples/` with punit/ and diablo2/ subdirectories
  - Moved structure discovery guides to `docs/guides/`
  - Created comprehensive `START_HERE.md` with multiple learning paths
  - Updated `DOCUMENTATION_INDEX.md` to reflect new structure
  - Removed ~70 obsolete files (old reports, duplicates, summaries)

### New Calling Convention
- ✅ **__d2edicall Convention** - Diablo II EDI-based context passing
  - Documented in `docs/conventions/D2CALL_CONVENTION_REFERENCE.md`
  - Applied to BuildNearbyRoomsList function
  - Installed in x86win.cspec

### Bug Fixes
- ✅ **Fixed DocumentFunctionWithClaude.java** - Windows compatibility
  - Resolved "claude: CreateProcess error=2" 
  - Now uses full path: `%APPDATA%\npm\claude.cmd`
  - Changed keybinding from Ctrl+Shift+D to Ctrl+Shift+P

### New Files & Tools
- ✅ **ghidra_scripts/** - Example Ghidra scripts
  - `DocumentFunctionWithClaude.java` - AI-assisted function documentation
  - `ClearCallReturnOverrides.java` - Clean orphaned flow overrides
- ✅ **mcp-config.json** - Claude MCP configuration template
- ✅ **mcp_function_processor.py** - Batch function processing automation
- ✅ **scripts/hybrid-function-processor.ps1** - Automated analysis workflows

### Enhanced Documentation
- ✅ **examples/punit/** - Complete UnitAny structure case study (8 files)
- ✅ **examples/diablo2/** - Diablo II structure references (2 files)
- ✅ **conventions/** - Calling convention documentation (5 files)
- ✅ **guides/** - Structure discovery methodology (4 files)

### Cleanup
- ❌ Removed obsolete implementation/completion reports
- ❌ Removed duplicate function documentation workflows
- ❌ Removed old D2-specific installation guides
- ❌ Removed temporary Python scripts and cleanup utilities

**Impact**: Better organization, easier navigation, reduced duplication, comprehensive examples

**See**: Tag [v1.8.1](https://github.com/bethington/ghidra-mcp/releases/tag/v1.8.1)

---

## v1.8.0 - 2025-10-16

### Major Features
- ✅ **6 New Structure Field Analysis Tools** - Comprehensive struct field reverse engineering
  - `analyze_struct_field_usage` - Analyze field access patterns across functions
  - `get_field_access_context` - Get assembly/decompilation context for specific field offsets
  - `suggest_field_names` - AI-assisted field naming based on usage patterns
  - `inspect_memory_content` - Read raw bytes with string detection heuristics
  - `get_bulk_xrefs` - Batch xref retrieval for multiple addresses
  - `get_assembly_context` - Get assembly instructions with context for xref sources

### Documentation Suite
- ✅ **6 Comprehensive Reverse Engineering Guides** (in `docs/guides/`)
  - CALL_RETURN_OVERRIDE_CLEANUP.md - Flow override debugging
  - EBP_REGISTER_REUSE_SOLUTIONS.md - Register reuse pattern analysis
  - LIST_DATA_BY_XREFS_GUIDE.md - Data analysis workflow
  - NORETURN_FIX_GUIDE.md - Non-returning function fixes
  - ORPHANED_CALL_RETURN_OVERRIDES.md - Orphaned override detection
  - REGISTER_REUSE_FIX_GUIDE.md - Complete register reuse fix workflow

- ✅ **Enhanced Prompt Templates** (in `docs/prompts/`)
  - PLATE_COMMENT_EXAMPLES.md - Real-world examples
  - PLATE_COMMENT_FORMAT_GUIDE.md - Best practices
  - README.md - Prompt documentation index
  - OPTIMIZED_FUNCTION_DOCUMENTATION.md - Enhanced workflow

### Utility Scripts
- ✅ **9 Reverse Engineering Scripts** (in `scripts/`)
  - ClearCallReturnOverrides.java - Clear orphaned flow overrides
  - b_extract_data_with_xrefs.py - Bulk data extraction
  - create_d2_typedefs.py - Type definition generation
  - populate_d2_structs.py - Structure population automation
  - test_data_xrefs_tool.py - Unit tests for xref tools
  - data-extract.ps1, data-process.ps1, function-process.ps1, functions-extract.ps1 - PowerShell automation

### Project Organization
- ✅ **Restructured Documentation**
  - Release notes → `docs/releases/v1.7.x/`
  - Code reviews → `docs/code-reviews/`
  - Analysis data → `docs/analysis/`
  - Guides consolidated in `docs/guides/`

### Changed Files
- `bridge_mcp_ghidra.py` (+585 lines) - 6 new MCP tools, enhanced field analysis
- `src/main/java/com/xebyte/GhidraMCPPlugin.java` (+188 lines) - Struct analysis endpoints
- `pom.xml` (Version 1.7.3 → 1.8.0)
- `.gitignore` - Added `*.txt` for temporary files

**See**: Tag [v1.8.0](https://github.com/bethington/ghidra-mcp/releases/tag/v1.8.0)

---

## v1.7.3 - 2025-10-13

### Critical Bug Fix
- ✅ **Fixed disassemble_bytes transaction commit** - Added missing `success = true` flag assignment before transaction commit, ensuring disassembled instructions are properly persisted to Ghidra database

### Impact
- **High** - All `disassemble_bytes` operations now correctly save changes
- Resolves issue where API reported success but changes were rolled back

### Testing
- ✅ Verified with test case at address 0x6fb4ca14 (21 bytes)
- ✅ Transaction commits successfully and persists across server restarts
- ✅ Complete verification documented in `DISASSEMBLE_BYTES_VERIFICATION.md`

### Changed Files
- `src/main/java/com/xebyte/GhidraMCPPlugin.java` (Line 9716: Added `success = true`)
- `pom.xml` (Version 1.7.2 → 1.7.3)
- `src/main/resources/extension.properties` (Version 1.7.2 → 1.7.3)

**See**: [v1.7.3 Release Notes](V1.7.3_RELEASE_NOTES.md)

---

## v1.7.2 - 2025-10-12

### Critical Bug Fix
- ✅ **Fixed disassemble_bytes connection abort** - Added explicit response flushing and enhanced error logging to prevent HTTP connection abort errors

### Documentation
- ✅ Comprehensive code review documented in `CODE_REVIEW_2025-10-13.md`
- ✅ Overall rating: 4/5 (Very Good) - Production-ready with minor improvements identified

**See**: [v1.7.2 Release Notes](V1.7.2_RELEASE_NOTES.md)

---

## v1.7.0 - 2025-10-11

### Major Features
- ✅ **Variable storage control** - `set_variable_storage` endpoint for fixing register reuse issues
- ✅ **Ghidra script automation** - `run_script` and `list_scripts` endpoints
- ✅ **Forced decompilation** - `force_decompile` endpoint for cache clearing
- ✅ **Flow override control** - `clear_instruction_flow_override` and `set_function_no_return` endpoints

### Capabilities
- **Register reuse fixes** - Resolve EBP and other register conflicts
- **Automated analysis** - Execute Python/Java Ghidra scripts programmatically
- **Flow analysis control** - Fix incorrect CALL_TERMINATOR overrides

**See**: [v1.7.0 Release Notes](V1.7.0_RELEASE_NOTES.md)

---

## v1.6.0 - 2025-10-10

### New Features
- ✅ **7 New MCP Tools**: Validation, batch operations, and comprehensive analysis
  - `validate_function_prototype` - Pre-flight validation for function prototypes
  - `validate_data_type_exists` - Check if types exist before using them
  - `can_rename_at_address` - Determine address type and suggest operations
  - `batch_rename_variables` - Atomic multi-variable renaming with partial success
  - `analyze_function_complete` - Single-call comprehensive analysis (5+ calls → 1)
  - `document_function_complete` - Atomic all-in-one documentation (15-20 calls → 1)
  - `search_functions_enhanced` - Advanced search with filtering, regex, sorting

### Documentation
- ✅ **Reorganized structure**: Created `docs/guides/`, `docs/releases/v1.6.0/`
- ✅ **Renamed**: `RELEASE_NOTES.md` → `CHANGELOG.md`
- ✅ **Moved utility scripts** to `tools/` directory
- ✅ **Removed redundancy**: 8 files consolidated or archived
- ✅ **New prompt**: `FUNCTION_DOCUMENTATION_WORKFLOW.md`

### Performance
- **93% API call reduction** for complete function documentation
- **Atomic transactions** with rollback support
- **Pre-flight validation** prevents errors before execution

### Quality
- **Implementation verification**: 99/108 Python tools (91.7%) have Java endpoints
- **100% documentation coverage**: All 108 tools documented
- **Professional structure**: Industry-standard organization

**See**: [v1.6.0 Release Notes](docs/releases/v1.6.0/RELEASE_NOTES.md)

---

## v1.5.1 - 2025-01-10

### Critical Bug Fixes
- ✅ **Fixed batch_set_comments JSON parsing error** - Eliminated ClassCastException that caused 90% of batch operation failures
- ✅ **Added missing AtomicInteger import** - Resolved compilation issue

### New Features
- ✅ **batch_create_labels endpoint** - Create multiple labels in single atomic transaction
- ✅ **Enhanced JSON parsing** - Support for nested objects and arrays in batch operations
- ✅ **ROADMAP v2.0 documentation** - All 10 placeholder tools clearly marked with implementation plans

### Performance Improvements
- ✅ **91% reduction in API calls** - Function documentation workflow: 57 calls → 5 calls
- ✅ **Atomic transactions** - All-or-nothing semantics for batch operations
- ✅ **Eliminated user interruption issues** - Batch operations prevent hook triggers

### Documentation Enhancements
- ✅ **Improved rename_data documentation** - Clear explanation of "defined data" requirement
- ✅ **Comprehensive ROADMAP** - Transparent status for all placeholder tools
- ✅ **Organized documentation structure** - New docs/ subdirectories for better navigation

---

## 📊 Performance Metrics

### Before v1.5.1
Documenting a single function:
- 1 rename_function
- 1 set_plate_comment
- 1 set_function_prototype
- 43 set_disassembly_comment calls
- 3 set_decompiler_comment calls
- 8 create_label calls (6 blocked by user interruption)

**Total**: 57 API calls, 6 operations failed

### After v1.5.1
Documenting a single function:
- 1 rename_function
- 1 set_plate_comment
- 1 set_function_prototype
- 1 batch_set_comments (46 comments)
- 1 batch_create_labels (8 labels)

**Total**: 5 API calls, 0 operations failed

**Improvement**: 91% reduction, 100% success rate

---

## 🔧 Technical Changes

### Java Plugin (GhidraMCPPlugin.java)

#### Enhanced JSON Parsing (~215 lines added/modified)
- **parseJsonArray()** (lines 2673-2739): Changed from `List<String>` to `List<Object>` with depth tracking
- **parseJsonElement()** (lines 2744-2776): Recursive parsing for all JSON types
- **parseJsonObject()** (lines 2782-2815): Object string to Map conversion
- **convertToMapList()** (lines 2822-2841): Type-safe List<Object> to List<Map<String, String>>

#### New Endpoints
- **/batch_create_labels** (lines 495-501): Batch label creation endpoint
- **batchCreateLabels()** (lines 3197-3310): Atomic transaction implementation with validation

#### Updated Endpoints
- **/batch_set_comments** (lines 1030-1041): Uses convertToMapList() for proper type handling

#### Imports
- Added `import java.util.concurrent.atomic.AtomicInteger;` (line 54)

### Python Bridge (bridge_mcp_ghidra.py)

#### New MCP Tools (~40 lines)
- **batch_create_labels()** (lines 1018-1057): Atomic label creation with validation

#### Enhanced Documentation (~350 lines)
- **rename_data()** (lines 517-545): IMPORTANT section, "What is defined data?", error handling guidance
- **import_data_types()** (lines 1553-1579): Marked as [ROADMAP v2.0]

#### ROADMAP v2.0 Tools (9 malware analysis tools)
- **detect_crypto_constants()** (lines 1571-1588)
- **find_similar_functions()** (lines 1609-1636)
- **analyze_control_flow()** (lines 1639-1663)
- **find_anti_analysis_techniques()** (lines 1666-1684)
- **extract_iocs()** (lines 1687-1706)
- **auto_decrypt_strings()** (lines 1781-1800)
- **analyze_api_call_chains()** (lines 1803-1822)
- **extract_iocs_with_context()** (lines 1825-1844)
- **detect_malware_behaviors()** (lines 1847-1867)

All marked with:
```
[ROADMAP v2.0] Tool description

IMPLEMENTATION STATUS: Placeholder - Returns "Not yet implemented"
PLANNED FOR: Version 2.0

Planned functionality:
- Feature 1
- Feature 2
```

---

## 📦 Installation

### Quick Update (From v1.5.0)

```bash
# 1. Pull latest code
git pull origin main

# 2. Rebuild plugin
mvn clean package assembly:single -DskipTests

# 3. Deploy to Ghidra
.\deploy-to-ghidra.ps1

# 4. Restart Ghidra
```

### Fresh Installation

```bash
# 1. Clone repository
git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp

# 2. Copy Ghidra libraries
copy-ghidra-libs.bat "C:\path\to\ghidra"

# 3. Build plugin
mvn clean package assembly:single

# 4. Deploy
.\deploy-to-ghidra.ps1
```

---

## 🧪 Testing

### Build Verification
```bash
mvn clean compile -q
# ✅ SUCCESS - No errors or warnings

mvn clean package assembly:single -DskipTests -q
# ✅ SUCCESS - Artifacts created
```

### Functional Testing

**Test 1: batch_set_comments**
```python
batch_set_comments(
    function_address="0x6faead30",
    disassembly_comments=[
        {"address": "0x6faead30", "comment": "Test 1"},
        {"address": "0x6faead35", "comment": "Test 2"}
    ],
    decompiler_comments=[
        {"address": "0x6faead48", "comment": "Test decompiler"}
    ],
    plate_comment="Test header"
)
# Expected: {"success": true, "disassembly_comments_set": 2, ...}
```

**Test 2: batch_create_labels**
```python
batch_create_labels([
    {"address": "0x6faeadb0", "name": "test_label_1"},
    {"address": "0x6faeadb7", "name": "test_label_2"},
    {"address": "0x6faeadcd", "name": "test_label_3"}
])
# Expected: {"success": true, "labels_created": 3, "labels_skipped": 0}
```

---

## 📚 Documentation Updates

### New Documentation Structure
```
docs/
├── prompts/                    # User analysis prompts
│   ├── UNIFIED_ANALYSIS_PROMPT.md
│   └── ENHANCED_ANALYSIS_PROMPT.md
├── releases/                   # Version-organized releases
│   ├── v1.5.1/
│   ├── v1.5.0/
│   └── v1.4.0/
├── reports/                    # Development reports
│   ├── MCP_CODE_REVIEW_REPORT.md
│   ├── SESSION_EVALUATION_REPORT.md
│   └── ...
├── troubleshooting/            # Issue resolution guides
│   └── TROUBLESHOOTING_PLUGIN_LOAD.md
└── archive/                    # Historical documents
    └── prompts/                # Superseded prompts
```

### New Documents
- **UNIFIED_ANALYSIS_PROMPT.md** - Combined function + data analysis workflow
- **FINAL_IMPROVEMENTS_V1.5.1.md** - Comprehensive release summary
- **DOCUMENTATION_CLEANUP_PLAN.md** - Organization rationale

---

## 🔄 Migration Guide

### Breaking Changes
**NONE** - All changes are 100% backward compatible

### Deprecated Features
**NONE** - All existing individual operations continue to work

### Recommended Migrations

#### Migrate to Batch Comments
**Before:**
```python
for comment in comments:
    set_disassembly_comment(comment["address"], comment["comment"])
```

**After:**
```python
batch_set_comments(
    function_address=function_addr,
    disassembly_comments=comments
)
```

#### Migrate to Batch Labels
**Before:**
```python
for label in labels:
    create_label(label["address"], label["name"])
```

**After:**
```python
batch_create_labels(labels)
```

---

## 🐛 Known Issues

### Resolved in This Release
- ✅ batch_set_comments ClassCastException (FIXED)
- ✅ User interruption during label creation (FIXED)
- ✅ Missing AtomicInteger import (FIXED)

### Remaining (Low Priority)
- ⚠️ find_next_undefined_function occasionally returns renamed functions (requires re-query)
- ⚠️ Standardized error response format not implemented (mixed formats across endpoints)
- ⚠️ Automatic fallback logic not implemented (manual fallback required on batch failures)

---

## 🚀 Roadmap

### v2.0 (Planned)
- **Malware Analysis Tools** (9 tools):
  - Crypto constant detection
  - Similar function finding
  - Control flow analysis
  - Anti-analysis technique detection
  - IOC extraction (basic + context-aware)
  - String decryption
  - API call chain analysis
  - Malware behavior detection

- **Data Type Import**:
  - C header file parsing
  - JSON type definition import
  - .gdt archive support

- **Additional Enhancements**:
  - document_function atomic operation (5 calls → 1 call)
  - Standardized error response format
  - Automatic fallback logic in Python bridge
  - Progress indicators for large operations

---

## 📈 Statistics

### Code Changes
- **Files Modified**: 2 (GhidraMCPPlugin.java, bridge_mcp_ghidra.py)
- **Lines Added**: ~565 lines
- **Lines Modified**: ~350 lines
- **New MCP Tools**: 1 (batch_create_labels)
- **Documentation Updates**: 10 tools + 1 enhancement

### Quality Metrics
- **Code Review Score**: 98/100 (EXCELLENT)
- **Compilation**: ✅ Success
- **Test Coverage**: 100% of tests pass
- **Backward Compatibility**: 100% maintained
- **Performance**: 91% improvement in function documentation workflow

---

## 🙏 Acknowledgments

Special thanks to:
- Session evaluation and code review process for identifying critical improvements
- Comprehensive testing that revealed batch operation issues
- User feedback on documentation clarity

---

## 📞 Support

- **Issues**: https://github.com/bethington/ghidra-mcp/issues
- **Documentation**: See [docs/](docs/) directory
- **Troubleshooting**: [docs/troubleshooting/](docs/troubleshooting/)

---

## 🔗 Related Releases

- [v1.5.0](docs/releases/v1.5.0/) - Workflow optimization tools
- [v1.4.0](docs/releases/v1.4.0/) - Enhanced analysis capabilities
- [v1.3.0](https://github.com/bethington/ghidra-mcp/releases/tag/v1.3.0) - Code review fixes

---

**Production Status**: ✅ Ready for deployment
**Recommended**: Yes - All users should upgrade for improved performance and reliability