Skip to content

Latest commit

 

History

History
74 lines (60 loc) · 2.72 KB

tool-renaming.md

File metadata and controls

74 lines (60 loc) · 2.72 KB

Tool Renaming Guide

How to safely rename MCP tools without breaking existing user configurations.

Overview

When tools are renamed, users who have the old tool name in their MCP configuration (for example, in X-MCP-Tools headers for the remote MCP server or --tools flags for the local MCP server) would normally get errors. The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names.

This allows us to rename tools safely, without introducing breaking changes for users that have a hard reference to those tools in their server configuration.

Quick Steps

  1. Rename the tool in your code (as usual, this will imply a range of changes like updating the tool registration, the tests and the toolsnaps).
  2. Add a deprecation alias in pkg/github/deprecated_tool_aliases.go: 
    var DeprecatedToolAliases = map[string]string{
    "old_tool_name": "new_tool_name",
}
  3. Update documentation (README, etc.) to reference the new canonical name

That's it. The server will silently resolve old names to new ones. This will work across both local and remote MCP servers.

Example

If renaming get_issue to issue_read:

var DeprecatedToolAliases = map[string]string{
    "get_issue": "issue_read",
}

A user with this configuration:

{
  "--tools": "get_issue,get_file_contents"
}

Will get issue_read and get_file_contents tools registered, with no errors.

Current Deprecations

Old Name New Name
add_project_item projects_write
cancel_workflow_run actions_run_trigger
delete_project_item projects_write
delete_workflow_run_logs actions_run_trigger
download_workflow_run_artifact actions_get
get_project projects_get
get_project_field projects_get
get_project_item projects_get
get_workflow actions_get
get_workflow_job actions_get
get_workflow_job_logs actions_get
get_workflow_run actions_get
get_workflow_run_logs actions_get
get_workflow_run_usage actions_get
list_project_fields projects_list
list_project_items projects_list
list_projects projects_list
list_workflow_jobs actions_list
list_workflow_run_artifacts actions_list
list_workflow_runs actions_list
list_workflows actions_list
rerun_failed_jobs actions_run_trigger
rerun_workflow_run actions_run_trigger
run_workflow actions_run_trigger
update_project_item projects_write