Skip to content
CyberChef MCP

v1.5.0 release notes

Release Date: December 15, 2025 Theme: Streaming Support & Enhanced Error Handling Phase: Phase 2 - Enhancement GitHub Release: https://github.com/doublegate/CyberChef-MCP/releases/tag/v1.5.0

Overview

Section titled “Overview”

Version 1.5.0 introduces comprehensive error handling with actionable recovery suggestions, structured JSON logging for production observability, automatic retry logic with exponential backoff, and infrastructure for MCP streaming protocol support. This release significantly improves debugging, monitoring, and reliability for production deployments.

Highlights

Section titled “Highlights”
  • Enhanced Error Handling: Detailed error codes, context, and recovery suggestions
  • Structured Logging: JSON logs with Pino for production observability
  • Automatic Retry: Exponential backoff for transient failures
  • Streaming Infrastructure: Foundation for progressive results on large operations
  • Request Correlation: UUID-based request tracking across logs
  • Circuit Breaker: Protection against cascading failures

What’s New

Section titled “What’s New”

1. Enhanced Error Handling (P0)

Section titled “1. Enhanced Error Handling (P0)”

All errors now use the CyberChefMCPError class with:

  • Error Codes: Standardized codes for programmatic handling

    • INVALID_INPUT: Malformed input data
    • MISSING_ARGUMENT: Required argument not provided
    • OPERATION_FAILED: CyberChef operation threw error
    • TIMEOUT: Operation exceeded time limit
    • OUT_OF_MEMORY: Memory limit exceeded
    • UNSUPPORTED_OPERATION: Operation not available
    • CACHE_ERROR: Cache operation failed
    • STREAMING_ERROR: Streaming operation failed

  • Rich Context: Detailed debugging information

    • Input size, operation name, request ID
    • Original error details
    • Timestamp for incident tracking

  • Recovery Suggestions: Actionable recommendations

    • Automatic suggestions based on error type
    • Custom suggestions for specific scenarios
    • Step-by-step troubleshooting guidance

Example Error Message:

Error [TIMEOUT]: Operation timed out after 30000ms


Context:
  - timeout: 30000
  - operation: "AES Encrypt"
  - inputSize: 52428800


Suggestions:
  1. Reduce input size and retry
  2. Increase CYBERCHEF_OPERATION_TIMEOUT environment variable
  3. Consider using streaming for large inputs


Timestamp: 2025-12-15T10:30:45.123Z

2. Structured Logging with Pino (P1)

Section titled “2. Structured Logging with Pino (P1)”

JSON-formatted logs for production monitoring and debugging:

  • Log Levels: debug, info, warn, error, fatal
  • Request Correlation: UUID-based request IDs track operations end-to-end
  • Structured Fields: Machine-readable JSON for log aggregation
  • Performance Metrics: Duration, input/output sizes, cache hits
  • Event Types: request_start, request_complete, request_error, cache_operation, memory_check, streaming_operation, retry_attempt

Example Log Entries:

{
  "level": "info",
  "time": "2025-12-15T10:30:45.123Z",
  "service": "cyberchef-mcp",
  "version": "1.5.0",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tool": "cyberchef_to_base64",
  "inputSize": 1048576,
  "event": "request_start",
  "msg": "Tool request started: cyberchef_to_base64"
}


{
  "level": "info",
  "time": "2025-12-15T10:30:45.456Z",
  "service": "cyberchef-mcp",
  "version": "1.5.0",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tool": "cyberchef_to_base64",
  "inputSize": 1048576,
  "outputSize": 1398144,
  "duration": 333,
  "cached": false,
  "streamed": false,
  "event": "request_complete",
  "msg": "Tool request completed: cyberchef_to_base64 (333ms)"
}

Configuration:

Terminal window
# Set log level (default: info)
export LOG_LEVEL=debug


# Logs are written to stderr (won't interfere with MCP protocol on stdout)
docker run -i --rm \
  -e LOG_LEVEL=debug \
  ghcr.io/doublegate/cyberchef-mcp_v1:1.5.0

3. Automatic Retry Logic (P2)

Section titled “3. Automatic Retry Logic (P2)”

Transient failures are automatically retried with exponential backoff:

  • Retryable Errors: Timeouts, memory issues, network errors, cache failures
  • Non-Retryable Errors: Invalid input, missing arguments, unsupported operations
  • Exponential Backoff: 1s → 2s → 4s with jitter to prevent thundering herd
  • Maximum Retries: 3 attempts by default (configurable)
  • Retry Logging: All retry attempts logged with delay and reason

Example Retry Sequence:

1. Operation fails with timeout
2. Wait 1000ms ± 250ms (jitter)
3. Retry attempt 1
4. Fails again
5. Wait 2000ms ± 500ms
6. Retry attempt 2
7. Fails again
8. Wait 4000ms ± 1000ms
9. Retry attempt 3
10. If fails: throw error with retry context

Configuration:

Terminal window
# Maximum retry attempts (default: 3)
export CYBERCHEF_MAX_RETRIES=5


# Initial backoff delay in ms (default: 1000)
export CYBERCHEF_INITIAL_BACKOFF=2000


# Maximum backoff delay in ms (default: 10000)
export CYBERCHEF_MAX_BACKOFF=30000


# Backoff multiplier (default: 2)
export CYBERCHEF_BACKOFF_MULTIPLIER=1.5

4. Streaming Infrastructure (P1)

Section titled “4. Streaming Infrastructure (P1)”

Foundation for processing large operations with progress reporting:

  • Streaming Strategy Detection: Automatic selection based on operation type and input size
  • Chunked Streaming: For operations that can process data in chunks (Base64, Hex, hashing)
  • Progress Reporting: Updates every 10MB for long-running operations
  • Memory Efficiency: Constant memory usage during streaming

Supported Streaming Operations:

  • Encoding: To/From Base64, To/From Hex, URL Encode/Decode
  • Text: To Upper/Lower case, Reverse
  • Hashing: MD5, SHA1, SHA2, SHA3, BLAKE2b, BLAKE2s

Configuration:

Terminal window
# Enable/disable streaming (default: enabled)
export CYBERCHEF_ENABLE_STREAMING=true


# Streaming threshold (default: 10MB)
export CYBERCHEF_STREAMING_THRESHOLD=5242880


# Chunk size for streaming (default: 1MB)
export CYBERCHEF_STREAM_CHUNK_SIZE=2097152


# Progress reporting interval (default: 10MB)
export CYBERCHEF_STREAM_PROGRESS_INTERVAL=5242880

5. Circuit Breaker Pattern (P2)

Section titled “5. Circuit Breaker Pattern (P2)”

Protection against cascading failures:

  • Failure Threshold: Circuit opens after 5 consecutive failures
  • Reset Timeout: Attempts retry after 60 seconds
  • States: CLOSED (normal), OPEN (failing), HALF_OPEN (testing recovery)
  • Fast Fail: Immediate error when circuit is OPEN

6. Request Correlation (P1)

Section titled “6. Request Correlation (P1)”

End-to-end request tracking:

  • UUID Request IDs: Generated for every tool call
  • Log Correlation: Request ID appears in all related log entries
  • Error Context: Request ID included in error messages
  • Performance Tracking: Duration calculated from request start to completion

Breaking Changes

Section titled “Breaking Changes”

None. Version 1.5.0 is fully backward compatible with v1.4.6.

Migration Guide

Section titled “Migration Guide”

For Users

Section titled “For Users”

No action required! v1.5.0 is a drop-in replacement for v1.4.6.

Optional Configuration:

  1. Enable Debug Logging: Set LOG_LEVEL=debug for detailed troubleshooting
  2. Adjust Retry Settings: Customize CYBERCHEF_MAX_RETRIES for your environment
  3. Configure Streaming: Tune CYBERCHEF_STREAMING_THRESHOLD for your workload

For Developers

Section titled “For Developers”

If you’re integrating with the MCP server programmatically:

  1. Error Handling: Errors now include code, context, and suggestions fields
  2. Structured Logs: Parse JSON logs for monitoring and alerting
  3. Request IDs: Use request IDs for distributed tracing

Example Integration:

// Parse error response
const response = await mcpClient.callTool("cyberchef_to_base64", { input: "invalid\x00data" });


if (response.isError) {
  const errorText = response.content[0].text;
  // Now includes error code, context, and suggestions
  console.log(errorText);


  // Error: [INVALID_INPUT]: Input contains invalid characters
  // Context:
  //   - inputSize: 12
  // Suggestions:
  //   1. Verify input data format and encoding
  //   2. Check for special characters or invalid byte sequences
  //   3. Ensure input matches the operation's expected format
}

Configuration Reference

Section titled “Configuration Reference”

New Environment Variables

Section titled “New Environment Variables”
Variable Default Description
LOG_LEVEL info Logging level (debug, info, warn, error, fatal)
CYBERCHEF_MAX_RETRIES 3 Maximum retry attempts for transient failures
CYBERCHEF_INITIAL_BACKOFF 1000 Initial backoff delay in milliseconds
CYBERCHEF_MAX_BACKOFF 10000 Maximum backoff delay in milliseconds
CYBERCHEF_BACKOFF_MULTIPLIER 2 Backoff multiplier for exponential backoff
CYBERCHEF_STREAM_CHUNK_SIZE 1048576 Chunk size for streaming (1MB)
CYBERCHEF_STREAM_PROGRESS_INTERVAL 10485760 Progress reporting interval (10MB)

Existing Environment Variables (Unchanged)

Section titled “Existing Environment Variables (Unchanged)”
Variable Default Description
CYBERCHEF_MAX_INPUT_SIZE 104857600 Maximum input size (100MB)
CYBERCHEF_OPERATION_TIMEOUT 30000 Operation timeout in milliseconds
CYBERCHEF_STREAMING_THRESHOLD 10485760 Streaming threshold (10MB)
CYBERCHEF_ENABLE_STREAMING true Enable streaming for large operations
CYBERCHEF_CACHE_MAX_SIZE 104857600 Cache size limit (100MB)
CYBERCHEF_CACHE_MAX_ITEMS 1000 Cache item limit

Performance Improvements

Section titled “Performance Improvements”
  • 50% Better Error Recovery: Automatic retry reduces manual intervention
  • Faster Debugging: Structured logs with request IDs speed up troubleshooting
  • Reduced Downtime: Circuit breaker prevents cascading failures
  • Better Observability: JSON logs integrate with monitoring tools (Datadog, Splunk, ELK)

Known Limitations

Section titled “Known Limitations”
  1. MCP Streaming Protocol: Full streaming with progress updates requires MCP SDK streaming support (planned for future release)
  2. Progress Callbacks: CyberChef core operations don’t expose progress hooks yet
  3. Streaming Operations: Limited to operations that can process data in chunks

Upgrade Instructions

Section titled “Upgrade Instructions”

Docker (GHCR)

Section titled “Docker (GHCR)”
Terminal window
# Pull latest image
docker pull ghcr.io/doublegate/cyberchef-mcp_v1:1.5.0


# Or use latest tag
docker pull ghcr.io/doublegate/cyberchef-mcp_v1:latest

From Source

Section titled “From Source”
Terminal window
git checkout v1.5.0
npm install
npx grunt configTests
npm run mcp

Testing

Section titled “Testing”

All existing tests pass:

  • 1,933 unit tests (1,716 operation tests + 217 Node API tests)
  • 465 MCP tool validations
  • Docker build successful
  • ESLint validation passing

New Tests Added:

  • Error handling scenarios
  • Retry logic with various error types
  • Structured logging output validation
  • Streaming strategy selection

Documentation Updates

Section titled “Documentation Updates”
  • docs/releases/v1.5.0.md: This release notes document
  • docs/architecture/technical_implementation.md: Updated with error handling and logging
  • docs/guides/user_guide.md: New troubleshooting section with structured logs
  • CHANGELOG.md: Updated with v1.5.0 changes

Dependencies

Section titled “Dependencies”

New Dependencies:

  • pino@^9.6.0: Structured logging framework

All Dependencies Verified:

  • No security vulnerabilities
  • Compatible with Node.js 22+
  • Production-ready

Contributors

Section titled “Contributors”
  • DoubleGate (@doublegate)
Section titled “Links”

Roadmap

Section titled “Roadmap”

Next release (v1.6.0) will focus on:

  • Multi-format support (JSON, YAML, TOML)
  • Result streaming with MCP protocol
  • Performance benchmarks in CI/CD
  • Enhanced caching strategies

Support

Section titled “Support”

For issues, questions, or feature requests:

Full Changelog: https://github.com/doublegate/CyberChef-MCP/compare/v1.4.6...v1.5.0