diff --git a/libs/aitools/mcp/discovery.go b/libs/aitools/mcp/discovery.go new file mode 100644 index 00000000000..bf34adc7d6b --- /dev/null +++ b/libs/aitools/mcp/discovery.go @@ -0,0 +1,163 @@ +// Package mcp holds the logic behind `databricks aitools mcp`: discovery of Databricks managed +// MCP services, server naming, and service and sign-in URLs. +package mcp + +import ( + "context" + "errors" + "fmt" + "slices" + "strings" + + "github.com/databricks/databricks-sdk-go" + "github.com/databricks/databricks-sdk-go/apierr" + "github.com/databricks/databricks-sdk-go/service/catalog" +) + +// mcpServicePrefix is the resource-name prefix of an MCP service. +const mcpServicePrefix = "mcp-services/" + +// oauthProviderOption is the source connection option that marks a service as needing sign-in. +const oauthProviderOption = "oauth_provider" + +// Service is an MCP service in a schema, as the API reports it. +type Service struct { + // FullName is catalog.schema.leaf. + FullName string + Leaf string + // Comment is the user-provided description from the API. + Comment string + // SignInRequired is true when the service's source connection has an oauth_provider, so + // each user signs in to the provider once. + SignInRequired bool + // OAuthProvider is the connection's oauth_provider option, empty when SignInRequired is false. + OAuthProvider string + // Known is the CLI's description of the service. It is nil outside system.ai and for + // system.ai services missing from the table. + Known *KnownService +} + +// Discover lists the MCP services in location (catalog.schema). Services whose source +// connection was deleted are dropped. Listing failures the CLI names are returned as *ListError. +func Discover(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]Service, error) { + list, err := listServices(ctx, w, location) + if err != nil { + return nil, mapListError(location, err) + } + + services := make([]Service, 0, len(list)) + for i := range list { + if isDeletedSource(&list[i]) { + continue + } + services = append(services, newService(&list[i])) + } + return services, nil +} + +// ListErrorKind names a listing failure. +type ListErrorKind string + +const ( + ListErrLocationNotFound ListErrorKind = "MCP_LOCATION_NOT_FOUND" + ListErrPermissionDenied ListErrorKind = "MCP_PERMISSION_DENIED" + ListErrRateLimited ListErrorKind = "RATE_LIMITED" +) + +// ListError is a classified failure to list MCP services. It wraps the SDK error, so +// errors.Is(err, apierr.ErrNotFound) and similar still work. +type ListError struct { + Kind ListErrorKind + Location string + Err error +} + +// Error names the likely cause and keeps the server's message, because the SDK maps +// different failures to the same sentinel (any 404, or a private link 403). +func (e *ListError) Error() string { + switch e.Kind { + case ListErrLocationNotFound: + return fmt.Sprintf("%s is not a schema visible to this profile: %v", e.Location, e.Err) + case ListErrPermissionDenied: + // Listing needs these two grants. Services the caller has no privilege on are + // left out of the result instead of failing it. + return fmt.Sprintf("cannot list MCP services in %s (listing needs USE_CATALOG on the catalog and USE_SCHEMA on the schema): %v", e.Location, e.Err) + case ListErrRateLimited: + return fmt.Sprintf("MCP service listing in %s was rate limited; retry in a minute: %v", e.Location, e.Err) + } + return fmt.Sprintf("cannot list MCP services in %s: %v", e.Location, e.Err) +} + +// Unwrap returns the SDK error. +func (e *ListError) Unwrap() error { + return e.Err +} + +// listServices reads every page of the services in location, with source connections. +func listServices(ctx context.Context, w *databricks.WorkspaceClient, location string) ([]catalog.McpService, error) { + return w.AiGateway.ListMcpServicesAll(ctx, catalog.ListMcpServicesRequest{ + Parent: "schemas/" + location, + View: catalog.ListMcpServicesRequestViewFull, + }) +} + +// unrelatedErrorCodes are failures that look like a missing schema (404) or missing grants +// (403) but are about the workspace or network: the API is not available, or private link +// blocked the request. They keep the server's message and get no location or grants hint. +var unrelatedErrorCodes = []string{"ENDPOINT_NOT_FOUND", "FEATURE_DISABLED", "PRIVATE_LINK_VALIDATION_ERROR"} + +// mapListError classifies a listing failure. Other errors are returned with context only. +func mapListError(location string, err error) error { + apiErr, isAPIErr := errors.AsType[*apierr.APIError](err) + + var kind ListErrorKind + switch { + case isAPIErr && slices.Contains(unrelatedErrorCodes, apiErr.ErrorCode): + // Not about the schema or grants: leave it unclassified. + case errors.Is(err, apierr.ErrNotFound): + kind = ListErrLocationNotFound + case errors.Is(err, apierr.ErrPermissionDenied): + kind = ListErrPermissionDenied + case errors.Is(err, apierr.ErrTooManyRequests): + kind = ListErrRateLimited + } + if kind == "" { + return fmt.Errorf("cannot list MCP services in %s: %w", location, err) + } + return &ListError{Kind: kind, Location: location, Err: err} +} + +// isDeletedSource reports whether the service's source connection was deleted. +func isDeletedSource(svc *catalog.McpService) bool { + return svc.Config != nil && svc.Config.SourceConnection != nil && svc.Config.SourceConnection.IsDeleted +} + +// oauthProvider returns the OAuth provider of a service's source connection, or "" when it +// has none. A non-empty provider means the user must sign in before the service is usable. +func oauthProvider(svc *catalog.McpService) string { + if svc.Config == nil || svc.Config.SourceConnection == nil { + return "" + } + return svc.Config.SourceConnection.Options[oauthProviderOption] +} + +// newService builds a Service from an API service. The API returns lowercase names whatever +// casing the caller used for the location, so the leaf and the system.ai check use the +// returned name. +func newService(svc *catalog.McpService) Service { + fullName := strings.TrimPrefix(svc.Name, mcpServicePrefix) + leaf := leafOf(fullName) + provider := oauthProvider(svc) + + s := Service{ + FullName: fullName, + Leaf: leaf, + Comment: svc.Comment, + SignInRequired: provider != "", + OAuthProvider: provider, + } + if known, ok := knownSystemAI[leaf]; ok && inSystemAI(fullName) { + s.Known = &known + } + return s +} diff --git a/libs/aitools/mcp/discovery_test.go b/libs/aitools/mcp/discovery_test.go new file mode 100644 index 00000000000..41660b2afc0 --- /dev/null +++ b/libs/aitools/mcp/discovery_test.go @@ -0,0 +1,305 @@ +package mcp + +import ( + "encoding/json" + "errors" + "io" + "net/http" + "net/http/httptest" + "sync/atomic" + "testing" + + "github.com/databricks/databricks-sdk-go" + "github.com/databricks/databricks-sdk-go/apierr" + "github.com/databricks/databricks-sdk-go/service/catalog" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const discoveryTestListPath = "/api/2.1/unity-catalog/mcp-services" + +// discoveryTestGitHubProvider is the oauth_provider the API reports for GitHub. +const discoveryTestGitHubProvider = "OAUTH_PROVIDER_GITHUB_MCP" + +// discoveryTestServe starts a fake list endpoint that answers request i with pages[i] and +// returns a client for it. It fails the test on a wrong path or query and counts requests. +func discoveryTestServe(t *testing.T, location string, pages ...string) (*databricks.WorkspaceClient, *atomic.Int32) { + t.Helper() + var calls atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) { + // The SDK resolves host metadata before the first API call; that is not a list call. + if r.URL.Path != discoveryTestListPath { + http.NotFound(rw, r) + return + } + n := int(calls.Add(1)) + assert.Equal(t, "schemas/"+location, r.URL.Query().Get("parent")) + assert.Equal(t, "FULL", r.URL.Query().Get("view")) + if n > len(pages) { + http.Error(rw, `{"error_code":"INTERNAL_ERROR","message":"unexpected call"}`, http.StatusInternalServerError) + return + } + rw.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(rw, pages[n-1]) + })) + t.Cleanup(server.Close) + + w, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + return w, &calls +} + +// discoveryTestPage marshals one list response page. +func discoveryTestPage(t *testing.T, nextPageToken string, services ...catalog.McpService) string { + t.Helper() + body, err := json.Marshal(catalog.ListMcpServicesResponse{McpServices: services, NextPageToken: nextPageToken}) + require.NoError(t, err) + return string(body) +} + +// discoveryTestInternal is a Databricks-owned service with no source connection. +func discoveryTestInternal(fullName string) catalog.McpService { + return catalog.McpService{Name: mcpServicePrefix + fullName} +} + +// discoveryTestExternal is a service backed by a source connection with the given options. +func discoveryTestExternal(fullName string, options map[string]string) catalog.McpService { + return catalog.McpService{ + Name: mcpServicePrefix + fullName, + Config: &catalog.McpServiceConfig{ + SourceConnection: &catalog.McpServiceConfigSourceConnection{ + Name: "connections/" + fullName, + Options: options, + }, + }, + } +} + +func TestDiscoverMakesOneCallForSingleSchemaPage(t *testing.T) { + w, calls := discoveryTestServe(t, "system.ai", + discoveryTestPage(t, "", discoveryTestInternal("system.ai.genie_one_mcp"), discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider})), + ) + + services, err := Discover(t.Context(), w, "system.ai") + require.NoError(t, err) + assert.Len(t, services, 2) + assert.Equal(t, int32(1), calls.Load()) +} + +func TestDiscoverFollowsPagination(t *testing.T) { + w, calls := discoveryTestServe(t, "main.tools", + discoveryTestPage(t, "page-2", discoveryTestInternal("main.tools.crm")), + discoveryTestPage(t, "", discoveryTestInternal("main.tools.billing")), + ) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 2) + assert.Equal(t, "main.tools.crm", services[0].FullName) + assert.Equal(t, "main.tools.billing", services[1].FullName) + assert.Equal(t, int32(2), calls.Load()) +} + +func TestDiscoverDetectsSignInFromOptions(t *testing.T) { + tests := []struct { + name string + svc catalog.McpService + wantSignIn bool + wantProvider string + }{ + { + name: "internal service has no source connection", + svc: discoveryTestInternal("main.tools.crm"), + wantSignIn: false, + }, + { + name: "source connection with oauth_provider needs sign-in", + svc: discoveryTestExternal("main.tools.crm", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}), + wantSignIn: true, + wantProvider: discoveryTestGitHubProvider, + }, + { + name: "source connection without oauth_provider does not need sign-in", + svc: discoveryTestExternal("main.tools.crm", map[string]string{"client_id": "abc"}), + wantSignIn: false, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + w, _ := discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", tt.svc)) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, tt.wantSignIn, services[0].SignInRequired) + assert.Equal(t, tt.wantProvider, services[0].OAuthProvider) + }) + } +} + +func TestDiscoverDropsDeletedSourceConnections(t *testing.T) { + deleted := discoveryTestExternal("main.tools.old", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}) + deleted.Config.SourceConnection.IsDeleted = true + + w, _ := discoveryTestServe(t, "main.tools", + discoveryTestPage(t, "", deleted, discoveryTestInternal("main.tools.crm")), + ) + + services, err := Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "main.tools.crm", services[0].FullName) + assert.Equal(t, "crm", services[0].Leaf) +} + +func TestDiscoverAttachesKnownOnlyInSystemAI(t *testing.T) { + github := discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}) + github.Comment = "API comment" + custom := discoveryTestInternal("system.ai.custom") + + w, _ := discoveryTestServe(t, "system.ai", discoveryTestPage(t, "", github, custom)) + services, err := Discover(t.Context(), w, "system.ai") + require.NoError(t, err) + require.Len(t, services, 2) + require.NotNil(t, services[0].Known) + assert.Equal(t, "GitHub", services[0].Known.Label) + assert.Equal(t, "API comment", services[0].Comment) + assert.Nil(t, services[1].Known) + + w, _ = discoveryTestServe(t, "main.tools", discoveryTestPage(t, "", discoveryTestExternal("main.tools.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}))) + services, err = Discover(t.Context(), w, "main.tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Nil(t, services[0].Known) +} + +func TestDiscoverTakesLeafFromReturnedNameForMixedCaseLocation(t *testing.T) { + w, _ := discoveryTestServe(t, "System.AI", discoveryTestPage(t, "", discoveryTestExternal("system.ai.github", map[string]string{oauthProviderOption: discoveryTestGitHubProvider}))) + services, err := Discover(t.Context(), w, "System.AI") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "github", services[0].Leaf) + require.NotNil(t, services[0].Known) + assert.Equal(t, "GitHub", services[0].Known.Label) + + w, _ = discoveryTestServe(t, "Main.Tools", discoveryTestPage(t, "", discoveryTestInternal("main.tools.crm"))) + services, err = Discover(t.Context(), w, "Main.Tools") + require.NoError(t, err) + require.Len(t, services, 1) + assert.Equal(t, "crm", services[0].Leaf) + assert.Nil(t, services[0].Known) +} + +func TestDiscoverMapsListingErrors(t *testing.T) { + tests := []struct { + name string + status int + body string + wantKind ListErrorKind + wantSDK error + wantMsg string + }{ + { + name: "missing schema is location not found", + status: http.StatusNotFound, + body: `{"error_code":"NOT_FOUND","message":"Schema 'main.tools' does not exist"}`, + wantKind: ListErrLocationNotFound, + wantSDK: apierr.ErrNotFound, + wantMsg: "main.tools is not a schema visible to this profile: Schema 'main.tools' does not exist", + }, + { + name: "forbidden is permission denied", + status: http.StatusForbidden, + body: `{"error_code":"PERMISSION_DENIED","message":"User does not have USE SCHEMA"}`, + wantKind: ListErrPermissionDenied, + wantSDK: apierr.ErrPermissionDenied, + wantMsg: "cannot list MCP services in main.tools (listing needs USE_CATALOG on the catalog and USE_SCHEMA on the schema): User does not have USE SCHEMA", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, _ *http.Request) { + rw.Header().Set("Content-Type", "application/json") + rw.WriteHeader(tt.status) + _, _ = io.WriteString(rw, tt.body) + })) + t.Cleanup(server.Close) + w, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + + _, err = Discover(t.Context(), w, "main.tools") + var listErr *ListError + require.ErrorAs(t, err, &listErr) + assert.Equal(t, tt.wantKind, listErr.Kind) + assert.Equal(t, "main.tools", listErr.Location) + assert.ErrorIs(t, err, tt.wantSDK) + assert.EqualError(t, err, tt.wantMsg) + }) + } +} + +func TestMapListError(t *testing.T) { + tests := []struct { + name string + err error + wantKind ListErrorKind + }{ + {name: "rate limited", err: apierr.ErrTooManyRequests, wantKind: ListErrRateLimited}, + {name: "resource exhausted is rate limited", err: apierr.ErrResourceExhausted, wantKind: ListErrRateLimited}, + {name: "resource does not exist is location not found", err: apierr.ErrResourceDoesNotExist, wantKind: ListErrLocationNotFound}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var listErr *ListError + require.ErrorAs(t, mapListError("system.ai", tt.err), &listErr) + assert.Equal(t, tt.wantKind, listErr.Kind) + }) + } +} + +func TestListErrorMessages(t *testing.T) { + cause := errors.New("server said no") + tests := []struct { + kind ListErrorKind + want string + }{ + {kind: ListErrRateLimited, want: "MCP service listing in system.ai was rate limited; retry in a minute: server said no"}, + {kind: "", want: "cannot list MCP services in system.ai: server said no"}, + } + for _, tt := range tests { + t.Run(string(tt.kind), func(t *testing.T) { + err := &ListError{Kind: tt.kind, Location: "system.ai", Err: cause} + assert.EqualError(t, err, tt.want) + }) + } +} + +func TestMapListErrorLeavesWorkspaceAndNetworkFailuresUnclassified(t *testing.T) { + tests := []struct { + code string + status int + }{ + {code: "ENDPOINT_NOT_FOUND", status: http.StatusNotFound}, + {code: "FEATURE_DISABLED", status: http.StatusNotFound}, + {code: "PRIVATE_LINK_VALIDATION_ERROR", status: http.StatusForbidden}, + } + for _, tt := range tests { + t.Run(tt.code, func(t *testing.T) { + apiErr := &apierr.APIError{ErrorCode: tt.code, StatusCode: tt.status, Message: "server message"} + err := mapListError("system.ai", apiErr) + + _, ok := errors.AsType[*ListError](err) + assert.False(t, ok) + assert.ErrorIs(t, err, apiErr) + assert.EqualError(t, err, "cannot list MCP services in system.ai: server message") + }) + } +} + +func TestMapListErrorLeavesOtherErrorsUnclassified(t *testing.T) { + err := mapListError("system.ai", apierr.ErrUnauthenticated) + + _, ok := errors.AsType[*ListError](err) + assert.False(t, ok) + assert.ErrorIs(t, err, apierr.ErrUnauthenticated) +} diff --git a/libs/aitools/mcp/known.go b/libs/aitools/mcp/known.go new file mode 100644 index 00000000000..9716b6d3c9b --- /dev/null +++ b/libs/aitools/mcp/known.go @@ -0,0 +1,60 @@ +package mcp + +// systemAILocation is the schema that ships the Databricks managed MCP services. +const systemAILocation = "system.ai" + +// KnownService is the CLI's own description of a system.ai service, keyed by leaf name. +type KnownService struct { + Label string + Summary string + Recommended bool + Beta bool + // Note is printed after install or sign-in. It is empty when there is nothing to add. + Note string +} + +// knownSystemAI describes the system.ai services listed at +// https://docs.databricks.com/aws/en/agents/mcp-tools/built-in-mcp-services. Discovery from +// the API decides what is offered; this table only adds labels and notes, so an unlisted +// service still appears. +var knownSystemAI = map[string]KnownService{ + "genie_one_mcp": { + Label: "Genie One", Summary: "Ask questions about your data", + Recommended: true, + }, + "dbsql": { + Label: "Databricks SQL", Summary: "Run SQL on a SQL warehouse", + Beta: true, Note: "Available with the account-level Unity Gateway.", + }, + "web_search": { + Label: "Web search", Summary: "Search the public web", + Beta: true, Note: "Not for consumer-only users; off in HIPAA workspaces.", + }, + "sandbox": { + Label: "Sandbox", Summary: "Run Python, SQL or shell in a sandbox", + Beta: true, + }, + "github": { + Label: "GitHub", Summary: "Repositories, issues, pull requests", + Note: "Public repositories only until a repository owner installs https://github.com/apps/databricks-github-connector.", + }, + "slack": { + Label: "Slack", Summary: "Channels and messages", + }, + "atlassian": { + Label: "Jira and Confluence", + }, + "google_drive": { + Label: "Google Drive", Summary: "Drive, Docs, Sheets, Slides", + }, + "google_calendar": { + Label: "Google Calendar", + }, + "gmail": { + Label: "Gmail", + }, + "microsoft_365": { + Label: "Microsoft 365", Summary: "SharePoint, Outlook, Teams", + Note: "Scopes ending in .All usually need tenant admin consent.", + }, +} diff --git a/libs/aitools/mcp/known_test.go b/libs/aitools/mcp/known_test.go new file mode 100644 index 00000000000..2b8ad314212 --- /dev/null +++ b/libs/aitools/mcp/known_test.go @@ -0,0 +1,39 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestKnownSystemAITable(t *testing.T) { + tests := []struct { + leaf string + label string + beta bool + recommended bool + }{ + {leaf: "genie_one_mcp", label: "Genie One", recommended: true}, + {leaf: "dbsql", label: "Databricks SQL", beta: true}, + {leaf: "web_search", label: "Web search", beta: true}, + {leaf: "sandbox", label: "Sandbox", beta: true}, + {leaf: "github", label: "GitHub"}, + {leaf: "slack", label: "Slack"}, + {leaf: "atlassian", label: "Jira and Confluence"}, + {leaf: "google_drive", label: "Google Drive"}, + {leaf: "google_calendar", label: "Google Calendar"}, + {leaf: "gmail", label: "Gmail"}, + {leaf: "microsoft_365", label: "Microsoft 365"}, + } + require.Len(t, knownSystemAI, len(tests)) + for _, tt := range tests { + t.Run(tt.leaf, func(t *testing.T) { + known, ok := knownSystemAI[tt.leaf] + require.True(t, ok) + assert.Equal(t, tt.label, known.Label) + assert.Equal(t, tt.beta, known.Beta) + assert.Equal(t, tt.recommended, known.Recommended) + }) + } +} diff --git a/libs/aitools/mcp/naming.go b/libs/aitools/mcp/naming.go new file mode 100644 index 00000000000..36ae7a1ef0a --- /dev/null +++ b/libs/aitools/mcp/naming.go @@ -0,0 +1,71 @@ +package mcp + +import ( + "fmt" + "regexp" + "strings" + "sync" +) + +// invalidNameChars matches each run of characters that a server name cannot contain. +var invalidNameChars = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`[^a-z0-9_-]+`) +}) + +// underscoreRuns matches two or more "_" in a row. +var underscoreRuns = sync.OnceValue(func() *regexp.Regexp { + return regexp.MustCompile(`_{2,}`) +}) + +// Sanitize lowercases s, replaces each run of characters outside [a-z0-9_-] with "-", +// collapses runs of "_" into one, and trims leading and trailing "-" and "_". Agents name +// tools mcp____ and split on "__", so a part of a server name must not contain +// "__" or start or end with "_". +func Sanitize(s string) string { + name := invalidNameChars().ReplaceAllString(strings.ToLower(s), "-") + name = underscoreRuns().ReplaceAllString(name, "_") + return strings.Trim(name, "-_") +} + +// ServerName returns the agent-facing name of the server for a service (catalog.schema.leaf) +// and a profile: - in system.ai, --- elsewhere. +// Each part is sanitized and parts that sanitize to nothing are left out. Tool names in +// agents are mcp____, so the name must stay stable for the entry's life. +func ServerName(fullName, profile string) string { + parts := strings.Split(fullName, ".") + if inSystemAI(fullName) { + parts = []string{leafOf(fullName)} + } + + var name []string + for _, part := range append(parts, profile) { + if s := Sanitize(part); s != "" { + name = append(name, s) + } + } + return strings.Join(name, "-") +} + +// leafOf returns the service name after the last ".". Unity Catalog names cannot contain ".". +func leafOf(fullName string) string { + return fullName[strings.LastIndex(fullName, ".")+1:] +} + +// inSystemAI reports whether a service full name is in system.ai, in any casing. +func inSystemAI(fullName string) bool { + return strings.HasPrefix(strings.ToLower(fullName), systemAILocation+".") +} + +// UniqueName returns base, or base-2, base-3, ... for the first candidate for which taken +// returns false. +func UniqueName(base string, taken func(string) bool) string { + if !taken(base) { + return base + } + for n := 2; ; n++ { + candidate := fmt.Sprintf("%s-%d", base, n) + if !taken(candidate) { + return candidate + } + } +} diff --git a/libs/aitools/mcp/naming_test.go b/libs/aitools/mcp/naming_test.go new file mode 100644 index 00000000000..c3dc35f559b --- /dev/null +++ b/libs/aitools/mcp/naming_test.go @@ -0,0 +1,75 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestSanitize(t *testing.T) { + tests := []struct { + in string + want string + }{ + {in: "logfood", want: "logfood"}, + {in: "Genie_One", want: "genie_one"}, + {in: "My.Profile", want: "my-profile"}, + {in: " --a..b-- ", want: "a-b"}, + {in: "..", want: ""}, + {in: "prod_", want: "prod"}, + {in: "my__ws", want: "my_ws"}, + {in: "__a___b__", want: "a_b"}, + {in: "a_.b", want: "a_-b"}, + } + for _, tt := range tests { + t.Run(tt.in, func(t *testing.T) { + assert.Equal(t, tt.want, Sanitize(tt.in)) + }) + } +} + +func TestServerName(t *testing.T) { + tests := []struct { + name string + fullName string + profile string + want string + }{ + {name: "system.ai keeps the leaf", fullName: "system.ai.genie_one_mcp", profile: "logfood", want: "genie_one_mcp-logfood"}, + {name: "system.ai github", fullName: "system.ai.github", profile: "dogfood", want: "github-dogfood"}, + {name: "customer schema includes catalog and schema", fullName: "main.tools.crm", profile: "prod", want: "main-tools-crm-prod"}, + {name: "profile is sanitized", fullName: "system.ai.dbsql", profile: "My.Profile", want: "dbsql-my-profile"}, + {name: "system.ai is case-insensitive", fullName: "System.AI.github", profile: "prod", want: "github-prod"}, + {name: "trailing underscore cannot form __ before the tool name", fullName: "system.ai.github", profile: "prod_", want: "github-prod"}, + {name: "parts that sanitize to nothing are left out", fullName: "main.tools.\u9867\u5ba2", profile: "prod", want: "main-tools-prod"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, tt.want, ServerName(tt.fullName, tt.profile)) + }) + } +} + +func TestUniqueName(t *testing.T) { + tests := []struct { + name string + base string + taken []string + want string + }{ + {name: "free base", base: "github-logfood", want: "github-logfood"}, + {name: "base taken", base: "github-logfood", taken: []string{"github-logfood"}, want: "github-logfood-2"}, + {name: "suffixes taken", base: "github-logfood", taken: []string{"github-logfood", "github-logfood-2"}, want: "github-logfood-3"}, + {name: "suffix only taken", base: "github-logfood", taken: []string{"github-logfood-2"}, want: "github-logfood"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + takenSet := make(map[string]bool) + for _, name := range tt.taken { + takenSet[name] = true + } + got := UniqueName(tt.base, func(name string) bool { return takenSet[name] }) + assert.Equal(t, tt.want, got) + }) + } +} diff --git a/libs/aitools/mcp/url.go b/libs/aitools/mcp/url.go new file mode 100644 index 00000000000..609c0626cd4 --- /dev/null +++ b/libs/aitools/mcp/url.go @@ -0,0 +1,15 @@ +package mcp + +import "net/url" + +// ServiceURL returns the streamable-HTTP endpoint of an MCP service. host is the workspace +// URL with its scheme, as config.Config.Host holds it. +func ServiceURL(host, fullName string) string { + return host + "/ai-gateway/mcp-services/" + url.PathEscape(fullName) +} + +// SignInURL returns the page where a user signs in to a sign-in-required service. +func SignInURL(host, fullName, workspaceID string) string { + query := url.Values{"name": {fullName}, "o": {workspaceID}} + return host + "/mcp-service-login?" + query.Encode() +} diff --git a/libs/aitools/mcp/url_test.go b/libs/aitools/mcp/url_test.go new file mode 100644 index 00000000000..2939dc2ad08 --- /dev/null +++ b/libs/aitools/mcp/url_test.go @@ -0,0 +1,25 @@ +package mcp + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestServiceURL(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/ai-gateway/mcp-services/system.ai.github", + ServiceURL("https://adb-123.azuredatabricks.test", "system.ai.github")) +} + +func TestServiceURLEscapesTheName(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/ai-gateway/mcp-services/main.tools.crm%23v2", + ServiceURL("https://adb-123.azuredatabricks.test", "main.tools.crm#v2")) +} + +func TestSignInURL(t *testing.T) { + assert.Equal(t, + "https://adb-123.azuredatabricks.test/mcp-service-login?name=system.ai.github&o=2548836972759138", + SignInURL("https://adb-123.azuredatabricks.test", "system.ai.github", "2548836972759138")) +} diff --git a/libs/testserver/handlers.go b/libs/testserver/handlers.go index a021fd8b53a..00d3e1fc9af 100644 --- a/libs/testserver/handlers.go +++ b/libs/testserver/handlers.go @@ -923,6 +923,10 @@ func AddDefaultHandlers(server *Server) { return req.Workspace.McpServicesCreate(req) }) + server.Handle("GET", "/api/2.1/unity-catalog/mcp-services", func(req Request) any { + return req.Workspace.McpServicesList(req) + }) + server.Handle("GET", "/api/2.1/unity-catalog/mcp-services/{name}", func(req Request) any { return MapGet(req.Workspace, req.Workspace.McpServices, req.Vars["name"]) }) diff --git a/libs/testserver/mcp_services.go b/libs/testserver/mcp_services.go index 41200d06951..1a2c9c05095 100644 --- a/libs/testserver/mcp_services.go +++ b/libs/testserver/mcp_services.go @@ -3,12 +3,20 @@ package testserver import ( "encoding/json" "fmt" + "maps" "net/http" + "slices" "strings" "github.com/databricks/databricks-sdk-go/service/catalog" ) +// Resource-name prefixes of MCP services and their parent schemas. +const ( + mcpServicesNamePrefix = "mcp-services/" + mcpServicesParentPrefix = "schemas/" +) + // McpServicesCreate fakes POST /api/2.1/unity-catalog/mcp-services. See // ModelServicesCreate for the shape: the McpService body is sent directly, // parent and mcp_service_id are query parameters, and the map is keyed by the @@ -24,10 +32,10 @@ func (s *FakeWorkspace) McpServicesCreate(req Request) Response { } } - schema := strings.TrimPrefix(req.URL.Query().Get("parent"), "schemas/") + schema := strings.TrimPrefix(req.URL.Query().Get("parent"), mcpServicesParentPrefix) key := schema + "." + req.URL.Query().Get("mcp_service_id") - ms.Name = "mcp-services/" + key + ms.Name = mcpServicesNamePrefix + key ms.CreatedBy = s.CurrentUser().UserName ms.UpdatedBy = s.CurrentUser().UserName ms.EffectiveOwner = s.CurrentUser().UserName @@ -67,3 +75,34 @@ func (s *FakeWorkspace) McpServicesUpdate(req Request, name string) Response { Body: existing, } } + +// McpServicesList fakes GET /api/2.1/unity-catalog/mcp-services. It filters by parent +// (schemas/{catalog}.{schema}, in any casing, as Unity Catalog names are case-insensitive) and +// drops the source connection unless view is FULL, as the real API does. Pagination is not +// faked: every match is returned in one page. +func (s *FakeWorkspace) McpServicesList(req Request) Response { + defer s.LockUnlock()() + + query := req.URL.Query() + prefix := strings.ToLower(strings.TrimPrefix(query.Get("parent"), mcpServicesParentPrefix)) + "." + full := query.Get("view") == string(catalog.ListMcpServicesRequestViewFull) + + var services []catalog.McpService + for _, key := range slices.Sorted(maps.Keys(s.McpServices)) { + if !strings.HasPrefix(strings.ToLower(key), prefix) { + continue + } + ms := s.McpServices[key] + if !full && ms.Config != nil { + // Copy so the stored service keeps its source connection for later FULL reads. + config := *ms.Config + config.SourceConnection = nil + ms.Config = &config + } + services = append(services, ms) + } + + return Response{ + Body: catalog.ListMcpServicesResponse{McpServices: services}, + } +} diff --git a/libs/testserver/mcp_services_test.go b/libs/testserver/mcp_services_test.go new file mode 100644 index 00000000000..c7166bbc908 --- /dev/null +++ b/libs/testserver/mcp_services_test.go @@ -0,0 +1,99 @@ +package testserver + +import ( + "net/url" + "testing" + + "github.com/databricks/databricks-sdk-go/service/catalog" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// mcpServicesTestGitHubProvider is the oauth_provider the API reports for GitHub. +const mcpServicesTestGitHubProvider = "OAUTH_PROVIDER_GITHUB_MCP" + +// mcpServicesTestList calls the list handler with the given query string. +func mcpServicesTestList(t *testing.T, workspace *FakeWorkspace, rawQuery string) []catalog.McpService { + t.Helper() + u, err := url.Parse("/api/2.1/unity-catalog/mcp-services?" + rawQuery) + require.NoError(t, err) + + response := workspace.McpServicesList(Request{URL: u}) + require.Equal(t, 0, response.StatusCode) + body, ok := response.Body.(catalog.ListMcpServicesResponse) + require.True(t, ok) + return body.McpServices +} + +// mcpServicesTestWorkspace returns a fake workspace with two system.ai services and one customer service. +func mcpServicesTestWorkspace(t *testing.T) *FakeWorkspace { + t.Helper() + workspace := NewFakeWorkspace("http://test", "dbapi123") + mcpServicesTestSeed(workspace, "system.ai.genie_one_mcp", "Genie", "") + mcpServicesTestSeed(workspace, "system.ai.github", "GitHub", mcpServicesTestGitHubProvider) + mcpServicesTestSeed(workspace, "main.tools.crm", "CRM", mcpServicesTestGitHubProvider) + return workspace +} + +func TestMcpServicesListFiltersByParent(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.Len(t, services, 2) + assert.Equal(t, "mcp-services/system.ai.genie_one_mcp", services[0].Name) + assert.Equal(t, "mcp-services/system.ai.github", services[1].Name) +} + +func TestMcpServicesListMatchesParentInAnyCase(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/System.AI&view=FULL") + require.Len(t, services, 2) + assert.Equal(t, "mcp-services/system.ai.genie_one_mcp", services[0].Name) +} + +func TestMcpServicesListViewFullKeepsSourceConnection(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.Len(t, services, 2) + assert.Nil(t, services[0].Config) + require.NotNil(t, services[1].Config) + require.NotNil(t, services[1].Config.SourceConnection) + assert.Equal(t, mcpServicesTestGitHubProvider, services[1].Config.SourceConnection.Options["oauth_provider"]) +} + +func TestMcpServicesListViewBasicOmitsSourceConnection(t *testing.T) { + workspace := mcpServicesTestWorkspace(t) + + for _, query := range []string{"parent=schemas/system.ai&view=BASIC", "parent=schemas/system.ai"} { + services := mcpServicesTestList(t, workspace, query) + require.Len(t, services, 2, query) + require.NotNil(t, services[1].Config, query) + assert.Nil(t, services[1].Config.SourceConnection, query) + } + + // BASIC must not strip the stored service, or a later FULL read would lose sign-in details. + services := mcpServicesTestList(t, workspace, "parent=schemas/system.ai&view=FULL") + require.NotNil(t, services[1].Config) + require.NotNil(t, services[1].Config.SourceConnection) +} + +// mcpServicesTestSeed stores an MCP service under fullName (catalog.schema.leaf). +// An empty oauthProvider seeds an internal Databricks service with no source connection; +// otherwise the service is backed by a source connection with that OAuth provider. +func mcpServicesTestSeed(s *FakeWorkspace, fullName, comment, oauthProvider string) { + ms := catalog.McpService{ + Name: mcpServicesNamePrefix + fullName, + Comment: comment, + } + if oauthProvider != "" { + ms.Config = &catalog.McpServiceConfig{ + SourceConnection: &catalog.McpServiceConfigSourceConnection{ + Name: "connections/" + fullName, + Options: map[string]string{"oauth_provider": oauthProvider}, + }, + } + } + s.McpServices[fullName] = ms +}