wehub-resource-sync
75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
# 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](../pkg/github/deprecated_tool_aliases.go):
|
|
```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`:
|
|
|
|
```go
|
|
var DeprecatedToolAliases = map[string]string{
|
|
"get_issue": "issue_read",
|
|
}
|
|
```
|
|
|
|
A user with this configuration:
|
|
```json
|
|
{
|
|
"--tools": "get_issue,get_file_contents"
|
|
}
|
|
```
|
|
|
|
Will get `issue_read` and `get_file_contents` tools registered, with no errors.
|
|
|
|
## Current Deprecations
|
|
|
|
<!-- START AUTOMATED ALIASES -->
|
|
| 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` |
|
|
<!-- END AUTOMATED ALIASES -->
|