Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

refactor(mcp): extract database resolver into tool_resolve.go (#19896)

Vincent Huang6e00313d6011
diff --git a/backend/api/mcp/tool_query.go b/backend/api/mcp/tool_query.go
index 9bc66e5cd4..c0d2f36933 100644
--- a/backend/api/mcp/tool_query.go
+++ b/backend/api/mcp/tool_query.go
@@ -16,7 +16,6 @@ const (
defaultQueryLimit = 100
maxQueryLimit = 1000
queryTimeout = 30 * time.Second
- resolveTimeout = 30 * time.Second
)
// QueryInput is the input for the query_database tool.
@@ -43,23 +42,6 @@ type QueryOutput struct {
LatencyMs int64 `json:"latencyMs"`
}
-// Candidate represents a database match for ambiguous resolution.
-type Candidate struct {
- Database string `json:"database"`
- Instance string `json:"instance"`
- Project string `json:"project"`
- Engine string `json:"engine"`
-}
-
-// resolvedDatabase holds the result of database resolution.
-type resolvedDatabase struct {
- resourceName string
- dataSourceID string
- ambiguous bool
- candidates []Candidate
- dataSourceIDs map[string]string // resourceName -> dataSourceID (populated when ambiguous)
-}
-
// queryDatabaseDescription is the description for the query_database tool.
const queryDatabaseDescription = `Execute a SQL query against a Bytebase database. Resolves the database by name automatically.
@@ -103,7 +85,7 @@ func (s *Server) handleQueryDatabase(ctx context.Context, req *mcp.CallToolReque
resolveCtx, resolveCancel := context.WithTimeout(ctx, resolveTimeout)
defer resolveCancel()
- resolved, err := s.resolveDatabase(resolveCtx, input)
+ resolved, err := s.resolveDatabase(resolveCtx, input.Database, input.Instance, input.Project)
if err != nil {
return formatToolError(err), nil, nil
}
@@ -131,274 +113,6 @@ func (s *Server) handleQueryDatabase(ctx context.Context, req *mcp.CallToolReque
}, output, nil
}
-// listDatabasesResponse is the typed response from ListDatabases API.
-type listDatabasesResponse struct {
- Databases []databaseEntry `json:"databases"`
- NextPageToken string `json:"nextPageToken,omitempty"`
-}
-
-// databaseEntry represents a database in the ListDatabases response.
-type databaseEntry struct {
- Name string `json:"name"`
- Project string `json:"project"`
- InstanceResource instanceResource `json:"instanceResource"`
-}
-
-// instanceResource holds instance details including data sources.
-type instanceResource struct {
- Name string `json:"name"`
- Engine string `json:"engine"`
- DataSources []dataSource `json:"dataSources"`
-}
-
-// dataSource represents a database data source.
-type dataSource struct {
- ID string `json:"id"`
- Type string `json:"type"`
-}
-
-// buildDatabaseFilter builds a CEL filter expression for ListDatabases.
-func buildDatabaseFilter(input QueryInput) string {
- // name.contains does substring matching server-side.
- filter := fmt.Sprintf("name.contains(%q)", input.Database)
- if input.Instance != "" {
- filter += fmt.Sprintf(" && instance == %q", "instances/"+input.Instance)
- }
- if input.Project != "" {
- filter += fmt.Sprintf(" && project == %q", "projects/"+input.Project)
- }
- return filter
-}
-
-// listDatabases lists databases matching the filter in the user's workspace.
-// Uses the workspace ID from the JWT token stored in context.
-func (s *Server) listDatabases(ctx context.Context, filter string) ([]databaseEntry, error) {
- workspaceID := getWorkspaceID(ctx)
- if workspaceID == "" {
- return nil, &toolError{
- Code: "AUTH_ERROR",
- Message: "workspace ID not found in token",
- Suggestion: "re-authenticate with Bytebase",
- }
- }
-
- var databases []databaseEntry
- pageToken := ""
- for {
- body := map[string]any{
- "parent": fmt.Sprintf("workspaces/%s", workspaceID),
- "filter": filter,
- "pageSize": 1000,
- }
- if pageToken != "" {
- body["pageToken"] = pageToken
- }
- resp, err := s.apiRequest(ctx, "/bytebase.v1.DatabaseService/ListDatabases", body)
- if err != nil {
- return nil, errors.Wrap(err, "failed to list databases")
- }
- if resp.Status == http.StatusForbidden {
- return nil, &toolError{
- Code: "PERMISSION_DENIED",
- Message: "you don't have permission to list databases in this workspace",
- Suggestion: "ask your workspace admin to grant you the bb.databases.list permission",
- }
- }
- if resp.Status >= 400 {
- return nil, errors.Errorf("failed to list databases: HTTP %d: %s", resp.Status, parseError(resp.Body))
- }
-
- var listResp listDatabasesResponse
- if err := json.Unmarshal(resp.Body, &listResp); err != nil {
- return nil, errors.Wrap(err, "failed to parse database list")
- }
- databases = append(databases, listResp.Databases...)
-
- if listResp.NextPageToken == "" {
- break
- }
- pageToken = listResp.NextPageToken
- }
- return databases, nil
-}
-
-// matchDatabases applies tiered matching (exact > case-insensitive > substring) and
-// returns the resolved result, an ambiguous result, or a not-found error.
-func matchDatabases(databases []databaseEntry, input QueryInput) (*resolvedDatabase, error) {
- matches := matchExact(databases, input.Database)
- if len(matches) == 0 {
- matches = matchCaseInsensitive(databases, input.Database)
- }
- if len(matches) == 0 {
- matches = matchSubstring(databases, input.Database)
- }
-
- if len(matches) == 0 {
- suggestion := "check the database name or use search_api to list available databases"
- if input.Instance != "" || input.Project != "" {
- suggestion = "try without instance/project filters, or use search_api to list available databases"
- }
- return nil, &toolError{
- Code: "DATABASE_NOT_FOUND",
- Message: fmt.Sprintf("no database matching %q", input.Database),
- Suggestion: suggestion,
- }
- }
-
- if len(matches) > 1 {
- return buildAmbiguousResult(matches), nil
- }
-
- db := matches[0]
- return &resolvedDatabase{
- resourceName: db.Name,
- dataSourceID: selectDataSource(db.InstanceResource.DataSources),
- }, nil
-}
-
-// buildAmbiguousResult constructs a resolvedDatabase with multiple candidates.
-func buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {
- candidates := make([]Candidate, 0, len(matches))
- dsIDs := make(map[string]string, len(matches))
- for _, db := range matches {
- candidates = append(candidates, Candidate{
- Database: db.Name,
- Instance: extractShortName(db.InstanceResource.Name),
- Project: extractShortName(db.Project),
- Engine: db.InstanceResource.Engine,
- })
- dsIDs[db.Name] = selectDataSource(db.InstanceResource.DataSources)
- }
- return &resolvedDatabase{ambiguous: true, candidates: candidates, dataSourceIDs: dsIDs}
-}
-
-// resolveDatabase resolves a database name to a unique resource using tiered matching.
-func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolvedDatabase, error) {
- databases, err := s.listDatabases(ctx, buildDatabaseFilter(input))
- if err != nil {
- return nil, err
- }
- return matchDatabases(databases, input)
-}
-
-// elicitDatabaseChoice prompts the user to pick from ambiguous database matches
-// using MCP elicitation. Returns an error if elicitation is unsupported, the user
-// cancels/declines, or the selection is invalid.
-func (*Server) elicitDatabaseChoice(ctx context.Context, req *mcp.CallToolRequest, resolved *resolvedDatabase) (*resolvedDatabase, error) {
- // Build enum values and a lookup map from display label to resource name.
- enumValues := make([]any, 0, len(resolved.candidates))
- resourceByLabel := make(map[string]string, len(resolved.candidates))
- for _, c := range resolved.candidates {
- label := fmt.Sprintf("%s (%s, %s)", c.Database, c.Instance, c.Engine)
- enumValues = append(enumValues, label)
- resourceByLabel[label] = c.Database
- }
-
- result, err := req.Session.Elicit(ctx, &mcp.ElicitParams{
- Mode: "form",
- Message: "Multiple databases match. Which one do you want to query?",
- RequestedSchema: map[string]any{
- "type": "object",
- "properties": map[string]any{
- "database": map[string]any{
- "type": "string",
- "enum": enumValues,
- "description": "Select the target database",
- },
- },
- "required": []string{"database"},
- },
- })
- if err != nil {
- return nil, err
- }
- if result.Action != "accept" {
- return nil, errors.Errorf("user %sd database selection", result.Action)
- }
-
- selected, ok := result.Content["database"].(string)
- if !ok {
- return nil, errors.New("invalid database selection")
- }
-
- resourceName, ok := resourceByLabel[selected]
- if !ok {
- return nil, errors.Errorf("unknown database selection: %s", selected)
- }
-
- return &resolvedDatabase{
- resourceName: resourceName,
- dataSourceID: resolved.dataSourceIDs[resourceName],
- }, nil
-}
-
-// matchExact returns databases whose short name exactly matches the input.
-func matchExact(databases []databaseEntry, name string) []databaseEntry {
- var result []databaseEntry
- for _, db := range databases {
- if extractDatabaseName(db.Name) == name {
- result = append(result, db)
- }
- }
- return result
-}
-
-// matchCaseInsensitive returns databases whose short name matches case-insensitively.
-func matchCaseInsensitive(databases []databaseEntry, name string) []databaseEntry {
- var result []databaseEntry
- lower := strings.ToLower(name)
- for _, db := range databases {
- if strings.ToLower(extractDatabaseName(db.Name)) == lower {
- result = append(result, db)
- }
- }
- return result
-}
-
-// matchSubstring returns databases whose short name contains the input as a substring.
-func matchSubstring(databases []databaseEntry, name string) []databaseEntry {
- var result []databaseEntry
- lower := strings.ToLower(name)
- for _, db := range databases {
- if strings.Contains(strings.ToLower(extractDatabaseName(db.Name)), lower) {
- result = append(result, db)
- }
- }
- return result
-}
-
-// extractDatabaseName extracts the database name from a resource name like "instances/prod-pg/databases/employee_db".
-func extractDatabaseName(resourceName string) string {
- parts := strings.Split(resourceName, "/")
- if len(parts) >= 4 {
- return parts[3]
- }
- return resourceName
-}
-
-// extractShortName extracts the last segment from a resource name like "instances/prod-pg" or "projects/hr-system".
-func extractShortName(resourceName string) string {
- parts := strings.Split(resourceName, "/")
- if len(parts) >= 2 {
- return parts[len(parts)-1]
- }
- return resourceName
-}
-
-// selectDataSource picks READ_ONLY if available, otherwise ADMIN.
-func selectDataSource(dataSources []dataSource) string {
- var adminID string
- for _, ds := range dataSources {
- if ds.Type == "READ_ONLY" {
- return ds.ID
- }
- if ds.Type == "ADMIN" {
- adminID = ds.ID
- }
- }
- return adminID
-}
-
// formatQueryOutput formats a successful query result as text header + JSON body.
func formatQueryOutput(statement, resourceName string, output *QueryOutput) string {
var sb strings.Builder
@@ -441,25 +155,6 @@ func formatToolError(err error) *mcp.CallToolResult {
}
}
-// formatAmbiguousResult returns an MCP result for ambiguous database matches.
-func formatAmbiguousResult(database string, candidates []Candidate) *mcp.CallToolResult {
- result := struct {
- Code string `json:"code"`
- Message string `json:"message"`
- Candidates []Candidate `json:"candidates"`
- }{
- Code: "AMBIGUOUS_TARGET",
- Message: fmt.Sprintf("Multiple databases match %q. Specify instance or project to narrow.", database),
- Candidates: candidates,
- }
-
- jsonBytes, _ := json.MarshalIndent(result, "", " ")
- return &mcp.CallToolResult{
- Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},
- IsError: true,
- }
-}
-
// queryResponse is the typed response from the SQL Query API.
type queryResponse struct {
Results []queryResult `json:"results"`
diff --git a/backend/api/mcp/tool_query_test.go b/backend/api/mcp/tool_query_test.go
index 7e83edeba2..0cf337c9d0 100644
--- a/backend/api/mcp/tool_query_test.go
+++ b/backend/api/mcp/tool_query_test.go
@@ -181,34 +181,40 @@ func mockQueryServer(databases []map[string]any, queryResp map[string]any) http.
func TestBuildDatabaseFilter(t *testing.T) {
tests := []struct {
- name string
- input QueryInput
- expect string
+ name string
+ database string
+ instance string
+ project string
+ expect string
}{
{
- name: "database only",
- input: QueryInput{Database: "employee_db"},
- expect: `name.contains("employee_db")`,
+ name: "database only",
+ database: "employee_db",
+ expect: `name.contains("employee_db")`,
},
{
- name: "with instance",
- input: QueryInput{Database: "employee_db", Instance: "prod-pg"},
- expect: `name.contains("employee_db") && instance == "instances/prod-pg"`,
+ name: "with instance",
+ database: "employee_db",
+ instance: "prod-pg",
+ expect: `name.contains("employee_db") && instance == "instances/prod-pg"`,
},
{
- name: "with project",
- input: QueryInput{Database: "employee_db", Project: "hr-system"},
- expect: `name.contains("employee_db") && project == "projects/hr-system"`,
+ name: "with project",
+ database: "employee_db",
+ project: "hr-system",
+ expect: `name.contains("employee_db") && project == "projects/hr-system"`,
},
{
- name: "with instance and project",
- input: QueryInput{Database: "employee_db", Instance: "prod-pg", Project: "hr-system"},
- expect: `name.contains("employee_db") && instance == "instances/prod-pg" && project == "projects/hr-system"`,
+ name: "with instance and project",
+ database: "employee_db",
+ instance: "prod-pg",
+ project: "hr-system",
+ expect: `name.contains("employee_db") && instance == "instances/prod-pg" && project == "projects/hr-system"`,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
- got := buildDatabaseFilter(tc.input)
+ got := buildDatabaseFilter(tc.database, tc.instance, tc.project)
require.Equal(t, tc.expect, got)
})
}
@@ -221,7 +227,7 @@ func TestQueryDatabase_SingleMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), "employee_db", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -234,7 +240,7 @@ func TestQueryDatabase_CaseInsensitiveMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "Employee_DB"})
+ resolved, err := s.resolveDatabase(testContext(), "Employee_DB", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -246,7 +252,7 @@ func TestQueryDatabase_SubstringMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee"})
+ resolved, err := s.resolveDatabase(testContext(), "employee", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -258,7 +264,7 @@ func TestQueryDatabase_NotFound(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- _, err := s.resolveDatabase(testContext(), QueryInput{Database: "nonexistent"})
+ _, err := s.resolveDatabase(testContext(), "nonexistent", "", "")
require.Error(t, err)
var te *toolError
@@ -273,10 +279,7 @@ func TestQueryDatabase_NotFoundWithFilters(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- _, err := s.resolveDatabase(testContext(), QueryInput{
- Database: "employee_db",
- Instance: "nonexistent-instance",
- })
+ _, err := s.resolveDatabase(testContext(), "employee_db", "nonexistent-instance", "")
require.Error(t, err)
var te *toolError
@@ -289,7 +292,7 @@ func TestQueryDatabase_MissingWorkspaceID(t *testing.T) {
s := newTestServerWithMock(t, http.NotFoundHandler())
// Use context.Background() — no workspace ID set.
- _, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ _, err := s.resolveDatabase(context.Background(), "employee_db", "", "")
require.Error(t, err)
var te *toolError
@@ -308,7 +311,7 @@ func TestQueryDatabase_WorkspacePermissionDenied(t *testing.T) {
})
s := newTestServerWithMock(t, handler)
- _, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ _, err := s.resolveDatabase(testContext(), "employee_db", "", "")
require.Error(t, err)
var te *toolError
@@ -324,7 +327,7 @@ func TestQueryDatabase_Ambiguous(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), "employee_db", "", "")
require.NoError(t, err)
require.True(t, resolved.ambiguous)
require.Len(t, resolved.candidates, 2)
@@ -341,10 +344,7 @@ func TestQueryDatabase_AmbiguousWithInstance(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{
- Database: "employee_db",
- Instance: "prod-pg",
- })
+ resolved, err := s.resolveDatabase(testContext(), "employee_db", "prod-pg", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -357,7 +357,7 @@ func TestQueryDatabase_ReadOnlyDatasource(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), "employee_db", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "ds-ro-1", resolved.dataSourceID)
@@ -369,7 +369,7 @@ func TestQueryDatabase_AdminFallback(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), "employee_db", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "ds-admin-1", resolved.dataSourceID)
@@ -446,7 +446,7 @@ func TestQueryDatabase_ExactMatchPriority(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee"})
+ resolved, err := s.resolveDatabase(testContext(), "employee", "", "")
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee", resolved.resourceName)
diff --git a/backend/api/mcp/tool_resolve.go b/backend/api/mcp/tool_resolve.go
new file mode 100644
index 0000000000..4e8b9a3747
--- /dev/null
+++ b/backend/api/mcp/tool_resolve.go
@@ -0,0 +1,319 @@
+package mcp
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "strings"
+ "time"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "github.com/pkg/errors"
+)
+
+const resolveTimeout = 30 * time.Second
+
+// Candidate represents a database match for ambiguous resolution.
+type Candidate struct {
+ Database string `json:"database"`
+ Instance string `json:"instance"`
+ Project string `json:"project"`
+ Engine string `json:"engine"`
+}
+
+// resolvedDatabase holds the result of database resolution.
+type resolvedDatabase struct {
+ resourceName string
+ dataSourceID string
+ ambiguous bool
+ candidates []Candidate
+ dataSourceIDs map[string]string // resourceName -> dataSourceID (populated when ambiguous)
+}
+
+// listDatabasesResponse is the typed response from ListDatabases API.
+type listDatabasesResponse struct {
+ Databases []databaseEntry `json:"databases"`
+ NextPageToken string `json:"nextPageToken,omitempty"`
+}
+
+// databaseEntry represents a database in the ListDatabases response.
+type databaseEntry struct {
+ Name string `json:"name"`
+ Project string `json:"project"`
+ InstanceResource instanceResource `json:"instanceResource"`
+}
+
+// instanceResource holds instance details including data sources.
+type instanceResource struct {
+ Name string `json:"name"`
+ Engine string `json:"engine"`
+ DataSources []dataSource `json:"dataSources"`
+}
+
+// dataSource represents a database data source.
+type dataSource struct {
+ ID string `json:"id"`
+ Type string `json:"type"`
+}
+
+// buildDatabaseFilter builds a CEL filter expression for ListDatabases.
+func buildDatabaseFilter(database, instance, project string) string {
+ // name.contains does substring matching server-side.
+ filter := fmt.Sprintf("name.contains(%q)", database)
+ if instance != "" {
+ filter += fmt.Sprintf(" && instance == %q", "instances/"+instance)
+ }
+ if project != "" {
+ filter += fmt.Sprintf(" && project == %q", "projects/"+project)
+ }
+ return filter
+}
+
+// listDatabases lists databases matching the filter in the user's workspace.
+// Uses the workspace ID from the JWT token stored in context.
+func (s *Server) listDatabases(ctx context.Context, filter string) ([]databaseEntry, error) {
+ workspaceID := getWorkspaceID(ctx)
+ if workspaceID == "" {
+ return nil, &toolError{
+ Code: "AUTH_ERROR",
+ Message: "workspace ID not found in token",
+ Suggestion: "re-authenticate with Bytebase",
+ }
+ }
+
+ var databases []databaseEntry
+ pageToken := ""
+ for {
+ body := map[string]any{
+ "parent": fmt.Sprintf("workspaces/%s", workspaceID),
+ "filter": filter,
+ "pageSize": 1000,
+ }
+ if pageToken != "" {
+ body["pageToken"] = pageToken
+ }
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.DatabaseService/ListDatabases", body)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to list databases")
+ }
+ if resp.Status == http.StatusForbidden {
+ return nil, &toolError{
+ Code: "PERMISSION_DENIED",
+ Message: "you don't have permission to list databases in this workspace",
+ Suggestion: "ask your workspace admin to grant you the bb.databases.list permission",
+ }
+ }
+ if resp.Status >= 400 {
+ return nil, errors.Errorf("failed to list databases: HTTP %d: %s", resp.Status, parseError(resp.Body))
+ }
+
+ var listResp listDatabasesResponse
+ if err := json.Unmarshal(resp.Body, &listResp); err != nil {
+ return nil, errors.Wrap(err, "failed to parse database list")
+ }
+ databases = append(databases, listResp.Databases...)
+
+ if listResp.NextPageToken == "" {
+ break
+ }
+ pageToken = listResp.NextPageToken
+ }
+ return databases, nil
+}
+
+// matchDatabases applies tiered matching (exact > case-insensitive > substring) and
+// returns the resolved result, an ambiguous result, or a not-found error.
+func matchDatabases(databases []databaseEntry, database, instance, project string) (*resolvedDatabase, error) {
+ matches := matchExact(databases, database)
+ if len(matches) == 0 {
+ matches = matchCaseInsensitive(databases, database)
+ }
+ if len(matches) == 0 {
+ matches = matchSubstring(databases, database)
+ }
+
+ if len(matches) == 0 {
+ suggestion := "check the database name or use search_api to list available databases"
+ if instance != "" || project != "" {
+ suggestion = "try without instance/project filters, or use search_api to list available databases"
+ }
+ return nil, &toolError{
+ Code: "DATABASE_NOT_FOUND",
+ Message: fmt.Sprintf("no database matching %q", database),
+ Suggestion: suggestion,
+ }
+ }
+
+ if len(matches) > 1 {
+ return buildAmbiguousResult(matches), nil
+ }
+
+ db := matches[0]
+ return &resolvedDatabase{
+ resourceName: db.Name,
+ dataSourceID: selectDataSource(db.InstanceResource.DataSources),
+ }, nil
+}
+
+// buildAmbiguousResult constructs a resolvedDatabase with multiple candidates.
+func buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {
+ candidates := make([]Candidate, 0, len(matches))
+ dsIDs := make(map[string]string, len(matches))
+ for _, db := range matches {
+ candidates = append(candidates, Candidate{
+ Database: db.Name,
+ Instance: extractShortName(db.InstanceResource.Name),
+ Project: extractShortName(db.Project),
+ Engine: db.InstanceResource.Engine,
+ })
+ dsIDs[db.Name] = selectDataSource(db.InstanceResource.DataSources)
+ }
+ return &resolvedDatabase{ambiguous: true, candidates: candidates, dataSourceIDs: dsIDs}
+}
+
+// resolveDatabase resolves a database name to a unique resource using tiered matching.
+func (s *Server) resolveDatabase(ctx context.Context, database, instance, project string) (*resolvedDatabase, error) {
+ databases, err := s.listDatabases(ctx, buildDatabaseFilter(database, instance, project))
+ if err != nil {
+ return nil, err
+ }
+ return matchDatabases(databases, database, instance, project)
+}
+
+// elicitDatabaseChoice prompts the user to pick from ambiguous database matches
+// using MCP elicitation. Returns an error if elicitation is unsupported, the user
+// cancels/declines, or the selection is invalid.
+func (*Server) elicitDatabaseChoice(ctx context.Context, req *mcp.CallToolRequest, resolved *resolvedDatabase) (*resolvedDatabase, error) {
+ // Build enum values and a lookup map from display label to resource name.
+ enumValues := make([]any, 0, len(resolved.candidates))
+ resourceByLabel := make(map[string]string, len(resolved.candidates))
+ for _, c := range resolved.candidates {
+ label := fmt.Sprintf("%s (%s, %s)", c.Database, c.Instance, c.Engine)
+ enumValues = append(enumValues, label)
+ resourceByLabel[label] = c.Database
+ }
+
+ result, err := req.Session.Elicit(ctx, &mcp.ElicitParams{
+ Mode: "form",
+ Message: "Multiple databases match. Which one do you want to query?",
+ RequestedSchema: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "database": map[string]any{
+ "type": "string",
+ "enum": enumValues,
+ "description": "Select the target database",
+ },
+ },
+ "required": []string{"database"},
+ },
+ })
+ if err != nil {
+ return nil, err
+ }
+ if result.Action != "accept" {
+ return nil, errors.Errorf("user %sd database selection", result.Action)
+ }
+
+ selected, ok := result.Content["database"].(string)
+ if !ok {
+ return nil, errors.New("invalid database selection")
+ }
+
+ resourceName, ok := resourceByLabel[selected]
+ if !ok {
+ return nil, errors.Errorf("unknown database selection: %s", selected)
+ }
+
+ return &resolvedDatabase{
+ resourceName: resourceName,
+ dataSourceID: resolved.dataSourceIDs[resourceName],
+ }, nil
+}
+
+// matchExact returns databases whose short name exactly matches the input.
+func matchExact(databases []databaseEntry, name string) []databaseEntry {
+ var result []databaseEntry
+ for _, db := range databases {
+ if extractDatabaseName(db.Name) == name {
+ result = append(result, db)
+ }
+ }
+ return result
+}
+
+// matchCaseInsensitive returns databases whose short name matches case-insensitively.
+func matchCaseInsensitive(databases []databaseEntry, name string) []databaseEntry {
+ var result []databaseEntry
+ lower := strings.ToLower(name)
+ for _, db := range databases {
+ if strings.ToLower(extractDatabaseName(db.Name)) == lower {
+ result = append(result, db)
+ }
+ }
+ return result
+}
+
+// matchSubstring returns databases whose short name contains the input as a substring.
+func matchSubstring(databases []databaseEntry, name string) []databaseEntry {
+ var result []databaseEntry
+ lower := strings.ToLower(name)
+ for _, db := range databases {
+ if strings.Contains(strings.ToLower(extractDatabaseName(db.Name)), lower) {
+ result = append(result, db)
+ }
+ }
+ return result
+}
+
+// extractDatabaseName extracts the database name from a resource name like "instances/prod-pg/databases/employee_db".
+func extractDatabaseName(resourceName string) string {
+ parts := strings.Split(resourceName, "/")
+ if len(parts) >= 4 {
+ return parts[3]
+ }
+ return resourceName
+}
+
+// extractShortName extracts the last segment from a resource name like "instances/prod-pg" or "projects/hr-system".
+func extractShortName(resourceName string) string {
+ parts := strings.Split(resourceName, "/")
+ if len(parts) >= 2 {
+ return parts[len(parts)-1]
+ }
+ return resourceName
+}
+
+// selectDataSource picks READ_ONLY if available, otherwise ADMIN.
+func selectDataSource(dataSources []dataSource) string {
+ var adminID string
+ for _, ds := range dataSources {
+ if ds.Type == "READ_ONLY" {
+ return ds.ID
+ }
+ if ds.Type == "ADMIN" {
+ adminID = ds.ID
+ }
+ }
+ return adminID
+}
+
+// formatAmbiguousResult returns an MCP result for ambiguous database matches.
+func formatAmbiguousResult(database string, candidates []Candidate) *mcp.CallToolResult {
+ result := struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ Candidates []Candidate `json:"candidates"`
+ }{
+ Code: "AMBIGUOUS_TARGET",
+ Message: fmt.Sprintf("Multiple databases match %q. Specify instance or project to narrow.", database),
+ Candidates: candidates,
+ }
+
+ jsonBytes, _ := json.MarshalIndent(result, "", " ")
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},
+ IsError: true,
+ }
+}