Skip to content

v2.0.0-breaking-changes.md

Latest commit

 

History

History
647 lines (486 loc) · 14 KB

v2.0.0-breaking-changes.md

File metadata and controls

647 lines (486 loc) · 14 KB

CyberChef MCP v2.0.0 Breaking Changes Guide

This document describes all breaking changes planned for CyberChef MCP v2.0.0 and provides migration guidance for users upgrading from v1.x.

Table of Contents

  1. Overview
  2. Breaking Changes Summary
  3. Tool Naming Convention (DEP001)
  4. Recipe Schema Format (DEP002)
  5. Error Response Format (DEP003)
  6. Configuration System (DEP004)
  7. Legacy Argument Handling (DEP005)
  8. Recipe Array Format (DEP006)
  9. Meta-Tool Renames (DEP007, DEP008)
  10. MCP Protocol Version Updates
  11. Migration Examples
  12. Testing Your Migration
  13. FAQ

Overview

CyberChef MCP v2.0.0 introduces several breaking changes to improve consistency, maintainability, and alignment with MCP best practices. These changes were announced in v1.8.0 with deprecation warnings to give users time to prepare.

Timeline

Version Status Description
v1.8.0 Released Deprecation warnings introduced
v1.8.x Current Migration preview tools available
v2.0.0 Planned Breaking changes enforced

Preparing for v2.0.0

  1. Enable deprecation warnings (default in v1.8.0+)
  2. Use the migration preview tool to analyze your recipes
  3. Test with v2 compatibility mode: V2_COMPATIBILITY_MODE=true
  4. Update your code following this guide

Breaking Changes Summary

Code Feature Impact Migration Effort
DEP001 Tool naming convention All tool calls Low
DEP002 Recipe schema format Recipe definitions Medium
DEP003 Error response format Error handling Low
DEP004 Configuration system Server configuration Low
DEP005 Legacy argument handling Recipe arguments Medium
DEP006 Recipe array format Recipe structure Medium
DEP007 cyberchef_bake rename Meta-tool calls Low
DEP008 cyberchef_search rename Meta-tool calls Low

Tool Naming Convention (DEP001)

What's Changing

The cyberchef_ prefix will be removed from all tool names in v2.0.0.

v1.x (Deprecated)

{
  "method": "tools/call",
  "params": {
    "name": "cyberchef_to_base64",
    "arguments": { "input": "Hello World" }
  }
}

v2.0.0 (New)

{
  "method": "tools/call",
  "params": {
    "name": "to_base64",
    "arguments": { "input": "Hello World" }
  }
}

Migration Steps

  1. Remove the cyberchef_ prefix from all tool names
  2. Update any hardcoded tool name references
  3. Update documentation and scripts

Tool Name Mapping

v1.x Name v2.0.0 Name
cyberchef_to_base64 to_base64
cyberchef_from_base64 from_base64
cyberchef_aes_encrypt aes_encrypt
cyberchef_aes_decrypt aes_decrypt
cyberchef_md5 md5
cyberchef_sha256 sha256
... ...

Recipe Schema Format (DEP002)

What's Changing

Recipe validation will use enhanced Zod v4 schemas with stricter type checking.

v1.x (Deprecated)

Loose validation allowing various formats:

{
  "recipe": [
    { "op": "To Base64" }
  ]
}

v2.0.0 (New)

Strict validation requiring complete recipe objects:

{
  "recipe": {
    "name": "My Recipe",
    "description": "Optional description",
    "operations": [
      { "op": "To Base64", "args": {} }
    ]
  }
}

Migration Steps

  1. Wrap array recipes in object format with name and operations
  2. Add explicit args objects to all operations (even if empty)
  3. Use the cyberchef_migration_preview tool to validate recipes

Error Response Format (DEP003)

What's Changing

Error responses will include structured error codes for programmatic handling.

v1.x (Deprecated)

{
  "error": {
    "message": "Invalid input: expected string"
  }
}

v2.0.0 (New)

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid input: expected string",
    "details": {
      "expected": "string",
      "received": "number",
      "path": "arguments.input"
    }
  }
}

Error Codes

Code Description
INVALID_INPUT Input validation failed
OPERATION_NOT_FOUND Unknown operation name
OPERATION_FAILED Operation execution error
RECIPE_INVALID Recipe validation failed
RATE_LIMITED Request rate limit exceeded
QUOTA_EXCEEDED Resource quota exceeded
INTERNAL_ERROR Unexpected server error

Migration Steps

  1. Update error handling to use error codes
  2. Add fallback handling for the message field
  3. Log or display details when available

Configuration System (DEP004)

What's Changing

Configuration will use a unified config file combined with environment variables.

v1.x (Deprecated)

Environment variables only:

CYBERCHEF_MAX_INPUT_SIZE=10485760
CYBERCHEF_CACHE_TTL=3600000
CYBERCHEF_ENABLE_TELEMETRY=false

v2.0.0 (New)

Unified config file (cyberchef.config.json) with env var overrides:

{
  "server": {
    "maxInputSize": 10485760,
    "cacheTTL": 3600000
  },
  "telemetry": {
    "enabled": false,
    "endpoint": null
  },
  "security": {
    "allowedOperations": ["*"],
    "blockedOperations": []
  }
}

Environment variables will still work as overrides:

# Overrides config file value
CYBERCHEF_MAX_INPUT_SIZE=20971520

Migration Steps

  1. Create cyberchef.config.json in your working directory
  2. Move environment variable settings to the config file
  3. Keep environment variables for deployment-specific overrides

Legacy Argument Handling (DEP005)

What's Changing

Positional array arguments will be replaced with named object arguments.

v1.x (Deprecated)

{
  "op": "To Base64",
  "args": ["A-Za-z0-9+/=", true]
}

v2.0.0 (New)

{
  "op": "To Base64",
  "args": {
    "alphabet": "A-Za-z0-9+/=",
    "showPrefix": true
  }
}

Migration Steps

  1. Convert array arguments to named objects
  2. Use the cyberchef_migration_preview tool in "transform" mode
  3. Consult operation documentation for argument names

Common Operations Argument Mapping

To Base64

Index Name Type
0 alphabet string

AES Encrypt

Index Name Type
0 key string
1 iv string
2 mode string
3 inputType string
4 outputType string

Find / Replace

Index Name Type
0 find string
1 replace string
2 global boolean

Recipe Array Format (DEP006)

What's Changing

Recipe operations using simple arrays will require explicit operation objects.

v1.x (Deprecated)

[
  { "op": "To Base64", "args": [] },
  { "op": "MD5", "args": [] }
]

v2.0.0 (New)

{
  "name": "Encode and Hash",
  "operations": [
    { "op": "To Base64", "args": {} },
    { "op": "MD5", "args": {} }
  ]
}

Migration Steps

  1. Wrap array recipes in an object with name and operations
  2. Convert array args to object args
  3. Add optional description and metadata fields

Meta-Tool Renames (DEP007, DEP008)

What's Changing

The cyberchef_bake and cyberchef_search meta-tools will be renamed.

DEP007: cyberchef_bake

Version Tool Name
v1.x cyberchef_bake
v2.0.0 bake

DEP008: cyberchef_search

Version Tool Name
v1.x cyberchef_search
v2.0.0 search

Migration Steps

  1. Update tool calls to use the new names
  2. Update any scripts or automation that reference these tools

MCP Protocol Version Updates

What's Changing

CyberChef MCP v2.0.0 will require MCP protocol version 2024-11-05 or later.

Protocol Changes

  1. Streaming responses - Large outputs will use streaming
  2. Progress notifications - Long operations report progress
  3. Cancellation support - Operations can be cancelled mid-execution
  4. Resource management - Explicit resource lifecycle management

Client Requirements

Ensure your MCP client supports:

  • Protocol version 2024-11-05 or later
  • Streaming content handling
  • Progress notification handling

Migration Examples

Example 1: Simple Tool Call Migration

Before (v1.x):

const result = await client.callTool({
  name: "cyberchef_to_base64",
  arguments: { input: "Hello World" }
});

After (v2.0.0):

const result = await client.callTool({
  name: "to_base64",
  arguments: { input: "Hello World" }
});

Example 2: Recipe Migration

Before (v1.x):

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

After (v2.0.0):

{
  "method": "tools/call",
  "params": {
    "name": "bake",
    "arguments": {
      "input": "Hello World",
      "recipe": {
        "name": "Encode and Hash",
        "operations": [
          { "op": "To Base64", "args": { "alphabet": "A-Za-z0-9+/=" } },
          { "op": "MD5", "args": {} }
        ]
      }
    }
  }
}

Example 3: Error Handling Migration

Before (v1.x):

try {
  const result = await client.callTool(params);
} catch (error) {
  console.error("Error:", error.message);
}

After (v2.0.0):

try {
  const result = await client.callTool(params);
} catch (error) {
  console.error(`Error [${error.code}]: ${error.message}`);
  if (error.details) {
    console.error("Details:", JSON.stringify(error.details, null, 2));
  }
}

Example 4: Using Migration Preview Tool

{
  "method": "tools/call",
  "params": {
    "name": "cyberchef_migration_preview",
    "arguments": {
      "recipe": [
        { "op": "To Base64", "args": ["A-Za-z0-9+/="] }
      ],
      "mode": "analyze"
    }
  }
}

Response:

{
  "compatible": true,
  "issues": [
    {
      "code": "DEP005",
      "location": "operations[0].args",
      "message": "Positional array arguments are deprecated",
      "severity": "warning",
      "fix": "Convert array arguments to named object: { key: value }"
    },
    {
      "code": "DEP006",
      "location": "root",
      "message": "Recipe passed as array instead of object",
      "severity": "warning",
      "fix": "Wrap recipe in object: { name: 'Recipe Name', operations: [...] }"
    }
  ],
  "issueCount": 2,
  "breakingCount": 0,
  "warningCount": 2
}

Testing Your Migration

Step 1: Enable Deprecation Warnings

Deprecation warnings are enabled by default in v1.8.0+. To ensure they're active:

# Ensure warnings are NOT suppressed
unset CYBERCHEF_SUPPRESS_DEPRECATIONS

Step 2: Use Migration Preview Tool

Analyze your recipes for compatibility:

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

Step 3: Enable v2 Compatibility Mode

Test with v2.0.0 behavior (deprecations become errors):

V2_COMPATIBILITY_MODE=true npm run mcp

Or in Docker:

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

Step 4: Transform Recipes

Use the transform mode to automatically convert recipes:

{
  "method": "tools/call",
  "params": {
    "name": "cyberchef_migration_preview",
    "arguments": {
      "recipe": [ /* legacy recipe */ ],
      "mode": "transform"
    }
  }
}

Step 5: Check Deprecation Stats

Review which deprecations you've triggered:

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

FAQ

Q: When will v2.0.0 be released?

A: v2.0.0 is planned for release after sufficient time has been given for users to migrate. Monitor the changelog and release notes for updates.

Q: Can I suppress deprecation warnings?

A: Yes, set CYBERCHEF_SUPPRESS_DEPRECATIONS=true. However, this is not recommended as it may cause issues when upgrading to v2.0.0.

Q: Will v1.x recipes work in v2.0.0?

A: No, v2.0.0 will enforce the new formats. Use the migration preview tool to update your recipes before upgrading.

Q: How do I report migration issues?

A: Open an issue on the GitHub repository with:

  1. Your current version
  2. The deprecation code(s) involved
  3. Your original recipe/configuration
  4. The error or unexpected behavior

Q: Is there a compatibility layer for v1.x recipes?

A: The transformRecipeToV2 function (available via the migration preview tool) provides automatic transformation. However, the result should be reviewed as some transformations are best-effort (e.g., array arguments are converted to arg0, arg1, etc.).

Q: What if I can't migrate before v2.0.0?

A: You can continue using v1.8.x until you're ready to migrate. v1.8.x will receive security updates for a reasonable period after v2.0.0 release.

Q: Do I need to update my MCP client?

A: Ensure your MCP client supports protocol version 2024-11-05 or later. Most modern MCP clients are compatible.

Q: Where can I find the argument names for operations?

A: Use the cyberchef_search tool to get operation details, or consult the CyberChef documentation. Argument names follow the operation's parameter names.

Need Help?

This document is part of CyberChef MCP v1.8.0 - Breaking Changes Preparation release.