v2.0.0 migration

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. Withdrawn Changes (DEP001, DEP007, DEP008)
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 — withdrawn, see item 3)
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	WITHDRAWN — nothing to do	None
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	WITHDRAWN — nothing to do	None
DEP008	cyberchef_search rename	WITHDRAWN — nothing to do	None

Three of the eight announced changes are not happening. DEP001, DEP007 and DEP008 warned since v1.8.0 that the cyberchef_ prefix would be removed. It is not being removed, in v2.0.0 or later. See Withdrawn Changes for the measurements behind the reversal. If you already renamed your tool calls in anticipation, revert them — the prefixed names are the ones that work.

---

Withdrawn Changes (DEP001, DEP007, DEP008)

The cyberchef_ prefix is permanent

These three deprecations are withdrawn, not deferred. No release will remove the cyberchef_ prefix, and cyberchef_bake and cyberchef_search keep their names.

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

That is correct in v1.x and it is correct in v2.0.0. No migration is required. If you renamed tool calls in anticipation of the announced change, revert them.

Why it was reversed

This is a reversal of a promise published in v1.8.0, so the reasoning is set out rather than the change simply dropped. All three points were measured against the running server:

1. It saves 2.6%. The tools/list payload is 483 tools, 183,115 bytes, roughly 45,800 tokens — charged on every request before the user types anything. Removing the prefix from every name saves 1,208 bytes. That is rounding error against the real number, and it does not justify breaking every existing integration.

2. Nineteen names collide once bare. MCP keeps tool names in a flat namespace per session, so a bare name competes with every other connected server:

bake  search  md5  sha1  sha2  hash  filter  sort  merge  diff
reverse  unique  fork  jump  label  comment  register  subtract  parse_uri

Nearly every other MCP server plausibly defines search. The prefix is what makes exposing a tool called “search” safe at all — which makes DEP007 and DEP008 the worst two of the three to enact.

3. The real problem is the tool count, not the name length. Published measurement puts model tool-selection quality as degrading past roughly 50 tool definitions; this server exposes 483. Curating which tools are exposed by default is a ~90% context reduction with no loss of reach, because cyberchef_bake can invoke any operation by name and cyberchef_search discovers them. Shortening names is a 2.6% reduction that breaks callers. The effort went to the first.

Withdrawing costs nobody anything

No code can depend on a name that has never shipped. The prefixed names have worked in every release and continue to.

What you will see at runtime

emitDeprecation("DEP001") no longer emits a deprecation. It emits a one-time informational notice, and — importantly — it is not elevated to an error under V2_COMPATIBILITY_MODE:

[WITHDRAWN] DEP001: Tool naming convention -- the announced change is NOT happening.
  WITHDRAWN: the 'cyberchef_' prefix is NOT being removed. It stays permanently.
  No action required. Keep using cyberchef_to_base64 and the other prefixed names.

V2_COMPATIBILITY_MODE=true exists so you can find out what v2.0.0 will break. Reporting a withdrawn change as an error there would be actively misleading — telling you to migrate away from a name that is staying is worse than saying nothing.

getToolName() returns the prefixed name in every mode, including with an explicit forV2 = true. The parameter is retained because it is exported and callers pass it; changing the arity would be a breaking change in service of a no-op.

---

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)

Corrected in v2.10.0. This section previously described the file below as shipping in v2.0.0. It did not: no loader was written, and a cyberchef.config.json was read by nothing at all until v2.10.0. If you created one on the strength of this guide between v2.0.0 and v2.9.0, it was silently ignored, and it will start taking effect the moment you upgrade to v2.10.0 – check its contents before you do. The schema below is the one that actually exists.

What changed

Settings can be given in a cyberchef.config.json file as well as through environment variables. Nothing is required: a deployment with no file behaves exactly as it did before.

The file

Sections group the settings; every setting is also still an environment variable. Written to the working directory, or wherever CYBERCHEF_CONFIG_FILE points.

{
  "server":        { "maxInputSize": 10485760, "operationTimeout": 30000 },
  "cache":         { "enabled": true, "maxSize": 104857600 },
  "security":      { "offline": false, "maxRegexLength": 1000 },
  "tools":         { "surface": "index" },
  "observability": { "metricsEnabled": false, "telemetryEnabled": false }
}

The available sections are server, cache, batch, streaming, workers, retry, rateLimit, recipes, http, socket, auth, tools, security, observability and compatibility. Every setting name and its environment-variable equivalent is listed in the configuration guide.

Precedence

environment variable  >  config file  >  built-in default

So docker run -e CYBERCHEF_OFFLINE=true still wins over a file baked into the image. The startup log names any setting the environment overrode, so the two never disagree silently.

It fails closed

Malformed JSON, an unknown section, an unknown setting or a value of the wrong type stops the server, with a message naming the mistake:

cyberchef.config.json: unknown setting "security.offlien" (did you mean "offline"?).
Known settings in "security": auditEnabled, maxRegexLength, offline

The server did not start. Fix the file, or remove it to use environment variables only.

That is deliberate. This file sets the offline switch, the regex-length cap and the operation allowlist, and the defect being corrected here was a configuration that was accepted and ignored. Running on defaults an operator did not choose, and does not know they have, is the worse outcome.

Migration steps

1. Create cyberchef.config.json in the working directory, or point CYBERCHEF_CONFIG_FILE at one.
2. Move settings out of environment variables into it, using the section names above.
3. Keep environment variables for whatever should be deployment-specific – they win.
4. Start the server and read the Config file: line in the startup log to confirm what applied.

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)

Withdrawn. cyberchef_bake and cyberchef_search keep their names permanently. See Withdrawn Changes.

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 — nothing to migrate

Tool names do not change. This is correct in v1.x and in v2.0.0:

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

An earlier draft of this guide showed an “After” block renaming this to to_base64. That was the DEP001 rename, which is withdrawn — the server has never exposed to_base64 and never will, so following that example would have produced a Tool not found error. Keep the prefixed name.

Example 2: Recipe Migration

The tool name is unchanged — cyberchef_bake in both. What changes is the recipe shape (DEP006) and the argument shape (DEP005).

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": "cyberchef_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?

• Documentation: Project README
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

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