Add support for Tool Override to CLI. (#1841)

This change adds a new `--tools-override` option to `thv run` and
similar commands. The new option accepts a path to a file containing a
JSON structure like the following

```json
{
  "toolsOverride": {
    "actual-name": {
      "name": "new-name",
      "description": "Overridden description."
    }
  }
}
```

The override file is read once when the MCP server is started, and is
not reloaded on `thv restart`. This behaviour might change in the
future.

Note that Tool Override feature is mostly orthogonal to Tool Filtering
one, with the exception of the name used for filtering.

Specifically, overrides just change the name or description of an
existing tool, but do not limit access to other tools; filtering does
the exact opposite. When both an override and a filter are specified
for the same tool, the name to be used when specifying the filter is
the overridden name. We decided to implement it this way for two
reasons

1. the user is likely to think of tools in the MCP server in terms of
   the new names rather than the actual ones, since the former are
   those visible to the Client, and
2. the MCP spec does not specify means for MCP servers to publish the
   full list of tools without first running it, and determining those
   available requires starting the server itself and issuing a
   `tools/list` call, i.e. require acting as a client.

As a consequence, it's impossible to reliably determine the full list
of tools, and a valid filter in one scenario might not work in another
one.

Fixes #1511

Author: blkt

cmd/thv/app/run_flags.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/stacklok/toolhive/pkg/auth"
 	"github.com/stacklok/toolhive/pkg/authz"
+	"github.com/stacklok/toolhive/pkg/cli"
 	cfg "github.com/stacklok/toolhive/pkg/config"
 	"github.com/stacklok/toolhive/pkg/container"
 	"github.com/stacklok/toolhive/pkg/container/runtime"
@@ -89,6 +90,8 @@ type RunFlags struct {
 
 	// Tools filter
 	ToolsFilter []string
+	// Tools override file
+	ToolsOverride string
 
 	// Configuration import
 	FromConfig string
@@ -200,6 +203,12 @@ func AddRunFlags(cmd *cobra.Command, config *RunFlags) {
 		nil,
 		"Filter MCP server tools (comma-separated list of tool names)",
 	)
+	cmd.Flags().StringVar(
+		&config.ToolsOverride,
+		"tools-override",
+		"",
+		"Path to a JSON file containing overrides for MCP server tools names and descriptions",
+	)
 	cmd.Flags().StringVar(&config.FromConfig, "from-config", "", "Load configuration from exported file")
 
 	// Environment file processing flags
@@ -420,18 +429,31 @@ func buildRunnerConfig(
 		}),
 	}
 
+	var toolsOverride map[string]runner.ToolOverride
+	if runFlags.ToolsOverride != "" {
+		loadedToolsOverride, err := cli.LoadToolsOverride(runFlags.ToolsOverride)
+		if err != nil {
+			return nil, fmt.Errorf("failed to load tools override: %v", err)
+		}
+		toolsOverride = *loadedToolsOverride
+	}
+
+	opts = append(opts, runner.WithToolsOverride(toolsOverride))
 	// Configure middleware from flags
-	opts = append(opts, runner.WithMiddlewareFromFlags(
-		oidcConfig,
-		runFlags.ToolsFilter,
-		nil,
-		telemetryConfig,
-		runFlags.AuthzConfig,
-		runFlags.EnableAudit,
-		runFlags.AuditConfig,
-		runFlags.Name,
-		runFlags.Transport,
-	))
+	opts = append(
+		opts,
+		runner.WithMiddlewareFromFlags(
+			oidcConfig,
+			runFlags.ToolsFilter,
+			toolsOverride,
+			telemetryConfig,
+			runFlags.AuthzConfig,
+			runFlags.EnableAudit,
+			runFlags.AuditConfig,
+			runFlags.Name,
+			runFlags.Transport,
+		),
+	)
 
 	if remoteServerMetadata, ok := serverMetadata.(*registry.RemoteServerMetadata); ok {
 		if remoteAuthConfig := getRemoteAuthFromRemoteServerMetadata(remoteServerMetadata); remoteAuthConfig != nil {

docs/cli/thv_run.md

@@ -0,0 +1,38 @@
+// Package cli provides utility functions specific to the
+// CLI that we want to test more thoroughly.
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/stacklok/toolhive/pkg/runner"
+)
+
+// ToolsOverrideJSON is a struct that represents the tools override JSON file.
+type toolsOverrideJSON struct {
+	ToolsOverride map[string]runner.ToolOverride `json:"toolsOverride"`
+}
+
+// LoadToolsOverride loads the tools override JSON file from the given path.
+func LoadToolsOverride(path string) (*map[string]runner.ToolOverride, error) {
+	jsonFile, err := os.Open(filepath.Clean(path))
+	if err != nil {
+		return nil, fmt.Errorf("failed to open tools override file: %v", err)
+	}
+	defer jsonFile.Close()
+
+	var toolsOverride toolsOverrideJSON
+	decoder := json.NewDecoder(jsonFile)
+	err = decoder.Decode(&toolsOverride)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode tools override file: %v", err)
+	}
+	if toolsOverride.ToolsOverride == nil {
+		return nil, errors.New("tools override are empty")
+	}
+	return &toolsOverride.ToolsOverride, nil
+}

pkg/cli/tools_override.go

@@ -0,0 +1,209 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/stacklok/toolhive/pkg/runner"
+)
+
+func TestLoadToolsOverride(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		jsonContent    string
+		expectedResult *map[string]runner.ToolOverride
+		expectError    bool
+	}{
+		{
+			name: "valid tools override with name and description",
+			jsonContent: `{
+				"toolsOverride": {
+					"original_tool": {
+						"name": "renamed_tool",
+						"description": "A new description for the tool"
+					}
+				}
+			}`,
+			expectedResult: &map[string]runner.ToolOverride{
+				"original_tool": {
+					Name:        "renamed_tool",
+					Description: "A new description for the tool",
+				},
+			},
+			expectError: false,
+		},
+		{
+			name: "valid tools override with only name",
+			jsonContent: `{
+				"toolsOverride": {
+					"tool1": {
+						"name": "new_tool_name"
+					}
+				}
+			}`,
+			expectedResult: &map[string]runner.ToolOverride{
+				"tool1": {
+					Name: "new_tool_name",
+				},
+			},
+			expectError: false,
+		},
+		{
+			name: "valid tools override with only description",
+			jsonContent: `{
+				"toolsOverride": {
+					"tool2": {
+						"description": "Updated description only"
+					}
+				}
+			}`,
+			expectedResult: &map[string]runner.ToolOverride{
+				"tool2": {
+					Description: "Updated description only",
+				},
+			},
+			expectError: false,
+		},
+		{
+			name: "valid tools override with multiple tools",
+			jsonContent: `{
+				"toolsOverride": {
+					"tool1": {
+						"name": "renamed_tool1",
+						"description": "Description for tool1"
+					},
+					"tool2": {
+						"name": "renamed_tool2"
+					},
+					"tool3": {
+						"description": "Description for tool3"
+					}
+				}
+			}`,
+			expectedResult: &map[string]runner.ToolOverride{
+				"tool1": {
+					Name:        "renamed_tool1",
+					Description: "Description for tool1",
+				},
+				"tool2": {
+					Name: "renamed_tool2",
+				},
+				"tool3": {
+					Description: "Description for tool3",
+				},
+			},
+			expectError: false,
+		},
+		{
+			name: "valid empty tools override",
+			jsonContent: `{
+				"toolsOverride": {}
+			}`,
+			expectedResult: &map[string]runner.ToolOverride{},
+			expectError:    false,
+		},
+		{
+			name: "invalid JSON syntax",
+			jsonContent: `{
+				"toolsOverride": {
+					"tool1": {
+						"name": "invalid_json"
+					}
+				}
+			`, // Missing closing brace
+			expectedResult: nil,
+			expectError:    true,
+		},
+		{
+			name: "missing toolsOverride field",
+			jsonContent: `{
+				"otherField": "value"
+			}`,
+			expectedResult: nil,
+			expectError:    true,
+		},
+		{
+			name: "null toolsOverride field",
+			jsonContent: `{
+				"toolsOverride": null
+			}`,
+			expectedResult: nil,
+			expectError:    true,
+		},
+		{
+			name:           "empty file",
+			jsonContent:    ``,
+			expectedResult: nil,
+			expectError:    true,
+		},
+		{
+			name:           "non-JSON content",
+			jsonContent:    `This is not JSON content`,
+			expectedResult: nil,
+			expectError:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Create a temporary file
+			tmpFile, err := os.CreateTemp("", "tools_override_test_*.json")
+			if err != nil {
+				t.Fatalf("Failed to create temp file: %v", err)
+			}
+			defer os.Remove(tmpFile.Name())
+
+			// Write test content to the file
+			if tt.jsonContent != "" {
+				_, err = tmpFile.WriteString(tt.jsonContent)
+				if err != nil {
+					t.Fatalf("Failed to write to temp file: %v", err)
+				}
+			}
+			tmpFile.Close()
+
+			// Test the LoadToolsOverride function
+			result, err := LoadToolsOverride(tmpFile.Name())
+
+			// Check error expectations
+			if tt.expectError {
+				assert.Error(t, err)
+				assert.Nil(t, result)
+			} else {
+				assert.NoError(t, err)
+				assert.NotNil(t, result)
+				// Compare the results
+				assert.Equal(t, tt.expectedResult, result)
+			}
+		})
+	}
+}
+
+func TestLoadToolsOverride_FileNotFound(t *testing.T) {
+	t.Parallel()
+
+	// Test with non-existent file
+	nonExistentFile := filepath.Join(os.TempDir(), "non_existent_file.json")
+
+	result, err := LoadToolsOverride(nonExistentFile)
+
+	if err == nil {
+		t.Errorf("Expected error for non-existent file but got none")
+	}
+
+	if result != nil {
+		t.Errorf("Expected nil result for non-existent file but got: %+v", result)
+	}
+
+	if !strings.Contains(err.Error(), "failed to open tools override file") {
+		t.Errorf("Expected error to contain 'failed to open tools override file', but got: %v", err)
+	}
+}

pkg/cli/tools_override_test.go

@@ -475,7 +475,7 @@ func addToolFilterMiddlewares(
 	toolsFilter []string,
 	toolsOverride map[string]ToolOverride,
 ) []types.MiddlewareConfig {
-	if len(toolsFilter) == 0 {
+	if len(toolsFilter) == 0 && len(toolsOverride) == 0 {
 		return middlewareConfigs
 	}
 
@@ -789,15 +789,6 @@ func (b *runConfigBuilder) validateConfig(imageMetadata *registry.ImageMetadata)
 		}
 	}
 
-	if c.ToolsFilter != nil && imageMetadata != nil && imageMetadata.Tools != nil {
-		logger.Debugf("Using tools filter: %v", c.ToolsFilter)
-		for _, tool := range c.ToolsFilter {
-			if !slices.Contains(imageMetadata.Tools, tool) {
-				return fmt.Errorf("tool %s not found in registry", tool)
-			}
-		}
-	}
-
 	if c.ToolsOverride != nil && imageMetadata != nil && imageMetadata.Tools != nil {
 		logger.Debugf("Using tools override: %v", c.ToolsOverride)
 		for toolName := range c.ToolsOverride {
@@ -807,6 +798,26 @@ func (b *runConfigBuilder) validateConfig(imageMetadata *registry.ImageMetadata)
 		}
 	}
 
+	if c.ToolsFilter != nil && imageMetadata != nil && imageMetadata.Tools != nil {
+		logger.Debugf("Using tools filter: %v", c.ToolsFilter)
+		for _, tool := range c.ToolsFilter {
+			name := tool
+
+			if c.ToolsOverride != nil {
+				for actualName, toolOverride := range c.ToolsOverride {
+					if toolOverride.Name == tool {
+						name = actualName
+						break
+					}
+				}
+			}
+
+			if !slices.Contains(imageMetadata.Tools, name) {
+				return fmt.Errorf("tool %s not found in registry", name)
+			}
+		}
+	}
+
 	return nil
 }