chore: import upstream snapshot with attribution

2026-07-13 12:37:57 +08:00
commit e30f8ba47c
533 changed files with 115926 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 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 -->