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 — WITHDRAWN in v2.0.0, see below
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 — WITHDRAWN in v2.0.0, see below
DEP008	cyberchef_search	Will be renamed to search — WITHDRAWN in v2.0.0, see below

Correction, added 2026-08-31. DEP001, DEP007 and DEP008 were withdrawn in v2.0.0. The cyberchef_ prefix is permanent and the two meta-tools keep their names. Removing the prefix was measured at 2.6% of the tools/list payload (1,208 of 183,115 bytes) against 19 colliding tool names in MCP’s flat namespace and a break for every existing integration. This page is left as the historical record of what v1.8.0 announced; see docs/v2.0.0-breaking-changes.md for what actually shipped.

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