From 6c460ce78c9cdf471ae64634a564e79d956c84a2 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 12:31:51 +0000 Subject: [PATCH 01/32] Add aitools mcp serve, the stdio proxy for managed MCP servers `databricks aitools mcp serve --profile

--service ` is the command each installed MCP entry runs. It binds to the profile, refusing to start when the profile is gone, re-pointed at another host, or cannot mint a token (exit 2 with the message on stderr), then bridges newline-delimited JSON-RPC on stdin/stdout to the service endpoint. - Binding runs before stdin is read; the bound config is set on the command context so the exit-time telemetry upload authenticates with it. - The proxy sets the User-Agent extras aitools-mcp/proxy and aitools-mcp-client/, plus the workspace routing header, and appends the bound workspace and profile to the initialize instructions. - A token refresh failure mid-session answers that request with an error naming the profile, then exits 2. - The root command skips the stale-version warning for serve, and the exit status now comes from root.ExitStatus through main. - Fake /ai-gateway/mcp-services/{name} endpoint in testserver, with acceptance tests for stdout purity and binding errors. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/.databrickscfg | 3 + .../mcp/serve-binding-errors/out.stderr.txt | 3 + .../mcp/serve-binding-errors/out.stdout.txt | 0 .../mcp/serve-binding-errors/out.test.toml | 1 + .../mcp/serve-binding-errors/output.txt | 33 ++++ .../mcp/serve-binding-errors/requests.ndjson | 4 + .../aitools/mcp/serve-binding-errors/script | 46 ++++++ .../mcp/serve-passthrough/.databrickscfg | 3 + .../mcp/serve-passthrough/out.stderr.txt | 1 + .../mcp/serve-passthrough/out.test.toml | 1 + .../aitools/mcp/serve-passthrough/output.txt | 10 ++ .../mcp/serve-passthrough/requests.ndjson | 4 + .../cmd/aitools/mcp/serve-passthrough/script | 14 ++ cmd/aitools/mcp.go | 1 + cmd/aitools/mcp_serve.go | 147 ++++++++++++++++++ cmd/aitools/mcp_serve_test.go | 69 ++++++++ cmd/aitools/mcp_test.go | 2 +- cmd/root/root.go | 7 +- cmd/root/silent_err.go | 24 +++ cmd/root/stale_version.go | 11 +- cmd/root/stale_version_test.go | 15 ++ libs/aitools/mcp/proxy/run.go | 64 ++++++++ libs/aitools/mcp/proxy/run_test.go | 89 +++++++++++ libs/testserver/handlers.go | 4 + libs/testserver/mcp_endpoint.go | 110 +++++++++++++ libs/testserver/mcp_endpoint_test.go | 54 +++++++ main.go | 2 +- 27 files changed, 713 insertions(+), 9 deletions(-) create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/.databrickscfg create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/out.test.toml create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/requests.ndjson create mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/script create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/.databrickscfg create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/out.test.toml create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/output.txt create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/requests.ndjson create mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/script create mode 100644 cmd/aitools/mcp_serve.go create mode 100644 cmd/aitools/mcp_serve_test.go create mode 100644 libs/aitools/mcp/proxy/run.go create mode 100644 libs/aitools/mcp/proxy/run_test.go create mode 100644 libs/testserver/mcp_endpoint.go create mode 100644 libs/testserver/mcp_endpoint_test.go diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/.databrickscfg b/acceptance/cmd/aitools/mcp/serve-binding-errors/.databrickscfg new file mode 100644 index 00000000000..0369be633c5 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/.databrickscfg @@ -0,0 +1,3 @@ +[logfood] +host = $DATABRICKS_HOST +token = test-token-logfood diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt new file mode 100644 index 00000000000..40d39ba099e --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt @@ -0,0 +1,3 @@ +Error: --output does not apply to serve: its stdout carries the MCP protocol + +Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.test.toml b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt new file mode 100644 index 00000000000..4138ce323f6 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -0,0 +1,33 @@ + +=== The bound profile is not in the config file + +>>> cat out.stderr.txt +MCP server system.ai.genie_one_mcp is bound to Databricks profile "gone", which no longer exists in .databrickscfg. Recreate it with: databricks auth login --profile gone or remove the server with: databricks aitools mcp remove --profile gone + +Exit code: 2 +stdout bytes: 0 + +=== The profile now points at another host than the one recorded + +>>> cat out.stderr.txt +MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --profile logfood and add it again. + +Exit code: 2 +stdout bytes: 0 + +=== Flags are required and validated before the binding checks + +>>> cat out.stderr.txt +Error: --profile is required + +Exit code: 1 + +>>> cat out.stderr.txt +Error: unknown agent "nope" + +Exit code: 1 + +>>> cat out.stderr.txt +Error: --output does not apply to serve: its stdout carries the MCP protocol + +Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/requests.ndjson b/acceptance/cmd/aitools/mcp/serve-binding-errors/requests.ndjson new file mode 100644 index 00000000000..e1176541638 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/requests.ndjson @@ -0,0 +1,4 @@ +{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"0.0.1"}}} +{"jsonrpc":"2.0","method":"notifications/initialized"} +{"jsonrpc":"2.0","id":2,"method":"tools/list"} +{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hello"}}} diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script new file mode 100644 index 00000000000..a4f658f5435 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -0,0 +1,46 @@ +# Isolate HOME so the state file written below lands in this test directory. +sethome home +envsubst < .databrickscfg > out && mv out .databrickscfg +export DATABRICKS_CONFIG_FILE=.databrickscfg + +# Binding failures exit 2 with one message on stderr. Nothing reaches stdout, and stdin is not read. +title "The bound profile is not in the config file" +errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt +echo "stdout bytes: $(wc -c < out.stdout.txt)" + +# A state record for logfood that points at another host: the proxy never follows the profile. +mkdir -p home/.databricks/aitools/mcp +cat > home/.databricks/aitools/mcp/state.json <<'JSON' +{ + "schema_version": 1, + "servers": [ + { + "name": "genie_one_mcp-logfood", + "service": "system.ai.genie_one_mcp", + "profile": "logfood", + "host": "https://other.test", + "workspace_id": "", + "sign_in_required": false, + "command": "", + "config_file": "", + "agents": {}, + "installed_at": "2026-01-01T00:00:00Z", + "cli_version": "0.0.0" + } + ] +} +JSON + +title "The profile now points at another host than the one recorded" +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt +echo "stdout bytes: $(wc -c < out.stdout.txt)" + +title "Flags are required and validated before the binding checks" +errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent nope < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/.databrickscfg b/acceptance/cmd/aitools/mcp/serve-passthrough/.databrickscfg new file mode 100644 index 00000000000..0369be633c5 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/.databrickscfg @@ -0,0 +1,3 @@ +[logfood] +host = $DATABRICKS_HOST +token = test-token-logfood diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt new file mode 100644 index 00000000000..ab0a72fa0b6 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt @@ -0,0 +1 @@ +No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL]. diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/out.test.toml b/acceptance/cmd/aitools/mcp/serve-passthrough/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt new file mode 100644 index 00000000000..1baa038b78f --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt @@ -0,0 +1,10 @@ + +=== Stdout holds one JSON-RPC message per line; the notification gets no reply +{"id":1,"instructions":"Fake Databricks MCP service for tests.\n\nThis server is bound to Databricks workspace [DATABRICKS_URL] (CLI profile \"logfood\"). Its tools act on that workspace only.","tools":[],"text":null,"error":null} +{"id":2,"instructions":null,"tools":["echo"],"text":null,"error":null} +{"id":3,"instructions":null,"tools":[],"text":"hello","error":null} + +=== Diagnostics go to stderr only + +>>> cat out.stderr.txt +No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL]. diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/requests.ndjson b/acceptance/cmd/aitools/mcp/serve-passthrough/requests.ndjson new file mode 100644 index 00000000000..e1176541638 --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/requests.ndjson @@ -0,0 +1,4 @@ +{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"0.0.1"}}} +{"jsonrpc":"2.0","method":"notifications/initialized"} +{"jsonrpc":"2.0","id":2,"method":"tools/list"} +{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hello"}}} diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script new file mode 100644 index 00000000000..5307e293fec --- /dev/null +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -0,0 +1,14 @@ +# Isolate HOME so the proxy finds no state file and no agent config, as on a fresh machine. +sethome home +envsubst < .databrickscfg > out && mv out .databrickscfg +export DATABRICKS_CONFIG_FILE=.databrickscfg + +# DATABRICKS_HOST points elsewhere; the proxy must still talk to the profile's host. +export DATABRICKS_HOST=https://elsewhere.test + +# Responses may arrive in any order, so they are sorted by id. jq -s also fails when any stdout line is not JSON. +title "Stdout holds one JSON-RPC message per line; the notification gets no reply" +$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> out.stderr.txt | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' + +title "Diagnostics go to stderr only" +trace cat out.stderr.txt diff --git a/cmd/aitools/mcp.go b/cmd/aitools/mcp.go index 69a7f872166..b275848610e 100644 --- a/cmd/aitools/mcp.go +++ b/cmd/aitools/mcp.go @@ -39,6 +39,7 @@ func NewMcpCmd() *cobra.Command { cmd.AddCommand(NewMcpAddCmd()) cmd.AddCommand(NewMcpListCmd()) cmd.AddCommand(NewMcpRemoveCmd()) + cmd.AddCommand(NewMcpServeCmd()) return cmd } diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go new file mode 100644 index 00000000000..bbef835d4cd --- /dev/null +++ b/cmd/aitools/mcp_serve.go @@ -0,0 +1,147 @@ +package aitools + +import ( + "context" + "errors" + "fmt" + "net/http" + "os" + "os/signal" + "sync" + "syscall" + + "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/aitools/agents" + "github.com/databricks/cli/libs/aitools/mcp" + "github.com/databricks/cli/libs/aitools/mcp/proxy" + "github.com/databricks/cli/libs/cmdctx" + "github.com/spf13/cobra" +) + +// serveExitCode is the exit status for binding and auth failures, so agents and `list --check` +// can tell them from transport errors. +const serveExitCode = 2 + +type mcpServeFlags struct { + service string + agent string +} + +// NewMcpServeCmd returns the hidden `aitools mcp serve`: the stdio MCP proxy an agent starts for one +// installed server. Its stdout carries only JSON-RPC messages; every diagnostic goes to stderr. +func NewMcpServeCmd() *cobra.Command { + var f mcpServeFlags + cmd := &cobra.Command{ + Use: "serve", + Short: "Serve one Databricks managed MCP server over stdio", + Hidden: true, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + return runMcpServe(cmd, f) + }, + } + cmd.Flags().StringVar(&f.service, "service", "", "Full name of the MCP service, for example system.ai.github") + cmd.Flags().StringVar(&f.agent, "agent", "", "Registry name of the calling agent, used only for the User-Agent") + return cmd +} + +// runMcpServe runs the binding checks, then bridges stdio to the service until stdin closes or a +// signal arrives. +func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { + if out := cmd.Flag("output"); out != nil && out.Changed { + return errors.New("--output does not apply to serve: its stdout carries the MCP protocol") + } + profileName := profileFlag(cmd) + if profileName == "" { + return errors.New("--profile is required") + } + if f.service == "" { + return errors.New("--service is required") + } + if f.agent != "" && agents.ByName(f.agent) == nil { + return fmt.Errorf("unknown agent %q", f.agent) + } + + state, err := mcp.LoadState(cmd.Context()) + if err != nil { + return serveFailure(cmd, 1, err) + } + cfg, _, err := mcp.Bind(cmd.Context(), mcp.BindOptions{ + Profile: profileName, + Service: f.service, + State: state, + Stderr: cmd.ErrOrStderr(), + }) + if err != nil { + return serveFailure(cmd, serveExitCode, err) + } + + // The bound profile authenticates the exit-time telemetry upload. + cmd.SetContext(cmdctx.SetConfigUsed(cmd.Context(), cfg)) + // Telemetry for the proxy start (PROXY_STARTED) is logged here by the telemetry change. + + ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM) + defer stop() + ctx, cancel := context.WithCancel(ctx) + defer cancel() + + refresh := &refreshGuard{authenticate: cfg.Authenticate, profile: profileName, cancel: cancel} + err = proxy.Run(ctx, proxy.Options{ + In: cmd.InOrStdin(), + Out: cmd.OutOrStdout(), + Err: cmd.ErrOrStderr(), + Endpoint: mcp.ServiceURL(cfg.Host, f.service), + Config: cfg, + Authenticate: refresh.authenticateRequest, + Profile: profileName, + Agent: f.agent, + }) + if err != nil { + return serveFailure(cmd, 1, err) + } + if refreshErr := refresh.failure(); refreshErr != nil { + return serveFailure(cmd, serveExitCode, refreshErr) + } + return nil +} + +// serveFailure prints err to stderr and returns the error that sets the exit status. Execute does +// not print it again, so the message is written exactly once. +func serveFailure(cmd *cobra.Command, status int, err error) error { + fmt.Fprintln(cmd.ErrOrStderr(), err) + return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) +} + +// refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed +// mid-session fails that request with an error naming the profile, then stops the proxy, so the +// command exits 2 and the next spawn re-runs the binding checks. +type refreshGuard struct { + authenticate func(*http.Request) error + profile string + cancel context.CancelFunc + + mu sync.Mutex + err error +} + +// authenticateRequest is the bridge's Authenticate. It is safe for concurrent use. +func (g *refreshGuard) authenticateRequest(r *http.Request) error { + err := g.authenticate(r) + if err == nil { + return nil + } + g.mu.Lock() + if g.err == nil { + g.err = err + } + g.mu.Unlock() + g.cancel() + return fmt.Errorf("token refresh failed for profile %s: %w\nRun: databricks auth login --profile %s", g.profile, err, g.profile) +} + +// failure returns the first refresh error, or nil when every token was refreshed. +func (g *refreshGuard) failure() error { + g.mu.Lock() + defer g.mu.Unlock() + return g.err +} diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go new file mode 100644 index 00000000000..ffcdd4c0642 --- /dev/null +++ b/cmd/aitools/mcp_serve_test.go @@ -0,0 +1,69 @@ +package aitools + +import ( + "bytes" + "context" + "errors" + "net/http" + "testing" + + "github.com/databricks/cli/cmd/root" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestMcpServeIsHidden(t *testing.T) { + assert.True(t, NewMcpServeCmd().Hidden) +} + +func TestRefreshGuardPassesThroughWhileTokensRefresh(t *testing.T) { + cancelled := false + g := &refreshGuard{ + authenticate: func(*http.Request) error { return nil }, + profile: "logfood", + cancel: func() { cancelled = true }, + } + + require.NoError(t, g.authenticateRequest(&http.Request{Header: http.Header{}})) + assert.NoError(t, g.failure()) + assert.False(t, cancelled) +} + +func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { + ctx, cancel := context.WithCancel(t.Context()) + calls := 0 + cause := errors.New("refresh token expired") + g := &refreshGuard{ + authenticate: func(*http.Request) error { + calls++ + return cause + }, + profile: "logfood", + cancel: cancel, + } + + err := g.authenticateRequest(&http.Request{Header: http.Header{}}) + require.Error(t, err) + assert.ErrorIs(t, err, cause) + assert.Contains(t, err.Error(), `profile logfood`) + assert.Contains(t, err.Error(), "databricks auth login --profile logfood") + assert.Equal(t, context.Canceled, ctx.Err()) + + // A second failure keeps the first error for the exit status. + _ = g.authenticateRequest(&http.Request{Header: http.Header{}}) + assert.Equal(t, 2, calls) + assert.ErrorIs(t, g.failure(), cause) +} + +func TestServeFailureSetsExitStatusWithoutReprinting(t *testing.T) { + cmd := NewMcpServeCmd() + var stderr bytes.Buffer + cmd.SetErr(&stderr) + cause := errors.New("MCP server x is bound to Databricks profile") + + err := serveFailure(cmd, serveExitCode, cause) + + assert.Equal(t, "MCP server x is bound to Databricks profile\n", stderr.String()) + assert.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 2, root.ExitStatus(err)) +} diff --git a/cmd/aitools/mcp_test.go b/cmd/aitools/mcp_test.go index 6625a722351..e4fa4036c4d 100644 --- a/cmd/aitools/mcp_test.go +++ b/cmd/aitools/mcp_test.go @@ -31,7 +31,7 @@ func TestMcpCommandIsHidden(t *testing.T) { for _, c := range mcp.Commands() { names = append(names, c.Name()) } - assert.Equal(t, []string{"add", "list", "remove"}, names) + assert.Equal(t, []string{"add", "list", "remove", "serve"}, names) for _, c := range NewAitoolsCmd().Commands() { if c.Name() == "mcp" { diff --git a/cmd/root/root.go b/cmd/root/root.go index 59b9777ef69..7db40092541 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -76,7 +76,7 @@ func New(ctx context.Context) *cobra.Command { slog.String("version", build.GetInfo().Version), slog.String("args", strings.Join(os.Args, ", "))) - warnIfStaleVersion(ctx) + warnIfStaleVersion(ctx, cmd) // Configure our user agent with the command that's about to be executed. ctx = withCommandInUserAgent(ctx, cmd) @@ -189,10 +189,7 @@ Stack Trace: } } - exitCode := 0 - if err != nil { - exitCode = 1 - } + exitCode := ExitStatus(err) commandStr := commandString(cmd) ctx = cmd.Context() diff --git a/cmd/root/silent_err.go b/cmd/root/silent_err.go index b361cc6b404..38146a71b39 100644 --- a/cmd/root/silent_err.go +++ b/cmd/root/silent_err.go @@ -5,3 +5,27 @@ import "errors" // ErrAlreadyPrinted is not printed to the user. It's used to signal that the command should exit with an error, // but the error message was already printed. var ErrAlreadyPrinted = errors.New("AlreadyPrinted") + +// ExitStatusError sets the process exit status to Status. Use it with ErrAlreadyPrinted, for example +// errors.Join(ErrAlreadyPrinted, &ExitStatusError{Status: 2, Err: err}), when the command has printed its own +// diagnostics and needs an exit status other than 1. +type ExitStatusError struct { + Status int + Err error +} + +func (e *ExitStatusError) Error() string { return e.Err.Error() } + +func (e *ExitStatusError) Unwrap() error { return e.Err } + +// ExitStatus returns the process exit status for err: 0 for nil, the Status of the first ExitStatusError +// in its chain, and 1 otherwise. +func ExitStatus(err error) int { + if err == nil { + return 0 + } + if se, ok := errors.AsType[*ExitStatusError](err); ok { + return se.Status + } + return 1 +} diff --git a/cmd/root/stale_version.go b/cmd/root/stale_version.go index b33c0b98fbc..bfaa3ee7896 100644 --- a/cmd/root/stale_version.go +++ b/cmd/root/stale_version.go @@ -9,6 +9,7 @@ import ( "github.com/databricks/cli/libs/cmdio" "github.com/databricks/cli/libs/dbr" "github.com/databricks/cli/libs/versioncheck" + "github.com/spf13/cobra" ) const ( @@ -39,9 +40,15 @@ func skipStaleVersionWarning(ctx context.Context, info build.Info) bool { return dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) } -func warnIfStaleVersion(ctx context.Context) { +// isMCPServe reports whether cmd is `aitools mcp serve`, whose stdout is the MCP protocol and must +// carry nothing else. cmd/root cannot import cmd/aitools, so the command is matched by name. +func isMCPServe(cmd *cobra.Command) bool { + return cmd.Name() == "serve" && cmd.Parent() != nil && cmd.Parent().Name() == "mcp" +} + +func warnIfStaleVersion(ctx context.Context, cmd *cobra.Command) { info := build.GetInfo() - if skipStaleVersionWarning(ctx, info) { + if isMCPServe(cmd) || skipStaleVersionWarning(ctx, info) { return } _, command := versioncheck.DetectInstallMethod(ctx) diff --git a/cmd/root/stale_version_test.go b/cmd/root/stale_version_test.go index a7bcb8f4da6..cfb6e1b0197 100644 --- a/cmd/root/stale_version_test.go +++ b/cmd/root/stale_version_test.go @@ -6,6 +6,7 @@ import ( "github.com/databricks/cli/internal/build" "github.com/databricks/cli/libs/dbr" + "github.com/spf13/cobra" "github.com/stretchr/testify/assert" ) @@ -65,3 +66,17 @@ func TestSkipStaleVersionWarning(t *testing.T) { }) } } + +func TestIsMCPServe(t *testing.T) { + aitools := &cobra.Command{Use: "aitools"} + mcp := &cobra.Command{Use: "mcp"} + serve := &cobra.Command{Use: "serve"} + add := &cobra.Command{Use: "add"} + aitools.AddCommand(mcp) + mcp.AddCommand(serve, add) + + assert.True(t, isMCPServe(serve)) + assert.False(t, isMCPServe(add)) + assert.False(t, isMCPServe(mcp)) + assert.False(t, isMCPServe(&cobra.Command{Use: "serve"})) +} diff --git a/libs/aitools/mcp/proxy/run.go b/libs/aitools/mcp/proxy/run.go new file mode 100644 index 00000000000..5df48fcb21a --- /dev/null +++ b/libs/aitools/mcp/proxy/run.go @@ -0,0 +1,64 @@ +package proxy + +import ( + "context" + "fmt" + "io" + "maps" + "net/http" + + "github.com/databricks/cli/libs/auth" + "github.com/databricks/databricks-sdk-go/config" + "github.com/databricks/databricks-sdk-go/useragent" +) + +// User-Agent extras of a proxied session. The SDK default already carries cli/ +// and agent/; these identify the proxy and the calling agent. +const ( + proxyAgentKey = "aitools-mcp" + clientAgentKey = "aitools-mcp-client" +) + +// Options is one `serve` session. The binding checks (mcp.Bind) have already passed. +type Options struct { + In io.Reader + Out io.Writer + Err io.Writer + // Endpoint is the service URL, as mcp.ServiceURL builds it. + Endpoint string + // Config is the bound profile's config. Its host is named in the instructions, and its + // workspace ID is sent as the routing header. + Config *config.Config + // Authenticate sets the Authorization header on each upstream request. + Authenticate func(*http.Request) error + // Profile is the bound profile's name, named in the instructions. + Profile string + // Agent is the registry name of the calling agent, or "" when --agent was not given. + Agent string +} + +// Run bridges opts.In to the service endpoint until In closes or ctx is done. It returns an error +// only when reading In fails. +func Run(ctx context.Context, opts Options) error { + ctx = useragent.InContext(ctx, proxyAgentKey, "proxy") + if opts.Agent != "" { + ctx = useragent.InContext(ctx, clientAgentKey, opts.Agent) + } + if agent := useragent.AgentProvider(); agent != "" { + ctx = useragent.InContext(ctx, useragent.AgentKey, agent) + } + + headers := map[string]string{"User-Agent": useragent.FromContext(ctx)} + maps.Copy(headers, auth.WorkspaceIDHeaders(opts.Config)) + + b := &Bridge{ + In: opts.In, + Out: opts.Out, + Err: opts.Err, + Endpoint: opts.Endpoint, + Authenticate: opts.Authenticate, + Headers: headers, + Instructions: fmt.Sprintf("This server is bound to Databricks workspace %s (CLI profile \"%s\"). Its tools act on that workspace only.", opts.Config.Host, opts.Profile), + } + return b.Run(ctx) +} diff --git a/libs/aitools/mcp/proxy/run_test.go b/libs/aitools/mcp/proxy/run_test.go new file mode 100644 index 00000000000..c0d158cf20d --- /dev/null +++ b/libs/aitools/mcp/proxy/run_test.go @@ -0,0 +1,89 @@ +package proxy + +import ( + "io" + "net/http" + "strings" + "testing" + + "github.com/databricks/databricks-sdk-go/config" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const initializeResult = `{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},` + + `"serverInfo":{"name":"genie_chat"},"instructions":"Base."}` + +// answerInitialize replies to initialize with initializeResult and to anything else with an empty result. +func answerInitialize(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + if m.Method == "initialize" { + _, _ = io.WriteString(w, `{"jsonrpc":"2.0","id":1,"result":`+initializeResult+`}`) + return + } + answer(w, r) +} + +func runOptions(t *testing.T, endpoint string, cfg *config.Config, input string) (Options, *syncBuffer, *syncBuffer) { + t.Helper() + var out, errOut syncBuffer + return Options{ + In: strings.NewReader(input), + Out: &out, + Err: &errOut, + Endpoint: endpoint, + Config: cfg, + Authenticate: func(r *http.Request) error { + r.Header.Set("Authorization", testToken) + return nil + }, + Profile: "logfood", + Agent: "claude-code", + }, &out, &errOut +} + +func TestRunSendsProxyUserAgentAndRoutingHeader(t *testing.T) { + srv, fake := newFakeEndpoint(t, answerInitialize) + cfg := &config.Config{Host: "https://workspace.test", WorkspaceID: "1965859176160743"} + opts, _, _ := runOptions(t, srv.URL, cfg, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + require.NoError(t, Run(t.Context(), opts)) + + reqs := fake.requests() + require.Len(t, reqs, 1) + ua := reqs[0].Header.Get("User-Agent") + assert.Contains(t, ua, "aitools-mcp/proxy") + assert.Contains(t, ua, "aitools-mcp-client/claude-code") + assert.Equal(t, "1965859176160743", reqs[0].Header.Get("X-Databricks-Workspace-Id")) + assert.Equal(t, testToken, reqs[0].Header.Get("Authorization")) +} + +func TestRunOmitsRoutingHeaderWithoutWorkspaceID(t *testing.T) { + srv, fake := newFakeEndpoint(t, answerInitialize) + opts, _, _ := runOptions(t, srv.URL, &config.Config{Host: "https://workspace.test"}, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + opts.Agent = "" + + require.NoError(t, Run(t.Context(), opts)) + + reqs := fake.requests() + require.Len(t, reqs, 1) + assert.Empty(t, reqs[0].Header.Values("X-Databricks-Workspace-Id")) + assert.NotContains(t, reqs[0].Header.Get("User-Agent"), "aitools-mcp-client") +} + +func TestRunNamesWorkspaceAndProfileInInstructions(t *testing.T) { + srv, _ := newFakeEndpoint(t, answerInitialize) + opts, out, _ := runOptions(t, srv.URL, &config.Config{Host: "https://workspace.test"}, + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`+"\n") + + require.NoError(t, Run(t.Context(), opts)) + + lines := outLines(out.String()) + require.Len(t, lines, 1) + reply := parseReply(t, lines[0]) + assert.Equal(t, + "Base.\n\nThis server is bound to Databricks workspace https://workspace.test (CLI profile \"logfood\"). Its tools act on that workspace only.", + reply.Result["instructions"]) +} diff --git a/libs/testserver/handlers.go b/libs/testserver/handlers.go index 00d3e1fc9af..9e91a98949b 100644 --- a/libs/testserver/handlers.go +++ b/libs/testserver/handlers.go @@ -939,6 +939,10 @@ func AddDefaultHandlers(server *Server) { return MapDelete(req.Workspace, req.Workspace.McpServices, req.Vars["name"]) }) + server.Handle("POST", "/ai-gateway/mcp-services/{name}", func(req Request) any { + return req.Workspace.McpEndpoint(req, req.Vars["name"]) + }) + // Feature Engineering features: server.Handle("POST", "/api/2.0/feature-engineering/features", func(req Request) any { return req.Workspace.FeaturesCreate(req) diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go new file mode 100644 index 00000000000..edafb3ee8fd --- /dev/null +++ b/libs/testserver/mcp_endpoint.go @@ -0,0 +1,110 @@ +package testserver + +import ( + "encoding/json" + "net/http" +) + +// JSON-RPC codes the fake endpoint answers with. +const ( + rpcCodeParseError = -32700 + rpcCodeMethodNotFound = -32601 + rpcCodeInvalidParams = -32602 + // rpcCodeSignInRequired is the gateway's answer to a service that needs a credential the + // caller does not have. + rpcCodeSignInRequired = -32006 +) + +const ( + fakeMcpProtocolVersion = "2025-06-18" + fakeMcpInstructions = "Fake Databricks MCP service for tests." + fakeMcpEchoTool = "echo" +) + +type mcpRPC struct { + ID json.RawMessage `json:"id,omitempty"` + Method string `json:"method"` + Params struct { + Name string `json:"name"` + Arguments map[string]any `json:"arguments"` + } `json:"params"` +} + +// McpEndpoint fakes POST /ai-gateway/mcp-services/{name}, a streamable HTTP MCP server with one +// tool, echo. A service stored with an OAuth source connection is external: no credential is +// ever mapped to it here, so tools/list and tools/call answer -32006 as the gateway does before +// sign-in. Notifications get 202 with no body. +func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { + defer s.LockUnlock()() + + var msg mcpRPC + if err := json.Unmarshal(req.Body, &msg); err != nil { + return Response{StatusCode: http.StatusBadRequest, Body: rpcError(nil, rpcCodeParseError, "Parse error")} + } + if msg.ID == nil { + return Response{StatusCode: http.StatusAccepted} + } + + external := s.mcpServiceIsExternal(name) + switch msg.Method { + case "initialize": + return rpcResult(msg.ID, map[string]any{ + "protocolVersion": fakeMcpProtocolVersion, + "capabilities": map[string]any{"tools": map[string]any{"listChanged": true}}, + "serverInfo": map[string]any{"name": "fake_" + name}, + "instructions": fakeMcpInstructions, + }) + case "tools/list": + if external { + return signInRequired(msg.ID) + } + return rpcResult(msg.ID, map[string]any{"tools": []any{ + map[string]any{ + "name": fakeMcpEchoTool, + "description": "Returns the text argument", + "inputSchema": map[string]any{ + "type": "object", + "properties": map[string]any{"text": map[string]any{"type": "string"}}, + }, + }, + }}) + case "tools/call": + if external { + return signInRequired(msg.ID) + } + if msg.Params.Name != fakeMcpEchoTool { + return Response{Body: rpcError(msg.ID, rpcCodeInvalidParams, "Unknown tool: "+msg.Params.Name)} + } + text, _ := msg.Params.Arguments["text"].(string) + return rpcResult(msg.ID, map[string]any{ + "content": []any{map[string]any{"type": "text", "text": text}}, + "isError": false, + }) + default: + return Response{Body: rpcError(msg.ID, rpcCodeMethodNotFound, "Method not found: "+msg.Method)} + } +} + +// mcpServiceIsExternal reports whether the stored service name takes an OAuth source connection. +func (s *FakeWorkspace) mcpServiceIsExternal(name string) bool { + ms, ok := s.McpServices[name] + return ok && ms.Config != nil && ms.Config.SourceConnection != nil && + ms.Config.SourceConnection.Options["oauth_provider"] != "" +} + +func rpcResult(id json.RawMessage, result any) Response { + return Response{Body: map[string]any{"jsonrpc": "2.0", "id": id, "result": result}} +} + +func rpcError(id json.RawMessage, code int, message string) map[string]any { + return map[string]any{ + "jsonrpc": "2.0", + "id": id, + "error": map[string]any{"code": code, "message": message, "data": nil}, + } +} + +func signInRequired(id json.RawMessage) Response { + return Response{Body: rpcError(id, rpcCodeSignInRequired, + "The MCP service request was rejected (HTTP 401). Sign-in is required.")} +} diff --git a/libs/testserver/mcp_endpoint_test.go b/libs/testserver/mcp_endpoint_test.go new file mode 100644 index 00000000000..b5ede67be6a --- /dev/null +++ b/libs/testserver/mcp_endpoint_test.go @@ -0,0 +1,54 @@ +package testserver + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mcpEndpointTestCall posts one JSON-RPC message to the fake endpoint for name and decodes the reply. +func mcpEndpointTestCall(t *testing.T, workspace *FakeWorkspace, name, message string) map[string]any { + t.Helper() + response := workspace.McpEndpoint(Request{Body: []byte(message)}, name) + require.Equal(t, 0, response.StatusCode) + encoded, err := json.Marshal(response.Body) + require.NoError(t, err) + var reply map[string]any + require.NoError(t, json.Unmarshal(encoded, &reply)) + return reply +} + +func TestMcpEndpointAnswersInternalService(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + const name = "system.ai.genie_one_mcp" + + reply := mcpEndpointTestCall(t, workspace, name, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`) + assert.Nil(t, reply["error"]) + result := reply["result"].(map[string]any) + assert.Equal(t, "echo", result["tools"].([]any)[0].(map[string]any)["name"]) + + reply = mcpEndpointTestCall(t, workspace, name, + `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hi"}}}`) + content := reply["result"].(map[string]any)["content"].([]any) + assert.Equal(t, "hi", content[0].(map[string]any)["text"]) +} + +func TestMcpEndpointRejectsExternalServiceWithoutCredential(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + const name = "system.ai.github" + mcpServicesTestSeed(workspace, name, "GitHub", mcpServicesTestGitHubProvider) + + reply := mcpEndpointTestCall(t, workspace, name, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`) + errBody := reply["error"].(map[string]any) + assert.EqualValues(t, -32006, errBody["code"]) + assert.Nil(t, reply["result"]) +} + +func TestMcpEndpointNotificationGetsNoBody(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","method":"notifications/initialized"}`)}, "system.ai.genie_one_mcp") + assert.Equal(t, 202, response.StatusCode) + assert.Nil(t, response.Body) +} diff --git a/main.go b/main.go index 6c4dddd40b6..9e75a969ce8 100644 --- a/main.go +++ b/main.go @@ -27,6 +27,6 @@ func main() { ctx := context.Background() err := root.Execute(ctx, cmd.New(ctx)) if err != nil { - os.Exit(1) + os.Exit(root.ExitStatus(err)) } } From 528b44950a25a070785415db3549c34c7ddea9e8 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 12:35:06 +0000 Subject: [PATCH 02/32] Reject --log-file stdout on aitools mcp serve Stdout carries the MCP protocol for serve, so an explicit --log-file stdout would mix log lines into it. serve now fails at flag validation, as it does for --output, and the binding-errors scenario covers both flags. Co-authored-by: Isaac --- .../cmd/aitools/mcp/serve-binding-errors/out.stderr.txt | 2 +- acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt | 5 +++++ acceptance/cmd/aitools/mcp/serve-binding-errors/script | 2 ++ cmd/aitools/mcp_serve.go | 3 +++ 4 files changed, 11 insertions(+), 1 deletion(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt index 40d39ba099e..1185b89b097 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt @@ -1,3 +1,3 @@ -Error: --output does not apply to serve: its stdout carries the MCP protocol +Error: --log-file stdout is not supported by serve: its stdout carries the MCP protocol Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index 4138ce323f6..04a558fbbc2 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -31,3 +31,8 @@ Exit code: 1 Error: --output does not apply to serve: its stdout carries the MCP protocol Exit code: 1 + +>>> cat out.stderr.txt +Error: --log-file stdout is not supported by serve: its stdout carries the MCP protocol + +Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index a4f658f5435..a0e5b57f543 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -44,3 +44,5 @@ errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_m trace cat out.stderr.txt errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > out.stdout.txt 2> out.stderr.txt trace cat out.stderr.txt +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout < requests.ndjson > out.stdout.txt 2> out.stderr.txt +trace cat out.stderr.txt diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index bbef835d4cd..035897b96b1 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -51,6 +51,9 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { if out := cmd.Flag("output"); out != nil && out.Changed { return errors.New("--output does not apply to serve: its stdout carries the MCP protocol") } + if logFile := cmd.Flag("log-file"); logFile != nil && logFile.Value.String() == "stdout" { + return errors.New("--log-file stdout is not supported by serve: its stdout carries the MCP protocol") + } profileName := profileFlag(cmd) if profileName == "" { return errors.New("--profile is required") From 88704f61587f19afa6931e0304f8ddc6176d18ff Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 13:16:31 +0000 Subject: [PATCH 03/32] Make the serve-binding-errors byte count portable macOS wc pads its count with spaces, so the golden differed from Linux. Strip the padding the way acceptance/ssh/bulk-transfer does. Co-authored-by: Isaac --- acceptance/cmd/aitools/mcp/serve-binding-errors/script | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index a0e5b57f543..31b26984ea1 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -7,7 +7,7 @@ export DATABRICKS_CONFIG_FILE=.databrickscfg title "The bound profile is not in the config file" errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt trace cat out.stderr.txt -echo "stdout bytes: $(wc -c < out.stdout.txt)" +echo "stdout bytes: $(wc -c < out.stdout.txt | tr -d ' ')" # A state record for logfood that points at another host: the proxy never follows the profile. mkdir -p home/.databricks/aitools/mcp @@ -35,7 +35,7 @@ JSON title "The profile now points at another host than the one recorded" errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt trace cat out.stderr.txt -echo "stdout bytes: $(wc -c < out.stdout.txt)" +echo "stdout bytes: $(wc -c < out.stdout.txt | tr -d ' ')" title "Flags are required and validated before the binding checks" errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt From cebf51c4afda711a4443e878d76352cb47c92706 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 17:10:09 +0000 Subject: [PATCH 04/32] Adapt serve acceptance to the shared state file and binding messages Card 03 moved MCP records into the `mcp` section of ~/.databricks/aitools/skills/.state.json. serve-binding-errors wrote a v1 file at the old path, so the bind found no record and the proxy started. The fixture now writes the new file and pins its record to the test's DATABRICKS_CONFIG_FILE, as `add` does; otherwise card 03 reports a config-file mismatch before the host change. Golden changes, all from card 03: - The PROFILE_NOT_FOUND text names the config path as resolved (absolute) and has one space before "or remove", not three. - The PROFILE_HOST_CHANGED text and the no-record notice have no trailing period. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/output.txt | 4 +- .../aitools/mcp/serve-binding-errors/script | 38 ++++++++++--------- .../mcp/serve-passthrough/out.stderr.txt | 2 +- .../aitools/mcp/serve-passthrough/output.txt | 2 +- 4 files changed, 24 insertions(+), 22 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index 04a558fbbc2..b2266d390b1 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -2,7 +2,7 @@ === The bound profile is not in the config file >>> cat out.stderr.txt -MCP server system.ai.genie_one_mcp is bound to Databricks profile "gone", which no longer exists in .databrickscfg. Recreate it with: databricks auth login --profile gone or remove the server with: databricks aitools mcp remove --profile gone +MCP server system.ai.genie_one_mcp is bound to Databricks profile "gone", which no longer exists in [TEST_TMP_DIR]/.databrickscfg. Recreate it with: databricks auth login --profile gone or remove the server with: databricks aitools mcp remove --profile gone Exit code: 2 stdout bytes: 0 @@ -10,7 +10,7 @@ stdout bytes: 0 === The profile now points at another host than the one recorded >>> cat out.stderr.txt -MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --profile logfood and add it again. +MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --profile logfood and add it again Exit code: 2 stdout bytes: 0 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index 31b26984ea1..3d1c12e0367 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -10,25 +10,27 @@ trace cat out.stderr.txt echo "stdout bytes: $(wc -c < out.stdout.txt | tr -d ' ')" # A state record for logfood that points at another host: the proxy never follows the profile. -mkdir -p home/.databricks/aitools/mcp -cat > home/.databricks/aitools/mcp/state.json <<'JSON' +mkdir -p home/.databricks/aitools/skills +cat > home/.databricks/aitools/skills/.state.json <>> cat out.stderr.txt -No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL]. +No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] From 136ce711d514f57377b4936285e2ba6983f10499 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:13:44 +0000 Subject: [PATCH 05/32] Set a 10 s connect timeout on the serve upstream transport The proxy bridge now takes an http.RoundTripper. A nil one means http.DefaultTransport, whose dialer waits 30 s. serve passes a transport that keeps the profile's proxy and TLS settings, as cmd/apps/logs.go does, and dials with a 10 s connect timeout. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 33 +++++++++++++++++++++++++++++++++ cmd/aitools/mcp_serve_test.go | 26 ++++++++++++++++++++++++++ libs/aitools/mcp/proxy/run.go | 3 +++ 3 files changed, 62 insertions(+) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index 035897b96b1..d7a4ea52790 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -2,19 +2,23 @@ package aitools import ( "context" + "crypto/tls" "errors" "fmt" + "net" "net/http" "os" "os/signal" "sync" "syscall" + "time" "github.com/databricks/cli/cmd/root" "github.com/databricks/cli/libs/aitools/agents" "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/cli/libs/aitools/mcp/proxy" "github.com/databricks/cli/libs/cmdctx" + "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" ) @@ -22,6 +26,34 @@ import ( // can tell them from transport errors. const serveExitCode = 2 +// serveConnectTimeout bounds one upstream connect. http.DefaultTransport waits 30 s. +const serveConnectTimeout = 10 * time.Second + +// serveDialer dials the upstream service with serveConnectTimeout. +func serveDialer() *net.Dialer { + return &net.Dialer{Timeout: serveConnectTimeout} +} + +// serveTransport is the transport of the bridge's upstream requests. It starts from +// http.DefaultTransport, so proxy use and the other timeouts stay as they are, and replaces the +// dialer to set the connect timeout. The profile's TLS settings are honored as cmd/apps/logs.go +// honors them. +func serveTransport(cfg *config.Config) *http.Transport { + tr := http.DefaultTransport.(*http.Transport).Clone() + tr.DialContext = serveDialer().DialContext + if base, ok := cfg.HTTPTransport.(*http.Transport); ok && base != nil { + tr.Proxy = base.Proxy + if base.TLSClientConfig != nil { + tr.TLSClientConfig = base.TLSClientConfig.Clone() + } + return tr + } + if cfg.InsecureSkipVerify { + tr.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} + } + return tr +} + type mcpServeFlags struct { service string agent string @@ -98,6 +130,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Authenticate: refresh.authenticateRequest, Profile: profileName, Agent: f.agent, + Transport: serveTransport(cfg), }) if err != nil { return serveFailure(cmd, 1, err) diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index ffcdd4c0642..07187b2e65e 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -3,11 +3,14 @@ package aitools import ( "bytes" "context" + "crypto/tls" "errors" "net/http" "testing" + "time" "github.com/databricks/cli/cmd/root" + "github.com/databricks/databricks-sdk-go/config" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -67,3 +70,26 @@ func TestServeFailureSetsExitStatusWithoutReprinting(t *testing.T) { assert.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) } + +func TestServeTransportHasConnectTimeout(t *testing.T) { + assert.Equal(t, 10*time.Second, serveDialer().Timeout) + + tr := serveTransport(&config.Config{}) + assert.NotNil(t, tr.DialContext) + require.NotNil(t, tr.TLSClientConfig) + assert.False(t, tr.TLSClientConfig.InsecureSkipVerify) +} + +func TestServeTransportSkipsTLSVerifyWhenProfileSetsIt(t *testing.T) { + tr := serveTransport(&config.Config{InsecureSkipVerify: true}) + require.NotNil(t, tr.TLSClientConfig) + assert.True(t, tr.TLSClientConfig.InsecureSkipVerify) +} + +func TestServeTransportKeepsProfileHTTPTransportTLS(t *testing.T) { + base := &http.Transport{TLSClientConfig: &tls.Config{ServerName: "profile.test"}} + tr := serveTransport(&config.Config{HTTPTransport: base}) + require.NotNil(t, tr.TLSClientConfig) + assert.Equal(t, "profile.test", tr.TLSClientConfig.ServerName) + assert.NotSame(t, base.TLSClientConfig, tr.TLSClientConfig) +} diff --git a/libs/aitools/mcp/proxy/run.go b/libs/aitools/mcp/proxy/run.go index 5df48fcb21a..247f024a2c0 100644 --- a/libs/aitools/mcp/proxy/run.go +++ b/libs/aitools/mcp/proxy/run.go @@ -35,6 +35,8 @@ type Options struct { Profile string // Agent is the registry name of the calling agent, or "" when --agent was not given. Agent string + // Transport performs the upstream requests. Nil means http.DefaultTransport, as in Bridge. + Transport http.RoundTripper } // Run bridges opts.In to the service endpoint until In closes or ctx is done. It returns an error @@ -58,6 +60,7 @@ func Run(ctx context.Context, opts Options) error { Endpoint: opts.Endpoint, Authenticate: opts.Authenticate, Headers: headers, + Transport: opts.Transport, Instructions: fmt.Sprintf("This server is bound to Databricks workspace %s (CLI profile \"%s\"). Its tools act on that workspace only.", opts.Config.Host, opts.Profile), } return b.Run(ctx) From 2ebe983f88cfdb74a3eeab8372d2990dcc18387c Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:14:13 +0000 Subject: [PATCH 06/32] Update serve binding-error goldens for the named-server messages Card 03 and 04 changed the binding messages. A profile with no state record now says the server needs the profile and how to set it up. A host change names the server in the remove hint, not the profile. Co-authored-by: Isaac --- acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index b2266d390b1..e7e6f9b9559 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -2,7 +2,7 @@ === The bound profile is not in the config file >>> cat out.stderr.txt -MCP server system.ai.genie_one_mcp is bound to Databricks profile "gone", which no longer exists in [TEST_TMP_DIR]/.databrickscfg. Recreate it with: databricks auth login --profile gone or remove the server with: databricks aitools mcp remove --profile gone +MCP server system.ai.genie_one_mcp needs Databricks profile "gone", which does not exist in [TEST_TMP_DIR]/.databrickscfg. Set it up with: databricks auth login --profile gone Exit code: 2 stdout bytes: 0 @@ -10,7 +10,7 @@ stdout bytes: 0 === The profile now points at another host than the one recorded >>> cat out.stderr.txt -MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --profile logfood and add it again +MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again Exit code: 2 stdout bytes: 0 From 96f258e36659fec2c57901de10c00d79bb4ab4ce Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:37:56 +0000 Subject: [PATCH 07/32] cmd/root: take the exit status from errors that set one ExitStatus honors an error with an ExitStatus() int method, found with errors.AsType, so serve no longer wraps its own status error. The method is not named ExitCode because os/exec's ExitError has that method, and a child process's code would become the CLI's exit status. mcp.BindError renames ExitCode to ExitStatus to match. The refresh failure is the AUTH_FAILED BindError, so it exits 2 as the binding failures do. The failed-execution log lines and the telemetry exit code now come from the same status, so the log no longer records exit_code 1 for an exit 2. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 26 +++++++++---------- cmd/aitools/mcp_serve_test.go | 32 +++++++++++++++++++++-- cmd/root/root.go | 9 ++++--- cmd/root/root_test.go | 35 +++++++++++++++++++++++++ cmd/root/silent_err.go | 23 +++++++---------- cmd/root/silent_err_test.go | 44 ++++++++++++++++++++++++++++++++ libs/aitools/mcp/binding.go | 4 +-- libs/aitools/mcp/binding_test.go | 2 +- 8 files changed, 138 insertions(+), 37 deletions(-) create mode 100644 cmd/root/silent_err_test.go diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index d7a4ea52790..e7596a82bfb 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -22,10 +22,6 @@ import ( "github.com/spf13/cobra" ) -// serveExitCode is the exit status for binding and auth failures, so agents and `list --check` -// can tell them from transport errors. -const serveExitCode = 2 - // serveConnectTimeout bounds one upstream connect. http.DefaultTransport waits 30 s. const serveConnectTimeout = 10 * time.Second @@ -99,7 +95,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { state, err := mcp.LoadState(cmd.Context()) if err != nil { - return serveFailure(cmd, 1, err) + return serveFailure(cmd, err) } cfg, _, err := mcp.Bind(cmd.Context(), mcp.BindOptions{ Profile: profileName, @@ -108,7 +104,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Stderr: cmd.ErrOrStderr(), }) if err != nil { - return serveFailure(cmd, serveExitCode, err) + return serveFailure(cmd, err) } // The bound profile authenticates the exit-time telemetry upload. @@ -133,19 +129,20 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Transport: serveTransport(cfg), }) if err != nil { - return serveFailure(cmd, 1, err) + return serveFailure(cmd, err) } if refreshErr := refresh.failure(); refreshErr != nil { - return serveFailure(cmd, serveExitCode, refreshErr) + return serveFailure(cmd, refreshErr) } return nil } -// serveFailure prints err to stderr and returns the error that sets the exit status. Execute does -// not print it again, so the message is written exactly once. -func serveFailure(cmd *cobra.Command, status int, err error) error { +// serveFailure prints err to stderr and returns it with the exit status that err carries: a binding +// or auth failure exits 2 (mcp.BindError), any other error exits 1. Execute does not print it again, +// so the message is written exactly once. +func serveFailure(cmd *cobra.Command, err error) error { fmt.Fprintln(cmd.ErrOrStderr(), err) - return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) + return errors.Join(root.ErrAlreadyPrinted, err) } // refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed @@ -166,13 +163,14 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { if err == nil { return nil } + authErr := mcp.AuthError(g.profile, err) g.mu.Lock() if g.err == nil { - g.err = err + g.err = authErr } g.mu.Unlock() g.cancel() - return fmt.Errorf("token refresh failed for profile %s: %w\nRun: databricks auth login --profile %s", g.profile, err, g.profile) + return authErr } // failure returns the first refresh error, or nil when every token was refreshed. diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index 07187b2e65e..1935dc2bf93 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -10,6 +10,7 @@ import ( "time" "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/databricks-sdk-go/config" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -48,7 +49,6 @@ func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { err := g.authenticateRequest(&http.Request{Header: http.Header{}}) require.Error(t, err) assert.ErrorIs(t, err, cause) - assert.Contains(t, err.Error(), `profile logfood`) assert.Contains(t, err.Error(), "databricks auth login --profile logfood") assert.Equal(t, context.Canceled, ctx.Err()) @@ -58,16 +58,44 @@ func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { assert.ErrorIs(t, g.failure(), cause) } +// The refresh failure reaches the user as the AUTH_FAILED error, which names the profile and its login command +// and exits 2. +func TestRefreshGuardStoresAuthError(t *testing.T) { + cause := errors.New("refresh token expired") + g := &refreshGuard{ + authenticate: func(*http.Request) error { return cause }, + profile: "my profile", + cancel: func() {}, + } + + _ = g.authenticateRequest(&http.Request{Header: http.Header{}}) + + be, ok := errors.AsType[*mcp.BindError](g.failure()) + require.True(t, ok) + assert.Equal(t, mcp.BindAuthFailed, be.Category) + assert.ErrorIs(t, be, cause) + assert.Contains(t, be.Error(), "databricks auth login --profile 'my profile'") + assert.Equal(t, 2, root.ExitStatus(g.failure())) +} + func TestServeFailureSetsExitStatusWithoutReprinting(t *testing.T) { cmd := NewMcpServeCmd() var stderr bytes.Buffer cmd.SetErr(&stderr) cause := errors.New("MCP server x is bound to Databricks profile") - err := serveFailure(cmd, serveExitCode, cause) + err := serveFailure(cmd, cause) assert.Equal(t, "MCP server x is bound to Databricks profile\n", stderr.String()) assert.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 1, root.ExitStatus(err)) + + bindErr := mcp.AuthError("logfood", cause) + stderr.Reset() + err = serveFailure(cmd, bindErr) + + assert.Equal(t, bindErr.Error()+"\n", stderr.String()) + assert.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) } diff --git a/cmd/root/root.go b/cmd/root/root.go index 7db40092541..09e3e375b2d 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -8,6 +8,7 @@ import ( "os" "runtime" "runtime/debug" + "strconv" "strings" "time" @@ -170,6 +171,8 @@ Stack Trace: fmt.Fprintf(cmd.ErrOrStderr(), "Error: %s\n", err.Error()) } + exitCode := ExitStatus(err) + // Log exit status and error // We only log if logger initialization succeeded and is stored in command // context @@ -179,18 +182,16 @@ Stack Trace: slog.String("exit_code", "0")) } else if errors.Is(err, ErrAlreadyPrinted) { logger.Debug("failed execution", - slog.String("exit_code", "1"), + slog.String("exit_code", strconv.Itoa(exitCode)), ) } else { logger.Info("failed execution", - slog.String("exit_code", "1"), + slog.String("exit_code", strconv.Itoa(exitCode)), slog.String("error", err.Error()), ) } } - exitCode := ExitStatus(err) - commandStr := commandString(cmd) ctx = cmd.Context() diff --git a/cmd/root/root_test.go b/cmd/root/root_test.go index ce1584eacd4..78a5a32c559 100644 --- a/cmd/root/root_test.go +++ b/cmd/root/root_test.go @@ -3,7 +3,12 @@ package root import ( "bytes" "context" + "encoding/json" "errors" + "io" + "os" + "path/filepath" + "strings" "testing" "github.com/databricks/cli/libs/cmdctx" @@ -177,3 +182,33 @@ func TestExecuteErrAlreadyPrintedNotEnriched(t *testing.T) { require.Error(t, err) assert.Empty(t, stderr.String()) } + +func TestExecuteLogsExitStatus(t *testing.T) { + logFile := filepath.Join(t.TempDir(), "run.log") + cmd := New(t.Context()) + cmd.AddCommand(&cobra.Command{ + Use: "fail", + RunE: func(*cobra.Command, []string) error { + return &testStatusError{status: 2, err: errors.New("binding failed")} + }, + }) + cmd.SetArgs([]string{"fail", "--log-file", logFile, "--log-level", "info", "--log-format", "json"}) + cmd.SetErr(io.Discard) + + err := Execute(t.Context(), cmd) + require.Error(t, err) + assert.Equal(t, 2, ExitStatus(err)) + + content, readErr := os.ReadFile(logFile) + require.NoError(t, readErr) + var failed map[string]any + for line := range strings.SplitSeq(strings.TrimSpace(string(content)), "\n") { + var rec map[string]any + require.NoError(t, json.Unmarshal([]byte(line), &rec)) + if rec["msg"] == "failed execution" { + failed = rec + } + } + require.NotNil(t, failed, "no failed execution record in %s", logFile) + assert.Equal(t, "2", failed["exit_code"]) +} diff --git a/cmd/root/silent_err.go b/cmd/root/silent_err.go index 38146a71b39..18c6083d3d7 100644 --- a/cmd/root/silent_err.go +++ b/cmd/root/silent_err.go @@ -6,26 +6,21 @@ import "errors" // but the error message was already printed. var ErrAlreadyPrinted = errors.New("AlreadyPrinted") -// ExitStatusError sets the process exit status to Status. Use it with ErrAlreadyPrinted, for example -// errors.Join(ErrAlreadyPrinted, &ExitStatusError{Status: 2, Err: err}), when the command has printed its own -// diagnostics and needs an exit status other than 1. -type ExitStatusError struct { - Status int - Err error +// exitStatuser is an error that sets the process exit status, such as mcp.BindError. The method is not named +// ExitCode: os/exec's ExitError has that method, and a child's exit code must not become the CLI's. +type exitStatuser interface { + error + ExitStatus() int } -func (e *ExitStatusError) Error() string { return e.Err.Error() } - -func (e *ExitStatusError) Unwrap() error { return e.Err } - -// ExitStatus returns the process exit status for err: 0 for nil, the Status of the first ExitStatusError -// in its chain, and 1 otherwise. +// ExitStatus returns the process exit status for err: 0 for nil, the ExitStatus of the first error in its chain +// that has one, and 1 otherwise. func ExitStatus(err error) int { if err == nil { return 0 } - if se, ok := errors.AsType[*ExitStatusError](err); ok { - return se.Status + if es, ok := errors.AsType[exitStatuser](err); ok { + return es.ExitStatus() } return 1 } diff --git a/cmd/root/silent_err_test.go b/cmd/root/silent_err_test.go new file mode 100644 index 00000000000..7be3ee8e569 --- /dev/null +++ b/cmd/root/silent_err_test.go @@ -0,0 +1,44 @@ +package root + +import ( + "errors" + "fmt" + "testing" + + "github.com/stretchr/testify/assert" +) + +// testStatusError sets its own exit status, as mcp.BindError does. +type testStatusError struct { + status int + err error +} + +func (e *testStatusError) Error() string { return e.err.Error() } + +func (e *testStatusError) Unwrap() error { return e.err } + +func (e *testStatusError) ExitStatus() int { return e.status } + +func TestExitStatus(t *testing.T) { + plain := errors.New("plain failure") + status := &testStatusError{status: 2, err: errors.New("binding failed")} + + tests := []struct { + name string + err error + want int + }{ + {name: "nil", err: nil, want: 0}, + {name: "plain error", err: plain, want: 1}, + {name: "status error", err: status, want: 2}, + {name: "wrapped status error", err: fmt.Errorf("serve: %w", status), want: 2}, + {name: "joined with already printed", err: errors.Join(ErrAlreadyPrinted, status), want: 2}, + {name: "joined plain error", err: errors.Join(ErrAlreadyPrinted, plain), want: 1}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, tc.want, ExitStatus(tc.err)) + }) + } +} diff --git a/libs/aitools/mcp/binding.go b/libs/aitools/mcp/binding.go index 20f68088306..0739bed335a 100644 --- a/libs/aitools/mcp/binding.go +++ b/libs/aitools/mcp/binding.go @@ -62,8 +62,8 @@ func (e *BindError) Unwrap() error { return e.cause } -// ExitCode returns the process exit status for this failure. -func (e *BindError) ExitCode() int { +// ExitStatus returns the process exit status for this failure. +func (e *BindError) ExitStatus() int { return bindExitCode } diff --git a/libs/aitools/mcp/binding_test.go b/libs/aitools/mcp/binding_test.go index 2d58a95d138..8cb584e9503 100644 --- a/libs/aitools/mcp/binding_test.go +++ b/libs/aitools/mcp/binding_test.go @@ -391,7 +391,7 @@ func requireBindError(t *testing.T, err error, want mcp.BindCategory) { var bindErr *mcp.BindError require.ErrorAs(t, err, &bindErr) assert.Equal(t, want, bindErr.Category) - assert.Equal(t, 2, bindErr.ExitCode()) + assert.Equal(t, 2, bindErr.ExitStatus()) } // bindingTestDefaultConfig writes contents to ~/.databrickscfg in a fresh home directory, with From 4264f58168a96c8eeed9ee04bb58692d14e0c80a Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:39:24 +0000 Subject: [PATCH 08/32] cmd/root: refuse stdout logs for commands whose stdout is a protocol A command annotated with root.StdoutCarriesProtocol gets its log destination checked before the log file is opened. A log file that is stdout, by name or by identity (/dev/stdout), is refused, so the protocol on stdout is never shared with a log line. The stale-version warning is skipped for such commands, because an agent shows the server's stderr on every start. aitools mcp serve carries the annotation. Its own check for --log-file stdout and the match by command name are removed. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/out.stderr.txt | 2 +- .../mcp/serve-binding-errors/output.txt | 2 +- cmd/aitools/mcp_serve.go | 12 ++-- cmd/root/logger.go | 21 +++++++ cmd/root/root.go | 5 ++ cmd/root/stale_version.go | 8 +-- cmd/root/stale_version_test.go | 15 ----- cmd/root/stdout_protocol.go | 15 +++++ cmd/root/stdout_protocol_test.go | 62 +++++++++++++++++++ 9 files changed, 112 insertions(+), 30 deletions(-) create mode 100644 cmd/root/stdout_protocol.go create mode 100644 cmd/root/stdout_protocol_test.go diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt index 1185b89b097..fdac79c126c 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt @@ -1,3 +1,3 @@ -Error: --log-file stdout is not supported by serve: its stdout carries the MCP protocol +Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index e7e6f9b9559..6f6ee9c6b9f 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -33,6 +33,6 @@ Error: --output does not apply to serve: its stdout carries the MCP protocol Exit code: 1 >>> cat out.stderr.txt -Error: --log-file stdout is not supported by serve: its stdout carries the MCP protocol +Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file Exit code: 1 diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index e7596a82bfb..64f7ecaa33c 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -17,6 +17,7 @@ import ( "github.com/databricks/cli/libs/aitools/agents" "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/cli/libs/aitools/mcp/proxy" + "github.com/databricks/cli/libs/aitools/mcpconfig" "github.com/databricks/cli/libs/cmdctx" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" @@ -64,6 +65,8 @@ func NewMcpServeCmd() *cobra.Command { Short: "Serve one Databricks managed MCP server over stdio", Hidden: true, Args: cobra.NoArgs, + // Stdout carries the MCP protocol, so root keeps logs and the stale-version warning off it. + Annotations: map[string]string{root.StdoutCarriesProtocol: "true"}, RunE: func(cmd *cobra.Command, args []string) error { return runMcpServe(cmd, f) }, @@ -76,18 +79,15 @@ func NewMcpServeCmd() *cobra.Command { // runMcpServe runs the binding checks, then bridges stdio to the service until stdin closes or a // signal arrives. func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { - if out := cmd.Flag("output"); out != nil && out.Changed { + if cmd.Flag("output").Changed { return errors.New("--output does not apply to serve: its stdout carries the MCP protocol") } - if logFile := cmd.Flag("log-file"); logFile != nil && logFile.Value.String() == "stdout" { - return errors.New("--log-file stdout is not supported by serve: its stdout carries the MCP protocol") - } profileName := profileFlag(cmd) if profileName == "" { - return errors.New("--profile is required") + return fmt.Errorf("%s is required", mcpconfig.ProfileFlag) } if f.service == "" { - return errors.New("--service is required") + return fmt.Errorf("%s is required", mcpconfig.ServiceFlag) } if f.agent != "" && agents.ByName(f.agent) == nil { return fmt.Errorf("unknown agent %q", f.agent) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 7bf948c878b..3df3cf898b5 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -43,6 +43,27 @@ func (f *logFlags) makeLogHandler(ctx context.Context, opts slog.HandlerOptions) } } +// writesToStdout reports whether the log file is the process's stdout: the name "stdout", or a path that is the same +// file, such as /dev/stdout. +func (f *logFlags) writesToStdout() bool { + name := f.file.String() + switch name { + case "stdout": + return true + case "stderr": + return false + } + fi, err := os.Stat(name) + if err != nil { + return false + } + out, err := os.Stdout.Stat() + if err != nil { + return false + } + return os.SameFile(fi, out) +} + func (f *logFlags) initializeContext(ctx context.Context) (context.Context, error) { if f.debug { err := f.level.Set("debug") diff --git a/cmd/root/root.go b/cmd/root/root.go index 09e3e375b2d..a802a711920 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -66,6 +66,11 @@ func New(ctx context.Context) *cobra.Command { return err } + // A protocol on stdout must not share it with logs. Refuse before the log file is opened or anything is written. + if carriesProtocol(cmd) && logFlags.writesToStdout() { + return fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) + } + // Configure default logger. ctx, err = logFlags.initializeContext(ctx) if err != nil { diff --git a/cmd/root/stale_version.go b/cmd/root/stale_version.go index bfaa3ee7896..63519ab316a 100644 --- a/cmd/root/stale_version.go +++ b/cmd/root/stale_version.go @@ -40,15 +40,9 @@ func skipStaleVersionWarning(ctx context.Context, info build.Info) bool { return dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) } -// isMCPServe reports whether cmd is `aitools mcp serve`, whose stdout is the MCP protocol and must -// carry nothing else. cmd/root cannot import cmd/aitools, so the command is matched by name. -func isMCPServe(cmd *cobra.Command) bool { - return cmd.Name() == "serve" && cmd.Parent() != nil && cmd.Parent().Name() == "mcp" -} - func warnIfStaleVersion(ctx context.Context, cmd *cobra.Command) { info := build.GetInfo() - if isMCPServe(cmd) || skipStaleVersionWarning(ctx, info) { + if carriesProtocol(cmd) || skipStaleVersionWarning(ctx, info) { return } _, command := versioncheck.DetectInstallMethod(ctx) diff --git a/cmd/root/stale_version_test.go b/cmd/root/stale_version_test.go index cfb6e1b0197..a7bcb8f4da6 100644 --- a/cmd/root/stale_version_test.go +++ b/cmd/root/stale_version_test.go @@ -6,7 +6,6 @@ import ( "github.com/databricks/cli/internal/build" "github.com/databricks/cli/libs/dbr" - "github.com/spf13/cobra" "github.com/stretchr/testify/assert" ) @@ -66,17 +65,3 @@ func TestSkipStaleVersionWarning(t *testing.T) { }) } } - -func TestIsMCPServe(t *testing.T) { - aitools := &cobra.Command{Use: "aitools"} - mcp := &cobra.Command{Use: "mcp"} - serve := &cobra.Command{Use: "serve"} - add := &cobra.Command{Use: "add"} - aitools.AddCommand(mcp) - mcp.AddCommand(serve, add) - - assert.True(t, isMCPServe(serve)) - assert.False(t, isMCPServe(add)) - assert.False(t, isMCPServe(mcp)) - assert.False(t, isMCPServe(&cobra.Command{Use: "serve"})) -} diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go new file mode 100644 index 00000000000..ba4620b8147 --- /dev/null +++ b/cmd/root/stdout_protocol.go @@ -0,0 +1,15 @@ +package root + +import "github.com/spf13/cobra" + +// StdoutCarriesProtocol is the cobra annotation of a command whose stdout carries a protocol, such as MCP JSON-RPC +// messages, so nothing else may be written there. Root refuses a log file on stdout for such a command, and it skips +// the stale-version warning. That warning goes to stderr, but an agent shows the server's stderr each time it starts +// the server, so the warning would repeat in every session. +const StdoutCarriesProtocol = "stdout-carries-protocol" + +// carriesProtocol reports whether cmd is annotated with StdoutCarriesProtocol. +func carriesProtocol(cmd *cobra.Command) bool { + _, ok := cmd.Annotations[StdoutCarriesProtocol] + return ok +} diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go new file mode 100644 index 00000000000..70db26aa072 --- /dev/null +++ b/cmd/root/stdout_protocol_test.go @@ -0,0 +1,62 @@ +package root + +import ( + "io" + "os" + "path/filepath" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// protocolTestCommand is a command annotated as writing a protocol to stdout. It records whether it ran. +func protocolTestCommand(ran *bool) *cobra.Command { + return &cobra.Command{ + Use: "serve", + Annotations: map[string]string{StdoutCarriesProtocol: "true"}, + RunE: func(*cobra.Command, []string) error { + *ran = true + return nil + }, + } +} + +func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { + for _, logFile := range []string{"stdout", "STDOUT", "/dev/stdout"} { + t.Run(logFile, func(t *testing.T) { + if logFile == "/dev/stdout" { + if _, err := os.Stat(logFile); err != nil { + t.Skip("this OS has no /dev/stdout") + } + } + ran := false + cmd := New(t.Context()) + cmd.AddCommand(protocolTestCommand(&ran)) + cmd.SetArgs([]string{"serve", "--log-file", logFile, "--log-level", "debug"}) + cmd.SetErr(io.Discard) + + err := Execute(t.Context(), cmd) + require.ErrorContains(t, err, "writes protocol messages to stdout") + assert.False(t, ran) + }) + } +} + +func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { + logFile := filepath.Join(t.TempDir(), "serve.log") + ran := false + cmd := New(t.Context()) + cmd.AddCommand(protocolTestCommand(&ran)) + cmd.SetArgs([]string{"serve", "--log-file", logFile, "--log-level", "debug"}) + cmd.SetErr(io.Discard) + + require.NoError(t, Execute(t.Context(), cmd)) + assert.True(t, ran) +} + +func TestCarriesProtocol(t *testing.T) { + assert.True(t, carriesProtocol(protocolTestCommand(new(bool)))) + assert.False(t, carriesProtocol(&cobra.Command{Use: "serve"})) +} From 506b5eb4a9e9fa5272dee4bc01f01a8c5d8fc9dc Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:41:54 +0000 Subject: [PATCH 09/32] serve: keep the session through cancelled requests and the shutdown DELETE A refresh failure stops the proxy only when it is a real token failure. A request whose own context ended (the client cancelled it, or shutdown began) fails that request alone, and the session DELETE at shutdown is best effort, so its auth failure is only logged. An unknown --agent no longer stops serve: it only feeds the User-Agent, and an entry written by a later release may name an agent this binary does not know. Unknown names are left out of the User-Agent and logged at debug. The first SIGINT or SIGTERM cancels the context and releases the signal handler before the context reports done, so a second signal during shutdown ends the process. The proxy ignores the profile's HTTPTransport: BoundConfig never sets it. The transport keeps the connect timeout and InsecureSkipVerify. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/output.txt | 4 +- cmd/aitools/mcp_serve.go | 55 ++++--- cmd/aitools/mcp_serve_test.go | 136 ++++++++++++++++-- libs/aitools/mcp/proxy/run.go | 5 +- 4 files changed, 168 insertions(+), 32 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index 6f6ee9c6b9f..f5bb864c3bd 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -23,9 +23,9 @@ Error: --profile is required Exit code: 1 >>> cat out.stderr.txt -Error: unknown agent "nope" +MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again -Exit code: 1 +Exit code: 2 >>> cat out.stderr.txt Error: --output does not apply to serve: its stdout carries the MCP protocol diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index 64f7ecaa33c..2b1801b4ce7 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -19,6 +19,7 @@ import ( "github.com/databricks/cli/libs/aitools/mcp/proxy" "github.com/databricks/cli/libs/aitools/mcpconfig" "github.com/databricks/cli/libs/cmdctx" + "github.com/databricks/cli/libs/log" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" ) @@ -33,18 +34,10 @@ func serveDialer() *net.Dialer { // serveTransport is the transport of the bridge's upstream requests. It starts from // http.DefaultTransport, so proxy use and the other timeouts stay as they are, and replaces the -// dialer to set the connect timeout. The profile's TLS settings are honored as cmd/apps/logs.go -// honors them. +// dialer to set the connect timeout. The profile's InsecureSkipVerify is honored. func serveTransport(cfg *config.Config) *http.Transport { tr := http.DefaultTransport.(*http.Transport).Clone() tr.DialContext = serveDialer().DialContext - if base, ok := cfg.HTTPTransport.(*http.Transport); ok && base != nil { - tr.Proxy = base.Proxy - if base.TLSClientConfig != nil { - tr.TLSClientConfig = base.TLSClientConfig.Clone() - } - return tr - } if cfg.InsecureSkipVerify { tr.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} } @@ -89,9 +82,6 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { if f.service == "" { return fmt.Errorf("%s is required", mcpconfig.ServiceFlag) } - if f.agent != "" && agents.ByName(f.agent) == nil { - return fmt.Errorf("unknown agent %q", f.agent) - } state, err := mcp.LoadState(cmd.Context()) if err != nil { @@ -109,9 +99,8 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { // The bound profile authenticates the exit-time telemetry upload. cmd.SetContext(cmdctx.SetConfigUsed(cmd.Context(), cfg)) - // Telemetry for the proxy start (PROXY_STARTED) is logged here by the telemetry change. - ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM) + ctx, stop := serveSignalContext(cmd.Context()) defer stop() ctx, cancel := context.WithCancel(ctx) defer cancel() @@ -125,7 +114,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Config: cfg, Authenticate: refresh.authenticateRequest, Profile: profileName, - Agent: f.agent, + Agent: serveAgent(cmd.Context(), f.agent), Transport: serveTransport(cfg), }) if err != nil { @@ -137,6 +126,35 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { return nil } +// serveSignalContext returns a context that the first SIGINT or SIGTERM cancels. The handler is released +// before the context reports done, so a second signal during shutdown ends the process rather than being +// swallowed. stop releases the handler and cancels the context. +func serveSignalContext(parent context.Context) (context.Context, context.CancelFunc) { + ctx, cancel := context.WithCancel(parent) + sigs := make(chan os.Signal, 1) + signal.Notify(sigs, os.Interrupt, syscall.SIGTERM) + go func() { + select { + case <-sigs: + signal.Stop(sigs) + cancel() + case <-ctx.Done(): + signal.Stop(sigs) + } + }() + return ctx, cancel +} + +// serveAgent returns the registry name of the calling agent for the User-Agent. A name this binary does +// not know, such as an agent added by a later release, is left out and logged; the server still serves. +func serveAgent(ctx context.Context, name string) string { + if name == "" || agents.ByName(name) != nil { + return name + } + log.Debugf(ctx, "--agent %q is not a known agent; leaving it out of the User-Agent", name) + return "" +} + // serveFailure prints err to stderr and returns it with the exit status that err carries: a binding // or auth failure exits 2 (mcp.BindError), any other error exits 1. Execute does not print it again, // so the message is written exactly once. @@ -147,7 +165,9 @@ func serveFailure(cmd *cobra.Command, err error) error { // refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed // mid-session fails that request with an error naming the profile, then stops the proxy, so the -// command exits 2 and the next spawn re-runs the binding checks. +// command exits 2 and the next spawn re-runs the binding checks. Two failures do not stop it: a request +// whose own context ended, which the client cancelled or shutdown ended, and the session DELETE at +// shutdown, which is best effort. type refreshGuard struct { authenticate func(*http.Request) error profile string @@ -163,6 +183,9 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { if err == nil { return nil } + if r.Context().Err() != nil || r.Method == http.MethodDelete { + return err + } authErr := mcp.AuthError(g.profile, err) g.mu.Lock() if g.err == nil { diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index 1935dc2bf93..af9b5f6fea3 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -1,11 +1,15 @@ package aitools import ( + "bufio" "bytes" "context" - "crypto/tls" "errors" + "fmt" "net/http" + "os" + "os/exec" + "runtime" "testing" "time" @@ -99,13 +103,8 @@ func TestServeFailureSetsExitStatusWithoutReprinting(t *testing.T) { assert.Equal(t, 2, root.ExitStatus(err)) } -func TestServeTransportHasConnectTimeout(t *testing.T) { +func TestServeDialerHasConnectTimeout(t *testing.T) { assert.Equal(t, 10*time.Second, serveDialer().Timeout) - - tr := serveTransport(&config.Config{}) - assert.NotNil(t, tr.DialContext) - require.NotNil(t, tr.TLSClientConfig) - assert.False(t, tr.TLSClientConfig.InsecureSkipVerify) } func TestServeTransportSkipsTLSVerifyWhenProfileSetsIt(t *testing.T) { @@ -114,10 +113,123 @@ func TestServeTransportSkipsTLSVerifyWhenProfileSetsIt(t *testing.T) { assert.True(t, tr.TLSClientConfig.InsecureSkipVerify) } -func TestServeTransportKeepsProfileHTTPTransportTLS(t *testing.T) { - base := &http.Transport{TLSClientConfig: &tls.Config{ServerName: "profile.test"}} - tr := serveTransport(&config.Config{HTTPTransport: base}) +func TestServeTransportVerifiesTLSByDefault(t *testing.T) { + tr := serveTransport(&config.Config{}) require.NotNil(t, tr.TLSClientConfig) - assert.Equal(t, "profile.test", tr.TLSClientConfig.ServerName) - assert.NotSame(t, base.TLSClientConfig, tr.TLSClientConfig) + assert.False(t, tr.TLSClientConfig.InsecureSkipVerify) +} + +// A request whose own context ended (the client cancelled it, or shutdown began) fails that request only: the +// token was not shown to be unusable. +func TestRefreshGuardIgnoresRequestThatEnded(t *testing.T) { + cancelled := false + g := &refreshGuard{ + authenticate: func(r *http.Request) error { return r.Context().Err() }, + profile: "logfood", + cancel: func() { cancelled = true }, + } + ctx, cancel := context.WithCancel(t.Context()) + cancel() + + err := g.authenticateRequest((&http.Request{Header: http.Header{}}).WithContext(ctx)) + + assert.ErrorIs(t, err, context.Canceled) + assert.NoError(t, g.failure()) + assert.False(t, cancelled) +} + +// The session DELETE at shutdown is best effort. Its auth failure is logged by the bridge, and a normal shutdown +// exits 0. +func TestRefreshGuardIgnoresSessionDelete(t *testing.T) { + cancelled := false + g := &refreshGuard{ + authenticate: func(*http.Request) error { return errors.New("refresh token expired") }, + profile: "logfood", + cancel: func() { cancelled = true }, + } + req, err := http.NewRequestWithContext(t.Context(), http.MethodDelete, "https://workspace.test/mcp", nil) + require.NoError(t, err) + + require.Error(t, g.authenticateRequest(req)) + + assert.NoError(t, g.failure()) + assert.False(t, cancelled) +} + +func TestServeAgentKeepsOnlyKnownAgents(t *testing.T) { + assert.Equal(t, "claude-code", serveAgent(t.Context(), "claude-code")) + assert.Empty(t, serveAgent(t.Context(), "agent-from-a-later-release")) + assert.Empty(t, serveAgent(t.Context(), "")) +} + +// signalHelperEnv marks the child process that TestServeSecondSignalEndsProcess starts. +const signalHelperEnv = "AITOOLS_SERVE_SIGNAL_HELPER" + +// TestServeSignalHelper is the child of TestServeSecondSignalEndsProcess. It runs the signal context serve uses, +// prints when the first signal cancels it, then stays alive as shutdown would. +func TestServeSignalHelper(t *testing.T) { + if os.Getenv(signalHelperEnv) == "" { + t.Skip("runs only as the child of TestServeSecondSignalEndsProcess") + } + ctx, cancel := serveSignalContext(t.Context()) + defer cancel() + fmt.Println("ready") + <-ctx.Done() + fmt.Println("cancelled") + time.Sleep(time.Minute) +} + +// The first signal cancels the context and the second one ends the process. A second signal that the handler +// swallowed during shutdown would leave the child running until the timeout. +func TestServeSecondSignalEndsProcess(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("Process.Signal cannot send SIGINT on Windows") + } + pr, pw, err := os.Pipe() + require.NoError(t, err) + defer pr.Close() + + cmd := exec.CommandContext(t.Context(), os.Args[0], "-test.run=^TestServeSignalHelper$") + cmd.Env = append(os.Environ(), signalHelperEnv+"=1") + cmd.Stdout = pw + require.NoError(t, cmd.Start()) + require.NoError(t, pw.Close()) + + lines := make(chan string) + go func() { + defer close(lines) + sc := bufio.NewScanner(pr) + for sc.Scan() { + lines <- sc.Text() + } + }() + waitForLine := func(want string) { + t.Helper() + for { + select { + case line, ok := <-lines: + require.True(t, ok, "child exited before it printed %q", want) + if line == want { + return + } + case <-time.After(20 * time.Second): + t.Fatalf("timed out waiting for %q", want) + } + } + } + + waitForLine("ready") + require.NoError(t, cmd.Process.Signal(os.Interrupt)) + waitForLine("cancelled") + require.NoError(t, cmd.Process.Signal(os.Interrupt)) + + exited := make(chan error, 1) + go func() { exited <- cmd.Wait() }() + select { + case err := <-exited: + require.Error(t, err, "the child exited without a signal") + case <-time.After(20 * time.Second): + _ = cmd.Process.Kill() + t.Fatal("the second signal did not end the process") + } } diff --git a/libs/aitools/mcp/proxy/run.go b/libs/aitools/mcp/proxy/run.go index 247f024a2c0..5aa60d6322c 100644 --- a/libs/aitools/mcp/proxy/run.go +++ b/libs/aitools/mcp/proxy/run.go @@ -12,8 +12,9 @@ import ( "github.com/databricks/databricks-sdk-go/useragent" ) -// User-Agent extras of a proxied session. The SDK default already carries cli/ -// and agent/; these identify the proxy and the calling agent. +// User-Agent extras of a proxied session. useragent.FromContext carries cli/ but not +// agent/, so Run adds that from useragent.AgentProvider. The extras identify the proxy and +// the calling agent. const ( proxyAgentKey = "aitools-mcp" clientAgentKey = "aitools-mcp-client" From 8c5fb6ee97daca501229765bb6911073858ec66b Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:43:27 +0000 Subject: [PATCH 10/32] serve acceptance: LOG files, native config path, unknown agent accepted serve-binding-errors records the config file as the binary spells it (pwd -W on Git Bash), so the binding check matches on Windows. The unknown --agent case moves to serve-passthrough, which shows that such an agent is served and logged at debug. The out.* files are goldens; the stdout and stderr captures now go to LOG.* files. The last binding case checks a log file on stdout at debug level. The testserver's MCP endpoint names the JSON-RPC version once and documents its helpers. The proxy test's runOptions is documented. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/out.stderr.txt | 3 -- .../mcp/serve-binding-errors/out.stdout.txt | 0 .../mcp/serve-binding-errors/output.txt | 18 ++++----- .../aitools/mcp/serve-binding-errors/script | 39 ++++++++++++------- .../mcp/serve-passthrough/out.stderr.txt | 1 - .../aitools/mcp/serve-passthrough/output.txt | 10 ++++- .../cmd/aitools/mcp/serve-passthrough/script | 9 ++++- libs/aitools/mcp/proxy/run_test.go | 2 + libs/testserver/mcp_endpoint.go | 8 +++- 9 files changed, 56 insertions(+), 34 deletions(-) delete mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt delete mode 100644 acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt delete mode 100644 acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt deleted file mode 100644 index fdac79c126c..00000000000 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stderr.txt +++ /dev/null @@ -1,3 +0,0 @@ -Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file - -Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/out.stdout.txt deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index f5bb864c3bd..09a4efd1899 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -1,7 +1,7 @@ === The bound profile is not in the config file ->>> cat out.stderr.txt +>>> cat LOG.stderr MCP server system.ai.genie_one_mcp needs Databricks profile "gone", which does not exist in [TEST_TMP_DIR]/.databrickscfg. Set it up with: databricks auth login --profile gone Exit code: 2 @@ -9,7 +9,7 @@ stdout bytes: 0 === The profile now points at another host than the one recorded ->>> cat out.stderr.txt +>>> cat LOG.stderr MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again Exit code: 2 @@ -17,22 +17,20 @@ stdout bytes: 0 === Flags are required and validated before the binding checks ->>> cat out.stderr.txt +>>> cat LOG.stderr Error: --profile is required Exit code: 1 ->>> cat out.stderr.txt -MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again - -Exit code: 2 - ->>> cat out.stderr.txt +>>> cat LOG.stderr Error: --output does not apply to serve: its stdout carries the MCP protocol Exit code: 1 ->>> cat out.stderr.txt +=== A log file on stdout is refused before anything is logged + +>>> cat LOG.stderr Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file Exit code: 1 +stdout bytes: 0 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index 3d1c12e0367..2f03dfe914b 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -3,11 +3,18 @@ sethome home envsubst < .databrickscfg > out && mv out .databrickscfg export DATABRICKS_CONFIG_FILE=.databrickscfg +# The state records the config file as the binary spells it. Git Bash's $PWD is /c/..., which the Windows binary does +# not match, so there use pwd -W, as sethome does. +case "$OSTYPE" in + msys*|cygwin*) cfgdir="$(pwd -W)" ;; + *) cfgdir="$PWD" ;; +esac + # Binding failures exit 2 with one message on stderr. Nothing reaches stdout, and stdin is not read. title "The bound profile is not in the config file" -errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt -echo "stdout bytes: $(wc -c < out.stdout.txt | tr -d ' ')" +errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr +echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" # A state record for logfood that points at another host: the proxy never follows the profile. mkdir -p home/.databricks/aitools/skills @@ -24,7 +31,7 @@ cat > home/.databricks/aitools/skills/.state.json < home/.databricks/aitools/skills/.state.json < out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt -echo "stdout bytes: $(wc -c < out.stdout.txt | tr -d ' ')" +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr +echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" title "Flags are required and validated before the binding checks" -errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt -errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent nope < requests.ndjson > out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt -errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt -errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout < requests.ndjson > out.stdout.txt 2> out.stderr.txt -trace cat out.stderr.txt +errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr + +# Logs and the stale-version warning never share stdout with the protocol, even at debug level. +title "A log file on stdout is refused before anything is logged" +errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr +echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt deleted file mode 100644 index 33ebfc94f7a..00000000000 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/out.stderr.txt +++ /dev/null @@ -1 +0,0 @@ -No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt index 3e98b01593c..278f55e1388 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt @@ -6,5 +6,13 @@ === Diagnostics go to stderr only ->>> cat out.stderr.txt +>>> cat LOG.stderr No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] + +=== An agent this binary does not know is accepted +{"id":1,"instructions":"Fake Databricks MCP service for tests.\n\nThis server is bound to Databricks workspace [DATABRICKS_URL] (CLI profile \"logfood\"). Its tools act on that workspace only.","tools":[],"text":null,"error":null} +{"id":2,"instructions":null,"tools":["echo"],"text":null,"error":null} +{"id":3,"instructions":null,"tools":[],"text":"hello","error":null} + +>>> grep -c not a known agent LOG.debug +1 diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script index 5307e293fec..f099eaefd37 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/script +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -8,7 +8,12 @@ export DATABRICKS_HOST=https://elsewhere.test # Responses may arrive in any order, so they are sorted by id. jq -s also fails when any stdout line is not JSON. title "Stdout holds one JSON-RPC message per line; the notification gets no reply" -$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> out.stderr.txt | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' title "Diagnostics go to stderr only" -trace cat out.stderr.txt +trace cat LOG.stderr + +# An agent this binary does not know still serves; it is left out of the User-Agent and logged at debug. +title "An agent this binary does not know is accepted" +$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent --log-level debug < requests.ndjson 2> LOG.debug | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace grep -c "not a known agent" LOG.debug diff --git a/libs/aitools/mcp/proxy/run_test.go b/libs/aitools/mcp/proxy/run_test.go index c0d158cf20d..852298a6df0 100644 --- a/libs/aitools/mcp/proxy/run_test.go +++ b/libs/aitools/mcp/proxy/run_test.go @@ -26,6 +26,8 @@ func answerInitialize(w http.ResponseWriter, r *http.Request) { answer(w, r) } +// runOptions returns Options that send input from stdin to endpoint as profile logfood and agent claude-code, with +// testToken as the authorization. It also returns the buffers that receive stdout and stderr. func runOptions(t *testing.T, endpoint string, cfg *config.Config, input string) (Options, *syncBuffer, *syncBuffer) { t.Helper() var out, errOut syncBuffer diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go index edafb3ee8fd..fb7fa7b39fc 100644 --- a/libs/testserver/mcp_endpoint.go +++ b/libs/testserver/mcp_endpoint.go @@ -16,11 +16,13 @@ const ( ) const ( + jsonRPCVersion = "2.0" fakeMcpProtocolVersion = "2025-06-18" fakeMcpInstructions = "Fake Databricks MCP service for tests." fakeMcpEchoTool = "echo" ) +// mcpRPC is the part of a client message the fake reads: the id, the method, and the tool call's name and arguments. type mcpRPC struct { ID json.RawMessage `json:"id,omitempty"` Method string `json:"method"` @@ -92,13 +94,15 @@ func (s *FakeWorkspace) mcpServiceIsExternal(name string) bool { ms.Config.SourceConnection.Options["oauth_provider"] != "" } +// rpcResult is the response to the request with id, carrying result. func rpcResult(id json.RawMessage, result any) Response { - return Response{Body: map[string]any{"jsonrpc": "2.0", "id": id, "result": result}} + return Response{Body: map[string]any{"jsonrpc": jsonRPCVersion, "id": id, "result": result}} } +// rpcError is the error response to the request with id. func rpcError(id json.RawMessage, code int, message string) map[string]any { return map[string]any{ - "jsonrpc": "2.0", + "jsonrpc": jsonRPCVersion, "id": id, "error": map[string]any{"code": code, "message": message, "data": nil}, } From 75f18d1c42164605445dd5c0fe2a2f01b30fbc4a Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:10:15 +0000 Subject: [PATCH 11/32] cmd/root: check the stdout log file by identity; exit status by named error A log file is refused for a protocol command when it is the process's stdout. The check now compares the opened file with os.Stdout: os.Stat of /dev/stdout does not match stdout on macOS when stdout is a pipe. The check runs after the file is opened and before the first log line. The log file is closed when Execute returns, so a test or an embedding caller does not keep it open (Windows cannot remove an open file). ExitStatus honors only the named type ExitStatusError, which serve returns for binding and auth failures. mcp.BindError no longer carries an exit status, so `mcp add` exits 1 in both output modes, as its SPEC says. An error with an ExitStatus method of its own no longer sets the status. Co-authored-by: Isaac --- cmd/aitools/mcp_add_test.go | 22 +++++++++++++++++ cmd/aitools/mcp_serve.go | 19 ++++++++------- cmd/aitools/mcp_serve_test.go | 18 ++++---------- cmd/root/logger.go | 27 +++++++-------------- cmd/root/root.go | 23 ++++++++++++++---- cmd/root/root_test.go | 3 ++- cmd/root/silent_err.go | 26 ++++++++++++-------- cmd/root/silent_err_test.go | 18 ++++++-------- cmd/root/stdout_protocol.go | 26 +++++++++++++++++++- cmd/root/stdout_protocol_test.go | 41 ++++++++++++++++++++++++++++++++ libs/aitools/mcp/binding.go | 9 ------- libs/aitools/mcp/binding_test.go | 1 - 12 files changed, 156 insertions(+), 77 deletions(-) diff --git a/cmd/aitools/mcp_add_test.go b/cmd/aitools/mcp_add_test.go index 6169d390538..1cad4af0ea6 100644 --- a/cmd/aitools/mcp_add_test.go +++ b/cmd/aitools/mcp_add_test.go @@ -882,6 +882,28 @@ func TestMcpAddRejectedTokenIsAuthFailed(t *testing.T) { assert.NoFileExists(t, filepath.Join(home, ".claude.json")) } +// TestMcpAddBindingFailureExitsOne checks that a binding failure is an ordinary failure of add: it exits 1 in text and +// in JSON mode. Exit 2 is serve's status for binding failures, which an agent restarts on. +func TestMcpAddBindingFailureExitsOne(t *testing.T) { + home := withHome(t) + withDatabricksBinary(t) + server := noRequestServer(t) + writeHomeConfig(t, home, "[logfood]\nhost = "+server.URL+"\nauth_type = pat\ntoken = dapi-logfood\n") + require.NoError(t, mcp.SaveState(t.Context(), &mcp.State{Servers: []mcp.Entry{{ + Name: "github-logfood", Service: "system.ai.github", Profile: "logfood", Host: "https://adb-123.test", + }}})) + args := []string{"--profile", "logfood", "--names", "github", "--agents", "claude-code"} + + _, err := newAddTestCmd(t, args...) + require.Error(t, err) + assert.Equal(t, protos.AitoolsErrorCategory(mcp.BindProfileHostChanged), errorCategory(err)) + assert.Equal(t, 1, root.ExitStatus(err)) + + _, err = newAddTestCmd(t, append(args, "--output", "json")...) + require.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 1, root.ExitStatus(err)) +} + // TestMcpAddRefusesBinaryNotNamedDatabricks checks that the binary must be databricks: an argv[0] with another name, not on PATH, is refused, not replaced. func TestMcpAddRefusesBinaryNotNamedDatabricks(t *testing.T) { home := withHome(t) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index 2b1801b4ce7..cbd10e7b76f 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -85,7 +85,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { state, err := mcp.LoadState(cmd.Context()) if err != nil { - return serveFailure(cmd, err) + return serveFailure(cmd, err, 1) } cfg, _, err := mcp.Bind(cmd.Context(), mcp.BindOptions{ Profile: profileName, @@ -94,7 +94,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Stderr: cmd.ErrOrStderr(), }) if err != nil { - return serveFailure(cmd, err) + return serveFailure(cmd, err, serveBindStatus) } // The bound profile authenticates the exit-time telemetry upload. @@ -118,10 +118,10 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { Transport: serveTransport(cfg), }) if err != nil { - return serveFailure(cmd, err) + return serveFailure(cmd, err, 1) } if refreshErr := refresh.failure(); refreshErr != nil { - return serveFailure(cmd, refreshErr) + return serveFailure(cmd, refreshErr, serveBindStatus) } return nil } @@ -155,12 +155,15 @@ func serveAgent(ctx context.Context, name string) string { return "" } -// serveFailure prints err to stderr and returns it with the exit status that err carries: a binding -// or auth failure exits 2 (mcp.BindError), any other error exits 1. Execute does not print it again, +// serveBindStatus is the exit status of a binding or auth failure. Agents and `list --check` tell it from a +// transport error, so it is not 1. +const serveBindStatus = 2 + +// serveFailure prints err to stderr and returns it with the exit status. Execute does not print it again, // so the message is written exactly once. -func serveFailure(cmd *cobra.Command, err error) error { +func serveFailure(cmd *cobra.Command, err error, status int) error { fmt.Fprintln(cmd.ErrOrStderr(), err) - return errors.Join(root.ErrAlreadyPrinted, err) + return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) } // refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index af9b5f6fea3..e6a227b6203 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -79,28 +79,20 @@ func TestRefreshGuardStoresAuthError(t *testing.T) { assert.Equal(t, mcp.BindAuthFailed, be.Category) assert.ErrorIs(t, be, cause) assert.Contains(t, be.Error(), "databricks auth login --profile 'my profile'") - assert.Equal(t, 2, root.ExitStatus(g.failure())) } -func TestServeFailureSetsExitStatusWithoutReprinting(t *testing.T) { +func TestServeFailurePrintsOnceWithStatus(t *testing.T) { cmd := NewMcpServeCmd() var stderr bytes.Buffer cmd.SetErr(&stderr) - cause := errors.New("MCP server x is bound to Databricks profile") + cause := mcp.AuthError("logfood", errors.New("refresh token expired")) - err := serveFailure(cmd, cause) + err := serveFailure(cmd, cause, serveBindStatus) - assert.Equal(t, "MCP server x is bound to Databricks profile\n", stderr.String()) - assert.ErrorIs(t, err, root.ErrAlreadyPrinted) - assert.Equal(t, 1, root.ExitStatus(err)) - - bindErr := mcp.AuthError("logfood", cause) - stderr.Reset() - err = serveFailure(cmd, bindErr) - - assert.Equal(t, bindErr.Error()+"\n", stderr.String()) + assert.Equal(t, cause.Error()+"\n", stderr.String()) assert.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) + assert.ErrorIs(t, err, cause) } func TestServeDialerHasConnectTimeout(t *testing.T) { diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 3df3cf898b5..54c986b836e 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -3,6 +3,7 @@ package root import ( "context" "fmt" + "io" "log/slog" "os" @@ -43,25 +44,15 @@ func (f *logFlags) makeLogHandler(ctx context.Context, opts slog.HandlerOptions) } } -// writesToStdout reports whether the log file is the process's stdout: the name "stdout", or a path that is the same -// file, such as /dev/stdout. -func (f *logFlags) writesToStdout() bool { - name := f.file.String() - switch name { - case "stdout": - return true - case "stderr": - return false - } - fi, err := os.Stat(name) - if err != nil { - return false - } - out, err := os.Stdout.Stat() - if err != nil { - return false +// logFileKey is the context key of the log file that initializeContext opened. Execute closes it when the command +// returns. +type logFileKey struct{} + +// closeLogFile closes the log file in ctx, if the command opened one. +func closeLogFile(ctx context.Context) { + if f, ok := ctx.Value(logFileKey{}).(io.Closer); ok { + _ = f.Close() } - return os.SameFile(fi, out) } func (f *logFlags) initializeContext(ctx context.Context) (context.Context, error) { diff --git a/cmd/root/root.go b/cmd/root/root.go index a802a711920..f5f704eab4f 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -66,17 +66,27 @@ func New(ctx context.Context) *cobra.Command { return err } - // A protocol on stdout must not share it with logs. Refuse before the log file is opened or anything is written. - if carriesProtocol(cmd) && logFlags.writesToStdout() { - return fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) - } - // Configure default logger. ctx, err = logFlags.initializeContext(ctx) if err != nil { return err } + // A protocol on stdout must not share it with logs. This runs after the log file is opened, which writes + // nothing, and before the first log line. + if carriesProtocol(cmd) { + var toStdout bool + toStdout, err = writesToStdout(logFlags.file.Writer()) + if err != nil { + return err + } + if toStdout { + _ = logFlags.file.Close() + return fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) + } + } + ctx = context.WithValue(ctx, logFileKey{}, &logFlags.file) + logger := log.GetLogger(ctx) logger.Info("start", slog.String("version", build.GetInfo().Version), @@ -160,6 +170,9 @@ Stack Trace: startTime := time.Now() + // Close the log file the command opened, after its last log line. + defer func() { closeLogFile(cmd.Context()) }() + // Run the command cmd, err = cmd.ExecuteContextC(ctx) if err != nil && !errors.Is(err, ErrAlreadyPrinted) { diff --git a/cmd/root/root_test.go b/cmd/root/root_test.go index 78a5a32c559..f25f682586e 100644 --- a/cmd/root/root_test.go +++ b/cmd/root/root_test.go @@ -184,12 +184,13 @@ func TestExecuteErrAlreadyPrintedNotEnriched(t *testing.T) { } func TestExecuteLogsExitStatus(t *testing.T) { + keepDefaultLogger(t) logFile := filepath.Join(t.TempDir(), "run.log") cmd := New(t.Context()) cmd.AddCommand(&cobra.Command{ Use: "fail", RunE: func(*cobra.Command, []string) error { - return &testStatusError{status: 2, err: errors.New("binding failed")} + return &ExitStatusError{Status: 2, Err: errors.New("binding failed")} }, }) cmd.SetArgs([]string{"fail", "--log-file", logFile, "--log-level", "info", "--log-format", "json"}) diff --git a/cmd/root/silent_err.go b/cmd/root/silent_err.go index 18c6083d3d7..4bdf0566467 100644 --- a/cmd/root/silent_err.go +++ b/cmd/root/silent_err.go @@ -1,26 +1,32 @@ package root -import "errors" +import ( + "errors" +) // ErrAlreadyPrinted is not printed to the user. It's used to signal that the command should exit with an error, // but the error message was already printed. var ErrAlreadyPrinted = errors.New("AlreadyPrinted") -// exitStatuser is an error that sets the process exit status, such as mcp.BindError. The method is not named -// ExitCode: os/exec's ExitError has that method, and a child's exit code must not become the CLI's. -type exitStatuser interface { - error - ExitStatus() int +// ExitStatusError is an error that exits the process with Status instead of 1. Only a command whose failures need +// a distinct status returns it; `serve` exits 2 for a binding or auth failure. +type ExitStatusError struct { + Status int + Err error } -// ExitStatus returns the process exit status for err: 0 for nil, the ExitStatus of the first error in its chain -// that has one, and 1 otherwise. +func (e *ExitStatusError) Error() string { return e.Err.Error() } + +func (e *ExitStatusError) Unwrap() error { return e.Err } + +// ExitStatus returns the process exit status for err: 0 for nil, the Status of the first *ExitStatusError in its +// chain, and 1 otherwise. func ExitStatus(err error) int { if err == nil { return 0 } - if es, ok := errors.AsType[exitStatuser](err); ok { - return es.ExitStatus() + if es, ok := errors.AsType[*ExitStatusError](err); ok { + return es.Status } return 1 } diff --git a/cmd/root/silent_err_test.go b/cmd/root/silent_err_test.go index 7be3ee8e569..221b4b15b7d 100644 --- a/cmd/root/silent_err_test.go +++ b/cmd/root/silent_err_test.go @@ -8,21 +8,15 @@ import ( "github.com/stretchr/testify/assert" ) -// testStatusError sets its own exit status, as mcp.BindError does. -type testStatusError struct { - status int - err error -} - -func (e *testStatusError) Error() string { return e.err.Error() } - -func (e *testStatusError) Unwrap() error { return e.err } +// duckStatusError has an ExitStatus method but is not an ExitStatusError, so it does not set the status. +type duckStatusError struct{} -func (e *testStatusError) ExitStatus() int { return e.status } +func (duckStatusError) Error() string { return "duck" } +func (duckStatusError) ExitStatus() int { return 7 } func TestExitStatus(t *testing.T) { plain := errors.New("plain failure") - status := &testStatusError{status: 2, err: errors.New("binding failed")} + status := &ExitStatusError{Status: 2, Err: errors.New("binding failed")} tests := []struct { name string @@ -35,6 +29,8 @@ func TestExitStatus(t *testing.T) { {name: "wrapped status error", err: fmt.Errorf("serve: %w", status), want: 2}, {name: "joined with already printed", err: errors.Join(ErrAlreadyPrinted, status), want: 2}, {name: "joined plain error", err: errors.Join(ErrAlreadyPrinted, plain), want: 1}, + // Only the named type sets a status: an error with an ExitStatus method of its own does not. + {name: "method without the type", err: duckStatusError{}, want: 1}, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index ba4620b8147..09364183a6c 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -1,6 +1,11 @@ package root -import "github.com/spf13/cobra" +import ( + "io" + "os" + + "github.com/spf13/cobra" +) // StdoutCarriesProtocol is the cobra annotation of a command whose stdout carries a protocol, such as MCP JSON-RPC // messages, so nothing else may be written there. Root refuses a log file on stdout for such a command, and it skips @@ -13,3 +18,22 @@ func carriesProtocol(cmd *cobra.Command) bool { _, ok := cmd.Annotations[StdoutCarriesProtocol] return ok } + +// writesToStdout reports whether w is the process's stdout. It compares the open file, not a path: on macOS, +// os.Stat of /dev/stdout does not match stdout when stdout is a pipe, but the opened /dev/stdout does. stderr is +// never stdout here, even when both share a terminal. +func writesToStdout(w io.Writer) (bool, error) { + f, ok := w.(*os.File) + if !ok || f == os.Stderr { + return false, nil + } + out, err := os.Stdout.Stat() + if err != nil { + return false, err + } + fi, err := f.Stat() + if err != nil { + return false, err + } + return os.SameFile(fi, out), nil +} diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index 70db26aa072..5a7fbf364eb 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -2,6 +2,7 @@ package root import ( "io" + "log/slog" "os" "path/filepath" "testing" @@ -23,7 +24,15 @@ func protocolTestCommand(ran *bool) *cobra.Command { } } +// keepDefaultLogger restores the slog default that Execute replaces when it opens a log file. +func keepDefaultLogger(t *testing.T) { + t.Helper() + prev := slog.Default() + t.Cleanup(func() { slog.SetDefault(prev) }) +} + func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { + keepDefaultLogger(t) for _, logFile := range []string{"stdout", "STDOUT", "/dev/stdout"} { t.Run(logFile, func(t *testing.T) { if logFile == "/dev/stdout" { @@ -45,6 +54,7 @@ func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { } func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { + keepDefaultLogger(t) logFile := filepath.Join(t.TempDir(), "serve.log") ran := false cmd := New(t.Context()) @@ -56,6 +66,37 @@ func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { assert.True(t, ran) } +// writesToStdout compares the open log file with the process's stdout, so a path that is stdout under another name is +// refused. stderr is never refused: a user who asks for it gets it, even if it shares a terminal with stdout. +func TestWritesToStdout(t *testing.T) { + ok, err := writesToStdout(os.Stdout) + require.NoError(t, err) + assert.True(t, ok) + + ok, err = writesToStdout(os.Stderr) + require.NoError(t, err) + assert.False(t, ok) + + file, err := os.Create(filepath.Join(t.TempDir(), "run.log")) + require.NoError(t, err) + defer file.Close() + ok, err = writesToStdout(file) + require.NoError(t, err) + assert.False(t, ok) + + pr, pw, err := os.Pipe() + require.NoError(t, err) + defer pr.Close() + defer pw.Close() + ok, err = writesToStdout(pw) + require.NoError(t, err) + assert.False(t, ok) + + ok, err = writesToStdout(io.Discard) + require.NoError(t, err) + assert.False(t, ok) +} + func TestCarriesProtocol(t *testing.T) { assert.True(t, carriesProtocol(protocolTestCommand(new(bool)))) assert.False(t, carriesProtocol(&cobra.Command{Use: "serve"})) diff --git a/libs/aitools/mcp/binding.go b/libs/aitools/mcp/binding.go index 0739bed335a..a886f378f23 100644 --- a/libs/aitools/mcp/binding.go +++ b/libs/aitools/mcp/binding.go @@ -17,10 +17,6 @@ import ( "github.com/databricks/databricks-sdk-go/config" ) -// bindExitCode is the exit status for binding failures, so callers can tell them apart -// from other errors. -const bindExitCode = 2 - // Commands that binding messages tell the user to run. const ( authLoginCommand = "databricks auth login" @@ -62,11 +58,6 @@ func (e *BindError) Unwrap() error { return e.cause } -// ExitStatus returns the process exit status for this failure. -func (e *BindError) ExitStatus() int { - return bindExitCode -} - // Bind checks that the profile still names the host and workspace recorded for the service, // then authenticates with the profile's own credentials. It never reads stdin, prompts, or // loads a bundle. It returns the resolved config and the matching state entry, which is nil diff --git a/libs/aitools/mcp/binding_test.go b/libs/aitools/mcp/binding_test.go index 8cb584e9503..af26cead5fb 100644 --- a/libs/aitools/mcp/binding_test.go +++ b/libs/aitools/mcp/binding_test.go @@ -391,7 +391,6 @@ func requireBindError(t *testing.T, err error, want mcp.BindCategory) { var bindErr *mcp.BindError require.ErrorAs(t, err, &bindErr) assert.Equal(t, want, bindErr.Category) - assert.Equal(t, 2, bindErr.ExitStatus()) } // bindingTestDefaultConfig writes contents to ~/.databrickscfg in a fresh home directory, with From 02e0d3f5a2451dbb4fce0267c9a312ce251981ee Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:17:24 +0000 Subject: [PATCH 12/32] cmd/root: refuse a stdout log before the logger is installed The check ran after initializeContext had installed the stdout logger, so a refused command still wrote its telemetry debug line to stdout. It now runs inside initializeContext, after the log file opens and before the default logger is set, and it closes the refused file. The log file is also recorded on the context here, so Execute closes it after the last log line. Co-authored-by: Isaac --- cmd/root/logger.go | 20 +++++++++++++++++++- cmd/root/root.go | 17 +---------------- 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 54c986b836e..5dd0607bf1a 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -55,7 +55,10 @@ func closeLogFile(ctx context.Context) { } } -func (f *logFlags) initializeContext(ctx context.Context) (context.Context, error) { +// initializeContext opens the log file and installs the default logger. For a command whose stdout carries a protocol, +// it refuses a log file that is stdout. That check runs before the logger is installed, so nothing reaches stdout, +// not even the telemetry upload that follows a refused command. +func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (context.Context, error) { if f.debug { err := f.level.Set("debug") if err != nil { @@ -77,12 +80,27 @@ func (f *logFlags) initializeContext(ctx context.Context) (context.Context, erro return nil, err } + if carriesProtocol(cmd) { + toStdout, stdoutErr := writesToStdout(f.file.Writer()) + if stdoutErr != nil || toStdout { + _ = f.file.Close() + } + if stdoutErr != nil { + return nil, stdoutErr + } + if toStdout { + return nil, fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) + } + } + handler, err := f.makeLogHandler(ctx, opts) if err != nil { return nil, err } slog.SetDefault(slog.New(handler).With(slog.Int("pid", os.Getpid()))) + // The log file is closed when Execute returns, after the last log line. + ctx = context.WithValue(ctx, logFileKey{}, &f.file) return log.NewContext(ctx, slog.Default()), nil } diff --git a/cmd/root/root.go b/cmd/root/root.go index f5f704eab4f..7d6b15f11fc 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -67,26 +67,11 @@ func New(ctx context.Context) *cobra.Command { } // Configure default logger. - ctx, err = logFlags.initializeContext(ctx) + ctx, err = logFlags.initializeContext(ctx, cmd) if err != nil { return err } - // A protocol on stdout must not share it with logs. This runs after the log file is opened, which writes - // nothing, and before the first log line. - if carriesProtocol(cmd) { - var toStdout bool - toStdout, err = writesToStdout(logFlags.file.Writer()) - if err != nil { - return err - } - if toStdout { - _ = logFlags.file.Close() - return fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) - } - } - ctx = context.WithValue(ctx, logFileKey{}, &logFlags.file) - logger := log.GetLogger(ctx) logger.Info("start", slog.String("version", build.GetInfo().Version), From f8e7d53169a170a7c5ca266102de61e710de701c Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:17:25 +0000 Subject: [PATCH 13/32] serve: exit 2 for binding and token failures, print each once, check the service name - A token that cannot be refreshed mid-session is printed once: the bridge logs it on the request that needed it, and serve exits 2 without printing it again. The session DELETE after that failure is sent without a credential, so it does not log the refresh error a second time. - A state file that cannot be read is a binding failure (exit 2). - --service must be a full three-part name, with the message naming the flag. - An unknown --agent is reported on stderr once, not at debug level. - The bound profile is no longer set as the command's config: serve logs no telemetry yet, so the setting had no effect. Card 10a adds it with the telemetry it serves. - The signal context is released by the same stop that cancels the refresh guard, so a second signal during a refresh-failure shutdown ends the process. - serveTransport sets InsecureSkipVerify on the clone's TLS config instead of replacing it. - The fake MCP endpoint answers a client response (an id with no method) with 202 and no body. - The second-signal test asserts the child was ended by the signal, not by a panic or exit. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/output.txt | 5 + .../aitools/mcp/serve-binding-errors/script | 2 + .../aitools/mcp/serve-passthrough/output.txt | 5 +- .../cmd/aitools/mcp/serve-passthrough/script | 6 +- cmd/aitools/mcp_serve.go | 63 +++-- cmd/aitools/mcp_serve_test.go | 218 +++++++++++++++--- libs/testserver/mcp_endpoint.go | 4 +- libs/testserver/mcp_endpoint_test.go | 8 + 8 files changed, 250 insertions(+), 61 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index 09a4efd1899..21f305e8b7a 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -22,6 +22,11 @@ Error: --profile is required Exit code: 1 +>>> cat LOG.stderr +Error: --service needs a full service name such as system.ai.github + +Exit code: 1 + >>> cat LOG.stderr Error: --output does not apply to serve: its stdout carries the MCP protocol diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index 2f03dfe914b..edd332918d6 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -49,6 +49,8 @@ echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" title "Flags are required and validated before the binding checks" errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr +errcode $CLI aitools mcp serve --profile logfood --service github < requests.ndjson > LOG.stdout 2> LOG.stderr +trace cat LOG.stderr errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt index 278f55e1388..d0cee74464a 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt @@ -14,5 +14,6 @@ No install record for system.ai.genie_one_mcp on profile "logfood"; using its cu {"id":2,"instructions":null,"tools":["echo"],"text":null,"error":null} {"id":3,"instructions":null,"tools":[],"text":"hello","error":null} ->>> grep -c not a known agent LOG.debug -1 +>>> cat LOG.future +No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] +unknown agent "future-agent"; it is left out of the User-Agent diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script index f099eaefd37..498d3c66787 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/script +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -13,7 +13,7 @@ $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --age title "Diagnostics go to stderr only" trace cat LOG.stderr -# An agent this binary does not know still serves; it is left out of the User-Agent and logged at debug. +# An agent this binary does not know still serves; it is left out of the User-Agent, with one line on stderr. title "An agent this binary does not know is accepted" -$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent --log-level debug < requests.ndjson 2> LOG.debug | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' -trace grep -c "not a known agent" LOG.debug +$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent < requests.ndjson 2> LOG.future | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace cat LOG.future diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index cbd10e7b76f..b9b9eb9e0be 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -5,10 +5,12 @@ import ( "crypto/tls" "errors" "fmt" + "io" "net" "net/http" "os" "os/signal" + "strings" "sync" "syscall" "time" @@ -18,8 +20,6 @@ import ( "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/cli/libs/aitools/mcp/proxy" "github.com/databricks/cli/libs/aitools/mcpconfig" - "github.com/databricks/cli/libs/cmdctx" - "github.com/databricks/cli/libs/log" "github.com/databricks/databricks-sdk-go/config" "github.com/spf13/cobra" ) @@ -34,12 +34,16 @@ func serveDialer() *net.Dialer { // serveTransport is the transport of the bridge's upstream requests. It starts from // http.DefaultTransport, so proxy use and the other timeouts stay as they are, and replaces the -// dialer to set the connect timeout. The profile's InsecureSkipVerify is honored. +// dialer to set the connect timeout. The profile's InsecureSkipVerify is honored; the clone keeps +// HTTP/2 enabled. func serveTransport(cfg *config.Config) *http.Transport { tr := http.DefaultTransport.(*http.Transport).Clone() tr.DialContext = serveDialer().DialContext if cfg.InsecureSkipVerify { - tr.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} + if tr.TLSClientConfig == nil { + tr.TLSClientConfig = &tls.Config{} + } + tr.TLSClientConfig.InsecureSkipVerify = true } return tr } @@ -82,10 +86,13 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { if f.service == "" { return fmt.Errorf("%s is required", mcpconfig.ServiceFlag) } + if !isFullName(strings.Split(f.service, ".")) { + return fmt.Errorf("%s needs a full service name such as system.ai.github", mcpconfig.ServiceFlag) + } state, err := mcp.LoadState(cmd.Context()) if err != nil { - return serveFailure(cmd, err, 1) + return serveFailure(cmd, err, serveBindStatus) } cfg, _, err := mcp.Bind(cmd.Context(), mcp.BindOptions{ Profile: profileName, @@ -97,31 +104,32 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { return serveFailure(cmd, err, serveBindStatus) } - // The bound profile authenticates the exit-time telemetry upload. - cmd.SetContext(cmdctx.SetConfigUsed(cmd.Context(), cfg)) - - ctx, stop := serveSignalContext(cmd.Context()) - defer stop() - ctx, cancel := context.WithCancel(ctx) - defer cancel() - - refresh := &refreshGuard{authenticate: cfg.Authenticate, profile: profileName, cancel: cancel} - err = proxy.Run(ctx, proxy.Options{ + return serveProxy(cmd, proxy.Options{ In: cmd.InOrStdin(), Out: cmd.OutOrStdout(), Err: cmd.ErrOrStderr(), Endpoint: mcp.ServiceURL(cfg.Host, f.service), Config: cfg, - Authenticate: refresh.authenticateRequest, + Authenticate: cfg.Authenticate, Profile: profileName, - Agent: serveAgent(cmd.Context(), f.agent), + Agent: serveAgent(f.agent, cmd.ErrOrStderr()), Transport: serveTransport(cfg), }) - if err != nil { +} + +// serveProxy bridges opts to the service until stdin closes or a signal arrives. opts.Authenticate is wrapped by a +// refreshGuard. A token that cannot be refreshed mid-session stops the proxy with serveBindStatus. The bridge has +// already logged that error on the request that needed the token, so it is returned without being printed again. +func serveProxy(cmd *cobra.Command, opts proxy.Options) error { + ctx, stop := serveSignalContext(cmd.Context()) + defer stop() + refresh := &refreshGuard{authenticate: opts.Authenticate, profile: opts.Profile, cancel: stop} + opts.Authenticate = refresh.authenticateRequest + if err := proxy.Run(ctx, opts); err != nil { return serveFailure(cmd, err, 1) } if refreshErr := refresh.failure(); refreshErr != nil { - return serveFailure(cmd, refreshErr, serveBindStatus) + return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: serveBindStatus, Err: refreshErr}) } return nil } @@ -146,12 +154,13 @@ func serveSignalContext(parent context.Context) (context.Context, context.Cancel } // serveAgent returns the registry name of the calling agent for the User-Agent. A name this binary does -// not know, such as an agent added by a later release, is left out and logged; the server still serves. -func serveAgent(ctx context.Context, name string) string { +// not know, such as an agent added by a later release, is left out and reported on stderr, so the server +// still serves. The registry filter also keeps useragent.With from panicking on a value it does not accept. +func serveAgent(name string, stderr io.Writer) string { if name == "" || agents.ByName(name) != nil { return name } - log.Debugf(ctx, "--agent %q is not a known agent; leaving it out of the User-Agent", name) + fmt.Fprintf(stderr, "unknown agent %q; it is left out of the User-Agent\n", name) return "" } @@ -168,9 +177,10 @@ func serveFailure(cmd *cobra.Command, err error, status int) error { // refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed // mid-session fails that request with an error naming the profile, then stops the proxy, so the -// command exits 2 and the next spawn re-runs the binding checks. Two failures do not stop it: a request -// whose own context ended, which the client cancelled or shutdown ended, and the session DELETE at -// shutdown, which is best effort. +// command exits 2 and the next spawn re-runs the binding checks. A request whose own context ended, +// which the client cancelled or shutdown ended, does not stop it. Nor does the session DELETE at +// shutdown, which is best effort: after a refresh failure it is sent without a credential, as the +// session is already over. type refreshGuard struct { authenticate func(*http.Request) error profile string @@ -182,6 +192,9 @@ type refreshGuard struct { // authenticateRequest is the bridge's Authenticate. It is safe for concurrent use. func (g *refreshGuard) authenticateRequest(r *http.Request) error { + if g.failure() != nil && r.Method == http.MethodDelete { + return nil + } err := g.authenticate(r) if err == nil { return nil diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index e6a227b6203..7d7762eff05 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -6,15 +6,23 @@ import ( "context" "errors" "fmt" + "io" "net/http" + "net/http/httptest" "os" "os/exec" + "path/filepath" "runtime" + "strings" + "sync/atomic" "testing" "time" "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/aitools/installer" "github.com/databricks/cli/libs/aitools/mcp" + "github.com/databricks/cli/libs/aitools/mcp/proxy" + "github.com/databricks/cli/libs/cmdio" "github.com/databricks/databricks-sdk-go/config" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -99,16 +107,38 @@ func TestServeDialerHasConnectTimeout(t *testing.T) { assert.Equal(t, 10*time.Second, serveDialer().Timeout) } -func TestServeTransportSkipsTLSVerifyWhenProfileSetsIt(t *testing.T) { - tr := serveTransport(&config.Config{InsecureSkipVerify: true}) - require.NotNil(t, tr.TLSClientConfig) - assert.True(t, tr.TLSClientConfig.InsecureSkipVerify) +// The profile's insecure_skip_verify reaches the transport, and HTTP/2 is kept with it. +func TestServeTransportTLSVerification(t *testing.T) { + tests := []struct { + name string + cfg *config.Config + insecure bool + }{ + {name: "verifies by default", cfg: &config.Config{}, insecure: false}, + {name: "profile skips verification", cfg: &config.Config{InsecureSkipVerify: true}, insecure: true}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + tr := serveTransport(tc.cfg) + assert.Equal(t, tc.insecure, tr.TLSClientConfig != nil && tr.TLSClientConfig.InsecureSkipVerify) + assert.True(t, tr.ForceAttemptHTTP2) + }) + } } -func TestServeTransportVerifiesTLSByDefault(t *testing.T) { - tr := serveTransport(&config.Config{}) - require.NotNil(t, tr.TLSClientConfig) - assert.False(t, tr.TLSClientConfig.InsecureSkipVerify) +func TestServeTransportKeepsHTTP2WhenSkippingVerification(t *testing.T) { + server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + fmt.Fprint(w, "ok") + })) + server.EnableHTTP2 = true + server.StartTLS() + defer server.Close() + + client := &http.Client{Transport: serveTransport(&config.Config{InsecureSkipVerify: true})} + resp, err := client.Get(server.URL) + require.NoError(t, err) + defer resp.Body.Close() + assert.Equal(t, 2, resp.ProtoMajor) } // A request whose own context ended (the client cancelled it, or shutdown began) fails that request only: the @@ -148,10 +178,135 @@ func TestRefreshGuardIgnoresSessionDelete(t *testing.T) { assert.False(t, cancelled) } +// An unknown agent is left out of the User-Agent and reported once on stderr, so the server still serves. func TestServeAgentKeepsOnlyKnownAgents(t *testing.T) { - assert.Equal(t, "claude-code", serveAgent(t.Context(), "claude-code")) - assert.Empty(t, serveAgent(t.Context(), "agent-from-a-later-release")) - assert.Empty(t, serveAgent(t.Context(), "")) + var stderr bytes.Buffer + assert.Equal(t, "claude-code", serveAgent("claude-code", &stderr)) + assert.Empty(t, stderr.String()) + + assert.Empty(t, serveAgent("agent-from-a-later-release", &stderr)) + assert.Equal(t, "unknown agent \"agent-from-a-later-release\"; it is left out of the User-Agent\n", stderr.String()) + + stderr.Reset() + assert.Empty(t, serveAgent("", &stderr)) + assert.Empty(t, stderr.String()) +} + +// A service that is not a full three-part name is refused before any binding check, with the flag named. +func TestMcpServeRejectsServiceWithoutThreeParts(t *testing.T) { + withHome(t) + for _, service := range []string{"github", "system.ai", "system..github", "a.b.c.d"} { + t.Run(service, func(t *testing.T) { + parent := newMCPTestRoot() + parent.SetArgs([]string{"mcp", "serve", "--profile", "logfood", "--service", service}) + err := parent.ExecuteContext(cmdio.MockDiscard(t.Context())) + require.ErrorContains(t, err, "--service needs a full service name such as system.ai.github") + assert.Equal(t, 1, root.ExitStatus(err)) + }) + } +} + +// A state file that cannot be read stops the binding checks, so it exits 2 like the other binding failures. +func TestMcpServeStateReadFailureExitsTwo(t *testing.T) { + withHome(t) + dir, err := installer.GlobalSkillsDir(t.Context()) + require.NoError(t, err) + require.NoError(t, os.MkdirAll(filepath.Join(dir, ".state.json"), 0o700)) + + parent := newMCPTestRoot() + var stderr bytes.Buffer + parent.SetErr(&stderr) + parent.SetArgs([]string{"mcp", "serve", "--profile", "logfood", "--service", "system.ai.github"}) + err = parent.ExecuteContext(cmdio.MockDiscard(t.Context())) + require.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 2, root.ExitStatus(err)) + assert.Contains(t, stderr.String(), ".state.json") +} + +// After a refresh failure the session DELETE is sent without a credential: the session is over, and a failed DELETE +// would log the refresh error a second time. Authenticate is not asked. +func TestRefreshGuardSendsDeleteWithoutCredentialAfterFailure(t *testing.T) { + asked := 0 + g := &refreshGuard{ + authenticate: func(*http.Request) error { + asked++ + return errors.New("refresh token expired") + }, + profile: "logfood", + cancel: func() {}, + } + require.Error(t, g.authenticateRequest(&http.Request{Header: http.Header{}})) + asked = 0 + + req, err := http.NewRequestWithContext(t.Context(), http.MethodDelete, "https://workspace.test/mcp", nil) + require.NoError(t, err) + assert.NoError(t, g.authenticateRequest(req)) + assert.Equal(t, 0, asked) +} + +// A token that expires mid-session fails the request that needs it. The bridge logs that failure once, with the +// profile and the login command; the proxy then exits 2 without printing it again, and the session DELETE at +// shutdown is still sent. +func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { + var deleted atomic.Bool + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + deleted.Store(true) + w.WriteHeader(http.StatusOK) + return + } + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Mcp-Session-Id", "session-1") + fmt.Fprint(w, `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"fake","version":"1"}}}`) + })) + defer server.Close() + + // The token expires with the tools/list request. From then on the session DELETE fails too, as an expired + // token would. + const refreshErr = "refresh token expired" + var expired atomic.Bool + authenticate := func(r *http.Request) error { + if r.Method != http.MethodPost { + if expired.Load() { + return errors.New(refreshErr) + } + return nil + } + body, err := r.GetBody() + if err != nil { + return err + } + data, err := io.ReadAll(body) + body.Close() + if err != nil { + return err + } + if strings.Contains(string(data), `"tools/list"`) { + expired.Store(true) + return errors.New(refreshErr) + } + return nil + } + + stdin := `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}` + "\n" + + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}` + "\n" + var stderr bytes.Buffer + cmd := NewMcpServeCmd() + cmd.SetContext(t.Context()) + err := serveProxy(cmd, proxy.Options{ + In: strings.NewReader(stdin), + Out: io.Discard, + Err: &stderr, + Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), + Config: &config.Config{Host: server.URL}, + Authenticate: authenticate, + Profile: "logfood", + }) + + require.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 2, root.ExitStatus(err)) + assert.Equal(t, "databricks aitools mcp serve: upstream: refresh token expired\nRun: databricks auth login --profile logfood\n", stderr.String()) + assert.True(t, deleted.Load(), "the session DELETE is still sent") } // signalHelperEnv marks the child process that TestServeSecondSignalEndsProcess starts. @@ -195,33 +350,38 @@ func TestServeSecondSignalEndsProcess(t *testing.T) { lines <- sc.Text() } }() - waitForLine := func(want string) { - t.Helper() - for { - select { - case line, ok := <-lines: - require.True(t, ok, "child exited before it printed %q", want) - if line == want { - return - } - case <-time.After(20 * time.Second): - t.Fatalf("timed out waiting for %q", want) - } - } - } - - waitForLine("ready") + waitForChildLine(t, lines, "ready") require.NoError(t, cmd.Process.Signal(os.Interrupt)) - waitForLine("cancelled") + waitForChildLine(t, lines, "cancelled") require.NoError(t, cmd.Process.Signal(os.Interrupt)) exited := make(chan error, 1) go func() { exited <- cmd.Wait() }() select { case err := <-exited: - require.Error(t, err, "the child exited without a signal") + // A signal ends the child with ExitCode -1. A panic or a normal exit would not, and must fail the test. + var exitErr *exec.ExitError + require.ErrorAs(t, err, &exitErr, "the child exited without a signal") + assert.Equal(t, -1, exitErr.ExitCode(), "the child should be ended by the second signal") case <-time.After(20 * time.Second): _ = cmd.Process.Kill() t.Fatal("the second signal did not end the process") } } + +// waitForChildLine reads the child's output lines until one equals want. It fails the test when the child closes its +// output first or the wait takes too long. +func waitForChildLine(t *testing.T, lines <-chan string, want string) { + t.Helper() + for { + select { + case line, ok := <-lines: + require.True(t, ok, "child exited before it printed %q", want) + if line == want { + return + } + case <-time.After(20 * time.Second): + t.Fatalf("timed out waiting for %q", want) + } + } +} diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go index fb7fa7b39fc..911dbd97f24 100644 --- a/libs/testserver/mcp_endpoint.go +++ b/libs/testserver/mcp_endpoint.go @@ -35,7 +35,7 @@ type mcpRPC struct { // McpEndpoint fakes POST /ai-gateway/mcp-services/{name}, a streamable HTTP MCP server with one // tool, echo. A service stored with an OAuth source connection is external: no credential is // ever mapped to it here, so tools/list and tools/call answer -32006 as the gateway does before -// sign-in. Notifications get 202 with no body. +// sign-in. Notifications and client responses, which have no method or no id, get 202 with no body. func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { defer s.LockUnlock()() @@ -43,7 +43,7 @@ func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { if err := json.Unmarshal(req.Body, &msg); err != nil { return Response{StatusCode: http.StatusBadRequest, Body: rpcError(nil, rpcCodeParseError, "Parse error")} } - if msg.ID == nil { + if msg.ID == nil || msg.Method == "" { return Response{StatusCode: http.StatusAccepted} } diff --git a/libs/testserver/mcp_endpoint_test.go b/libs/testserver/mcp_endpoint_test.go index b5ede67be6a..b444ed7951b 100644 --- a/libs/testserver/mcp_endpoint_test.go +++ b/libs/testserver/mcp_endpoint_test.go @@ -52,3 +52,11 @@ func TestMcpEndpointNotificationGetsNoBody(t *testing.T) { assert.Equal(t, 202, response.StatusCode) assert.Nil(t, response.Body) } + +// A client's answer to a request from the server has an id and no method. It is not a request, so it gets 202 with no body. +func TestMcpEndpointClientResponseGetsNoBody(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","id":7,"result":{}}`)}, "system.ai.genie_one_mcp") + assert.Equal(t, 202, response.StatusCode) + assert.Nil(t, response.Body) +} From 14e1feae2f589ece8e8288ca1166e686bc5e8108 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:40:22 +0000 Subject: [PATCH 14/32] cmd/root: check stdout against the streams it is given writesToStdout read the process's os.Stdout and os.Stderr. Under `go test -json` the testing package sets os.Stderr to os.Stdout, so the stdout cases were taken for stderr and the check passed the log file through. Take the two streams as parameters, and give the tests pipes and a separate stderr of their own. Production behavior is unchanged. Co-authored-by: Isaac --- cmd/root/logger.go | 2 +- cmd/root/stdout_protocol.go | 13 +++--- cmd/root/stdout_protocol_test.go | 73 ++++++++++++++++++++++---------- 3 files changed, 58 insertions(+), 30 deletions(-) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 5dd0607bf1a..77a88fea165 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -81,7 +81,7 @@ func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (c } if carriesProtocol(cmd) { - toStdout, stdoutErr := writesToStdout(f.file.Writer()) + toStdout, stdoutErr := writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) if stdoutErr != nil || toStdout { _ = f.file.Close() } diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index 09364183a6c..986c0981618 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -19,15 +19,16 @@ func carriesProtocol(cmd *cobra.Command) bool { return ok } -// writesToStdout reports whether w is the process's stdout. It compares the open file, not a path: on macOS, -// os.Stat of /dev/stdout does not match stdout when stdout is a pipe, but the opened /dev/stdout does. stderr is -// never stdout here, even when both share a terminal. -func writesToStdout(w io.Writer) (bool, error) { +// writesToStdout reports whether w is stdout, given the process's stdout and stderr. It compares the open file, not a +// path: on macOS, os.Stat of /dev/stdout does not match stdout when stdout is a pipe, but the opened /dev/stdout does. +// stderr is never stdout here, even when both share a terminal. The streams are parameters because under +// `go test -json` the testing package sets os.Stderr to os.Stdout. +func writesToStdout(w io.Writer, stdout, stderr *os.File) (bool, error) { f, ok := w.(*os.File) - if !ok || f == os.Stderr { + if !ok || f == stderr { return false, nil } - out, err := os.Stdout.Stat() + out, err := stdout.Stat() if err != nil { return false, err } diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index 5a7fbf364eb..f790b6e5c58 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -31,8 +31,23 @@ func keepDefaultLogger(t *testing.T) { t.Cleanup(func() { slog.SetDefault(prev) }) } +// useSeparateStderr points os.Stderr at a file of its own, as an agent gives the server separate stdout and stderr. +// Under `go test -json` os.Stderr is os.Stdout, which would make the stdout cases below look like stderr. +func useSeparateStderr(t *testing.T) { + t.Helper() + f, err := os.Create(filepath.Join(t.TempDir(), "stderr.txt")) + require.NoError(t, err) + prev := os.Stderr + os.Stderr = f + t.Cleanup(func() { + os.Stderr = prev + f.Close() + }) +} + func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { keepDefaultLogger(t) + useSeparateStderr(t) for _, logFile := range []string{"stdout", "STDOUT", "/dev/stdout"} { t.Run(logFile, func(t *testing.T) { if logFile == "/dev/stdout" { @@ -55,6 +70,7 @@ func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { keepDefaultLogger(t) + useSeparateStderr(t) logFile := filepath.Join(t.TempDir(), "serve.log") ran := false cmd := New(t.Context()) @@ -66,35 +82,46 @@ func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { assert.True(t, ran) } -// writesToStdout compares the open log file with the process's stdout, so a path that is stdout under another name is -// refused. stderr is never refused: a user who asks for it gets it, even if it shares a terminal with stdout. +// writesToStdout compares the log file with the stdout and stderr it is given, so a path that is stdout under +// another name is refused. stderr is never refused. The streams are pipes of the test's own, not the process's. func TestWritesToStdout(t *testing.T) { - ok, err := writesToStdout(os.Stdout) - require.NoError(t, err) - assert.True(t, ok) - - ok, err = writesToStdout(os.Stderr) - require.NoError(t, err) - assert.False(t, ok) - + stdout := newPipe(t) + stderr := newPipe(t) + other := newPipe(t) file, err := os.Create(filepath.Join(t.TempDir(), "run.log")) require.NoError(t, err) - defer file.Close() - ok, err = writesToStdout(file) - require.NoError(t, err) - assert.False(t, ok) + t.Cleanup(func() { file.Close() }) - pr, pw, err := os.Pipe() - require.NoError(t, err) - defer pr.Close() - defer pw.Close() - ok, err = writesToStdout(pw) - require.NoError(t, err) - assert.False(t, ok) + tests := []struct { + name string + w io.Writer + want bool + }{ + {name: "stdout", w: stdout, want: true}, + {name: "stderr", w: stderr, want: false}, + {name: "another pipe", w: other, want: false}, + {name: "regular file", w: file, want: false}, + {name: "not a file", w: io.Discard, want: false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + ok, err := writesToStdout(tc.w, stdout, stderr) + require.NoError(t, err) + assert.Equal(t, tc.want, ok) + }) + } +} - ok, err = writesToStdout(io.Discard) +// newPipe returns the write end of a pipe that the test closes. +func newPipe(t *testing.T) *os.File { + t.Helper() + pr, pw, err := os.Pipe() require.NoError(t, err) - assert.False(t, ok) + t.Cleanup(func() { + pr.Close() + pw.Close() + }) + return pw } func TestCarriesProtocol(t *testing.T) { From d64f9c1d050ed8eaac42b42b66a6c12fb157be8d Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:40:46 +0000 Subject: [PATCH 15/32] cmd/root: compare stdout by identity only for regular files on Windows On Windows os.SameFile reports any two pipes or character devices as the same file, because their file ids are zero. With stdout piped, a null device or a named-pipe log file was refused as stdout. Compare by identity only for regular files there; elsewhere nothing changes. stdout itself is matched by pointer, so the stdout keyword is still refused on every OS. Co-authored-by: Isaac --- cmd/root/stdout_protocol.go | 5 ++++- cmd/root/stdout_protocol_other.go | 10 ++++++++++ cmd/root/stdout_protocol_test.go | 4 ++++ cmd/root/stdout_protocol_windows.go | 10 ++++++++++ 4 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 cmd/root/stdout_protocol_other.go create mode 100644 cmd/root/stdout_protocol_windows.go diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index 986c0981618..b2e4c8aa4c2 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -28,6 +28,9 @@ func writesToStdout(w io.Writer, stdout, stderr *os.File) (bool, error) { if !ok || f == stderr { return false, nil } + if f == stdout { + return true, nil + } out, err := stdout.Stat() if err != nil { return false, err @@ -36,5 +39,5 @@ func writesToStdout(w io.Writer, stdout, stderr *os.File) (bool, error) { if err != nil { return false, err } - return os.SameFile(fi, out), nil + return sameFileInfo(fi, out), nil } diff --git a/cmd/root/stdout_protocol_other.go b/cmd/root/stdout_protocol_other.go new file mode 100644 index 00000000000..5e0cdf31f6c --- /dev/null +++ b/cmd/root/stdout_protocol_other.go @@ -0,0 +1,10 @@ +//go:build !windows + +package root + +import "os" + +// sameFileInfo reports whether a and b describe the same file. +func sameFileInfo(a, b os.FileInfo) bool { + return os.SameFile(a, b) +} diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index f790b6e5c58..9a47c8faa96 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -91,6 +91,9 @@ func TestWritesToStdout(t *testing.T) { file, err := os.Create(filepath.Join(t.TempDir(), "run.log")) require.NoError(t, err) t.Cleanup(func() { file.Close() }) + null, err := os.OpenFile(os.DevNull, os.O_WRONLY, 0) + require.NoError(t, err) + t.Cleanup(func() { null.Close() }) tests := []struct { name string @@ -101,6 +104,7 @@ func TestWritesToStdout(t *testing.T) { {name: "stderr", w: stderr, want: false}, {name: "another pipe", w: other, want: false}, {name: "regular file", w: file, want: false}, + {name: "null device", w: null, want: false}, {name: "not a file", w: io.Discard, want: false}, } for _, tc := range tests { diff --git a/cmd/root/stdout_protocol_windows.go b/cmd/root/stdout_protocol_windows.go new file mode 100644 index 00000000000..734761fd03b --- /dev/null +++ b/cmd/root/stdout_protocol_windows.go @@ -0,0 +1,10 @@ +package root + +import "os" + +// sameFileInfo reports whether a and b describe the same file. On Windows os.SameFile reports any two pipes or +// character devices as the same file, since their file ids are zero. Only regular files are compared by identity, so +// a pipe or a null device is never taken for stdout. +func sameFileInfo(a, b os.FileInfo) bool { + return a.Mode().IsRegular() && b.Mode().IsRegular() && os.SameFile(a, b) +} From be0b52bcecd08bcdb78740390b1eaf8b30677c37 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:41:14 +0000 Subject: [PATCH 16/32] cmd/root: allow a log file that is stderr when stdout is the same file When stdout and stderr are one file, as on a terminal, a log file opened as /dev/stderr or /dev/tty was refused as stdout, while --log-file stderr was allowed. The protocol already shares that file with the diagnostics, so the check cannot help there: a destination that is the same file as stderr is not refused. Other destinations are compared as before. Co-authored-by: Isaac --- cmd/root/stdout_protocol.go | 29 ++++++++++++++++++++++------- cmd/root/stdout_protocol_test.go | 20 ++++++++++++++++++++ 2 files changed, 42 insertions(+), 7 deletions(-) diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index b2e4c8aa4c2..c3e67a8846a 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -21,23 +21,38 @@ func carriesProtocol(cmd *cobra.Command) bool { // writesToStdout reports whether w is stdout, given the process's stdout and stderr. It compares the open file, not a // path: on macOS, os.Stat of /dev/stdout does not match stdout when stdout is a pipe, but the opened /dev/stdout does. -// stderr is never stdout here, even when both share a terminal. The streams are parameters because under -// `go test -json` the testing package sets os.Stderr to os.Stdout. +// The streams are parameters because under `go test -json` the testing package sets os.Stderr to os.Stdout. +// +// A file that is also stderr is not stdout. When stdout and stderr are one file, as on a terminal, the protocol +// already shares it with the diagnostics, so the check cannot help and the log file is allowed. func writesToStdout(w io.Writer, stdout, stderr *os.File) (bool, error) { f, ok := w.(*os.File) - if !ok || f == stderr { + if !ok { return false, nil } - if f == stdout { + toStdout, err := sameFile(f, stdout) + if err != nil || !toStdout { + return false, err + } + toStderr, err := sameFile(f, stderr) + if err != nil { + return false, err + } + return !toStderr, nil +} + +// sameFile reports whether a and b are the same open file. +func sameFile(a, b *os.File) (bool, error) { + if a == b { return true, nil } - out, err := stdout.Stat() + ai, err := a.Stat() if err != nil { return false, err } - fi, err := f.Stat() + bi, err := b.Stat() if err != nil { return false, err } - return sameFileInfo(fi, out), nil + return sameFileInfo(ai, bi), nil } diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index 9a47c8faa96..eff30df722b 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -116,6 +116,26 @@ func TestWritesToStdout(t *testing.T) { } } +// When stdout and stderr are one file, as on a terminal, a log file that is that file is not refused: the protocol +// already shares it with the diagnostics. A second handle to it is that file, so it is not refused either. +func TestWritesToStdoutAllowsStderrFile(t *testing.T) { + path := filepath.Join(t.TempDir(), "terminal.txt") + shared, err := os.Create(path) + require.NoError(t, err) + t.Cleanup(func() { shared.Close() }) + second, err := os.OpenFile(path, os.O_WRONLY, 0) + require.NoError(t, err) + t.Cleanup(func() { second.Close() }) + + ok, err := writesToStdout(second, shared, shared) + require.NoError(t, err) + assert.False(t, ok) + + ok, err = writesToStdout(shared, shared, shared) + require.NoError(t, err) + assert.False(t, ok) +} + // newPipe returns the write end of a pipe that the test closes. func newPipe(t *testing.T) *os.File { t.Helper() From fb642e9d155874e93e7e009db3765e59aaf0ee43 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:42:29 +0000 Subject: [PATCH 17/32] cmd/root: close the log file and restore the logger when Execute returns Execute closed the log file through the context of the command that ran. On a panic the command's context was never returned, so the file stayed open, and the default logger kept writing to it after Execute returned, or closed. Execute now keeps a slot in its own context that initializeContext fills, closes the file in a defer (which also runs on a panic), and restores the default logger that was in place before the command. Co-authored-by: Isaac --- cmd/root/logger.go | 22 ++++++++++++------- cmd/root/root.go | 12 +++++++++-- cmd/root/stdout_protocol_test.go | 37 ++++++++++++++++++++++++++++++-- 3 files changed, 59 insertions(+), 12 deletions(-) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 77a88fea165..6196c0625f7 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -44,14 +44,18 @@ func (f *logFlags) makeLogHandler(ctx context.Context, opts slog.HandlerOptions) } } -// logFileKey is the context key of the log file that initializeContext opened. Execute closes it when the command -// returns. +// logFileKey is the context key of the logFileSlot that Execute puts in the context. type logFileKey struct{} -// closeLogFile closes the log file in ctx, if the command opened one. -func closeLogFile(ctx context.Context) { - if f, ok := ctx.Value(logFileKey{}).(io.Closer); ok { - _ = f.Close() +// logFileSlot holds the log file that initializeContext opened. Execute closes it when it returns. +type logFileSlot struct { + file io.Closer // nil until initializeContext opens the log file +} + +// close closes the log file, if one was opened. +func (s *logFileSlot) close() { + if s.file != nil { + _ = s.file.Close() } } @@ -79,6 +83,10 @@ func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (c if err != nil { return nil, err } + // Commands run without Execute have no slot, and then nothing closes the file. + if slot, ok := ctx.Value(logFileKey{}).(*logFileSlot); ok { + slot.file = &f.file + } if carriesProtocol(cmd) { toStdout, stdoutErr := writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) @@ -99,8 +107,6 @@ func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (c } slog.SetDefault(slog.New(handler).With(slog.Int("pid", os.Getpid()))) - // The log file is closed when Execute returns, after the last log line. - ctx = context.WithValue(ctx, logFileKey{}, &f.file) return log.NewContext(ctx, slog.Default()), nil } diff --git a/cmd/root/root.go b/cmd/root/root.go index 7d6b15f11fc..f9c7f71d6af 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -155,8 +155,16 @@ Stack Trace: startTime := time.Now() - // Close the log file the command opened, after its last log line. - defer func() { closeLogFile(cmd.Context()) }() + // initializeContext puts the log file it opens in this slot. When Execute returns, whether the command returned or + // panicked, the file is closed after the last log line, and the default logger that was in place is restored, so + // nothing writes to the closed file. + var logFile logFileSlot + ctx = context.WithValue(ctx, logFileKey{}, &logFile) + prevLogger := slog.Default() + defer func() { + logFile.close() + slog.SetDefault(prevLogger) + }() // Run the command cmd, err = cmd.ExecuteContextC(ctx) diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index eff30df722b..e90791a7aec 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -1,6 +1,7 @@ package root import ( + "fmt" "io" "log/slog" "os" @@ -46,7 +47,6 @@ func useSeparateStderr(t *testing.T) { } func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { - keepDefaultLogger(t) useSeparateStderr(t) for _, logFile := range []string{"stdout", "STDOUT", "/dev/stdout"} { t.Run(logFile, func(t *testing.T) { @@ -68,8 +68,41 @@ func TestExecuteRefusesStdoutLogForProtocolCommand(t *testing.T) { } } +// TestExecuteClosesLogFileAndRestoresLogger checks that once Execute returns, the file the command logged to is closed +// and the default logger writes elsewhere. It also checks the panic path, where the command never returns. +func TestExecuteClosesLogFileAndRestoresLogger(t *testing.T) { + prev := slog.Default() + t.Cleanup(func() { slog.SetDefault(prev) }) + for _, panics := range []bool{false, true} { + t.Run(fmt.Sprintf("panics=%v", panics), func(t *testing.T) { + var slot *logFileSlot + cmd := New(t.Context()) + cmd.AddCommand(&cobra.Command{ + Use: "serve", + RunE: func(cmd *cobra.Command, _ []string) error { + var ok bool + slot, ok = cmd.Context().Value(logFileKey{}).(*logFileSlot) + require.True(t, ok) + if panics { + panic("boom") + } + return nil + }, + }) + logFile := filepath.Join(t.TempDir(), "run.log") + cmd.SetArgs([]string{"serve", "--log-file", logFile}) + cmd.SetErr(io.Discard) + + err := Execute(t.Context(), cmd) + assert.Equal(t, panics, err != nil) + assert.Equal(t, prev, slog.Default()) + require.NotNil(t, slot) + assert.ErrorIs(t, slot.file.Close(), os.ErrClosed) + }) + } +} + func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { - keepDefaultLogger(t) useSeparateStderr(t) logFile := filepath.Join(t.TempDir(), "serve.log") ran := false From e8bb12e7b122752c8ab8a46c7cb0ffcbe1d27de0 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:43:21 +0000 Subject: [PATCH 18/32] libs/aitools/mcp/proxy: let Authenticate skip the session DELETE A caller whose credential is known to be unusable has no reason to send the session DELETE at shutdown: it would fail and log the failure again. Authenticate can now return ErrSkipRequest for the DELETE. The bridge then sends and logs nothing for it. Any other request that returns the sentinel is an error like any other. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 12 ++++++++++-- libs/aitools/mcp/proxy/bridge_test.go | 26 ++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index bc3357e7619..3946624de63 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -51,6 +51,10 @@ var ( errNoResponse = errors.New("upstream sent no response") // errUpstreamTooLarge is the error for an upstream message over maxLineBytes, whether it is a body or an event. errUpstreamTooLarge = fmt.Errorf("an upstream message exceeds the %d MiB limit", maxLineBytes>>20) + // ErrSkipRequest is returned by Authenticate to leave the session DELETE unsent: the bridge neither sends nor logs + // it. The DELETE is the only request that needs no answer. Any other request that returns it is an error like any + // other. + ErrSkipRequest = errors.New("request skipped") ) // Hooks intercepts upstream messages before they are written to stdout. @@ -68,7 +72,8 @@ type Bridge struct { Out io.Writer Err io.Writer Endpoint string - // Authenticate sets the Authorization header on each upstream request. + // Authenticate sets the Authorization header on each upstream request. It may return ErrSkipRequest for the + // session DELETE (see ErrSkipRequest). Authenticate func(*http.Request) error // Headers are set on every upstream request. Headers map[string]string @@ -305,9 +310,12 @@ func (c *conn) deleteSession(ctx context.Context, sent upstreamState) { } } -// sendDelete sends the DELETE that ends the session sent. +// sendDelete sends the DELETE that ends the session sent. A DELETE that Authenticate skips (ErrSkipRequest) is not sent. func (c *conn) sendDelete(ctx context.Context, sent upstreamState) error { req, err := c.newRequest(ctx, http.MethodDelete, nil, sent) + if errors.Is(err, ErrSkipRequest) { + return nil + } if err != nil { return err } diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go index 0c3e5e09556..89fe538b7a8 100644 --- a/libs/aitools/mcp/proxy/bridge_test.go +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -1928,6 +1928,32 @@ func TestRunRecordsSessionOnlyFromInitializeResult(t *testing.T) { assert.Empty(t, deletedSessions(fake), "no session was started, so none is deleted") } +// Authenticate returns ErrSkipRequest for the session DELETE: no DELETE is sent, and nothing is logged, since the +// session is over. +func TestRunSkipsSessionDeleteWhenAuthenticateSkipsIt(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + w.WriteHeader(http.StatusOK) + return + } + w.Header().Set("Mcp-Session-Id", "s1") + answer(w, r) + }) + b := bridgeFor(srv.URL) + authenticate := b.Authenticate + b.Authenticate = func(r *http.Request) error { + if r.Method == http.MethodDelete { + return ErrSkipRequest + } + return authenticate(r) + } + + _, errOut := runAll(t, b, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`+"\n") + + assert.Empty(t, deletedSessions(fake)) + assert.Empty(t, errOut) +} + // deletedSessions returns the Mcp-Session-Id of each DELETE the fake endpoint received, in order. func deletedSessions(fake *fakeEndpoint) []string { var sessions []string From 7e1311d029ec6837bd8c432c6a96ae9117f15f90 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:46:03 +0000 Subject: [PATCH 19/32] cmd/aitools: stop a refresh-failed serve cleanly and say why After a token refresh failure, every later request asked for a token again and logged the login hint again, a request cancelled before its failure was logged left nothing on stderr, and a stdin error after the failure exited 1 and hid the auth status. Now the first failing request carries the hint, with the restart step; later requests fail at once with a short error that does not repeat it; the session DELETE is skipped (proxy.ErrSkipRequest); and serve prints one final line and exits 2, whatever the bridge returned. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 49 ++++++--- cmd/aitools/mcp_serve_test.go | 188 +++++++++++++++++++++++++++++++--- 2 files changed, 208 insertions(+), 29 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index b9b9eb9e0be..5aa9fba4ecf 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -118,19 +118,26 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { } // serveProxy bridges opts to the service until stdin closes or a signal arrives. opts.Authenticate is wrapped by a -// refreshGuard. A token that cannot be refreshed mid-session stops the proxy with serveBindStatus. The bridge has -// already logged that error on the request that needed the token, so it is returned without being printed again. +// refreshGuard. A token that cannot be refreshed mid-session stops the proxy with serveBindStatus; see proxyResult. func serveProxy(cmd *cobra.Command, opts proxy.Options) error { ctx, stop := serveSignalContext(cmd.Context()) defer stop() refresh := &refreshGuard{authenticate: opts.Authenticate, profile: opts.Profile, cancel: stop} opts.Authenticate = refresh.authenticateRequest - if err := proxy.Run(ctx, opts); err != nil { - return serveFailure(cmd, err, 1) - } + return proxyResult(cmd, refresh, proxy.Run(ctx, opts)) +} + +// proxyResult is the outcome of serve once the bridge has returned with runErr. A refresh failure wins over runErr: the +// stdin error that can follow a stopped session is a consequence of it. The bridge logs the failing request's error, +// but not when the client cancelled that request first, so the final line always says why the proxy stopped. +func proxyResult(cmd *cobra.Command, refresh *refreshGuard, runErr error) error { if refreshErr := refresh.failure(); refreshErr != nil { + fmt.Fprintf(cmd.ErrOrStderr(), "stopped after a token refresh failure for profile %s\n", refresh.profile) return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: serveBindStatus, Err: refreshErr}) } + if runErr != nil { + return serveFailure(cmd, runErr, 1) + } return nil } @@ -175,12 +182,11 @@ func serveFailure(cmd *cobra.Command, err error, status int) error { return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) } -// refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed -// mid-session fails that request with an error naming the profile, then stops the proxy, so the -// command exits 2 and the next spawn re-runs the binding checks. A request whose own context ended, -// which the client cancelled or shutdown ended, does not stop it. Nor does the session DELETE at -// shutdown, which is best effort: after a refresh failure it is sent without a credential, as the -// session is already over. +// refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed mid-session fails +// that request with an error that names the profile and its login command, then stops the proxy, so the command exits +// 2 and the next spawn re-runs the binding checks. Later requests fail at once, without asking for a token again. A +// request whose own context ended, which the client cancelled or shutdown ended, does not stop it. Nor does the +// session DELETE at shutdown, which is best effort: after a refresh failure it is skipped, as the session is over. type refreshGuard struct { authenticate func(*http.Request) error profile string @@ -192,8 +198,11 @@ type refreshGuard struct { // authenticateRequest is the bridge's Authenticate. It is safe for concurrent use. func (g *refreshGuard) authenticateRequest(r *http.Request) error { - if g.failure() != nil && r.Method == http.MethodDelete { - return nil + if g.failure() != nil { + if r.Method == http.MethodDelete { + return proxy.ErrSkipRequest + } + return g.stoppedError() } err := g.authenticate(r) if err == nil { @@ -202,16 +211,26 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { if r.Context().Err() != nil || r.Method == http.MethodDelete { return err } - authErr := mcp.AuthError(g.profile, err) + // The hint says to restart the server, since the next spawn is what picks up the new login. + authErr := fmt.Errorf("%w, then restart the MCP server in your agent", mcp.AuthError(g.profile, err)) g.mu.Lock() - if g.err == nil { + first := g.err == nil + if first { g.err = authErr } g.mu.Unlock() + if !first { + return g.stoppedError() + } g.cancel() return authErr } +// stoppedError is the error for a request that arrives after the refresh failure. It does not repeat the login hint. +func (g *refreshGuard) stoppedError() error { + return fmt.Errorf("the session is stopping after a token refresh failure for profile %s", g.profile) +} + // failure returns the first refresh error, or nil when every token was refreshed. func (g *refreshGuard) failure() error { g.mu.Lock() diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index 7d7762eff05..a379c95640f 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -14,6 +14,7 @@ import ( "path/filepath" "runtime" "strings" + "sync" "sync/atomic" "testing" "time" @@ -61,12 +62,30 @@ func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { err := g.authenticateRequest(&http.Request{Header: http.Header{}}) require.Error(t, err) assert.ErrorIs(t, err, cause) - assert.Contains(t, err.Error(), "databricks auth login --profile logfood") + assert.Contains(t, err.Error(), "databricks auth login --profile logfood, then restart the MCP server in your agent") assert.Equal(t, context.Canceled, ctx.Err()) + assert.ErrorIs(t, g.failure(), cause) +} - // A second failure keeps the first error for the exit status. - _ = g.authenticateRequest(&http.Request{Header: http.Header{}}) - assert.Equal(t, 2, calls) +// After the first failure no request asks for a token again. Each later request fails at once with a short error that +// does not repeat the login hint. +func TestRefreshGuardStopsLaterRequestsWithoutAskingAgain(t *testing.T) { + calls := 0 + cause := errors.New("refresh token expired") + g := &refreshGuard{ + authenticate: func(*http.Request) error { + calls++ + return cause + }, + profile: "logfood", + cancel: func() {}, + } + require.Error(t, g.authenticateRequest(&http.Request{Header: http.Header{}})) + + err := g.authenticateRequest(&http.Request{Header: http.Header{}}) + + assert.Equal(t, 1, calls) + assert.EqualError(t, err, "the session is stopping after a token refresh failure for profile logfood") assert.ErrorIs(t, g.failure(), cause) } @@ -223,9 +242,9 @@ func TestMcpServeStateReadFailureExitsTwo(t *testing.T) { assert.Contains(t, stderr.String(), ".state.json") } -// After a refresh failure the session DELETE is sent without a credential: the session is over, and a failed DELETE -// would log the refresh error a second time. Authenticate is not asked. -func TestRefreshGuardSendsDeleteWithoutCredentialAfterFailure(t *testing.T) { +// After a refresh failure the session DELETE is skipped: the session is over, and a DELETE without a credential would +// fail and log the refresh error a second time. Authenticate is not asked. +func TestRefreshGuardSkipsSessionDeleteAfterFailure(t *testing.T) { asked := 0 g := &refreshGuard{ authenticate: func(*http.Request) error { @@ -240,10 +259,45 @@ func TestRefreshGuardSendsDeleteWithoutCredentialAfterFailure(t *testing.T) { req, err := http.NewRequestWithContext(t.Context(), http.MethodDelete, "https://workspace.test/mcp", nil) require.NoError(t, err) - assert.NoError(t, g.authenticateRequest(req)) + assert.ErrorIs(t, g.authenticateRequest(req), proxy.ErrSkipRequest) assert.Equal(t, 0, asked) } +// Once the bridge has returned, a refresh failure is the exit status and the final line, whatever Run returned. A +// stdin error that follows the failure is a consequence of it and is not reported. +func TestProxyResultRefreshFailureWinsOverStdinError(t *testing.T) { + cause := errors.New("refresh token expired") + g := &refreshGuard{ + authenticate: func(*http.Request) error { return cause }, + profile: "logfood", + cancel: func() {}, + } + require.Error(t, g.authenticateRequest(&http.Request{Header: http.Header{}})) + cmd := NewMcpServeCmd() + var stderr bytes.Buffer + cmd.SetErr(&stderr) + + err := proxyResult(cmd, g, errors.New("read stdin: input/output error")) + + assert.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, serveBindStatus, root.ExitStatus(err)) + assert.ErrorIs(t, err, cause) + assert.Equal(t, "stopped after a token refresh failure for profile logfood\n", stderr.String()) +} + +// Without a refresh failure, a stdin error is printed and exits 1. +func TestProxyResultReportsStdinErrorWithoutRefreshFailure(t *testing.T) { + g := &refreshGuard{profile: "logfood"} + cmd := NewMcpServeCmd() + var stderr bytes.Buffer + cmd.SetErr(&stderr) + + err := proxyResult(cmd, g, errors.New("read stdin: input/output error")) + + assert.Equal(t, 1, root.ExitStatus(err)) + assert.Equal(t, "read stdin: input/output error\n", stderr.String()) +} + // A token that expires mid-session fails the request that needs it. The bridge logs that failure once, with the // profile and the login command; the proxy then exits 2 without printing it again, and the session DELETE at // shutdown is still sent. @@ -288,14 +342,120 @@ func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { return nil } - stdin := `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}` + "\n" + - `{"jsonrpc":"2.0","id":2,"method":"tools/list"}` + "\n" var stderr bytes.Buffer + var stdout lockedBuffer + in := feedAfterAnswers(t, &stdout, []string{ + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, + }, nil) cmd := NewMcpServeCmd() cmd.SetContext(t.Context()) + cmd.SetErr(&stderr) + err := serveProxy(cmd, proxy.Options{ + In: in, + Out: &stdout, + Err: &stderr, + Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), + Config: &config.Config{Host: server.URL}, + Authenticate: authenticate, + Profile: "logfood", + }) + + require.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 2, root.ExitStatus(err)) + assert.Equal(t, "databricks aitools mcp serve: upstream: refresh token expired\n"+ + "Run: databricks auth login --profile logfood, then restart the MCP server in your agent\n"+ + "stopped after a token refresh failure for profile logfood\n", stderr.String()) + assert.False(t, deleted.Load(), "no session DELETE is sent after a refresh failure") +} + +// lockedBuffer collects what serve writes to stdout. The bridge writes from several goroutines. +type lockedBuffer struct { + mu sync.Mutex + buf bytes.Buffer +} + +func (b *lockedBuffer) Write(p []byte) (int, error) { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.Write(p) +} + +func (b *lockedBuffer) String() string { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.String() +} + +// feedAfterAnswers returns stdin for serve. It sends each line once the answer to the line before it is on out, as an +// MCP client does: the bridge runs requests concurrently, so a later request could otherwise overtake the initialize. +// The input then ends with end, or closes when end is nil. The answers are the ones the test expects from the fake +// endpoint, so the feeder waits for the ids of the lines it has sent. +func feedAfterAnswers(t *testing.T, out *lockedBuffer, lines []string, end error) io.Reader { + t.Helper() + pr, pw := io.Pipe() + t.Cleanup(func() { pw.Close() }) + go func() { + for i, line := range lines { + if i > 0 { + want := fmt.Sprintf(`"id":%d,`, i) + deadline := time.Now().Add(10 * time.Second) + for !strings.Contains(out.String(), want) && time.Now().Before(deadline) { + time.Sleep(time.Millisecond) + } + } + if _, err := io.WriteString(pw, line+"\n"); err != nil { + return + } + } + if end != nil { + pw.CloseWithError(end) + return + } + pw.Close() + }() + return pr +} + +// A stdin error after the refresh failure does not change the exit status or the final line. +func TestServeProxyRefreshFailureWinsOverStdinError(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Mcp-Session-Id", "session-1") + fmt.Fprint(w, `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"fake","version":"1"}}}`) + })) + defer server.Close() + + authenticate := func(r *http.Request) error { + if r.Method != http.MethodPost { + return nil + } + body, err := r.GetBody() + if err != nil { + return err + } + data, err := io.ReadAll(body) + body.Close() + if err != nil { + return err + } + if strings.Contains(string(data), `"tools/list"`) { + return errors.New("refresh token expired") + } + return nil + } + var stderr bytes.Buffer + var stdout lockedBuffer + in := feedAfterAnswers(t, &stdout, []string{ + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, + }, errors.New("input/output error")) + cmd := NewMcpServeCmd() + cmd.SetContext(t.Context()) + cmd.SetErr(&stderr) err := serveProxy(cmd, proxy.Options{ - In: strings.NewReader(stdin), - Out: io.Discard, + In: in, + Out: &stdout, Err: &stderr, Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), Config: &config.Config{Host: server.URL}, @@ -305,8 +465,8 @@ func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { require.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) - assert.Equal(t, "databricks aitools mcp serve: upstream: refresh token expired\nRun: databricks auth login --profile logfood\n", stderr.String()) - assert.True(t, deleted.Load(), "the session DELETE is still sent") + assert.NotContains(t, stderr.String(), "input/output error") + assert.True(t, strings.HasSuffix(stderr.String(), "stopped after a token refresh failure for profile logfood\n"), stderr.String()) } // signalHelperEnv marks the child process that TestServeSecondSignalEndsProcess starts. From a3e38094c9f7ec8a48b09fe1fbf1fbd299210f66 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:47:38 +0000 Subject: [PATCH 20/32] libs/testserver: answer 404 for an MCP service the workspace does not have The fake MCP endpoint answered any service name, so a wrong service name or path in the proxy's command still passed. A name with no service now gets 404, as the gateway answers a name that has none, and the tests and the serve acceptance case seed the service they use. Co-authored-by: Isaac --- .../cmd/aitools/mcp/serve-passthrough/script | 3 +++ libs/testserver/mcp_endpoint.go | 22 ++++++++++++------- libs/testserver/mcp_endpoint_test.go | 18 +++++++++++++++ 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script index 498d3c66787..5ed987c1ee3 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/script +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -6,6 +6,9 @@ export DATABRICKS_CONFIG_FILE=.databrickscfg # DATABRICKS_HOST points elsewhere; the proxy must still talk to the profile's host. export DATABRICKS_HOST=https://elsewhere.test +# The service the proxy serves, created in the fake workspace. The fake answers 404 for a service it does not have. +MSYS_NO_PATHCONV=1 $CLI api post "/api/2.1/unity-catalog/mcp-services?parent=schemas/system.ai&mcp_service_id=genie_one_mcp" --profile logfood --json '{"comment": "Ask questions about your data"}' &> LOG.create-genie_one_mcp-logfood + # Responses may arrive in any order, so they are sorted by id. jq -s also fails when any stdout line is not JSON. title "Stdout holds one JSON-RPC message per line; the notification gets no reply" $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go index 911dbd97f24..92adfd45f91 100644 --- a/libs/testserver/mcp_endpoint.go +++ b/libs/testserver/mcp_endpoint.go @@ -3,6 +3,8 @@ package testserver import ( "encoding/json" "net/http" + + "github.com/databricks/databricks-sdk-go/service/catalog" ) // JSON-RPC codes the fake endpoint answers with. @@ -33,12 +35,17 @@ type mcpRPC struct { } // McpEndpoint fakes POST /ai-gateway/mcp-services/{name}, a streamable HTTP MCP server with one -// tool, echo. A service stored with an OAuth source connection is external: no credential is -// ever mapped to it here, so tools/list and tools/call answer -32006 as the gateway does before -// sign-in. Notifications and client responses, which have no method or no id, get 202 with no body. +// tool, echo. A name the workspace has no service for is 404. A service stored with an OAuth source +// connection is external: no credential is ever mapped to it here, so tools/list and tools/call +// answer -32006 as the gateway does before sign-in. Notifications and client responses, which have +// no method or no id, get 202 with no body. func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { defer s.LockUnlock()() + service, ok := s.McpServices[name] + if !ok { + return Response{StatusCode: http.StatusNotFound} + } var msg mcpRPC if err := json.Unmarshal(req.Body, &msg); err != nil { return Response{StatusCode: http.StatusBadRequest, Body: rpcError(nil, rpcCodeParseError, "Parse error")} @@ -47,7 +54,7 @@ func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { return Response{StatusCode: http.StatusAccepted} } - external := s.mcpServiceIsExternal(name) + external := mcpServiceIsExternal(service) switch msg.Method { case "initialize": return rpcResult(msg.ID, map[string]any{ @@ -87,10 +94,9 @@ func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { } } -// mcpServiceIsExternal reports whether the stored service name takes an OAuth source connection. -func (s *FakeWorkspace) mcpServiceIsExternal(name string) bool { - ms, ok := s.McpServices[name] - return ok && ms.Config != nil && ms.Config.SourceConnection != nil && +// mcpServiceIsExternal reports whether the service takes an OAuth source connection. +func mcpServiceIsExternal(ms catalog.McpService) bool { + return ms.Config != nil && ms.Config.SourceConnection != nil && ms.Config.SourceConnection.Options["oauth_provider"] != "" } diff --git a/libs/testserver/mcp_endpoint_test.go b/libs/testserver/mcp_endpoint_test.go index b444ed7951b..a227395dee1 100644 --- a/libs/testserver/mcp_endpoint_test.go +++ b/libs/testserver/mcp_endpoint_test.go @@ -23,6 +23,7 @@ func mcpEndpointTestCall(t *testing.T, workspace *FakeWorkspace, name, message s func TestMcpEndpointAnswersInternalService(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") const name = "system.ai.genie_one_mcp" + mcpServicesTestSeed(workspace, name, "Genie", "") reply := mcpEndpointTestCall(t, workspace, name, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`) assert.Nil(t, reply["error"]) @@ -46,8 +47,24 @@ func TestMcpEndpointRejectsExternalServiceWithoutCredential(t *testing.T) { assert.Nil(t, reply["result"]) } +// A service the fake does not have is 404, as the gateway answers a name that no service has, whatever the message. +func TestMcpEndpointUnknownServiceIsNotFound(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") + + for _, body := range []string{ + `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`, + `{"jsonrpc":"2.0","method":"notifications/initialized"}`, + } { + response := workspace.McpEndpoint(Request{Body: []byte(body)}, "system.ai.genie_one_mc") + assert.Equal(t, 404, response.StatusCode, body) + assert.Nil(t, response.Body) + } +} + func TestMcpEndpointNotificationGetsNoBody(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","method":"notifications/initialized"}`)}, "system.ai.genie_one_mcp") assert.Equal(t, 202, response.StatusCode) assert.Nil(t, response.Body) @@ -56,6 +73,7 @@ func TestMcpEndpointNotificationGetsNoBody(t *testing.T) { // A client's answer to a request from the server has an id and no method. It is not a request, so it gets 202 with no body. func TestMcpEndpointClientResponseGetsNoBody(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","id":7,"result":{}}`)}, "system.ai.genie_one_mcp") assert.Equal(t, 202, response.StatusCode) assert.Nil(t, response.Body) From 6e2c7172716469edf293bd3afd2b3a6da7e12ff2 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:49:08 +0000 Subject: [PATCH 21/32] cmd/root: test the stale-version skip for protocol commands; simplify logger The stale-version skip for a command whose stdout carries a protocol had no test. Move the decision into staleVersionSkipped, which takes the build info, and test it. In initializeContext the refused log file no longer needs a close: Execute closes the file it opened. Co-authored-by: Isaac --- cmd/root/logger.go | 9 +++------ cmd/root/stale_version.go | 8 +++++++- cmd/root/stale_version_test.go | 10 ++++++++++ 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 6196c0625f7..686e1a34436 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -89,12 +89,9 @@ func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (c } if carriesProtocol(cmd) { - toStdout, stdoutErr := writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) - if stdoutErr != nil || toStdout { - _ = f.file.Close() - } - if stdoutErr != nil { - return nil, stdoutErr + toStdout, err := writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) + if err != nil { + return nil, err } if toStdout { return nil, fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) diff --git a/cmd/root/stale_version.go b/cmd/root/stale_version.go index 63519ab316a..81ea6f6ec25 100644 --- a/cmd/root/stale_version.go +++ b/cmd/root/stale_version.go @@ -40,9 +40,15 @@ func skipStaleVersionWarning(ctx context.Context, info build.Info) bool { return dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) } +// staleVersionSkipped reports whether cmd gets no stale-version warning: a command whose stdout carries a protocol +// never does, and neither does a build that skipStaleVersionWarning skips. +func staleVersionSkipped(ctx context.Context, cmd *cobra.Command, info build.Info) bool { + return carriesProtocol(cmd) || skipStaleVersionWarning(ctx, info) +} + func warnIfStaleVersion(ctx context.Context, cmd *cobra.Command) { info := build.GetInfo() - if carriesProtocol(cmd) || skipStaleVersionWarning(ctx, info) { + if staleVersionSkipped(ctx, cmd, info) { return } _, command := versioncheck.DetectInstallMethod(ctx) diff --git a/cmd/root/stale_version_test.go b/cmd/root/stale_version_test.go index a7bcb8f4da6..d17379e6252 100644 --- a/cmd/root/stale_version_test.go +++ b/cmd/root/stale_version_test.go @@ -6,6 +6,7 @@ import ( "github.com/databricks/cli/internal/build" "github.com/databricks/cli/libs/dbr" + "github.com/spf13/cobra" "github.com/stretchr/testify/assert" ) @@ -65,3 +66,12 @@ func TestSkipStaleVersionWarning(t *testing.T) { }) } } + +// A command whose stdout carries a protocol gets no stale-version warning, even on a stale build. The warning goes to +// stderr, but an agent shows the server's stderr every time it starts the server. +func TestStaleVersionSkippedForProtocolCommand(t *testing.T) { + ctx := dbr.MockRuntime(t.Context(), dbr.Environment{}) + release := build.Info{Version: "1.18.0"} + assert.True(t, staleVersionSkipped(ctx, protocolTestCommand(new(bool)), release)) + assert.False(t, staleVersionSkipped(ctx, &cobra.Command{Use: "list"}, release)) +} From 1e0c584297985442e8e3589b930c8c5d48fb144a Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:49:09 +0000 Subject: [PATCH 22/32] cmd/aitools: serve takes add's flag names from mcpconfig and inlines its dialer The flag names of serve are the constants that add writes into agent configs, so an entry binds what add wrote; a test parses that argv with serve's flags. The dialer helper existed only for a test of a constant, so it is inlined and the test dropped. The binding status doc no longer cites a list command that is not in this tree. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 18 ++++++++---------- cmd/aitools/mcp_serve_test.go | 22 ++++++++++++++++++---- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index 5aa9fba4ecf..5d1780876f6 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -27,18 +27,13 @@ import ( // serveConnectTimeout bounds one upstream connect. http.DefaultTransport waits 30 s. const serveConnectTimeout = 10 * time.Second -// serveDialer dials the upstream service with serveConnectTimeout. -func serveDialer() *net.Dialer { - return &net.Dialer{Timeout: serveConnectTimeout} -} - // serveTransport is the transport of the bridge's upstream requests. It starts from // http.DefaultTransport, so proxy use and the other timeouts stay as they are, and replaces the // dialer to set the connect timeout. The profile's InsecureSkipVerify is honored; the clone keeps // HTTP/2 enabled. func serveTransport(cfg *config.Config) *http.Transport { tr := http.DefaultTransport.(*http.Transport).Clone() - tr.DialContext = serveDialer().DialContext + tr.DialContext = (&net.Dialer{Timeout: serveConnectTimeout}).DialContext if cfg.InsecureSkipVerify { if tr.TLSClientConfig == nil { tr.TLSClientConfig = &tls.Config{} @@ -68,8 +63,11 @@ func NewMcpServeCmd() *cobra.Command { return runMcpServe(cmd, f) }, } - cmd.Flags().StringVar(&f.service, "service", "", "Full name of the MCP service, for example system.ai.github") - cmd.Flags().StringVar(&f.agent, "agent", "", "Registry name of the calling agent, used only for the User-Agent") + // The names are the ones `aitools mcp add` writes into each agent's config, so an entry binds what add wrote. + cmd.Flags().StringVar(&f.service, strings.TrimPrefix(mcpconfig.ServiceFlag, "--"), "", + "Full name of the MCP service, for example system.ai.github") + cmd.Flags().StringVar(&f.agent, strings.TrimPrefix(mcpconfig.AgentFlag, "--"), "", + "Registry name of the calling agent, used only for the User-Agent") return cmd } @@ -171,8 +169,8 @@ func serveAgent(name string, stderr io.Writer) string { return "" } -// serveBindStatus is the exit status of a binding or auth failure. Agents and `list --check` tell it from a -// transport error, so it is not 1. +// serveBindStatus is the exit status of a binding or auth failure. It is not 1, so an agent can tell a failed +// binding or sign-in from the other failures, which exit 1. const serveBindStatus = 2 // serveFailure prints err to stderr and returns it with the exit status. Execute does not print it again, diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index a379c95640f..47d85a85d38 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -23,6 +23,7 @@ import ( "github.com/databricks/cli/libs/aitools/installer" "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/cli/libs/aitools/mcp/proxy" + "github.com/databricks/cli/libs/aitools/mcpconfig" "github.com/databricks/cli/libs/cmdio" "github.com/databricks/databricks-sdk-go/config" "github.com/stretchr/testify/assert" @@ -33,6 +34,23 @@ func TestMcpServeIsHidden(t *testing.T) { assert.True(t, NewMcpServeCmd().Hidden) } +// The argv that `aitools mcp add` writes into an agent config parses with serve's flags. +func TestServeParsesArgvThatAddWrites(t *testing.T) { + parent := newMCPTestRoot() + serve, _, err := parent.Find([]string{"mcp", "serve"}) + require.NoError(t, err) + argv := []string{mcpconfig.ProfileFlag, "logfood", mcpconfig.ServiceFlag, "system.ai.github", mcpconfig.AgentFlag, "claude-code"} + require.NoError(t, serve.ParseFlags(argv)) + + profile, err := serve.Flags().GetString("profile") + require.NoError(t, err) + service, err := serve.Flags().GetString("service") + require.NoError(t, err) + agent, err := serve.Flags().GetString("agent") + require.NoError(t, err) + assert.Equal(t, []string{"logfood", "system.ai.github", "claude-code"}, []string{profile, service, agent}) +} + func TestRefreshGuardPassesThroughWhileTokensRefresh(t *testing.T) { cancelled := false g := &refreshGuard{ @@ -122,10 +140,6 @@ func TestServeFailurePrintsOnceWithStatus(t *testing.T) { assert.ErrorIs(t, err, cause) } -func TestServeDialerHasConnectTimeout(t *testing.T) { - assert.Equal(t, 10*time.Second, serveDialer().Timeout) -} - // The profile's insecure_skip_verify reaches the transport, and HTTP/2 is kept with it. func TestServeTransportTLSVerification(t *testing.T) { tests := []struct { From 651637489f897d14f91a0da55dfee56365bd3270 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 01:49:58 +0000 Subject: [PATCH 23/32] acceptance: show the serve command line in its goldens The serve cases ran the command without printing it, so the flags under test did not appear in the goldens. Wrap each invocation in trace. Co-authored-by: Isaac --- .../cmd/aitools/mcp/serve-binding-errors/output.txt | 12 ++++++++++++ .../cmd/aitools/mcp/serve-binding-errors/script | 12 ++++++------ .../cmd/aitools/mcp/serve-passthrough/output.txt | 4 ++++ acceptance/cmd/aitools/mcp/serve-passthrough/script | 4 ++-- 4 files changed, 24 insertions(+), 8 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index 21f305e8b7a..d5da631f49c 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -2,6 +2,8 @@ === The bound profile is not in the config file >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --profile gone --service system.ai.genie_one_mcp MCP server system.ai.genie_one_mcp needs Databricks profile "gone", which does not exist in [TEST_TMP_DIR]/.databrickscfg. Set it up with: databricks auth login --profile gone Exit code: 2 @@ -10,6 +12,8 @@ stdout bytes: 0 === The profile now points at another host than the one recorded >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again Exit code: 2 @@ -18,16 +22,22 @@ stdout bytes: 0 === Flags are required and validated before the binding checks >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --service system.ai.genie_one_mcp Error: --profile is required Exit code: 1 >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --profile logfood --service github Error: --service needs a full service name such as system.ai.github Exit code: 1 >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json Error: --output does not apply to serve: its stdout carries the MCP protocol Exit code: 1 @@ -35,6 +45,8 @@ Exit code: 1 === A log file on stdout is refused before anything is logged >>> cat LOG.stderr + +>>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file Exit code: 1 diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index edd332918d6..663645121f2 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -12,7 +12,7 @@ esac # Binding failures exit 2 with one message on stderr. Nothing reaches stdout, and stdin is not read. title "The bound profile is not in the config file" -errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" @@ -42,20 +42,20 @@ cat > home/.databricks/aitools/skills/.state.json < LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" title "Flags are required and validated before the binding checks" -errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr -errcode $CLI aitools mcp serve --profile logfood --service github < requests.ndjson > LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service github < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr -errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr # Logs and the stale-version warning never share stdout with the protocol, even at debug level. title "A log file on stdout is refused before anything is logged" -errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug < requests.ndjson > LOG.stdout 2> LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug < requests.ndjson > LOG.stdout 2> LOG.stderr trace cat LOG.stderr echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt index d0cee74464a..eba527069a2 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/output.txt @@ -7,6 +7,8 @@ === Diagnostics go to stderr only >>> cat LOG.stderr + +>>> [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] === An agent this binary does not know is accepted @@ -15,5 +17,7 @@ No install record for system.ai.genie_one_mcp on profile "logfood"; using its cu {"id":3,"instructions":null,"tools":[],"text":"hello","error":null} >>> cat LOG.future + +>>> [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent No install record for system.ai.genie_one_mcp on profile "logfood"; using its current host [DATABRICKS_URL] unknown agent "future-agent"; it is left out of the User-Agent diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script index 5ed987c1ee3..c9536e2e1f2 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/script +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -11,12 +11,12 @@ MSYS_NO_PATHCONV=1 $CLI api post "/api/2.1/unity-catalog/mcp-services?parent=sch # Responses may arrive in any order, so they are sorted by id. jq -s also fails when any stdout line is not JSON. title "Stdout holds one JSON-RPC message per line; the notification gets no reply" -$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' title "Diagnostics go to stderr only" trace cat LOG.stderr # An agent this binary does not know still serves; it is left out of the User-Agent, with one line on stderr. title "An agent this binary does not know is accepted" -$CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent < requests.ndjson 2> LOG.future | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent < requests.ndjson 2> LOG.future | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' trace cat LOG.future From a3a3cb12b5d11683dc3fe63468ce41279f7b8d92 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:15:20 +0000 Subject: [PATCH 24/32] cmd/root: restore the standard log writer and flags after Execute slog.SetDefault redirects the standard log package to the new handler, so after Execute closed the log file, log.Printf still wrote to it. Execute now saves and restores log.Writer() and log.Flags() with the default logger. Co-authored-by: Isaac --- cmd/root/root.go | 5 +++++ cmd/root/root_test.go | 28 ++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/cmd/root/root.go b/cmd/root/root.go index f9c7f71d6af..3c0b188ab92 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + stdlog "log" "log/slog" "os" "runtime" @@ -160,10 +161,14 @@ Stack Trace: // nothing writes to the closed file. var logFile logFileSlot ctx = context.WithValue(ctx, logFileKey{}, &logFile) + // slog.SetDefault also redirects the standard log package, so both are restored. prevLogger := slog.Default() + prevLogWriter, prevLogFlags := stdlog.Writer(), stdlog.Flags() defer func() { logFile.close() slog.SetDefault(prevLogger) + stdlog.SetOutput(prevLogWriter) + stdlog.SetFlags(prevLogFlags) }() // Run the command diff --git a/cmd/root/root_test.go b/cmd/root/root_test.go index f25f682586e..dc57f76068b 100644 --- a/cmd/root/root_test.go +++ b/cmd/root/root_test.go @@ -6,6 +6,7 @@ import ( "encoding/json" "errors" "io" + stdlog "log" "os" "path/filepath" "strings" @@ -213,3 +214,30 @@ func TestExecuteLogsExitStatus(t *testing.T) { require.NotNil(t, failed, "no failed execution record in %s", logFile) assert.Equal(t, "2", failed["exit_code"]) } + +// TestExecuteRestoresStdLogOutput checks that the standard log package writes where it did before Execute, not to the +// log file that Execute closes. slog.SetDefault redirects the standard log package to a non-default handler. +func TestExecuteRestoresStdLogOutput(t *testing.T) { + keepDefaultLogger(t) + var out bytes.Buffer + prevWriter, prevFlags := stdlog.Writer(), stdlog.Flags() + stdlog.SetOutput(&out) + t.Cleanup(func() { + stdlog.SetOutput(prevWriter) + stdlog.SetFlags(prevFlags) + }) + + logFile := filepath.Join(t.TempDir(), "run.log") + cmd := New(t.Context()) + cmd.AddCommand(&cobra.Command{ + Use: "ok", + RunE: func(*cobra.Command, []string) error { return nil }, + }) + cmd.SetArgs([]string{"ok", "--log-file", logFile, "--log-level", "debug"}) + cmd.SetErr(io.Discard) + require.NoError(t, Execute(t.Context(), cmd)) + + stdlog.Print("after execute") + assert.Equal(t, prevFlags, stdlog.Flags()) + assert.Contains(t, out.String(), "after execute") +} From 75c0f69d065ca6b6be7cd25319d396ba38c196ef Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:15:22 +0000 Subject: [PATCH 25/32] cmd/root: treat a stream that cannot be stat'ed as not stdout The stdout check ran for every protocol command, including the default stderr log, and a failed Stat returned an error that stopped the command, so `2>&-` made `serve` fail. A stat failure now means the stream is not stdout, and writesToStdout returns a bool. Co-authored-by: Isaac --- cmd/root/logger.go | 10 ++----- cmd/root/stdout_protocol.go | 29 ++++++++------------ cmd/root/stdout_protocol_test.go | 47 ++++++++++++++++++++++++++++---- 3 files changed, 55 insertions(+), 31 deletions(-) diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 686e1a34436..90a1d4ce4dd 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -88,14 +88,8 @@ func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (c slot.file = &f.file } - if carriesProtocol(cmd) { - toStdout, err := writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) - if err != nil { - return nil, err - } - if toStdout { - return nil, fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) - } + if carriesProtocol(cmd) && writesToStdout(f.file.Writer(), os.Stdout, os.Stderr) { + return nil, fmt.Errorf("%s writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file", cmd.CommandPath()) } handler, err := f.makeLogHandler(ctx, opts) diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index c3e67a8846a..19b54270c9a 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -25,34 +25,27 @@ func carriesProtocol(cmd *cobra.Command) bool { // // A file that is also stderr is not stdout. When stdout and stderr are one file, as on a terminal, the protocol // already shares it with the diagnostics, so the check cannot help and the log file is allowed. -func writesToStdout(w io.Writer, stdout, stderr *os.File) (bool, error) { +func writesToStdout(w io.Writer, stdout, stderr *os.File) bool { f, ok := w.(*os.File) - if !ok { - return false, nil + if !ok || f == stderr { + return false } - toStdout, err := sameFile(f, stdout) - if err != nil || !toStdout { - return false, err - } - toStderr, err := sameFile(f, stderr) - if err != nil { - return false, err - } - return !toStderr, nil + return sameFile(f, stdout) && !sameFile(f, stderr) } -// sameFile reports whether a and b are the same open file. -func sameFile(a, b *os.File) (bool, error) { +// sameFile reports whether a and b are the same open file. A stream that cannot be stat'ed, such as a closed one, is +// not the same file as anything. +func sameFile(a, b *os.File) bool { if a == b { - return true, nil + return true } ai, err := a.Stat() if err != nil { - return false, err + return false } bi, err := b.Stat() if err != nil { - return false, err + return false } - return sameFileInfo(ai, bi), nil + return sameFileInfo(ai, bi) } diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index e90791a7aec..def6f8df332 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -142,8 +142,7 @@ func TestWritesToStdout(t *testing.T) { } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - ok, err := writesToStdout(tc.w, stdout, stderr) - require.NoError(t, err) + ok := writesToStdout(tc.w, stdout, stderr) assert.Equal(t, tc.want, ok) }) } @@ -160,13 +159,51 @@ func TestWritesToStdoutAllowsStderrFile(t *testing.T) { require.NoError(t, err) t.Cleanup(func() { second.Close() }) - ok, err := writesToStdout(second, shared, shared) - require.NoError(t, err) + ok := writesToStdout(second, shared, shared) + assert.False(t, ok) + + ok = writesToStdout(shared, shared, shared) assert.False(t, ok) +} - ok, err = writesToStdout(shared, shared, shared) +// TestWritesToStdoutIgnoresStatFailure checks that a stream that cannot be stat'ed is not stdout: a closed stderr does +// not stop a protocol command, and a closed stdout is not the file a log file names. +func TestWritesToStdoutIgnoresStatFailure(t *testing.T) { + stdout := newPipe(t) + closed := newPipe(t) + require.NoError(t, closed.Close()) + file, err := os.Create(filepath.Join(t.TempDir(), "run.log")) require.NoError(t, err) + t.Cleanup(func() { file.Close() }) + + ok := writesToStdout(stdout, stdout, closed) + assert.True(t, ok, "stdout is still stdout when stderr is closed") + + ok = writesToStdout(file, stdout, closed) assert.False(t, ok) + + ok = writesToStdout(file, closed, stdout) + assert.False(t, ok) +} + +// TestExecuteRunsProtocolCommandWithClosedStderr checks that a protocol command without a log file runs when stderr is +// closed, as `2>&-` leaves it. +func TestExecuteRunsProtocolCommandWithClosedStderr(t *testing.T) { + closed, err := os.Create(filepath.Join(t.TempDir(), "stderr.txt")) + require.NoError(t, err) + require.NoError(t, closed.Close()) + prev := os.Stderr + os.Stderr = closed + t.Cleanup(func() { os.Stderr = prev }) + + ran := false + cmd := New(t.Context()) + cmd.AddCommand(protocolTestCommand(&ran)) + cmd.SetArgs([]string{"serve"}) + cmd.SetErr(io.Discard) + + require.NoError(t, Execute(t.Context(), cmd)) + assert.True(t, ran) } // newPipe returns the write end of a pipe that the test closes. From 42a7590c3f6de1b66ac5254f16fc2d3e2a71dec0 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:15:36 +0000 Subject: [PATCH 26/32] libs/testserver: match MCP service names without regard to case Unity Catalog names are case-insensitive, and the fake's listing already matches them that way. The MCP endpoint looked the name up exactly, so a service addressed in another case got 404. Co-authored-by: Isaac --- libs/testserver/mcp_endpoint.go | 14 +++++++++++++- libs/testserver/mcp_endpoint_test.go | 10 ++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go index 92adfd45f91..eb8e694f592 100644 --- a/libs/testserver/mcp_endpoint.go +++ b/libs/testserver/mcp_endpoint.go @@ -3,6 +3,7 @@ package testserver import ( "encoding/json" "net/http" + "strings" "github.com/databricks/databricks-sdk-go/service/catalog" ) @@ -42,7 +43,7 @@ type mcpRPC struct { func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { defer s.LockUnlock()() - service, ok := s.McpServices[name] + service, ok := s.mcpServiceNamed(name) if !ok { return Response{StatusCode: http.StatusNotFound} } @@ -94,6 +95,17 @@ func (s *FakeWorkspace) McpEndpoint(req Request, name string) Response { } } +// mcpServiceNamed returns the stored service with the given full name. Unity Catalog names are case-insensitive, so the +// match ignores case, as McpServicesList does. +func (s *FakeWorkspace) mcpServiceNamed(name string) (catalog.McpService, bool) { + for key, service := range s.McpServices { + if strings.EqualFold(key, name) { + return service, true + } + } + return catalog.McpService{}, false +} + // mcpServiceIsExternal reports whether the service takes an OAuth source connection. func mcpServiceIsExternal(ms catalog.McpService) bool { return ms.Config != nil && ms.Config.SourceConnection != nil && diff --git a/libs/testserver/mcp_endpoint_test.go b/libs/testserver/mcp_endpoint_test.go index a227395dee1..eb1ff836165 100644 --- a/libs/testserver/mcp_endpoint_test.go +++ b/libs/testserver/mcp_endpoint_test.go @@ -36,6 +36,16 @@ func TestMcpEndpointAnswersInternalService(t *testing.T) { assert.Equal(t, "hi", content[0].(map[string]any)["text"]) } +// Unity Catalog names are case-insensitive, so the endpoint matches a service name whatever its case, as the listing does. +func TestMcpEndpointMatchesServiceNameWithoutCase(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") + + reply := mcpEndpointTestCall(t, workspace, "SYSTEM.AI.Genie_One_MCP", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`) + assert.Nil(t, reply["error"]) + assert.NotNil(t, reply["result"]) +} + func TestMcpEndpointRejectsExternalServiceWithoutCredential(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") const name = "system.ai.github" From 459756c88e7784016f323a7988b63080f2470f73 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:16:47 +0000 Subject: [PATCH 27/32] acceptance: check serve's stdout framing line by line jq -s also accepts pretty-printed or several-per-line JSON, so the passthrough test did not check that each stdout line is one message. The filter now reads each line with fromjson. The binding-errors steps send stderr to the script output, so each traced command, its stderr and its exit code appear in order in the golden. Co-authored-by: Isaac --- .../mcp/serve-binding-errors/output.txt | 12 ------------ .../aitools/mcp/serve-binding-errors/script | 18 ++++++------------ .../cmd/aitools/mcp/serve-passthrough/script | 9 ++++++--- 3 files changed, 12 insertions(+), 27 deletions(-) diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt index d5da631f49c..14931a34324 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/output.txt @@ -1,8 +1,6 @@ === The bound profile is not in the config file ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --profile gone --service system.ai.genie_one_mcp MCP server system.ai.genie_one_mcp needs Databricks profile "gone", which does not exist in [TEST_TMP_DIR]/.databrickscfg. Set it up with: databricks auth login --profile gone @@ -11,8 +9,6 @@ stdout bytes: 0 === The profile now points at another host than the one recorded ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp MCP server genie_one_mcp-logfood was set up for https://other.test, but profile "logfood" now points at [DATABRICKS_URL]. Run: databricks aitools mcp remove --names genie_one_mcp-logfood and add it again @@ -21,22 +17,16 @@ stdout bytes: 0 === Flags are required and validated before the binding checks ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --service system.ai.genie_one_mcp Error: --profile is required Exit code: 1 ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --profile logfood --service github Error: --service needs a full service name such as system.ai.github Exit code: 1 ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json Error: --output does not apply to serve: its stdout carries the MCP protocol @@ -44,8 +34,6 @@ Exit code: 1 === A log file on stdout is refused before anything is logged ->>> cat LOG.stderr - >>> errcode [CLI] aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug Error: databricks aitools mcp serve writes protocol messages to stdout, so its logs cannot go to stdout; use --log-file stderr or a file diff --git a/acceptance/cmd/aitools/mcp/serve-binding-errors/script b/acceptance/cmd/aitools/mcp/serve-binding-errors/script index 663645121f2..d4ff2c2bbfd 100644 --- a/acceptance/cmd/aitools/mcp/serve-binding-errors/script +++ b/acceptance/cmd/aitools/mcp/serve-binding-errors/script @@ -12,8 +12,7 @@ esac # Binding failures exit 2 with one message on stderr. Nothing reaches stdout, and stdin is not read. title "The bound profile is not in the config file" -trace errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr -trace cat LOG.stderr +trace errcode $CLI aitools mcp serve --profile gone --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" # A state record for logfood that points at another host: the proxy never follows the profile. @@ -42,20 +41,15 @@ cat > home/.databricks/aitools/skills/.state.json < LOG.stdout 2> LOG.stderr -trace cat LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" title "Flags are required and validated before the binding checks" -trace errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout 2> LOG.stderr -trace cat LOG.stderr -trace errcode $CLI aitools mcp serve --profile logfood --service github < requests.ndjson > LOG.stdout 2> LOG.stderr -trace cat LOG.stderr -trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout 2> LOG.stderr -trace cat LOG.stderr +trace errcode $CLI aitools mcp serve --service system.ai.genie_one_mcp < requests.ndjson > LOG.stdout +trace errcode $CLI aitools mcp serve --profile logfood --service github < requests.ndjson > LOG.stdout +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --output json < requests.ndjson > LOG.stdout # Logs and the stale-version warning never share stdout with the protocol, even at debug level. title "A log file on stdout is refused before anything is logged" -trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug < requests.ndjson > LOG.stdout 2> LOG.stderr -trace cat LOG.stderr +trace errcode $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --log-file stdout --log-level debug < requests.ndjson > LOG.stdout echo "stdout bytes: $(wc -c < LOG.stdout | tr -d ' ')" diff --git a/acceptance/cmd/aitools/mcp/serve-passthrough/script b/acceptance/cmd/aitools/mcp/serve-passthrough/script index c9536e2e1f2..9a16ce3999c 100644 --- a/acceptance/cmd/aitools/mcp/serve-passthrough/script +++ b/acceptance/cmd/aitools/mcp/serve-passthrough/script @@ -9,14 +9,17 @@ export DATABRICKS_HOST=https://elsewhere.test # The service the proxy serves, created in the fake workspace. The fake answers 404 for a service it does not have. MSYS_NO_PATHCONV=1 $CLI api post "/api/2.1/unity-catalog/mcp-services?parent=schemas/system.ai&mcp_service_id=genie_one_mcp" --profile logfood --json '{"comment": "Ask questions about your data"}' &> LOG.create-genie_one_mcp-logfood -# Responses may arrive in any order, so they are sorted by id. jq -s also fails when any stdout line is not JSON. +# Each stdout line must be one complete JSON value, so a pretty-printed or doubled-up message fails the filter. Responses +# may arrive in any order, so they are sorted by id. +frames='split("\n") | map(select(length > 0) | fromjson) | sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' + title "Stdout holds one JSON-RPC message per line; the notification gets no reply" -trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent claude-code < requests.ndjson 2> LOG.stderr | jq -Rsc "$frames" title "Diagnostics go to stderr only" trace cat LOG.stderr # An agent this binary does not know still serves; it is left out of the User-Agent, with one line on stderr. title "An agent this binary does not know is accepted" -trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent < requests.ndjson 2> LOG.future | jq -sc 'sort_by(.id)[] | {id, instructions: .result.instructions, tools: [.result.tools[]?.name], text: .result.content[0].text, error}' +trace $CLI aitools mcp serve --profile logfood --service system.ai.genie_one_mcp --agent future-agent < requests.ndjson 2> LOG.future | jq -Rsc "$frames" trace cat LOG.future From 00477df589c727e1a8f6e151913bbf582214d76d Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:19:06 +0000 Subject: [PATCH 28/32] cmd/aitools, cmd/root, libs/testserver: refactor serve tests and helpers No behavior change. The refresh-failure tests share one fake endpoint and one Authenticate, and the exit-with-status error is built by one helper. Stale-version skipping is one predicate, the refresh-failure messages are constants in the tests, and the two no-body endpoint tests are one table. Comments are trimmed to their reasons, test comments start with the test name, and the silent_err.go import is back to its original form. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 23 +-- cmd/aitools/mcp_serve_test.go | 212 +++++++++++++-------------- cmd/root/logger.go | 3 +- cmd/root/root.go | 5 +- cmd/root/silent_err.go | 4 +- cmd/root/stale_version.go | 13 +- cmd/root/stale_version_test.go | 9 +- cmd/root/stdout_protocol.go | 14 +- cmd/root/stdout_protocol_test.go | 8 +- libs/aitools/mcp/proxy/bridge.go | 5 +- libs/testserver/mcp_endpoint.go | 1 + libs/testserver/mcp_endpoint_test.go | 40 ++--- 12 files changed, 160 insertions(+), 177 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index 5d1780876f6..e04c6fdfb64 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -115,8 +115,8 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { }) } -// serveProxy bridges opts to the service until stdin closes or a signal arrives. opts.Authenticate is wrapped by a -// refreshGuard. A token that cannot be refreshed mid-session stops the proxy with serveBindStatus; see proxyResult. +// serveProxy bridges opts to the service until stdin closes or a signal arrives. Authenticate goes through a +// refreshGuard, so a refresh failure stops the proxy; see proxyResult. func serveProxy(cmd *cobra.Command, opts proxy.Options) error { ctx, stop := serveSignalContext(cmd.Context()) defer stop() @@ -125,13 +125,12 @@ func serveProxy(cmd *cobra.Command, opts proxy.Options) error { return proxyResult(cmd, refresh, proxy.Run(ctx, opts)) } -// proxyResult is the outcome of serve once the bridge has returned with runErr. A refresh failure wins over runErr: the -// stdin error that can follow a stopped session is a consequence of it. The bridge logs the failing request's error, -// but not when the client cancelled that request first, so the final line always says why the proxy stopped. +// proxyResult returns the outcome of serve once the bridge has returned with runErr. A refresh failure wins, since a +// stdin error after it is a consequence. The final line always names the failure, as the bridge may not have logged it. func proxyResult(cmd *cobra.Command, refresh *refreshGuard, runErr error) error { if refreshErr := refresh.failure(); refreshErr != nil { fmt.Fprintf(cmd.ErrOrStderr(), "stopped after a token refresh failure for profile %s\n", refresh.profile) - return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: serveBindStatus, Err: refreshErr}) + return exitAlreadyPrinted(refreshErr, serveBindStatus) } if runErr != nil { return serveFailure(cmd, runErr, 1) @@ -177,14 +176,18 @@ const serveBindStatus = 2 // so the message is written exactly once. func serveFailure(cmd *cobra.Command, err error, status int) error { fmt.Fprintln(cmd.ErrOrStderr(), err) + return exitAlreadyPrinted(err, status) +} + +// exitAlreadyPrinted returns err as an error that exits with status and that Execute does not print again. +func exitAlreadyPrinted(err error, status int) error { return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) } // refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed mid-session fails -// that request with an error that names the profile and its login command, then stops the proxy, so the command exits -// 2 and the next spawn re-runs the binding checks. Later requests fail at once, without asking for a token again. A -// request whose own context ended, which the client cancelled or shutdown ended, does not stop it. Nor does the -// session DELETE at shutdown, which is best effort: after a refresh failure it is skipped, as the session is over. +// that request with an error that names the profile and its login command, then stops the proxy, which exits 2. Later +// requests fail at once, without asking for a token again. A request whose own context ended does not stop it, nor +// does the session DELETE at shutdown, which is skipped after a refresh failure. type refreshGuard struct { authenticate func(*http.Request) error profile string diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index 47d85a85d38..ab9c257aa5e 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -34,7 +34,8 @@ func TestMcpServeIsHidden(t *testing.T) { assert.True(t, NewMcpServeCmd().Hidden) } -// The argv that `aitools mcp add` writes into an agent config parses with serve's flags. +// TestServeParsesArgvThatAddWrites checks that the argv that `aitools mcp add` writes into an agent config parses with +// serve's flags. func TestServeParsesArgvThatAddWrites(t *testing.T) { parent := newMCPTestRoot() serve, _, err := parent.Find([]string{"mcp", "serve"}) @@ -67,7 +68,7 @@ func TestRefreshGuardPassesThroughWhileTokensRefresh(t *testing.T) { func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { ctx, cancel := context.WithCancel(t.Context()) calls := 0 - cause := errors.New("refresh token expired") + cause := errors.New(refreshTokenExpired) g := &refreshGuard{ authenticate: func(*http.Request) error { calls++ @@ -80,16 +81,16 @@ func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { err := g.authenticateRequest(&http.Request{Header: http.Header{}}) require.Error(t, err) assert.ErrorIs(t, err, cause) - assert.Contains(t, err.Error(), "databricks auth login --profile logfood, then restart the MCP server in your agent") + assert.Contains(t, err.Error(), refreshLoginHint) assert.Equal(t, context.Canceled, ctx.Err()) assert.ErrorIs(t, g.failure(), cause) } -// After the first failure no request asks for a token again. Each later request fails at once with a short error that -// does not repeat the login hint. +// TestRefreshGuardStopsLaterRequestsWithoutAskingAgain checks that after the first failure no request asks for a token +// again. Each later request fails at once with a short error that does not repeat the login hint. func TestRefreshGuardStopsLaterRequestsWithoutAskingAgain(t *testing.T) { calls := 0 - cause := errors.New("refresh token expired") + cause := errors.New(refreshTokenExpired) g := &refreshGuard{ authenticate: func(*http.Request) error { calls++ @@ -107,10 +108,10 @@ func TestRefreshGuardStopsLaterRequestsWithoutAskingAgain(t *testing.T) { assert.ErrorIs(t, g.failure(), cause) } -// The refresh failure reaches the user as the AUTH_FAILED error, which names the profile and its login command -// and exits 2. +// TestRefreshGuardStoresAuthError checks that the refresh failure reaches the user as the AUTH_FAILED error, which names +// the profile and its login command. func TestRefreshGuardStoresAuthError(t *testing.T) { - cause := errors.New("refresh token expired") + cause := errors.New(refreshTokenExpired) g := &refreshGuard{ authenticate: func(*http.Request) error { return cause }, profile: "my profile", @@ -130,7 +131,7 @@ func TestServeFailurePrintsOnceWithStatus(t *testing.T) { cmd := NewMcpServeCmd() var stderr bytes.Buffer cmd.SetErr(&stderr) - cause := mcp.AuthError("logfood", errors.New("refresh token expired")) + cause := mcp.AuthError("logfood", errors.New(refreshTokenExpired)) err := serveFailure(cmd, cause, serveBindStatus) @@ -140,7 +141,8 @@ func TestServeFailurePrintsOnceWithStatus(t *testing.T) { assert.ErrorIs(t, err, cause) } -// The profile's insecure_skip_verify reaches the transport, and HTTP/2 is kept with it. +// TestServeTransportTLSVerification checks that the profile's insecure_skip_verify reaches the transport, and that +// HTTP/2 is kept with it. func TestServeTransportTLSVerification(t *testing.T) { tests := []struct { name string @@ -174,8 +176,8 @@ func TestServeTransportKeepsHTTP2WhenSkippingVerification(t *testing.T) { assert.Equal(t, 2, resp.ProtoMajor) } -// A request whose own context ended (the client cancelled it, or shutdown began) fails that request only: the -// token was not shown to be unusable. +// TestRefreshGuardIgnoresRequestThatEnded checks that a request whose own context ended (the client cancelled it, or +// shutdown began) fails that request only: the token was not shown to be unusable. func TestRefreshGuardIgnoresRequestThatEnded(t *testing.T) { cancelled := false g := &refreshGuard{ @@ -193,12 +195,12 @@ func TestRefreshGuardIgnoresRequestThatEnded(t *testing.T) { assert.False(t, cancelled) } -// The session DELETE at shutdown is best effort. Its auth failure is logged by the bridge, and a normal shutdown -// exits 0. +// TestRefreshGuardIgnoresSessionDelete checks that the session DELETE at shutdown is best effort. Its auth failure is +// logged by the bridge, and a normal shutdown exits 0. func TestRefreshGuardIgnoresSessionDelete(t *testing.T) { cancelled := false g := &refreshGuard{ - authenticate: func(*http.Request) error { return errors.New("refresh token expired") }, + authenticate: func(*http.Request) error { return errors.New(refreshTokenExpired) }, profile: "logfood", cancel: func() { cancelled = true }, } @@ -211,7 +213,8 @@ func TestRefreshGuardIgnoresSessionDelete(t *testing.T) { assert.False(t, cancelled) } -// An unknown agent is left out of the User-Agent and reported once on stderr, so the server still serves. +// TestServeAgentKeepsOnlyKnownAgents checks that an unknown agent is left out of the User-Agent and reported once on +// stderr, so the server still serves. func TestServeAgentKeepsOnlyKnownAgents(t *testing.T) { var stderr bytes.Buffer assert.Equal(t, "claude-code", serveAgent("claude-code", &stderr)) @@ -225,7 +228,8 @@ func TestServeAgentKeepsOnlyKnownAgents(t *testing.T) { assert.Empty(t, stderr.String()) } -// A service that is not a full three-part name is refused before any binding check, with the flag named. +// TestMcpServeRejectsServiceWithoutThreeParts checks that a service that is not a full three-part name is refused before +// any binding check, with the flag named. func TestMcpServeRejectsServiceWithoutThreeParts(t *testing.T) { withHome(t) for _, service := range []string{"github", "system.ai", "system..github", "a.b.c.d"} { @@ -239,7 +243,8 @@ func TestMcpServeRejectsServiceWithoutThreeParts(t *testing.T) { } } -// A state file that cannot be read stops the binding checks, so it exits 2 like the other binding failures. +// TestMcpServeStateReadFailureExitsTwo checks that a state file that cannot be read stops the binding checks, so it +// exits 2 like the other binding failures. func TestMcpServeStateReadFailureExitsTwo(t *testing.T) { withHome(t) dir, err := installer.GlobalSkillsDir(t.Context()) @@ -256,14 +261,15 @@ func TestMcpServeStateReadFailureExitsTwo(t *testing.T) { assert.Contains(t, stderr.String(), ".state.json") } -// After a refresh failure the session DELETE is skipped: the session is over, and a DELETE without a credential would -// fail and log the refresh error a second time. Authenticate is not asked. +// TestRefreshGuardSkipsSessionDeleteAfterFailure checks that after a refresh failure the session DELETE is skipped: the +// session is over, and a DELETE without a credential would fail and log the refresh error a second time. Authenticate is +// not asked. func TestRefreshGuardSkipsSessionDeleteAfterFailure(t *testing.T) { asked := 0 g := &refreshGuard{ authenticate: func(*http.Request) error { asked++ - return errors.New("refresh token expired") + return errors.New(refreshTokenExpired) }, profile: "logfood", cancel: func() {}, @@ -277,10 +283,11 @@ func TestRefreshGuardSkipsSessionDeleteAfterFailure(t *testing.T) { assert.Equal(t, 0, asked) } -// Once the bridge has returned, a refresh failure is the exit status and the final line, whatever Run returned. A -// stdin error that follows the failure is a consequence of it and is not reported. +// TestProxyResultRefreshFailureWinsOverStdinError checks that once the bridge has returned, a refresh failure is the exit +// status and the final line, whatever Run returned. A stdin error that follows the failure is a consequence of it and is +// not reported. func TestProxyResultRefreshFailureWinsOverStdinError(t *testing.T) { - cause := errors.New("refresh token expired") + cause := errors.New(refreshTokenExpired) g := &refreshGuard{ authenticate: func(*http.Request) error { return cause }, profile: "logfood", @@ -296,10 +303,11 @@ func TestProxyResultRefreshFailureWinsOverStdinError(t *testing.T) { assert.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, serveBindStatus, root.ExitStatus(err)) assert.ErrorIs(t, err, cause) - assert.Equal(t, "stopped after a token refresh failure for profile logfood\n", stderr.String()) + assert.Equal(t, refreshStoppedLine, stderr.String()) } -// Without a refresh failure, a stdin error is printed and exits 1. +// TestProxyResultReportsStdinErrorWithoutRefreshFailure checks that without a refresh failure, a stdin error is printed +// and exits 1. func TestProxyResultReportsStdinErrorWithoutRefreshFailure(t *testing.T) { g := &refreshGuard{profile: "logfood"} cmd := NewMcpServeCmd() @@ -312,11 +320,38 @@ func TestProxyResultReportsStdinErrorWithoutRefreshFailure(t *testing.T) { assert.Equal(t, "read stdin: input/output error\n", stderr.String()) } -// A token that expires mid-session fails the request that needs it. The bridge logs that failure once, with the -// profile and the login command; the proxy then exits 2 without printing it again, and the session DELETE at -// shutdown is still sent. -func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { - var deleted atomic.Bool +// The refresh failure fixtures: the cause that the fake token gives, the login hint that serve prints with it, and the +// final line that serve prints once the proxy has stopped. +const ( + refreshTokenExpired = "refresh token expired" + refreshLoginHint = "databricks auth login --profile logfood, then restart the MCP server in your agent" + refreshStoppedLine = "stopped after a token refresh failure for profile logfood\n" +) + +// expiresOnToolsList is an Authenticate whose token expires with the tools/list request, as a refresh token can +// mid-session. It reads the request body, so it answers POST requests only. +func expiresOnToolsList(r *http.Request) error { + if r.Method != http.MethodPost { + return nil + } + body, err := r.GetBody() + if err != nil { + return err + } + data, err := io.ReadAll(body) + body.Close() + if err != nil { + return err + } + if strings.Contains(string(data), `"tools/list"`) { + return errors.New(refreshTokenExpired) + } + return nil +} + +// newRefreshFailureServer is a fake endpoint that answers initialize. It sets deleted when it gets a session DELETE. +func newRefreshFailureServer(t *testing.T, deleted *atomic.Bool) *httptest.Server { + t.Helper() server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if r.Method == http.MethodDelete { deleted.Store(true) @@ -327,41 +362,23 @@ func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { w.Header().Set("Mcp-Session-Id", "session-1") fmt.Fprint(w, `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"fake","version":"1"}}}`) })) - defer server.Close() - - // The token expires with the tools/list request. From then on the session DELETE fails too, as an expired - // token would. - const refreshErr = "refresh token expired" - var expired atomic.Bool - authenticate := func(r *http.Request) error { - if r.Method != http.MethodPost { - if expired.Load() { - return errors.New(refreshErr) - } - return nil - } - body, err := r.GetBody() - if err != nil { - return err - } - data, err := io.ReadAll(body) - body.Close() - if err != nil { - return err - } - if strings.Contains(string(data), `"tools/list"`) { - expired.Store(true) - return errors.New(refreshErr) - } - return nil - } + t.Cleanup(server.Close) + return server +} +// runRefreshFailureSession serves an initialize and a tools/list whose token expires. Stdin ends with end, or closes +// cleanly when end is nil. It returns what serve printed to stderr, whether the endpoint got a session DELETE, and +// serve's error. +func runRefreshFailureSession(t *testing.T, end error) (string, bool, error) { + t.Helper() + var deleted atomic.Bool + server := newRefreshFailureServer(t, &deleted) var stderr bytes.Buffer var stdout lockedBuffer in := feedAfterAnswers(t, &stdout, []string{ `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, - }, nil) + }, end) cmd := NewMcpServeCmd() cmd.SetContext(t.Context()) cmd.SetErr(&stderr) @@ -371,16 +388,24 @@ func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { Err: &stderr, Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), Config: &config.Config{Host: server.URL}, - Authenticate: authenticate, + Authenticate: expiresOnToolsList, Profile: "logfood", }) + return stderr.String(), deleted.Load(), err +} + +// TestServeProxyRefreshFailurePrintsOnceAndExitsTwo checks that a token that expires mid-session fails the request that +// needs it. The bridge logs that failure once, with the profile and the login command. The proxy then exits 2 without +// printing it again, and sends no session DELETE at shutdown. +func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { + stderr, deleted, err := runRefreshFailureSession(t, nil) require.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) - assert.Equal(t, "databricks aitools mcp serve: upstream: refresh token expired\n"+ - "Run: databricks auth login --profile logfood, then restart the MCP server in your agent\n"+ - "stopped after a token refresh failure for profile logfood\n", stderr.String()) - assert.False(t, deleted.Load(), "no session DELETE is sent after a refresh failure") + assert.Equal(t, "databricks aitools mcp serve: upstream: "+refreshTokenExpired+"\n"+ + "Run: "+refreshLoginHint+"\n"+ + refreshStoppedLine, stderr) + assert.False(t, deleted, "no session DELETE is sent after a refresh failure") } // lockedBuffer collects what serve writes to stdout. The bridge writes from several goroutines. @@ -431,56 +456,15 @@ func feedAfterAnswers(t *testing.T, out *lockedBuffer, lines []string, end error return pr } -// A stdin error after the refresh failure does not change the exit status or the final line. +// TestServeProxyRefreshFailureWinsOverStdinError checks that a stdin error after the refresh failure does not change the +// exit status or the final line. func TestServeProxyRefreshFailureWinsOverStdinError(t *testing.T) { - server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "application/json") - w.Header().Set("Mcp-Session-Id", "session-1") - fmt.Fprint(w, `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"fake","version":"1"}}}`) - })) - defer server.Close() - - authenticate := func(r *http.Request) error { - if r.Method != http.MethodPost { - return nil - } - body, err := r.GetBody() - if err != nil { - return err - } - data, err := io.ReadAll(body) - body.Close() - if err != nil { - return err - } - if strings.Contains(string(data), `"tools/list"`) { - return errors.New("refresh token expired") - } - return nil - } - var stderr bytes.Buffer - var stdout lockedBuffer - in := feedAfterAnswers(t, &stdout, []string{ - `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, - `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, - }, errors.New("input/output error")) - cmd := NewMcpServeCmd() - cmd.SetContext(t.Context()) - cmd.SetErr(&stderr) - err := serveProxy(cmd, proxy.Options{ - In: in, - Out: &stdout, - Err: &stderr, - Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), - Config: &config.Config{Host: server.URL}, - Authenticate: authenticate, - Profile: "logfood", - }) + stderr, _, err := runRefreshFailureSession(t, errors.New("input/output error")) require.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) - assert.NotContains(t, stderr.String(), "input/output error") - assert.True(t, strings.HasSuffix(stderr.String(), "stopped after a token refresh failure for profile logfood\n"), stderr.String()) + assert.NotContains(t, stderr, "input/output error") + assert.True(t, strings.HasSuffix(stderr, refreshStoppedLine), stderr) } // signalHelperEnv marks the child process that TestServeSecondSignalEndsProcess starts. @@ -500,8 +484,8 @@ func TestServeSignalHelper(t *testing.T) { time.Sleep(time.Minute) } -// The first signal cancels the context and the second one ends the process. A second signal that the handler -// swallowed during shutdown would leave the child running until the timeout. +// TestServeSecondSignalEndsProcess checks that the first signal cancels the context and the second one ends the +// process. A second signal that the handler swallowed during shutdown would leave the child running until the timeout. func TestServeSecondSignalEndsProcess(t *testing.T) { if runtime.GOOS == "windows" { t.Skip("Process.Signal cannot send SIGINT on Windows") diff --git a/cmd/root/logger.go b/cmd/root/logger.go index 90a1d4ce4dd..89dfd021af2 100644 --- a/cmd/root/logger.go +++ b/cmd/root/logger.go @@ -60,8 +60,7 @@ func (s *logFileSlot) close() { } // initializeContext opens the log file and installs the default logger. For a command whose stdout carries a protocol, -// it refuses a log file that is stdout. That check runs before the logger is installed, so nothing reaches stdout, -// not even the telemetry upload that follows a refused command. +// it refuses a log file on stdout before the logger is installed, so not even a refused command's telemetry reaches stdout. func (f *logFlags) initializeContext(ctx context.Context, cmd *cobra.Command) (context.Context, error) { if f.debug { err := f.level.Set("debug") diff --git a/cmd/root/root.go b/cmd/root/root.go index 3c0b188ab92..28c80e29d85 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -156,9 +156,8 @@ Stack Trace: startTime := time.Now() - // initializeContext puts the log file it opens in this slot. When Execute returns, whether the command returned or - // panicked, the file is closed after the last log line, and the default logger that was in place is restored, so - // nothing writes to the closed file. + // initializeContext puts the log file it opens in this slot. It is closed when Execute returns, even on a panic, and + // the loggers are restored, so nothing writes to the closed file. var logFile logFileSlot ctx = context.WithValue(ctx, logFileKey{}, &logFile) // slog.SetDefault also redirects the standard log package, so both are restored. diff --git a/cmd/root/silent_err.go b/cmd/root/silent_err.go index 4bdf0566467..7898678b447 100644 --- a/cmd/root/silent_err.go +++ b/cmd/root/silent_err.go @@ -1,8 +1,6 @@ package root -import ( - "errors" -) +import "errors" // ErrAlreadyPrinted is not printed to the user. It's used to signal that the command should exit with an error, // but the error message was already printed. diff --git a/cmd/root/stale_version.go b/cmd/root/stale_version.go index 81ea6f6ec25..727620841df 100644 --- a/cmd/root/stale_version.go +++ b/cmd/root/stale_version.go @@ -32,20 +32,15 @@ func staleVersionWarning(buildTime, now time.Time, upgradeCommand string) string return msg + "See " + InstallDocsURL + " to upgrade.\n" } -func skipStaleVersionWarning(ctx context.Context, info build.Info) bool { - if info.IsDevelopment() { +// staleVersionSkipped reports whether cmd gets no stale-version warning. A command whose stdout carries a protocol never +// gets one, nor does a development build, nor a CLI on DBR, which installs the latest version by default. +func staleVersionSkipped(ctx context.Context, cmd *cobra.Command, info build.Info) bool { + if carriesProtocol(cmd) || info.IsDevelopment() { return true } - // DBR installs the latest CLI by default, so skip the warning there. return dbr.HasDetection(ctx) && dbr.RunsOnRuntime(ctx) } -// staleVersionSkipped reports whether cmd gets no stale-version warning: a command whose stdout carries a protocol -// never does, and neither does a build that skipStaleVersionWarning skips. -func staleVersionSkipped(ctx context.Context, cmd *cobra.Command, info build.Info) bool { - return carriesProtocol(cmd) || skipStaleVersionWarning(ctx, info) -} - func warnIfStaleVersion(ctx context.Context, cmd *cobra.Command) { info := build.GetInfo() if staleVersionSkipped(ctx, cmd, info) { diff --git a/cmd/root/stale_version_test.go b/cmd/root/stale_version_test.go index d17379e6252..0d438b84068 100644 --- a/cmd/root/stale_version_test.go +++ b/cmd/root/stale_version_test.go @@ -44,7 +44,7 @@ func TestStaleVersionWarning(t *testing.T) { } } -func TestSkipStaleVersionWarning(t *testing.T) { +func TestStaleVersionSkipped(t *testing.T) { release := build.Info{Version: "1.18.0"} notDBR := dbr.Environment{} @@ -62,13 +62,14 @@ func TestSkipStaleVersionWarning(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { ctx := dbr.MockRuntime(t.Context(), tc.runtime) - assert.Equal(t, tc.want, skipStaleVersionWarning(ctx, tc.info)) + assert.Equal(t, tc.want, staleVersionSkipped(ctx, &cobra.Command{Use: "list"}, tc.info)) }) } } -// A command whose stdout carries a protocol gets no stale-version warning, even on a stale build. The warning goes to -// stderr, but an agent shows the server's stderr every time it starts the server. +// TestStaleVersionSkippedForProtocolCommand checks that a command whose stdout carries a protocol gets no stale-version +// warning, even on a stale build. The warning goes to stderr, but an agent shows the server's stderr every time it starts +// the server. func TestStaleVersionSkippedForProtocolCommand(t *testing.T) { ctx := dbr.MockRuntime(t.Context(), dbr.Environment{}) release := build.Info{Version: "1.18.0"} diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index 19b54270c9a..114b44be993 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -8,9 +8,8 @@ import ( ) // StdoutCarriesProtocol is the cobra annotation of a command whose stdout carries a protocol, such as MCP JSON-RPC -// messages, so nothing else may be written there. Root refuses a log file on stdout for such a command, and it skips -// the stale-version warning. That warning goes to stderr, but an agent shows the server's stderr each time it starts -// the server, so the warning would repeat in every session. +// messages. Root refuses a log file on stdout for such a command and skips the stale-version warning, which an agent +// would show in every session. const StdoutCarriesProtocol = "stdout-carries-protocol" // carriesProtocol reports whether cmd is annotated with StdoutCarriesProtocol. @@ -19,12 +18,11 @@ func carriesProtocol(cmd *cobra.Command) bool { return ok } -// writesToStdout reports whether w is stdout, given the process's stdout and stderr. It compares the open file, not a -// path: on macOS, os.Stat of /dev/stdout does not match stdout when stdout is a pipe, but the opened /dev/stdout does. -// The streams are parameters because under `go test -json` the testing package sets os.Stderr to os.Stdout. +// writesToStdout reports whether w is the open stdout file. It compares files, not paths: on macOS a stat of +// /dev/stdout does not match a stdout pipe, but the opened /dev/stdout does. The streams are parameters so tests can +// pass their own, since under `go test -json` os.Stderr is os.Stdout. // -// A file that is also stderr is not stdout. When stdout and stderr are one file, as on a terminal, the protocol -// already shares it with the diagnostics, so the check cannot help and the log file is allowed. +// A file that is also stderr is not stdout, because one terminal file carries both diagnostics and protocol. func writesToStdout(w io.Writer, stdout, stderr *os.File) bool { f, ok := w.(*os.File) if !ok || f == stderr { diff --git a/cmd/root/stdout_protocol_test.go b/cmd/root/stdout_protocol_test.go index def6f8df332..67c66ae2f10 100644 --- a/cmd/root/stdout_protocol_test.go +++ b/cmd/root/stdout_protocol_test.go @@ -115,8 +115,8 @@ func TestExecuteAllowsFileLogForProtocolCommand(t *testing.T) { assert.True(t, ran) } -// writesToStdout compares the log file with the stdout and stderr it is given, so a path that is stdout under -// another name is refused. stderr is never refused. The streams are pipes of the test's own, not the process's. +// TestWritesToStdout checks that a path that is stdout under another name is refused. stderr is never refused. The +// streams are pipes of the test's own, not the process's. func TestWritesToStdout(t *testing.T) { stdout := newPipe(t) stderr := newPipe(t) @@ -148,8 +148,8 @@ func TestWritesToStdout(t *testing.T) { } } -// When stdout and stderr are one file, as on a terminal, a log file that is that file is not refused: the protocol -// already shares it with the diagnostics. A second handle to it is that file, so it is not refused either. +// TestWritesToStdoutAllowsStderrFile checks that when stdout and stderr are one file, as on a terminal, a log file that +// is that file is not refused: the protocol already shares it with the diagnostics. A second handle to it is that file. func TestWritesToStdoutAllowsStderrFile(t *testing.T) { path := filepath.Join(t.TempDir(), "terminal.txt") shared, err := os.Create(path) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index 3946624de63..5e22aa33bfa 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -51,9 +51,8 @@ var ( errNoResponse = errors.New("upstream sent no response") // errUpstreamTooLarge is the error for an upstream message over maxLineBytes, whether it is a body or an event. errUpstreamTooLarge = fmt.Errorf("an upstream message exceeds the %d MiB limit", maxLineBytes>>20) - // ErrSkipRequest is returned by Authenticate to leave the session DELETE unsent: the bridge neither sends nor logs - // it. The DELETE is the only request that needs no answer. Any other request that returns it is an error like any - // other. + // ErrSkipRequest is returned by Authenticate to leave the session DELETE unsent, which needs no answer. Any other + // request that returns it fails like any other. ErrSkipRequest = errors.New("request skipped") ) diff --git a/libs/testserver/mcp_endpoint.go b/libs/testserver/mcp_endpoint.go index eb8e694f592..52b600370b1 100644 --- a/libs/testserver/mcp_endpoint.go +++ b/libs/testserver/mcp_endpoint.go @@ -126,6 +126,7 @@ func rpcError(id json.RawMessage, code int, message string) map[string]any { } } +// signInRequired is the answer to a request for an external service, which the gateway gives before sign-in. func signInRequired(id json.RawMessage) Response { return Response{Body: rpcError(id, rpcCodeSignInRequired, "The MCP service request was rejected (HTTP 401). Sign-in is required.")} diff --git a/libs/testserver/mcp_endpoint_test.go b/libs/testserver/mcp_endpoint_test.go index eb1ff836165..8c17f3ca621 100644 --- a/libs/testserver/mcp_endpoint_test.go +++ b/libs/testserver/mcp_endpoint_test.go @@ -36,7 +36,8 @@ func TestMcpEndpointAnswersInternalService(t *testing.T) { assert.Equal(t, "hi", content[0].(map[string]any)["text"]) } -// Unity Catalog names are case-insensitive, so the endpoint matches a service name whatever its case, as the listing does. +// TestMcpEndpointMatchesServiceNameWithoutCase checks that the endpoint matches a service name whatever its case, as +// Unity Catalog names are case-insensitive and the listing already matches them that way. func TestMcpEndpointMatchesServiceNameWithoutCase(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") @@ -57,7 +58,8 @@ func TestMcpEndpointRejectsExternalServiceWithoutCredential(t *testing.T) { assert.Nil(t, reply["result"]) } -// A service the fake does not have is 404, as the gateway answers a name that no service has, whatever the message. +// TestMcpEndpointUnknownServiceIsNotFound checks that a name no service has is 404, whatever the message. The name is +// one letter short of the seeded service, so it also shows that the endpoint matches whole names, not prefixes. func TestMcpEndpointUnknownServiceIsNotFound(t *testing.T) { workspace := NewFakeWorkspace("http://test", "dbapi123") mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") @@ -72,19 +74,23 @@ func TestMcpEndpointUnknownServiceIsNotFound(t *testing.T) { } } -func TestMcpEndpointNotificationGetsNoBody(t *testing.T) { - workspace := NewFakeWorkspace("http://test", "dbapi123") - mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") - response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","method":"notifications/initialized"}`)}, "system.ai.genie_one_mcp") - assert.Equal(t, 202, response.StatusCode) - assert.Nil(t, response.Body) -} - -// A client's answer to a request from the server has an id and no method. It is not a request, so it gets 202 with no body. -func TestMcpEndpointClientResponseGetsNoBody(t *testing.T) { - workspace := NewFakeWorkspace("http://test", "dbapi123") - mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") - response := workspace.McpEndpoint(Request{Body: []byte(`{"jsonrpc":"2.0","id":7,"result":{}}`)}, "system.ai.genie_one_mcp") - assert.Equal(t, 202, response.StatusCode) - assert.Nil(t, response.Body) +// TestMcpEndpointNoBodyForNotificationsAndResponses checks that a notification, and a client's answer to a request from +// the server (an id and no method), get 202 with no body. +func TestMcpEndpointNoBodyForNotificationsAndResponses(t *testing.T) { + tests := []struct { + name string + body string + }{ + {name: "notification", body: `{"jsonrpc":"2.0","method":"notifications/initialized"}`}, + {name: "client response", body: `{"jsonrpc":"2.0","id":7,"result":{}}`}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") + response := workspace.McpEndpoint(Request{Body: []byte(tc.body)}, "system.ai.genie_one_mcp") + assert.Equal(t, 202, response.StatusCode) + assert.Nil(t, response.Body) + }) + } } From 765535273e1ca2b333b6fdf2df4bc173d15dac37 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:19:30 +0000 Subject: [PATCH 29/32] cmd/aitools, cmd/root: document serve's binding limitation and the Windows console case serve checks its binding only at start. A profile re-pointed to another host during the session keeps receiving the endpoint of the bound host, so that is documented on the command. The refresh hint's restart is needed because a new spawn re-runs the binding checks. The stdout check treats a Windows console as a file that is not stdout, so `--log-file stdout` is refused there even in a terminal. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 7 ++++++- cmd/root/stdout_protocol.go | 4 +++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index e04c6fdfb64..f04920c5615 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -50,6 +50,10 @@ type mcpServeFlags struct { // NewMcpServeCmd returns the hidden `aitools mcp serve`: the stdio MCP proxy an agent starts for one // installed server. Its stdout carries only JSON-RPC messages; every diagnostic goes to stderr. +// +// Known limitation: the binding is checked only when serve starts. If the profile is pointed at another host during +// the session, for example by `databricks auth login --profile P --host B`, serve keeps sending the profile's token, +// which is now B's, to the endpoint of the host it was bound to. func NewMcpServeCmd() *cobra.Command { var f mcpServeFlags cmd := &cobra.Command{ @@ -212,7 +216,8 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { if r.Context().Err() != nil || r.Method == http.MethodDelete { return err } - // The hint says to restart the server, since the next spawn is what picks up the new login. + // The hint says to restart the server: a new spawn re-runs the binding checks, and it is the one that picks up the + // new login. authErr := fmt.Errorf("%w, then restart the MCP server in your agent", mcp.AuthError(g.profile, err)) g.mu.Lock() first := g.err == nil diff --git a/cmd/root/stdout_protocol.go b/cmd/root/stdout_protocol.go index 114b44be993..528ce78318a 100644 --- a/cmd/root/stdout_protocol.go +++ b/cmd/root/stdout_protocol.go @@ -22,7 +22,9 @@ func carriesProtocol(cmd *cobra.Command) bool { // /dev/stdout does not match a stdout pipe, but the opened /dev/stdout does. The streams are parameters so tests can // pass their own, since under `go test -json` os.Stderr is os.Stdout. // -// A file that is also stderr is not stdout, because one terminal file carries both diagnostics and protocol. +// A file that is also stderr is not stdout, because one terminal file carries both diagnostics and protocol. That holds +// on Unix only. On Windows a console is not a regular file, so sameFileInfo never matches it, and `--log-file stdout` +// is refused even in a terminal. func writesToStdout(w io.Writer, stdout, stderr *os.File) bool { f, ok := w.(*os.File) if !ok || f == stderr { From da97402e8e5be8fa169e53a301d2e674f536e799 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 02:22:33 +0000 Subject: [PATCH 30/32] cmd/root: allow the standard log import in the logger restore depguard forbids the standard log package outside a few generators. The import is needed here because slog.SetDefault redirects that package, and libs/log has no way to restore it. The exception is annotated where it is used. Co-authored-by: Isaac --- cmd/root/root.go | 2 +- cmd/root/root_test.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cmd/root/root.go b/cmd/root/root.go index 28c80e29d85..064f8771990 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -4,7 +4,7 @@ import ( "context" "errors" "fmt" - stdlog "log" + stdlog "log" //nolint:depguard // slog.SetDefault redirects the standard log package, and Execute restores it "log/slog" "os" "runtime" diff --git a/cmd/root/root_test.go b/cmd/root/root_test.go index dc57f76068b..b4e68f32097 100644 --- a/cmd/root/root_test.go +++ b/cmd/root/root_test.go @@ -6,7 +6,7 @@ import ( "encoding/json" "errors" "io" - stdlog "log" + stdlog "log" //nolint:depguard // checks the standard log package that slog.SetDefault redirects "os" "path/filepath" "strings" From 16ba1c0388c13e4e500a9d75dfd750a9e07e18ca Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 07:10:38 +0000 Subject: [PATCH 31/32] aitools mcp serve: fail only the request on a transient token failure Serve stopped on any token refresh failure. A network error, a timeout or a 5xx from the token endpoint is not a credential the user must replace, so serve now fails only the request that needed the token, with the login hint, and keeps serving. The next request asks for a token again. A failure stops serve only when the token is rejected: the token endpoint answers 400 or 401 with invalid_grant or invalid_client, or the U2M client reports an invalid refresh token. Anything else is transient, including errors that cannot be classified. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 57 +++++++-- cmd/aitools/mcp_serve_test.go | 223 +++++++++++++++++++++++++++++++--- 2 files changed, 258 insertions(+), 22 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index f04920c5615..b9f042add2b 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -3,6 +3,7 @@ package aitools import ( "context" "crypto/tls" + "encoding/json" "errors" "fmt" "io" @@ -20,8 +21,11 @@ import ( "github.com/databricks/cli/libs/aitools/mcp" "github.com/databricks/cli/libs/aitools/mcp/proxy" "github.com/databricks/cli/libs/aitools/mcpconfig" + "github.com/databricks/cli/libs/auth/u2m" "github.com/databricks/databricks-sdk-go/config" + "github.com/databricks/databricks-sdk-go/httpclient" "github.com/spf13/cobra" + "golang.org/x/oauth2" ) // serveConnectTimeout bounds one upstream connect. http.DefaultTransport waits 30 s. @@ -120,7 +124,7 @@ func runMcpServe(cmd *cobra.Command, f mcpServeFlags) error { } // serveProxy bridges opts to the service until stdin closes or a signal arrives. Authenticate goes through a -// refreshGuard, so a refresh failure stops the proxy; see proxyResult. +// refreshGuard, so a rejected token stops the proxy; see proxyResult. func serveProxy(cmd *cobra.Command, opts proxy.Options) error { ctx, stop := serveSignalContext(cmd.Context()) defer stop() @@ -129,8 +133,8 @@ func serveProxy(cmd *cobra.Command, opts proxy.Options) error { return proxyResult(cmd, refresh, proxy.Run(ctx, opts)) } -// proxyResult returns the outcome of serve once the bridge has returned with runErr. A refresh failure wins, since a -// stdin error after it is a consequence. The final line always names the failure, as the bridge may not have logged it. +// proxyResult returns the outcome of serve once the bridge has returned with runErr. A rejected token wins, since a +// stdin error after it is a consequence. The final line always names the rejection, as the bridge may not have logged it. func proxyResult(cmd *cobra.Command, refresh *refreshGuard, runErr error) error { if refreshErr := refresh.failure(); refreshErr != nil { fmt.Fprintf(cmd.ErrOrStderr(), "stopped after a token refresh failure for profile %s\n", refresh.profile) @@ -188,10 +192,11 @@ func exitAlreadyPrinted(err error, status int) error { return errors.Join(root.ErrAlreadyPrinted, &root.ExitStatusError{Status: status, Err: err}) } -// refreshGuard wraps the profile's authenticate for the bridge. A token that cannot be refreshed mid-session fails -// that request with an error that names the profile and its login command, then stops the proxy, which exits 2. Later -// requests fail at once, without asking for a token again. A request whose own context ended does not stop it, nor -// does the session DELETE at shutdown, which is skipped after a refresh failure. +// refreshGuard wraps the profile's authenticate for the bridge. A rejected token (see credentialRejected) fails that +// request with an error that names the profile and its login command, then stops the proxy, which exits 2. Later +// requests fail at once, without asking for a token again. A transient failure fails only its request, and the next +// request asks for a token again. A request whose own context ended does not stop it, nor does the session DELETE at +// shutdown, which is skipped after a rejection. type refreshGuard struct { authenticate func(*http.Request) error profile string @@ -216,6 +221,10 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { if r.Context().Err() != nil || r.Method == http.MethodDelete { return err } + if !credentialRejected(err) { + // Serve keeps running and the next request asks for a token again, so the hint does not say to restart. + return mcp.AuthError(g.profile, err) + } // The hint says to restart the server: a new spawn re-runs the binding checks, and it is the one that picks up the // new login. authErr := fmt.Errorf("%w, then restart the MCP server in your agent", mcp.AuthError(g.profile, err)) @@ -237,9 +246,41 @@ func (g *refreshGuard) stoppedError() error { return fmt.Errorf("the session is stopping after a token refresh failure for profile %s", g.profile) } -// failure returns the first refresh error, or nil when every token was refreshed. +// failure returns the first rejection, or nil while no token has been rejected. func (g *refreshGuard) failure() error { g.mu.Lock() defer g.mu.Unlock() return g.err } + +// credentialRejected reports whether a token failure is one that a new login fixes. That is the CLI's U2M reporting an +// invalid refresh token, or a token endpoint that answers 400 or 401 with the RFC 6749 section 5.2 error invalid_grant +// or invalid_client. Everything else is transient and returns false: network errors, timeouts, 5xx responses, and +// any error this check cannot classify. A transient failure is retried by the next request. +func credentialRejected(err error) bool { + if _, ok := errors.AsType[*u2m.InvalidRefreshTokenError](err); ok { + return true + } + // The CLI's U2M client returns an *httpclient.HttpError for an error response, with the response body as its message. + if httpErr, ok := errors.AsType[*httpclient.HttpError](err); ok { + var body struct { + Error string `json:"error"` + } + if json.Unmarshal([]byte(httpErr.Message), &body) != nil { + return false + } + return rejectedOAuthError(httpErr.StatusCode, body.Error) + } + // golang.org/x/oauth2 returns this for an error response from its own HTTP client. It always sets Response. + if retrieveErr, ok := errors.AsType[*oauth2.RetrieveError](err); ok { + return rejectedOAuthError(retrieveErr.Response.StatusCode, retrieveErr.ErrorCode) + } + return false +} + +// rejectedOAuthError reports whether a token endpoint's error response, with its HTTP status and RFC 6749 error code, +// is a rejection. +func rejectedOAuthError(status int, code string) bool { + return (status == http.StatusBadRequest || status == http.StatusUnauthorized) && + (code == "invalid_grant" || code == "invalid_client") +} diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index ab9c257aa5e..a08bf9b959a 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -4,6 +4,7 @@ import ( "bufio" "bytes" "context" + "encoding/json" "errors" "fmt" "io" @@ -26,8 +27,10 @@ import ( "github.com/databricks/cli/libs/aitools/mcpconfig" "github.com/databricks/cli/libs/cmdio" "github.com/databricks/databricks-sdk-go/config" + "github.com/databricks/databricks-sdk-go/httpclient" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "golang.org/x/oauth2" ) func TestMcpServeIsHidden(t *testing.T) { @@ -68,7 +71,7 @@ func TestRefreshGuardPassesThroughWhileTokensRefresh(t *testing.T) { func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { ctx, cancel := context.WithCancel(t.Context()) calls := 0 - cause := errors.New(refreshTokenExpired) + cause := refreshRejected g := &refreshGuard{ authenticate: func(*http.Request) error { calls++ @@ -90,7 +93,7 @@ func TestRefreshGuardStopsProxyOnFirstFailure(t *testing.T) { // again. Each later request fails at once with a short error that does not repeat the login hint. func TestRefreshGuardStopsLaterRequestsWithoutAskingAgain(t *testing.T) { calls := 0 - cause := errors.New(refreshTokenExpired) + cause := refreshRejected g := &refreshGuard{ authenticate: func(*http.Request) error { calls++ @@ -111,7 +114,7 @@ func TestRefreshGuardStopsLaterRequestsWithoutAskingAgain(t *testing.T) { // TestRefreshGuardStoresAuthError checks that the refresh failure reaches the user as the AUTH_FAILED error, which names // the profile and its login command. func TestRefreshGuardStoresAuthError(t *testing.T) { - cause := errors.New(refreshTokenExpired) + cause := refreshRejected g := &refreshGuard{ authenticate: func(*http.Request) error { return cause }, profile: "my profile", @@ -127,6 +130,68 @@ func TestRefreshGuardStoresAuthError(t *testing.T) { assert.Contains(t, be.Error(), "databricks auth login --profile 'my profile'") } +// TestRefreshGuardTransientFailureFailsOnlyThatRequest checks that a token failure which is not a rejection fails that +// request with the login hint and nothing else. The proxy keeps running, and the next request asks for a token again. +func TestRefreshGuardTransientFailureFailsOnlyThatRequest(t *testing.T) { + cancelled := false + asked := 0 + transient := errors.New("dial tcp: i/o timeout") + g := &refreshGuard{ + authenticate: func(*http.Request) error { + asked++ + if asked == 1 { + return transient + } + return nil + }, + profile: "logfood", + cancel: func() { cancelled = true }, + } + + err := g.authenticateRequest(&http.Request{Header: http.Header{}}) + + require.Error(t, err) + assert.ErrorIs(t, err, transient) + assert.Contains(t, err.Error(), "databricks auth login --profile logfood") + assert.NotContains(t, err.Error(), "restart") + assert.NoError(t, g.failure()) + assert.False(t, cancelled) + assert.NoError(t, g.authenticateRequest(&http.Request{Header: http.Header{}})) + assert.Equal(t, 2, asked) +} + +// TestCredentialRejected checks which token failures stop the proxy. A rejection is one that a new login fixes. Every +// other failure is transient, including the ones this check cannot classify. +func TestCredentialRejected(t *testing.T) { + oauthResponse := func(status int, body string) error { + return &httpclient.HttpError{Response: &http.Response{StatusCode: status}, Message: body} + } + tests := []struct { + name string + err error + want bool + }{ + {name: "refresh rejected, golang.org/x/oauth2 error", err: refreshRejected, want: true}, + {name: "invalid_client with 401", err: &oauth2.RetrieveError{Response: &http.Response{StatusCode: http.StatusUnauthorized}, ErrorCode: "invalid_client"}, want: true}, + {name: "invalid_grant with 500", err: &oauth2.RetrieveError{Response: &http.Response{StatusCode: http.StatusInternalServerError}, ErrorCode: "invalid_grant"}, want: false}, + {name: "server_error with 400", err: &oauth2.RetrieveError{Response: &http.Response{StatusCode: http.StatusBadRequest}, ErrorCode: "server_error"}, want: false}, + {name: "oauth2 response without an error code", err: &oauth2.RetrieveError{Response: &http.Response{StatusCode: http.StatusBadRequest}, Body: []byte("")}, want: false}, + {name: "HTTP invalid_grant with 400", err: oauthResponse(400, `{"error":"invalid_grant","error_description":"Refresh token has expired"}`), want: true}, + {name: "HTTP invalid_client with 401", err: oauthResponse(401, `{"error":"invalid_client"}`), want: true}, + {name: "HTTP invalid_grant, wrapped", err: fmt.Errorf("token refresh: %w", oauthResponse(400, `{"error":"invalid_grant"}`)), want: true}, + {name: "HTTP invalid_grant with 503", err: oauthResponse(503, `{"error":"invalid_grant"}`), want: false}, + {name: "HTTP invalid_request with 400", err: oauthResponse(400, `{"error":"invalid_request"}`), want: false}, + {name: "HTTP body is not JSON", err: oauthResponse(400, "Bad Gateway"), want: false}, + {name: "network error", err: errors.New("dial tcp: i/o timeout"), want: false}, + {name: "deadline exceeded", err: context.DeadlineExceeded, want: false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, tc.want, credentialRejected(tc.err)) + }) + } +} + func TestServeFailurePrintsOnceWithStatus(t *testing.T) { cmd := NewMcpServeCmd() var stderr bytes.Buffer @@ -269,7 +334,7 @@ func TestRefreshGuardSkipsSessionDeleteAfterFailure(t *testing.T) { g := &refreshGuard{ authenticate: func(*http.Request) error { asked++ - return errors.New(refreshTokenExpired) + return refreshRejected }, profile: "logfood", cancel: func() {}, @@ -287,7 +352,7 @@ func TestRefreshGuardSkipsSessionDeleteAfterFailure(t *testing.T) { // status and the final line, whatever Run returned. A stdin error that follows the failure is a consequence of it and is // not reported. func TestProxyResultRefreshFailureWinsOverStdinError(t *testing.T) { - cause := errors.New(refreshTokenExpired) + cause := refreshRejected g := &refreshGuard{ authenticate: func(*http.Request) error { return cause }, profile: "logfood", @@ -328,25 +393,155 @@ const ( refreshStoppedLine = "stopped after a token refresh failure for profile logfood\n" ) -// expiresOnToolsList is an Authenticate whose token expires with the tools/list request, as a refresh token can -// mid-session. It reads the request body, so it answers POST requests only. -func expiresOnToolsList(r *http.Request) error { +// refreshRejected is the error of a refresh that the token endpoint rejects, which a new login fixes. It is the shape +// the SDK's client returns for an error response from golang.org/x/oauth2. +var refreshRejected = &oauth2.RetrieveError{ + Response: &http.Response{StatusCode: http.StatusBadRequest}, + ErrorCode: "invalid_grant", + ErrorDescription: refreshTokenExpired, +} + +// isToolsList reports whether r is a tools/list POST. It reads a copy of the body, so it is for Authenticate only. +func isToolsList(r *http.Request) (bool, error) { if r.Method != http.MethodPost { - return nil + return false, nil } body, err := r.GetBody() if err != nil { - return err + return false, err } data, err := io.ReadAll(body) body.Close() if err != nil { + return false, err + } + return strings.Contains(string(data), `"tools/list"`), nil +} + +// expiresOnToolsList is an Authenticate whose token expires with the tools/list request, as a refresh token can +// mid-session. +func expiresOnToolsList(r *http.Request) error { + listed, err := isToolsList(r) + if err != nil || !listed { return err } - if strings.Contains(string(data), `"tools/list"`) { - return errors.New(refreshTokenExpired) + return refreshRejected +} + +// failsToolsListOnce is an Authenticate whose first tools/list fails with err. Later calls succeed, as they do once the +// token endpoint is back. +func failsToolsListOnce(err error) func(*http.Request) error { + var failed atomic.Bool + return func(r *http.Request) error { + listed, readErr := isToolsList(r) + if readErr != nil { + return readErr + } + if listed && failed.CompareAndSwap(false, true) { + return err + } + return nil } - return nil +} + +// newEchoMCPServer is a fake endpoint that answers each request with its own id. Its initialize answer sets a session ID, +// so the session DELETE at shutdown is sent. +func newEchoMCPServer(t *testing.T) *httptest.Server { + t.Helper() + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + w.WriteHeader(http.StatusOK) + return + } + var msg struct { + ID json.RawMessage `json:"id"` + Method string `json:"method"` + } + if err := json.NewDecoder(r.Body).Decode(&msg); err != nil { + w.WriteHeader(http.StatusBadRequest) + return + } + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Mcp-Session-Id", "session-1") + result := `{"tools":[]}` + if msg.Method == "initialize" { + result = `{"protocolVersion":"2025-06-18","capabilities":{},"serverInfo":{"name":"fake","version":"1"}}` + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":%s}`, msg.ID, result) + })) + t.Cleanup(server.Close) + return server +} + +// TestServeProxyTransientRefreshFailureKeepsServing checks that a token failure which is not a rejection fails only the +// request that needed the token. The agent gets the error with the login hint. Serve keeps running, the next request +// asks for a token again and succeeds, and stdin closing exits 0. +func TestServeProxyTransientRefreshFailureKeepsServing(t *testing.T) { + server := newEchoMCPServer(t) + var stdout lockedBuffer + var stderr bytes.Buffer + in := feedAfterAnswers(t, &stdout, []string{ + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, + `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`, + }, nil) + cmd := NewMcpServeCmd() + cmd.SetContext(t.Context()) + cmd.SetErr(&stderr) + + err := serveProxy(cmd, proxy.Options{ + In: in, + Out: &stdout, + Err: &stderr, + Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), + Config: &config.Config{Host: server.URL}, + Authenticate: failsToolsListOnce(errors.New("dial tcp: i/o timeout")), + Profile: "logfood", + }) + + require.NoError(t, err) + out := stdout.String() + assert.Contains(t, out, `"id":2,"error"`) + assert.Contains(t, out, "databricks auth login --profile logfood") + assert.Contains(t, out, `"id":3,"result"`) + assert.NotContains(t, stderr.String(), "stopped after") +} + +// TestServeProxyRefreshRejectionStopsAfterTransientFailure checks that a rejection after a transient failure still stops +// the proxy: the earlier failure does not change how the rejection is handled. +func TestServeProxyRefreshRejectionStopsAfterTransientFailure(t *testing.T) { + server := newEchoMCPServer(t) + var stdout lockedBuffer + var stderr bytes.Buffer + in := feedAfterAnswers(t, &stdout, []string{ + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`, + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`, + `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`, + }, nil) + cmd := NewMcpServeCmd() + cmd.SetContext(t.Context()) + cmd.SetErr(&stderr) + transient := failsToolsListOnce(errors.New("dial tcp: i/o timeout")) + rejected := func(r *http.Request) error { + if err := transient(r); err != nil { + return err + } + return expiresOnToolsList(r) + } + + err := serveProxy(cmd, proxy.Options{ + In: in, + Out: &stdout, + Err: &stderr, + Endpoint: mcp.ServiceURL(server.URL, "system.ai.github"), + Config: &config.Config{Host: server.URL}, + Authenticate: rejected, + Profile: "logfood", + }) + + require.ErrorIs(t, err, root.ErrAlreadyPrinted) + assert.Equal(t, 2, root.ExitStatus(err)) + assert.True(t, strings.HasSuffix(stderr.String(), refreshStoppedLine), stderr.String()) } // newRefreshFailureServer is a fake endpoint that answers initialize. It sets deleted when it gets a session DELETE. @@ -402,7 +597,7 @@ func TestServeProxyRefreshFailurePrintsOnceAndExitsTwo(t *testing.T) { require.ErrorIs(t, err, root.ErrAlreadyPrinted) assert.Equal(t, 2, root.ExitStatus(err)) - assert.Equal(t, "databricks aitools mcp serve: upstream: "+refreshTokenExpired+"\n"+ + assert.Equal(t, "databricks aitools mcp serve: upstream: "+refreshRejected.Error()+"\n"+ "Run: "+refreshLoginHint+"\n"+ refreshStoppedLine, stderr) assert.False(t, deleted, "no session DELETE is sent after a refresh failure") From 10450c9edae0d066bea71f290ca356d9ba2d9a30 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 07:12:34 +0000 Subject: [PATCH 32/32] aitools mcp serve: no login hint for a transient token failure A failure that is not a rejection, such as a network blip, says nothing about the credential, so the request's error no longer tells the user to log in. It says the next request tries again. Co-authored-by: Isaac --- cmd/aitools/mcp_serve.go | 5 +++-- cmd/aitools/mcp_serve_test.go | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/cmd/aitools/mcp_serve.go b/cmd/aitools/mcp_serve.go index b9f042add2b..dd5446eb05e 100644 --- a/cmd/aitools/mcp_serve.go +++ b/cmd/aitools/mcp_serve.go @@ -222,8 +222,9 @@ func (g *refreshGuard) authenticateRequest(r *http.Request) error { return err } if !credentialRejected(err) { - // Serve keeps running and the next request asks for a token again, so the hint does not say to restart. - return mcp.AuthError(g.profile, err) + // A failure that is not a rejection, such as a network blip, says nothing about the credential: a login would + // not fix it, and the next request asks for a token again, so the message names neither. + return fmt.Errorf("could not get a token for Databricks profile \"%s\": %w; the next request tries again", g.profile, err) } // The hint says to restart the server: a new spawn re-runs the binding checks, and it is the one that picks up the // new login. diff --git a/cmd/aitools/mcp_serve_test.go b/cmd/aitools/mcp_serve_test.go index a08bf9b959a..a49f8f85693 100644 --- a/cmd/aitools/mcp_serve_test.go +++ b/cmd/aitools/mcp_serve_test.go @@ -152,7 +152,8 @@ func TestRefreshGuardTransientFailureFailsOnlyThatRequest(t *testing.T) { require.Error(t, err) assert.ErrorIs(t, err, transient) - assert.Contains(t, err.Error(), "databricks auth login --profile logfood") + assert.Contains(t, err.Error(), `could not get a token for Databricks profile "logfood"`) + assert.NotContains(t, err.Error(), "auth login", "a login does not fix a transient failure") assert.NotContains(t, err.Error(), "restart") assert.NoError(t, g.failure()) assert.False(t, cancelled) @@ -502,7 +503,7 @@ func TestServeProxyTransientRefreshFailureKeepsServing(t *testing.T) { require.NoError(t, err) out := stdout.String() assert.Contains(t, out, `"id":2,"error"`) - assert.Contains(t, out, "databricks auth login --profile logfood") + assert.Contains(t, out, "the next request tries again") assert.Contains(t, out, `"id":3,"result"`) assert.NotContains(t, stderr.String(), "stopped after") }