Skip to content

v1.8.0.md

Latest commit

 

History

History
320 lines (247 loc) · 7.49 KB

v1.8.0.md

File metadata and controls

320 lines (247 loc) · 7.49 KB

CyberChef MCP v1.8.0 Release Notes

Release Date: December 2024 Codename: Breaking Changes Preparation

Overview

CyberChef MCP v1.8.0 is a preparatory release that introduces deprecation warnings, migration tools, and documentation to help users prepare for the breaking changes coming in v2.0.0. This release focuses on providing a smooth transition path while maintaining full backward compatibility.

Highlights

  • Deprecation Warning System - Runtime warnings for APIs changing in v2.0.0
  • Migration Preview Tool - Analyze and transform recipes for v2.0.0 compatibility
  • v2.0.0 Compatibility Mode - Opt-in preview of v2.0.0 behavior
  • Deprecation Stats Tool - Track deprecated API usage in your session
  • Comprehensive Breaking Changes Documentation

New Features

Deprecation Warning System (P0)

A comprehensive runtime warning system that alerts users when they use APIs that will change in v2.0.0.

Deprecation Codes:

Code Feature Description
DEP001 Tool naming cyberchef_ prefix will be removed
DEP002 Recipe schema Enhanced Zod v4 validation
DEP003 Error responses Structured error codes
DEP004 Configuration Unified config file + env vars
DEP005 Arguments Named object args replace arrays
DEP006 Recipe format Explicit operation objects required
DEP007 cyberchef_bake Will be renamed to bake
DEP008 cyberchef_search Will be renamed to search

Features:

  • Warnings emitted once per session per code (no spam)
  • Suppressible via CYBERCHEF_SUPPRESS_DEPRECATIONS=true
  • Detailed migration guidance included with each warning
  • Session-based tracking with statistics

Migration Preview Tool (P1)

New MCP tool cyberchef_migration_preview for analyzing and transforming recipes.

Usage:

{
  "method": "tools/call",
  "params": {
    "name": "cyberchef_migration_preview",
    "arguments": {
      "recipe": { /* your recipe */ },
      "mode": "analyze"
    }
  }
}

Modes:

  • analyze - Check recipe for v2.0.0 compatibility issues
  • transform - Automatically convert recipe to v2.0.0 format

Output (analyze mode):

{
  "compatible": true,
  "issues": [
    {
      "code": "DEP005",
      "location": "operations[0].args",
      "message": "Positional array arguments are deprecated",
      "severity": "warning",
      "fix": "Convert array arguments to named object"
    }
  ],
  "issueCount": 1,
  "breakingCount": 0,
  "warningCount": 1
}

v2.0.0 Compatibility Mode (P1)

Opt-in preview of v2.0.0 behavior where deprecation warnings become errors.

Enable:

V2_COMPATIBILITY_MODE=true npm run mcp

Or in Docker:

docker run -i --rm -e V2_COMPATIBILITY_MODE=true cyberchef-mcp

Behavior changes:

  • Deprecation warnings elevated to errors
  • Tool naming follows v2.0.0 conventions
  • Stricter recipe validation

Deprecation Stats Tool (P2)

New MCP tool cyberchef_deprecation_stats for tracking deprecated API usage.

Usage:

{
  "method": "tools/call",
  "params": {
    "name": "cyberchef_deprecation_stats",
    "arguments": {}
  }
}

Output:

{
  "warned": ["DEP001", "DEP005"],
  "warnedDetails": [
    {
      "code": "DEP001",
      "feature": "Tool naming convention",
      "description": "The 'cyberchef_' prefix will be removed...",
      "removalVersion": "2.0.0"
    }
  ],
  "total": 2,
  "suppressed": false,
  "v2CompatibilityMode": false,
  "availableCodes": ["DEP001", "DEP002", "DEP003", "DEP004", "DEP005", "DEP006", "DEP007", "DEP008"],
  "sessionDuration": 45000
}

Documentation

Breaking Changes Guide

Comprehensive documentation at docs/v2.0.0-breaking-changes.md covering:

  1. Tool Naming Convention changes
  2. Recipe Schema changes
  3. Error Response Format changes
  4. Configuration System changes
  5. Legacy Argument Handling changes
  6. Recipe Array Format changes
  7. Meta-Tool Renames
  8. MCP Protocol Version updates
  9. Migration examples for each change
  10. FAQ section

Configuration

New Environment Variables

Variable Default Description
V2_COMPATIBILITY_MODE false Enable v2.0.0 behavior preview
CYBERCHEF_SUPPRESS_DEPRECATIONS false Suppress deprecation warnings

Testing

Test Coverage

Category Tests Status
Deprecation System 43 Passing
Migration Preview 38 Passing
Total New Tests 81 Passing

Running Tests

# Run all MCP tests including v1.8.0 features
npm run test:mcp

# Run deprecation tests specifically
npm run test:mcp -- deprecation

# Run migration preview tests specifically
npm run test:mcp -- migration-preview

Migration Path

Recommended Migration Steps

  1. Upgrade to v1.8.0 - Install this release
  2. Monitor deprecation warnings - Note which deprecations you trigger
  3. Use migration preview - Analyze your recipes with cyberchef_migration_preview
  4. Transform recipes - Use transform mode to convert recipes
  5. Test with v2 mode - Enable V2_COMPATIBILITY_MODE=true
  6. Update tool names - Remove cyberchef_ prefixes
  7. Review breaking changes doc - Read docs/v2.0.0-breaking-changes.md

Example Migration

Before (v1.x):

{
  "name": "cyberchef_bake",
  "arguments": {
    "input": "Hello",
    "recipe": [
      { "op": "To Base64", "args": ["A-Za-z0-9+/="] }
    ]
  }
}

After (v2.0.0 compatible):

{
  "name": "bake",
  "arguments": {
    "input": "Hello",
    "recipe": {
      "name": "Encode Recipe",
      "operations": [
        { "op": "To Base64", "args": { "alphabet": "A-Za-z0-9+/=" } }
      ]
    }
  }
}

API Changes

New Exports from mcp-server.mjs

// Deprecation system
export {
    DEPRECATION_CODES,
    emitDeprecation,
    emitToolNamingDeprecation,
    emitMetaToolDeprecation,
    emitRecipeFormatDeprecation,
    getDeprecationStats,
    resetDeprecations,
    analyzeRecipeCompatibility,
    transformRecipeToV2,
    getToolName,
    stripToolPrefix,
    isV2CompatibilityMode,
    areSuppressed
};

// Configuration constants
export {
    V2_COMPATIBILITY_MODE,
    SUPPRESS_DEPRECATIONS
};

New Module: deprecation.mjs

A standalone module (src/node/deprecation.mjs) containing:

  • Deprecation code definitions
  • Warning emission logic
  • Recipe analysis and transformation
  • Session tracking
  • Utility functions

Compatibility

Backward Compatibility

  • All v1.7.x APIs remain functional
  • No breaking changes in this release
  • Existing recipes and configurations work unchanged

Forward Compatibility

  • Deprecation warnings guide users toward v2.0.0 patterns
  • Migration tools enable gradual transition
  • v2 compatibility mode allows testing before upgrade

Upgrade Instructions

From v1.7.x

# Pull latest image
docker pull ghcr.io/doublegate/cyberchef-mcp_v1:1.8.0

# Or update local installation
npm install

Verification

# Check version
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | docker run -i --rm ghcr.io/doublegate/cyberchef-mcp_v1:1.8.0

# Verify new tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | docker run -i --rm ghcr.io/doublegate/cyberchef-mcp_v1:1.8.0 | grep migration_preview

Known Issues

None at this time.

Contributors

  • DoubleGate (maintainer)

License

Apache-2.0

Full Changelog: v1.7.3...v1.8.0