|
| 1 | +#Tool Renaming Guide |
| 2 | + |
| 3 | +How to safely rename MCP tools without breaking existing user configurations. |
| 4 | + |
| 5 | +##Overview |
| 6 | + |
| 7 | +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. |
| 8 | +The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +##Quick Steps |
| 13 | + |
| 14 | +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). |
| 15 | +2.**Add a deprecation alias** in[pkg/github/deprecated_tool_aliases.go](../pkg/github/deprecated_tool_aliases.go): |
| 16 | +```go |
| 17 | +varDeprecatedToolAliases =map[string]string{ |
| 18 | +"old_tool_name":"new_tool_name", |
| 19 | + } |
| 20 | +``` |
| 21 | +3.**Update documentation** (README, etc.) to reference the new canonical name |
| 22 | + |
| 23 | +That's it. The server will silently resolve old names to new ones. This will work across both local and remote MCP servers. |
| 24 | + |
| 25 | +##Example |
| 26 | + |
| 27 | +If renaming`get_issue` to`issue_read`: |
| 28 | + |
| 29 | +```go |
| 30 | +varDeprecatedToolAliases =map[string]string{ |
| 31 | +"get_issue":"issue_read", |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +A user with this configuration: |
| 36 | +```json |
| 37 | +{ |
| 38 | +"--tools":"get_issue,get_file_contents" |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +Will get`issue_read` and`get_file_contents` tools registered, with no errors. |