Skip to content

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

feat(mcp): simplify resolveDatabase with workspace-scoped ListDatabases (#19823)

Vincent Huang625f25b802ff
diff --git a/backend/api/mcp/server.go b/backend/api/mcp/server.go
index c5921c81f1..1c3f10580e 100644
--- a/backend/api/mcp/server.go
+++ b/backend/api/mcp/server.go
@@ -130,9 +130,16 @@ func (s *Server) authMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
return echo.NewHTTPError(http.StatusUnauthorized, "invalid token: missing subject")
}
- // Store access token in request context for MCP tools to forward auth
+ // Extract workspace ID from token claims.
+ workspaceID, ok := claims["workspace_id"].(string)
+ if !ok {
+ workspaceID = ""
+ }
+
+ // Store access token and workspace ID in request context for MCP tools.
ctx := c.Request().Context()
ctx = withAccessToken(ctx, tokenStr)
+ ctx = withWorkspaceID(ctx, workspaceID)
c.SetRequest(c.Request().WithContext(ctx))
return next(c)
diff --git a/backend/api/mcp/tool_http.go b/backend/api/mcp/tool_http.go
index 62fe49d45b..bff9e1b36d 100644
--- a/backend/api/mcp/tool_http.go
+++ b/backend/api/mcp/tool_http.go
@@ -109,3 +109,19 @@ func getAccessToken(ctx context.Context) string {
}
return ""
}
+
+// Context key for storing the workspace ID.
+type workspaceIDKey struct{}
+
+// withWorkspaceID adds the workspace ID to the context.
+func withWorkspaceID(ctx context.Context, id string) context.Context {
+ return context.WithValue(ctx, workspaceIDKey{}, id)
+}
+
+// getWorkspaceID retrieves the workspace ID from the context.
+func getWorkspaceID(ctx context.Context) string {
+ if id, ok := ctx.Value(workspaceIDKey{}).(string); ok {
+ return id
+ }
+ return ""
+}
diff --git a/backend/api/mcp/tool_http_test.go b/backend/api/mcp/tool_http_test.go
index d90356ad26..9572dc27d3 100644
--- a/backend/api/mcp/tool_http_test.go
+++ b/backend/api/mcp/tool_http_test.go
@@ -85,3 +85,19 @@ func TestApiRequest_RawMessage(t *testing.T) {
require.Equal(t, int64(12345), r.ID)
require.Equal(t, int64(9999999999), r.Count)
}
+
+// testContext returns a context with a test workspace ID.
+func testContext() context.Context {
+ return withWorkspaceID(context.Background(), "wk-test")
+}
+
+func TestWorkspaceIDContext(t *testing.T) {
+ ctx := context.Background()
+
+ // Empty context returns empty string.
+ require.Equal(t, "", getWorkspaceID(ctx))
+
+ // Round-trips through context.
+ ctx = withWorkspaceID(ctx, "wk-test-123")
+ require.Equal(t, "wk-test-123", getWorkspaceID(ctx))
+}
diff --git a/backend/api/mcp/tool_query.go b/backend/api/mcp/tool_query.go
index ab8289a49f..9bc66e5cd4 100644
--- a/backend/api/mcp/tool_query.go
+++ b/backend/api/mcp/tool_query.go
@@ -133,7 +133,8 @@ func (s *Server) handleQueryDatabase(ctx context.Context, req *mcp.CallToolReque
// listDatabasesResponse is the typed response from ListDatabases API.
type listDatabasesResponse struct {
- Databases []databaseEntry `json:"databases"`
+ Databases []databaseEntry `json:"databases"`
+ NextPageToken string `json:"nextPageToken,omitempty"`
}
// databaseEntry represents a database in the ListDatabases response.
@@ -169,31 +170,61 @@ func buildDatabaseFilter(input QueryInput) string {
return filter
}
-// resolveDatabase resolves a database name to a unique resource using tiered matching.
-func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolvedDatabase, error) {
- body := map[string]any{
- "parent": "workspaces/-",
- "filter": buildDatabaseFilter(input),
- "pageSize": 1000,
- }
- 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 >= 400 {
- return nil, errors.Errorf("failed to list databases: HTTP %d: %s", resp.Status, parseError(resp.Body))
+// 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 listResp listDatabasesResponse
- if err := json.Unmarshal(resp.Body, &listResp); err != nil {
- return nil, errors.Wrap(err, "failed to parse database list")
- }
+ 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))
+ }
- // Server-side filter already narrows by name substring and instance/project.
- // Apply client-side tiered matching to pick the best result.
- databases := listResp.Databases
+ 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
+}
- // Tiered matching: exact -> case-insensitive exact -> substring.
+// 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)
@@ -215,21 +246,9 @@ func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolv
}
if len(matches) > 1 {
- 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}, nil
+ return buildAmbiguousResult(matches), nil
}
- // Single match.
db := matches[0]
return &resolvedDatabase{
resourceName: db.Name,
@@ -237,6 +256,31 @@ func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolv
}, 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.
diff --git a/backend/api/mcp/tool_query_test.go b/backend/api/mcp/tool_query_test.go
index 6de9cc45fa..7e83edeba2 100644
--- a/backend/api/mcp/tool_query_test.go
+++ b/backend/api/mcp/tool_query_test.go
@@ -44,25 +44,39 @@ func makeDatabaseWithDualDS(name, instanceName, project, engine, adminDSID, read
}
}
-// mockListDatabases returns an HTTP handler that serves a ListDatabases response.
-// It applies basic filter awareness: if the request contains a "filter" field with
-// an instance constraint, only matching databases are returned.
+// mockListDatabases returns an HTTP handler that serves ListDatabases requests.
+// Supports both workspace-scoped (parent: "workspaces/...") and project-scoped parents.
func mockListDatabases(databases []map[string]any) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+
var reqBody struct {
+ Parent string `json:"parent"`
Filter string `json:"filter"`
}
_ = json.NewDecoder(r.Body).Decode(&reqBody)
- result := databases
+ // For workspace-scoped requests, include all databases.
+ // For project-scoped requests, filter by parent project.
+ var scoped []map[string]any
+ if strings.HasPrefix(reqBody.Parent, "workspaces/") {
+ scoped = databases
+ } else {
+ for _, db := range databases {
+ proj, ok := db["project"].(string)
+ if ok && proj == reqBody.Parent {
+ scoped = append(scoped, db)
+ }
+ }
+ }
+
+ result := scoped
if reqBody.Filter != "" {
- result = applyMockFilter(databases, reqBody.Filter)
+ result = applyMockFilter(scoped, reqBody.Filter)
}
- resp := map[string]any{"databases": result}
- w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
- _ = json.NewEncoder(w).Encode(resp)
+ _ = json.NewEncoder(w).Encode(map[string]any{"databases": result})
})
}
@@ -83,10 +97,6 @@ func applyMockFilter(databases []map[string]any, filter string) []map[string]any
if !ok {
continue
}
- project, ok := db["project"].(string)
- if !ok {
- continue
- }
match := true
// Check name.contains("x") — substring match
@@ -117,7 +127,7 @@ func applyMockFilter(databases []map[string]any, filter string) []map[string]any
end := strings.Index(filter[start:], `"`)
if end > 0 {
expected := filter[start : start+end]
- if project != expected {
+ if proj, ok := db["project"].(string); ok && proj != expected {
match = false
}
}
@@ -169,6 +179,41 @@ 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: "database only",
+ input: QueryInput{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 project",
+ input: QueryInput{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"`,
+ },
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ got := buildDatabaseFilter(tc.input)
+ require.Equal(t, tc.expect, got)
+ })
+ }
+}
+
func TestQueryDatabase_SingleMatch(t *testing.T) {
databases := []map[string]any{
makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
@@ -176,7 +221,7 @@ func TestQueryDatabase_SingleMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -189,7 +234,7 @@ func TestQueryDatabase_CaseInsensitiveMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "Employee_DB"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "Employee_DB"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -201,7 +246,7 @@ func TestQueryDatabase_SubstringMatch(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
@@ -213,7 +258,7 @@ func TestQueryDatabase_NotFound(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- _, err := s.resolveDatabase(context.Background(), QueryInput{Database: "nonexistent"})
+ _, err := s.resolveDatabase(testContext(), QueryInput{Database: "nonexistent"})
require.Error(t, err)
var te *toolError
@@ -228,7 +273,7 @@ func TestQueryDatabase_NotFoundWithFilters(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- _, err := s.resolveDatabase(context.Background(), QueryInput{
+ _, err := s.resolveDatabase(testContext(), QueryInput{
Database: "employee_db",
Instance: "nonexistent-instance",
})
@@ -240,6 +285,38 @@ func TestQueryDatabase_NotFoundWithFilters(t *testing.T) {
require.Contains(t, te.Suggestion, "without instance/project filters")
}
+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"})
+ require.Error(t, err)
+
+ var te *toolError
+ require.ErrorAs(t, err, &te)
+ require.Equal(t, "AUTH_ERROR", te.Code)
+}
+
+func TestQueryDatabase_WorkspacePermissionDenied(t *testing.T) {
+ handler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusForbidden)
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "message": "permission denied",
+ "code": "PERMISSION_DENIED",
+ })
+ })
+ s := newTestServerWithMock(t, handler)
+
+ _, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
+ require.Error(t, err)
+
+ var te *toolError
+ require.ErrorAs(t, err, &te)
+ require.Equal(t, "PERMISSION_DENIED", te.Code)
+ require.Contains(t, te.Suggestion, "bb.databases.list")
+}
+
func TestQueryDatabase_Ambiguous(t *testing.T) {
databases := []map[string]any{
makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
@@ -247,7 +324,7 @@ func TestQueryDatabase_Ambiguous(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
require.NoError(t, err)
require.True(t, resolved.ambiguous)
require.Len(t, resolved.candidates, 2)
@@ -264,7 +341,7 @@ func TestQueryDatabase_AmbiguousWithInstance(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{
Database: "employee_db",
Instance: "prod-pg",
})
@@ -280,7 +357,7 @@ func TestQueryDatabase_ReadOnlyDatasource(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "ds-ro-1", resolved.dataSourceID)
@@ -292,7 +369,7 @@ func TestQueryDatabase_AdminFallback(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee_db"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "ds-admin-1", resolved.dataSourceID)
@@ -347,7 +424,7 @@ func TestQueryDatabase_LimitNormalization(t *testing.T) {
qr := makeQueryResponse([]string{"id"}, []string{"int4"}, [][]any{{"1"}}, "0.001s")
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT 1",
Limit: 2000,
@@ -369,7 +446,7 @@ func TestQueryDatabase_ExactMatchPriority(t *testing.T) {
}
s := newTestServerWithMock(t, mockListDatabases(databases))
- resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee"})
+ resolved, err := s.resolveDatabase(testContext(), QueryInput{Database: "employee"})
require.NoError(t, err)
require.False(t, resolved.ambiguous)
require.Equal(t, "instances/prod-pg/databases/employee", resolved.resourceName)
@@ -390,7 +467,7 @@ func TestQueryDatabase_FullFlow(t *testing.T) {
)
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT id, name FROM users",
})
@@ -426,7 +503,7 @@ func TestQueryDatabase_EmptyResult(t *testing.T) {
)
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT * FROM users WHERE id = -1",
})
@@ -452,7 +529,7 @@ func TestQueryDatabase_Truncation(t *testing.T) {
qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.050s")
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT id FROM users",
// Default limit is 100.
@@ -480,7 +557,7 @@ func TestQueryDatabase_CustomLimit(t *testing.T) {
qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.020s")
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT id FROM users",
Limit: 50,
@@ -505,7 +582,7 @@ func TestQueryDatabase_LimitCappedAt1000(t *testing.T) {
qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.003s")
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT id FROM users",
Limit: 2000,
@@ -537,7 +614,7 @@ func TestQueryDatabase_QueryError(t *testing.T) {
})
s := newTestServerWithMock(t, handler)
- result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, _, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELEC * FROM users",
})
@@ -566,7 +643,7 @@ func TestQueryDatabase_PermissionDenied(t *testing.T) {
})
s := newTestServerWithMock(t, handler)
- result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, _, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT * FROM users",
})
@@ -591,7 +668,7 @@ func TestQueryDatabase_MaskedValues(t *testing.T) {
)
s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- _, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ _, structured, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT id, ssn, name FROM users",
})
diff --git a/docs/plans/2026-03-13-mcp-query-database-tool.md b/docs/plans/2026-03-13-mcp-query-database-tool.md
new file mode 100644
index 0000000000..31998c65e2
--- /dev/null
+++ b/docs/plans/2026-03-13-mcp-query-database-tool.md
@@ -0,0 +1,1613 @@
+# MCP `query_database` Tool Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a composite `query_database` MCP tool that resolves databases and executes SQL queries in a single call, replacing the current 3+ tool call workflow.
+
+**Architecture:** Extract shared HTTP plumbing from `tool_call.go` into `tool_http.go`, then build `tool_query.go` on top. The query tool calls internal Bytebase API endpoints (DatabaseService/ListDatabases, SQLService/Query) via HTTP, keeping MCP loosely coupled from service packages. Tests use `httptest.NewServer` to mock internal APIs.
+
+**Tech Stack:** Go, MCP Go SDK (`github.com/modelcontextprotocol/go-sdk/mcp`), `github.com/stretchr/testify`, `net/http/httptest`
+
+**Design doc:** `/Users/vincent/CLAUDE_BB/plans/2026-03-13-mcp-query-database-tool-design.md`
+
+---
+
+### Task 1: Extract shared HTTP helpers into `tool_http.go`
+
+**Files:**
+- Create: `backend/api/mcp/tool_http.go`
+- Modify: `backend/api/mcp/tool_call.go`
+
+**Step 1: Create `tool_http.go` with shared HTTP plumbing**
+
+Read `backend/api/mcp/tool_call.go` for the existing HTTP logic (lines 70-148). Extract into a new file:
+
+```go
+package mcp
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "time"
+
+ "github.com/pkg/errors"
+)
+
+// apiResponse holds a raw API response.
+type apiResponse struct {
+ Status int
+ Body json.RawMessage
+}
+
+// toolError represents a structured error with actionable suggestion.
+type toolError struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ Suggestion string `json:"suggestion,omitempty"`
+}
+
+func (e *toolError) Error() string {
+ if e.Suggestion != "" {
+ return fmt.Sprintf("%s: %s (%s)", e.Code, e.Message, e.Suggestion)
+ }
+ return fmt.Sprintf("%s: %s", e.Code, e.Message)
+}
+
+// apiRequest executes an authenticated POST to an internal Bytebase endpoint.
+func (s *Server) apiRequest(ctx context.Context, path string, body any) (*apiResponse, error) {
+ var bodyReader io.Reader
+ if body != nil {
+ bodyBytes, err := json.Marshal(body)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to marshal request body")
+ }
+ bodyReader = bytes.NewReader(bodyBytes)
+ } else {
+ bodyReader = bytes.NewReader([]byte("{}"))
+ }
+
+ url := fmt.Sprintf("http://localhost:%d%s", s.profile.Port, path)
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bodyReader)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to create HTTP request")
+ }
+
+ httpReq.Header.Set("Content-Type", "application/json")
+ httpReq.Header.Set("Connect-Protocol-Version", "1")
+
+ if token := getAccessToken(ctx); token != "" {
+ httpReq.Header.Set("Authorization", "Bearer "+token)
+ }
+
+ client := &http.Client{Timeout: 30 * time.Second}
+ resp, err := client.Do(httpReq)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to execute API request")
+ }
+ defer resp.Body.Close()
+
+ respBody, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to read response body")
+ }
+
+ return &apiResponse{
+ Status: resp.StatusCode,
+ Body: json.RawMessage(respBody),
+ }, nil
+}
+
+// parseError extracts a structured error from an API error response body.
+func parseError(body json.RawMessage) string {
+ var errResp struct {
+ Message string `json:"message"`
+ Code string `json:"code"`
+ }
+ if err := json.Unmarshal(body, &errResp); err == nil {
+ if errResp.Message != "" {
+ return errResp.Message
+ }
+ if errResp.Code != "" {
+ return errResp.Code
+ }
+ }
+ return ""
+}
+```
+
+**Step 2: Refactor `tool_call.go` to use `apiRequest`**
+
+Replace the inline HTTP logic in `handleCallAPI` (lines 70-148) with a call to `s.apiRequest()`. Keep `CallInput`, `CallOutput`, `formatCallOutput`, `isBinaryContentType` in `tool_call.go`. Remove `withAccessToken`/`getAccessToken` from `tool_call.go` (they're already there, move the context helpers to `tool_http.go`).
+
+The refactored `handleCallAPI` should look like:
+
+```go
+func (s *Server) handleCallAPI(ctx context.Context, _ *mcp.CallToolRequest, input CallInput) (*mcp.CallToolResult, any, error) {
+ if input.OperationID == "" {
+ return nil, nil, errors.New("operationId is required")
+ }
+
+ endpoint, ok := s.openAPIIndex.GetEndpoint(input.OperationID)
+ if !ok {
+ return nil, nil, errors.Errorf("unknown operation %s, use search_api to find valid operations", input.OperationID)
+ }
+
+ body := input.Body
+ if body == nil {
+ body = make(map[string]any)
+ }
+
+ resp, err := s.apiRequest(ctx, endpoint.Path, body)
+ if err != nil {
+ return nil, nil, err
+ }
+
+ // Check for binary response
+ contentType := http.DetectContentType(resp.Body)
+ if isBinaryContentType(contentType) {
+ return nil, nil, errors.Errorf("binary response not supported (content-type: %s)", contentType)
+ }
+
+ // Parse JSON response
+ var respJSON any
+ if len(resp.Body) > 0 {
+ if err := json.Unmarshal(resp.Body, &respJSON); err != nil {
+ respJSON = string(resp.Body)
+ }
+ }
+
+ output := CallOutput{
+ Status: resp.Status,
+ Response: respJSON,
+ }
+
+ if resp.Status >= 400 {
+ output.Error = parseError(resp.Body)
+ if output.Error == "" {
+ output.Error = fmt.Sprintf("HTTP %d", resp.Status)
+ }
+ }
+
+ text := formatCallOutput(output, endpoint)
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: text}},
+ }, output, nil
+}
+```
+
+Note: The binary content type check changes slightly — the original checked the response `Content-Type` header, but `apiRequest` doesn't return headers. Two options:
+- (a) Add `Headers http.Header` to `apiResponse` — preferred, minimal change.
+- (b) Use `http.DetectContentType` on the body — less accurate.
+
+Go with option (a): add `Headers http.Header` to `apiResponse` and set it in `apiRequest`.
+
+**Step 3: Move context helpers to `tool_http.go`**
+
+Move `accessTokenKey`, `withAccessToken`, `getAccessToken` from `tool_call.go` (lines 190-204) to `tool_http.go`. They're used by both `tool_call.go` and the new `tool_query.go`.
+
+**Step 4: Run existing tests to verify refactor didn't break anything**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run ^TestFormatCallOutput`
+
+Expected: Both `TestFormatCallOutput` and `TestFormatCallOutputError` PASS.
+
+**Step 5: Run full MCP test suite**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/...`
+
+Expected: All existing tests PASS.
+
+**Step 6: Run lint**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: No lint errors.
+
+**Step 7: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_http.go backend/api/mcp/tool_call.go
+git commit -m "refactor(mcp): extract shared HTTP helpers into tool_http.go
+
+Extract apiRequest, apiResponse, toolError, parseError, and context
+helpers from tool_call.go into tool_http.go for reuse by new tools."
+```
+
+---
+
+### Task 2: Write `tool_http_test.go`
+
+**Files:**
+- Create: `backend/api/mcp/tool_http_test.go`
+
+**Step 1: Write tests for shared HTTP helpers**
+
+```go
+package mcp
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/component/config"
+)
+
+// newTestServerWithMock creates an MCP Server pointing at a mock HTTP backend.
+// Returns the Server and a cleanup function.
+func newTestServerWithMock(t *testing.T, handler http.Handler) *Server {
+ t.Helper()
+ mockServer := httptest.NewServer(handler)
+ t.Cleanup(mockServer.Close)
+
+ // Parse the port from mock server URL
+ // httptest.NewServer URL is like "http://127.0.0.1:PORT"
+ var port int
+ _, err := fmt.Sscanf(mockServer.URL, "http://127.0.0.1:%d", &port)
+ require.NoError(t, err)
+
+ profile := &config.Profile{Port: port}
+ // We can't use NewServer here because it loads the OpenAPI index.
+ // Instead, construct the Server directly with only what we need.
+ return &Server{profile: profile}
+}
+
+func TestApiRequest_AuthForwarding(t *testing.T) {
+ var receivedAuth string
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ receivedAuth = r.Header.Get("Authorization")
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte(`{"ok": true}`))
+ })
+
+ s := newTestServerWithMock(t, handler)
+ ctx := withAccessToken(context.Background(), "test-token-123")
+
+ resp, err := s.apiRequest(ctx, "/test/path", map[string]string{"key": "value"})
+ require.NoError(t, err)
+ require.Equal(t, http.StatusOK, resp.Status)
+ require.Equal(t, "Bearer test-token-123", receivedAuth)
+}
+
+func TestApiRequest_ErrorParsing(t *testing.T) {
+ handler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusForbidden)
+ w.Write([]byte(`{"message": "permission denied", "code": "PERMISSION_DENIED"}`))
+ })
+
+ s := newTestServerWithMock(t, handler)
+ resp, err := s.apiRequest(context.Background(), "/test/path", nil)
+ require.NoError(t, err)
+ require.Equal(t, http.StatusForbidden, resp.Status)
+
+ msg := parseError(resp.Body)
+ require.Equal(t, "permission denied", msg)
+}
+
+func TestApiRequest_RawMessage(t *testing.T) {
+ handler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ // Integer value that would become float64 with map[string]any
+ w.Write([]byte(`{"id": 12345, "count": 9999999999}`))
+ })
+
+ s := newTestServerWithMock(t, handler)
+ resp, err := s.apiRequest(context.Background(), "/test/path", nil)
+ require.NoError(t, err)
+
+ // Verify raw JSON is preserved (not decoded to map[string]any)
+ require.Equal(t, json.RawMessage(`{"id": 12345, "count": 9999999999}`), resp.Body)
+
+ // Decode into typed struct to verify integers are preserved
+ var result struct {
+ ID int64 `json:"id"`
+ Count int64 `json:"count"`
+ }
+ err = json.Unmarshal(resp.Body, &result)
+ require.NoError(t, err)
+ require.Equal(t, int64(12345), result.ID)
+ require.Equal(t, int64(9999999999), result.Count)
+}
+```
+
+Note: `newTestServerWithMock` needs `"fmt"` in the import block for `fmt.Sscanf`.
+
+**Step 2: Run tests**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run ^TestApiRequest`
+
+Expected: All 3 tests PASS.
+
+**Step 3: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_http_test.go
+git commit -m "test(mcp): add tests for shared HTTP helpers"
+```
+
+---
+
+### Task 3: Implement `tool_query.go` — types and registration
+
+**Files:**
+- Create: `backend/api/mcp/tool_query.go`
+- Modify: `backend/api/mcp/server.go` (line 63)
+
+**Step 1: Write the failing test for tool registration**
+
+Create `backend/api/mcp/tool_query_test.go`:
+
+```go
+package mcp
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/common"
+ "github.com/bytebase/bytebase/backend/component/config"
+)
+
+func TestQueryDatabaseToolRegistered(t *testing.T) {
+ profile := &config.Profile{Mode: common.ReleaseModeDev}
+ s, err := NewServer(nil, profile, "test-secret")
+ require.NoError(t, err)
+ require.NotNil(t, s)
+ // The tool should be registered without error.
+ // Full handler tests follow in subsequent tasks.
+}
+```
+
+**Step 2: Run test to verify it passes (baseline)**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run ^TestQueryDatabaseToolRegistered`
+
+Expected: PASS (this is a baseline — NewServer already works).
+
+**Step 3: Create `tool_query.go` with types, description, and registration**
+
+```go
+package mcp
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "time"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "github.com/pkg/errors"
+)
+
+const (
+ defaultQueryLimit = 100
+ maxQueryLimit = 1000
+ queryTimeout = 30 * time.Second
+ resolveTimeout = 30 * time.Second
+)
+
+// QueryInput is the input for the query_database tool.
+type QueryInput struct {
+ // Database is the database name or substring to match (required).
+ Database string `json:"database"`
+ // Statement is the SQL query to execute (required).
+ Statement string `json:"statement"`
+ // Instance narrows database resolution to a specific instance (optional).
+ Instance string `json:"instance,omitempty"`
+ // Project narrows database resolution to a specific project (optional).
+ Project string `json:"project,omitempty"`
+ // Limit is the max rows to return (default: 100, max: 1000).
+ Limit int `json:"limit,omitempty"`
+}
+
+// QueryOutput is the structured output for successful queries.
+type QueryOutput struct {
+ Columns []string `json:"columns"`
+ ColumnTypes []string `json:"columnTypes"`
+ Rows [][]any `json:"rows"`
+ RowCount int `json:"rowCount"`
+ Truncated bool `json:"truncated"`
+ 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"`
+}
+
+const queryDatabaseDescription = `Execute SQL queries against Bytebase databases in a single call. Resolves database by name automatically.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| database | Yes | Database name or substring to match |
+| statement | Yes | SQL query to execute |
+| instance | No | Instance name to narrow search |
+| project | No | Project name to narrow search |
+| limit | No | Max rows (default: 100, max: 1000) |
+
+**Examples:**
+query_database(database="employees", statement="SELECT * FROM users LIMIT 10")
+query_database(database="employee_db", instance="prod-pg", statement="SELECT count(*) FROM orders")`
+
+func (s *Server) registerQueryTool() {
+ mcp.AddTool(s.mcpServer, &mcp.Tool{
+ Name: "query_database",
+ Description: queryDatabaseDescription,
+ }, s.handleQueryDatabase)
+}
+
+func (s *Server) handleQueryDatabase(ctx context.Context, _ *mcp.CallToolRequest, input QueryInput) (*mcp.CallToolResult, any, error) {
+ // Validate input
+ if input.Database == "" {
+ return nil, nil, errors.New("database is required")
+ }
+ if input.Statement == "" {
+ return nil, nil, errors.New("statement is required")
+ }
+
+ // Normalize limit
+ limit := input.Limit
+ if limit <= 0 {
+ limit = defaultQueryLimit
+ }
+ if limit > maxQueryLimit {
+ limit = maxQueryLimit
+ }
+
+ // Step 1: Resolve database
+ resolveCtx, resolveCancel := context.WithTimeout(ctx, resolveTimeout)
+ defer resolveCancel()
+
+ resolved, err := s.resolveDatabase(resolveCtx, input)
+ if err != nil {
+ return nil, nil, err
+ }
+
+ // If ambiguous, return candidates
+ if resolved.ambiguous {
+ return s.formatAmbiguousResult(input.Database, resolved.candidates)
+ }
+
+ // Step 2: Execute query
+ queryCtx, queryCancel := context.WithTimeout(ctx, queryTimeout)
+ defer queryCancel()
+
+ output, err := s.executeQuery(queryCtx, resolved, input.Statement, limit)
+ if err != nil {
+ text := fmt.Sprintf("Query failed on %s\n\n%s", resolved.resourceName, err.Error())
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: text}},
+ IsError: true,
+ }, nil, nil
+ }
+
+ // Step 3: Format output
+ text := s.formatQueryOutput(input.Statement, resolved.resourceName, output)
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: text}},
+ }, output, nil
+}
+```
+
+**Step 4: Add stub methods for `resolveDatabase`, `executeQuery`, `formatAmbiguousResult`, `formatQueryOutput`**
+
+These go at the bottom of `tool_query.go`. They will be implemented in Tasks 4 and 5.
+
+```go
+// resolvedDatabase holds the result of database resolution.
+type resolvedDatabase struct {
+ resourceName string // e.g., "instances/prod-pg/databases/employee_db"
+ dataSourceID string // datasource ID to use for queries
+ ambiguous bool // true if multiple matches found
+ candidates []Candidate // populated when ambiguous
+}
+
+func (s *Server) resolveDatabase(_ context.Context, _ QueryInput) (*resolvedDatabase, error) {
+ return nil, errors.New("not implemented")
+}
+
+func (s *Server) executeQuery(_ context.Context, _ *resolvedDatabase, _ string, _ int) (*QueryOutput, error) {
+ return nil, errors.New("not implemented")
+}
+
+func (s *Server) formatAmbiguousResult(database string, candidates []Candidate) (*mcp.CallToolResult, any, error) {
+ 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,
+ }
+ resultJSON, _ := json.MarshalIndent(result, "", " ")
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(resultJSON)}},
+ IsError: true,
+ }, result, nil
+}
+
+func (*Server) formatQueryOutput(statement, resourceName string, output *QueryOutput) string {
+ var sb strings.Builder
+
+ columnList := strings.Join(output.Columns, ", ")
+ fmt.Fprintf(&sb, "Query: %s\n", statement)
+ fmt.Fprintf(&sb, "Database: %s\n", resourceName)
+
+ if output.Truncated {
+ fmt.Fprintf(&sb, "Result: Showing %d rows, %d columns (%s) | %dms\n",
+ output.RowCount, len(output.Columns), columnList, output.LatencyMs)
+ sb.WriteString("Truncated: use limit param for more (max 1000).\n")
+ } else {
+ fmt.Fprintf(&sb, "Result: %d rows, %d columns (%s) | %dms\n",
+ output.RowCount, len(output.Columns), columnList, output.LatencyMs)
+ }
+
+ sb.WriteString("\n")
+ outputJSON, _ := json.Marshal(output)
+ sb.Write(outputJSON)
+
+ return sb.String()
+}
+```
+
+**Step 5: Register the tool in `server.go`**
+
+Modify `backend/api/mcp/server.go` line 63, add `s.registerQueryTool()`:
+
+```go
+func (s *Server) registerTools() {
+ s.registerSearchTool()
+ s.registerCallTool()
+ s.registerSkillTool()
+ s.registerQueryTool()
+}
+```
+
+**Step 6: Run tests and lint**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run ^TestQueryDatabaseToolRegistered`
+
+Expected: PASS.
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: No errors (stub methods may have unused params — prefix with `_` if lint complains).
+
+**Step 7: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_query.go backend/api/mcp/tool_query_test.go backend/api/mcp/server.go
+git commit -m "feat(mcp): add query_database tool skeleton with types and registration"
+```
+
+---
+
+### Task 4: Implement database resolution (`resolveDatabase`)
+
+**Files:**
+- Modify: `backend/api/mcp/tool_query.go`
+- Modify: `backend/api/mcp/tool_query_test.go`
+
+**Step 1: Write failing tests for database resolution**
+
+Add to `tool_query_test.go`. These tests use `httptest.NewServer` to mock the `DatabaseService/ListDatabases` endpoint.
+
+Key: The internal endpoint path is `/bytebase.v1.DatabaseService/ListDatabases` (Connect RPC POST). The request body has `parent` and optionally `filter`. The response is JSON with a `databases` array.
+
+Reference the proto structure from the exploration: each database has:
+- `name`: resource name like `"instances/prod-pg/databases/employee_db"`
+- `project`: like `"projects/hr-system"`
+- `instanceResource.dataSources`: array with `{id, type}` where type is `"ADMIN"` or `"READ_ONLY"`
+- `instanceResource.engine`: like `"POSTGRES"`
+- `instanceResource.name`: like `"instances/prod-pg"`
+
+```go
+// mockListDatabases returns an http.Handler that responds to ListDatabases requests
+// with the given database entries.
+func mockListDatabases(databases []map[string]any) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/bytebase.v1.DatabaseService/ListDatabases" {
+ http.Error(w, "not found", http.StatusNotFound)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ resp := map[string]any{"databases": databases}
+ json.NewEncoder(w).Encode(resp)
+ })
+}
+
+func makeDatabase(name, instanceName, project, engine, dsID, dsType string) map[string]any {
+ db := map[string]any{
+ "name": name,
+ "project": project,
+ "instanceResource": map[string]any{
+ "name": instanceName,
+ "engine": engine,
+ "dataSources": []map[string]any{
+ {"id": dsID, "type": dsType},
+ },
+ },
+ }
+ return db
+}
+
+func makeDatabaseWithDualDS(name, instanceName, project, engine, adminDSID, readOnlyDSID string) map[string]any {
+ db := map[string]any{
+ "name": name,
+ "project": project,
+ "instanceResource": map[string]any{
+ "name": instanceName,
+ "engine": engine,
+ "dataSources": []map[string]any{
+ {"id": adminDSID, "type": "ADMIN"},
+ {"id": readOnlyDSID, "type": "READ_ONLY"},
+ },
+ },
+ }
+ return db
+}
+
+func TestQueryDatabase_SingleMatch(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ require.NoError(t, err)
+ require.False(t, resolved.ambiguous)
+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
+ require.Equal(t, "admin-ds", resolved.dataSourceID)
+}
+
+func TestQueryDatabase_CaseInsensitiveMatch(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "Employee_DB"})
+ require.NoError(t, err)
+ require.False(t, resolved.ambiguous)
+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
+}
+
+func TestQueryDatabase_SubstringMatch(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee"})
+ require.NoError(t, err)
+ require.False(t, resolved.ambiguous)
+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
+}
+
+func TestQueryDatabase_NotFound(t *testing.T) {
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{}))
+
+ _, err := s.resolveDatabase(context.Background(), QueryInput{Database: "nonexistent"})
+ require.Error(t, err)
+ var te *toolError
+ require.ErrorAs(t, err, &te)
+ require.Equal(t, "DATABASE_NOT_FOUND", te.Code)
+}
+
+func TestQueryDatabase_Ambiguous(t *testing.T) {
+ db1 := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "ds1", "ADMIN",
+ )
+ db2 := makeDatabase(
+ "instances/staging/databases/employee_db",
+ "instances/staging", "projects/hr", "POSTGRES",
+ "ds2", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db1, db2}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ require.NoError(t, err)
+ require.True(t, resolved.ambiguous)
+ require.Len(t, resolved.candidates, 2)
+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.candidates[0].Database)
+ require.Equal(t, "instances/staging/databases/employee_db", resolved.candidates[1].Database)
+}
+
+func TestQueryDatabase_AmbiguousWithInstance(t *testing.T) {
+ db1 := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "ds1", "ADMIN",
+ )
+ db2 := makeDatabase(
+ "instances/staging/databases/employee_db",
+ "instances/staging", "projects/hr", "POSTGRES",
+ "ds2", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db1, db2}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{
+ Database: "employee_db",
+ Instance: "prod-pg",
+ })
+ require.NoError(t, err)
+ require.False(t, resolved.ambiguous)
+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)
+}
+
+func TestQueryDatabase_ReadOnlyDatasource(t *testing.T) {
+ db := makeDatabaseWithDualDS(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "readonly-ds",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ require.NoError(t, err)
+ require.Equal(t, "readonly-ds", resolved.dataSourceID)
+}
+
+func TestQueryDatabase_AdminFallback(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ s := newTestServerWithMock(t, mockListDatabases([]map[string]any{db}))
+
+ resolved, err := s.resolveDatabase(context.Background(), QueryInput{Database: "employee_db"})
+ require.NoError(t, err)
+ require.Equal(t, "admin-ds", resolved.dataSourceID)
+}
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run "^TestQueryDatabase_(SingleMatch|CaseInsensitiveMatch|SubstringMatch|NotFound|Ambiguous|ReadOnly|AdminFallback)"`
+
+Expected: FAIL — `resolveDatabase` returns "not implemented".
+
+**Step 3: Implement `resolveDatabase`**
+
+Replace the stub in `tool_query.go`:
+
+```go
+func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolvedDatabase, error) {
+ // Build filter for ListDatabases
+ body := map[string]any{
+ "parent": "workspaces/-",
+ }
+
+ // Call DatabaseService/ListDatabases
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.DatabaseService/ListDatabases", body)
+ if err != nil {
+ return nil, err
+ }
+ if resp.Status >= 400 {
+ msg := parseError(resp.Body)
+ if msg == "" {
+ msg = fmt.Sprintf("HTTP %d", resp.Status)
+ }
+ return nil, &toolError{
+ Code: "API_ERROR",
+ Message: msg,
+ }
+ }
+
+ // Parse response
+ var listResp struct {
+ Databases []struct {
+ Name string `json:"name"`
+ Project string `json:"project"`
+ InstanceResource struct {
+ Name string `json:"name"`
+ Engine string `json:"engine"`
+ DataSources []struct {
+ ID string `json:"id"`
+ Type string `json:"type"`
+ } `json:"dataSources"`
+ } `json:"instanceResource"`
+ } `json:"databases"`
+ }
+ if err := json.Unmarshal(resp.Body, &listResp); err != nil {
+ return nil, errors.Wrap(err, "failed to parse database list")
+ }
+
+ // Extract the short database name from resource name.
+ // "instances/prod-pg/databases/employee_db" -> "employee_db"
+ extractDBName := func(resourceName string) string {
+ parts := strings.Split(resourceName, "/")
+ if len(parts) >= 4 {
+ return parts[3]
+ }
+ return resourceName
+ }
+
+ // Extract short instance name from resource name.
+ // "instances/prod-pg" -> "prod-pg"
+ extractInstanceName := func(resourceName string) string {
+ parts := strings.Split(resourceName, "/")
+ if len(parts) >= 2 {
+ return parts[1]
+ }
+ return resourceName
+ }
+
+ // Extract short project name from resource name.
+ // "projects/hr" -> "hr"
+ extractProjectName := func(resourceName string) string {
+ parts := strings.Split(resourceName, "/")
+ if len(parts) >= 2 {
+ return parts[1]
+ }
+ return resourceName
+ }
+
+ // Filter by instance and project if provided
+ type dbEntry struct {
+ resourceName string
+ instanceName string
+ projectName string
+ engine string
+ dataSources []struct {
+ ID string
+ Type string
+ }
+ }
+
+ var filtered []dbEntry
+ for _, db := range listResp.Databases {
+ instName := extractInstanceName(db.InstanceResource.Name)
+ projName := extractProjectName(db.Project)
+
+ if input.Instance != "" && !strings.EqualFold(instName, input.Instance) {
+ continue
+ }
+ if input.Project != "" && !strings.EqualFold(projName, input.Project) {
+ continue
+ }
+
+ entry := dbEntry{
+ resourceName: db.Name,
+ instanceName: instName,
+ projectName: projName,
+ engine: db.InstanceResource.Engine,
+ }
+ for _, ds := range db.InstanceResource.DataSources {
+ entry.dataSources = append(entry.dataSources, struct {
+ ID string
+ Type string
+ }{ID: ds.ID, Type: ds.Type})
+ }
+ filtered = append(filtered, entry)
+ }
+
+ // Strict matching: exact -> case-insensitive exact -> substring
+ matchTiers := []func(dbName, query string) bool{
+ func(dbName, query string) bool { return dbName == query },
+ func(dbName, query string) bool { return strings.EqualFold(dbName, query) },
+ func(dbName, query string) bool { return strings.Contains(strings.ToLower(dbName), strings.ToLower(query)) },
+ }
+
+ var matches []dbEntry
+ for _, matchFn := range matchTiers {
+ matches = nil
+ for _, entry := range filtered {
+ dbName := extractDBName(entry.resourceName)
+ if matchFn(dbName, input.Database) {
+ matches = append(matches, entry)
+ }
+ }
+ if len(matches) > 0 {
+ break
+ }
+ }
+
+ if len(matches) == 0 {
+ return nil, &toolError{
+ Code: "DATABASE_NOT_FOUND",
+ Message: fmt.Sprintf("no database matching %q found", input.Database),
+ Suggestion: "use call_api(operationId=\"DatabaseService/ListDatabases\", body={\"parent\": \"workspaces/-\"}) to list available databases",
+ }
+ }
+
+ if len(matches) > 1 {
+ candidates := make([]Candidate, 0, len(matches))
+ for _, m := range matches {
+ candidates = append(candidates, Candidate{
+ Database: m.resourceName,
+ Instance: m.instanceName,
+ Project: m.projectName,
+ Engine: m.engine,
+ })
+ }
+ return &resolvedDatabase{ambiguous: true, candidates: candidates}, nil
+ }
+
+ // Single match — select datasource
+ match := matches[0]
+ dsID := selectDataSource(match.dataSources)
+
+ return &resolvedDatabase{
+ resourceName: match.resourceName,
+ dataSourceID: dsID,
+ }, nil
+}
+
+// selectDataSource picks READ_ONLY if available, otherwise falls back to ADMIN.
+func selectDataSource(dataSources []struct{ ID, Type string }) 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
+}
+```
+
+**Step 4: Run resolution tests**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run "^TestQueryDatabase_(SingleMatch|CaseInsensitiveMatch|SubstringMatch|NotFound|Ambiguous|ReadOnly|AdminFallback)"`
+
+Expected: All PASS.
+
+**Step 5: Run lint**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: No errors.
+
+**Step 6: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_query.go backend/api/mcp/tool_query_test.go
+git commit -m "feat(mcp): implement database resolution for query_database tool
+
+Resolves databases with strict matching (exact > case-insensitive > substring).
+Auto-selects READ_ONLY datasource with ADMIN fallback.
+Returns AMBIGUOUS_TARGET with candidates when multiple databases match."
+```
+
+---
+
+### Task 5: Implement query execution (`executeQuery`)
+
+**Files:**
+- Modify: `backend/api/mcp/tool_query.go`
+- Modify: `backend/api/mcp/tool_query_test.go`
+
+**Step 1: Write failing tests for query execution**
+
+Add to `tool_query_test.go`. These need a mock that handles both ListDatabases AND SQLService/Query.
+
+```go
+// mockQueryServer returns a handler that serves both ListDatabases and Query endpoints.
+func mockQueryServer(databases []map[string]any, queryResponse map[string]any) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/bytebase.v1.DatabaseService/ListDatabases":
+ json.NewEncoder(w).Encode(map[string]any{"databases": databases})
+ case "/bytebase.v1.SQLService/Query":
+ json.NewEncoder(w).Encode(queryResponse)
+ default:
+ http.Error(w, "not found", http.StatusNotFound)
+ }
+ })
+}
+
+// makeQueryResponse builds a mock SQLService/Query response.
+func makeQueryResponse(columns []string, columnTypes []string, rows [][]map[string]any, latency string) map[string]any {
+ queryRows := make([]map[string]any, 0, len(rows))
+ for _, row := range rows {
+ queryRows = append(queryRows, map[string]any{"values": row})
+ }
+ return map[string]any{
+ "results": []map[string]any{
+ {
+ "columnNames": columns,
+ "columnTypeNames": columnTypes,
+ "rows": queryRows,
+ "rowsCount": fmt.Sprintf("%d", len(rows)),
+ "latency": latency,
+ "statement": "SELECT ...",
+ },
+ },
+ }
+}
+
+func TestQueryDatabase_FullFlow(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ rows := [][]map[string]any{
+ {{"stringValue": "1"}, {"stringValue": "John"}, {"stringValue": "[email protected]"}},
+ {{"stringValue": "2"}, {"stringValue": "Jane"}, {"stringValue": "[email protected]"}},
+ }
+ qr := makeQueryResponse(
+ []string{"id", "name", "email"},
+ []string{"int4", "varchar", "varchar"},
+ rows, "0.012s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ result, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT * FROM users",
+ })
+ require.NoError(t, err)
+ require.NotNil(t, result)
+ require.False(t, result.IsError)
+
+ qo, ok := output.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, []string{"id", "name", "email"}, qo.Columns)
+ require.Equal(t, []string{"int4", "varchar", "varchar"}, qo.ColumnTypes)
+ require.Len(t, qo.Rows, 2)
+ require.Equal(t, 2, qo.RowCount)
+ require.False(t, qo.Truncated)
+}
+
+func TestQueryDatabase_EmptyResult(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ qr := makeQueryResponse(
+ []string{"id", "name"},
+ []string{"int4", "varchar"},
+ [][]map[string]any{}, "0.005s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ result, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT * FROM users WHERE id = -1",
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ qo := output.(*QueryOutput)
+ require.Len(t, qo.Rows, 0)
+ require.Equal(t, 0, qo.RowCount)
+ require.False(t, qo.Truncated)
+}
+
+func TestQueryDatabase_Truncation(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ // Generate 150 rows
+ rows := make([][]map[string]any, 150)
+ for i := range rows {
+ rows[i] = []map[string]any{{"stringValue": fmt.Sprintf("%d", i+1)}}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.230s")
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ result, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ // default limit = 100
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ qo := output.(*QueryOutput)
+ require.Equal(t, 100, qo.RowCount)
+ require.Len(t, qo.Rows, 100)
+ require.True(t, qo.Truncated)
+
+ // Verify text header mentions truncation
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "Truncated")
+}
+
+func TestQueryDatabase_CustomLimit(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ rows := make([][]map[string]any, 100)
+ for i := range rows {
+ rows[i] = []map[string]any{{"stringValue": fmt.Sprintf("%d", i+1)}}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.1s")
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ result, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ Limit: 50,
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ qo := output.(*QueryOutput)
+ require.Equal(t, 50, qo.RowCount)
+ require.Len(t, qo.Rows, 50)
+ require.True(t, qo.Truncated)
+}
+
+func TestQueryDatabase_LimitCappedAt1000(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ rows := make([][]map[string]any, 5)
+ for i := range rows {
+ rows[i] = []map[string]any{{"stringValue": fmt.Sprintf("%d", i+1)}}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.1s")
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ // limit=2000 should be capped to 1000, but we only have 5 rows so no truncation
+ _, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ Limit: 2000,
+ })
+ require.NoError(t, err)
+
+ qo := output.(*QueryOutput)
+ require.Equal(t, 5, qo.RowCount)
+ require.False(t, qo.Truncated)
+}
+
+func TestQueryDatabase_QueryError(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/bytebase.v1.DatabaseService/ListDatabases":
+ json.NewEncoder(w).Encode(map[string]any{
+ "databases": []map[string]any{db},
+ })
+ case "/bytebase.v1.SQLService/Query":
+ w.WriteHeader(http.StatusBadRequest)
+ json.NewEncoder(w).Encode(map[string]any{
+ "message": "syntax error at or near \"SELEC\"",
+ "code": "INVALID_ARGUMENT",
+ })
+ }
+ })
+ s := newTestServerWithMock(t, handler)
+
+ result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELEC * FROM users",
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "Query failed")
+ require.Contains(t, text, "syntax error")
+}
+
+func TestQueryDatabase_PermissionDenied(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/bytebase.v1.DatabaseService/ListDatabases":
+ json.NewEncoder(w).Encode(map[string]any{
+ "databases": []map[string]any{db},
+ })
+ case "/bytebase.v1.SQLService/Query":
+ w.WriteHeader(http.StatusForbidden)
+ json.NewEncoder(w).Encode(map[string]any{
+ "message": "permission denied",
+ "code": "PERMISSION_DENIED",
+ })
+ }
+ })
+ s := newTestServerWithMock(t, handler)
+
+ result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT * FROM users",
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "permission denied")
+}
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run "^TestQueryDatabase_(FullFlow|EmptyResult|Truncation|CustomLimit|LimitCapped|QueryError|PermissionDenied)"`
+
+Expected: FAIL — `executeQuery` returns "not implemented".
+
+**Step 3: Implement `executeQuery`**
+
+Replace the stub in `tool_query.go`:
+
+```go
+func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, statement string, limit int) (*QueryOutput, error) {
+ body := map[string]any{
+ "name": resolved.resourceName,
+ "dataSourceId": resolved.dataSourceID,
+ "statement": statement,
+ }
+
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.SQLService/Query", body)
+ if err != nil {
+ return nil, err
+ }
+ if resp.Status >= 400 {
+ msg := parseError(resp.Body)
+ if msg == "" {
+ msg = fmt.Sprintf("HTTP %d", resp.Status)
+ }
+ return nil, &toolError{
+ Code: "QUERY_ERROR",
+ Message: msg,
+ Suggestion: "check SQL syntax and permissions",
+ }
+ }
+
+ // Parse the query response
+ var queryResp struct {
+ Results []struct {
+ ColumnNames []string `json:"columnNames"`
+ ColumnTypeNames []string `json:"columnTypeNames"`
+ Rows []json.RawMessage `json:"rows"`
+ RowsCount json.Number `json:"rowsCount"`
+ Latency string `json:"latency"`
+ Error string `json:"error"`
+ Statement string `json:"statement"`
+ } `json:"results"`
+ }
+ if err := json.Unmarshal(resp.Body, &queryResp); err != nil {
+ return nil, errors.Wrap(err, "failed to parse query response")
+ }
+
+ if len(queryResp.Results) == 0 {
+ return &QueryOutput{}, nil
+ }
+
+ result := queryResp.Results[0]
+
+ // Check for query-level error
+ if result.Error != "" {
+ return nil, &toolError{
+ Code: "QUERY_ERROR",
+ Message: result.Error,
+ Suggestion: "check SQL syntax for the database engine",
+ }
+ }
+
+ // Parse latency
+ var latencyMs int64
+ if result.Latency != "" {
+ latencyMs = parseLatencyMs(result.Latency)
+ }
+
+ // Flatten rows: each row is {"values": [{"stringValue": "x"}, {"int32Value": 1}, ...]}
+ allRows, err := flattenRows(result.Rows)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to parse query rows")
+ }
+
+ // Apply limit and truncation
+ truncated := len(allRows) > limit
+ if truncated {
+ allRows = allRows[:limit]
+ }
+
+ return &QueryOutput{
+ Columns: result.ColumnNames,
+ ColumnTypes: result.ColumnTypeNames,
+ Rows: allRows,
+ RowCount: len(allRows),
+ Truncated: truncated,
+ LatencyMs: latencyMs,
+ }, nil
+}
+
+// flattenRows converts protobuf RowValue oneofs into plain Go values.
+func flattenRows(rawRows []json.RawMessage) ([][]any, error) {
+ var rows [][]any
+ for _, rawRow := range rawRows {
+ var row struct {
+ Values []json.RawMessage `json:"values"`
+ }
+ if err := json.Unmarshal(rawRow, &row); err != nil {
+ return nil, err
+ }
+
+ flatRow := make([]any, 0, len(row.Values))
+ for _, rawVal := range row.Values {
+ val := flattenRowValue(rawVal)
+ flatRow = append(flatRow, val)
+ }
+ rows = append(rows, flatRow)
+ }
+ return rows, nil
+}
+
+// flattenRowValue extracts the plain value from a protobuf RowValue oneof.
+func flattenRowValue(raw json.RawMessage) any {
+ var valMap map[string]json.RawMessage
+ if err := json.Unmarshal(raw, &valMap); err != nil {
+ return string(raw)
+ }
+
+ // Priority order for oneof fields
+ oneofFields := []string{
+ "nullValue", "boolValue", "bytesValue", "doubleValue", "floatValue",
+ "int32Value", "int64Value", "stringValue", "uint32Value", "uint64Value",
+ "valueValue", "timestampValue", "timestampTzValue",
+ }
+
+ for _, field := range oneofFields {
+ rawVal, ok := valMap[field]
+ if !ok {
+ continue
+ }
+
+ if field == "nullValue" {
+ return nil
+ }
+
+ // For timestamp types, extract the string representation
+ if field == "timestampValue" || field == "timestampTzValue" {
+ var ts struct {
+ Value string `json:"value"`
+ }
+ if err := json.Unmarshal(rawVal, &ts); err == nil && ts.Value != "" {
+ return ts.Value
+ }
+ // Fall through to raw string
+ }
+
+ // Try to decode as a basic type
+ var val any
+ if err := json.Unmarshal(rawVal, &val); err == nil {
+ return val
+ }
+ return string(rawVal)
+ }
+
+ return nil
+}
+
+// parseLatencyMs parses a duration string like "0.012s" into milliseconds.
+func parseLatencyMs(latency string) int64 {
+ latency = strings.TrimSpace(latency)
+ if strings.HasSuffix(latency, "s") {
+ latency = strings.TrimSuffix(latency, "s")
+ var seconds float64
+ if _, err := fmt.Sscanf(latency, "%f", &seconds); err == nil {
+ return int64(seconds * 1000)
+ }
+ }
+ return 0
+}
+```
+
+**Step 4: Run all query tests**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run "^TestQueryDatabase_"`
+
+Expected: All PASS.
+
+**Step 5: Run full test suite and lint**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/...`
+
+Expected: All tests PASS.
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: No lint errors.
+
+**Step 6: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_query.go backend/api/mcp/tool_query_test.go
+git commit -m "feat(mcp): implement query execution for query_database tool
+
+Executes SQL via SQLService/Query, flattens protobuf RowValue oneofs
+into plain values, enforces row limits with truncation metadata."
+```
+
+---
+
+### Task 6: Add masked value and timeout tests
+
+**Files:**
+- Modify: `backend/api/mcp/tool_query_test.go`
+
+**Step 1: Write masked value passthrough test**
+
+```go
+func TestQueryDatabase_MaskedValues(t *testing.T) {
+ db := makeDatabase(
+ "instances/prod-pg/databases/employee_db",
+ "instances/prod-pg", "projects/hr", "POSTGRES",
+ "admin-ds", "ADMIN",
+ )
+ // Masked values should pass through unchanged
+ rows := [][]map[string]any{
+ {{"stringValue": "1"}, {"stringValue": "******"}, {"stringValue": "**rn**"}},
+ }
+ qr := makeQueryResponse(
+ []string{"id", "ssn", "name"},
+ []string{"int4", "varchar", "varchar"},
+ rows, "0.005s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer([]map[string]any{db}, qr))
+
+ _, output, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id, ssn, name FROM users",
+ })
+ require.NoError(t, err)
+
+ qo := output.(*QueryOutput)
+ require.Len(t, qo.Rows, 1)
+ require.Equal(t, "******", qo.Rows[0][1])
+ require.Equal(t, "**rn**", qo.Rows[0][2])
+}
+
+func TestQueryDatabase_Timeout(t *testing.T) {
+ // Slow handler that blocks longer than the context timeout
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path == "/bytebase.v1.DatabaseService/ListDatabases" {
+ // Simulate slow response
+ select {
+ case <-r.Context().Done():
+ return
+ case <-time.After(5 * time.Second):
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]any{"databases": []any{}})
+ }
+ }
+ })
+ s := newTestServerWithMock(t, handler)
+
+ ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+ defer cancel()
+
+ _, err := s.resolveDatabase(ctx, QueryInput{Database: "employee_db"})
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "context deadline exceeded")
+}
+```
+
+**Step 2: Run new tests**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/... -run "^TestQueryDatabase_(MaskedValues|Timeout)$"`
+
+Expected: Both PASS.
+
+**Step 3: Run full test suite**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/...`
+
+Expected: All PASS.
+
+**Step 4: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_query_test.go
+git commit -m "test(mcp): add masked values and timeout tests for query_database"
+```
+
+---
+
+### Task 7: Update skill description and build verification
+
+**Files:**
+- Modify: `backend/api/mcp/tool_skill.go` (line 35)
+
+**Step 1: Update `get_skill` description to mention `query_database`**
+
+In `tool_skill.go`, update `getSkillDescription` to mention the new tool. Users should know they can use `query_database` directly instead of following the `query` skill workflow.
+
+Change line 31-35:
+```go
+const getSkillDescription = `Get step-by-step guides for Bytebase tasks.
+
+**Tip:** Use query_database tool for SQL queries — it handles database resolution automatically.
+
+**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)
+
+Skills: query, database-change, grant-permission`
+```
+
+**Step 2: Run all tests**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go test -v -count=1 ./backend/api/mcp/...`
+
+Expected: All PASS.
+
+**Step 3: Build the project**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
+
+Expected: Build succeeds.
+
+**Step 4: Run lint**
+
+Run: `cd /Users/vincent/CLAUDE_BB/bytebase && golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: No lint errors.
+
+**Step 5: Commit**
+
+```bash
+cd /Users/vincent/CLAUDE_BB/bytebase
+git add backend/api/mcp/tool_skill.go
+git commit -m "docs(mcp): update get_skill description to mention query_database tool"
+```
+
+---
+
+## Summary of files
+
+| Action | File |
+|--------|------|
+| Create | `backend/api/mcp/tool_http.go` |
+| Create | `backend/api/mcp/tool_http_test.go` |
+| Create | `backend/api/mcp/tool_query.go` |
+| Create | `backend/api/mcp/tool_query_test.go` |
+| Modify | `backend/api/mcp/tool_call.go` (refactor to use shared helpers) |
+| Modify | `backend/api/mcp/server.go` (register new tool) |
+| Modify | `backend/api/mcp/tool_skill.go` (update description) |
diff --git a/docs/plans/2026-04-02-fix-resolve-database-permissions.md b/docs/plans/2026-04-02-fix-resolve-database-permissions.md
new file mode 100644
index 0000000000..f6c123ab64
--- /dev/null
+++ b/docs/plans/2026-04-02-fix-resolve-database-permissions.md
@@ -0,0 +1,202 @@
+# Fix resolveDatabase Permission Model
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Fix `resolveDatabase` to work with standard user permissions (WorkspaceMember) by listing databases through project-scoped API calls instead of workspace-scoped.
+
+**Architecture:** Replace the single `workspaces/-` ListDatabases call with: list user's projects → list databases per project with existing CEL filter. This respects Bytebase's RBAC model where most users have project-level access, not workspace-level `bb.databases.list`.
+
+**Tech Stack:** Go, existing MCP server infrastructure
+
+---
+
+## Problem
+
+`resolveDatabase` calls `ListDatabases` with `parent: "workspaces/-"`. This fails because:
+1. `workspaces/-` is not a valid wildcard — `-` doesn't match the real workspace ID
+2. Even with the correct workspace ID, the `WorkspaceMember` role (default for new/OAuth users) doesn't have `bb.databases.list` at workspace scope
+3. Users access databases through project memberships, not workspace-level permissions
+
+## Solution
+
+Replace the single ListDatabases call with a two-step approach:
+1. Call `ProjectService/ListProjects` (no special permissions needed — returns projects the user has access to)
+2. For each project, call `DatabaseService/ListDatabases` with `parent: "projects/{id}"` and the existing CEL filter
+
+This is N+1 calls but N is small (few projects) and the server-side filter keeps responses minimal. If the user provides a `project` input param, skip step 1 and query that project directly.
+
+---
+
+### Task 1: Refactor resolveDatabase to use project-scoped queries
+
+**Files:**
+- Modify: `backend/api/mcp/tool_query.go`
+
+**Step 1: Add `listProjects` helper method**
+
+```go
+// listProjects returns project resource names the user has access to.
+func (s *Server) listProjects(ctx context.Context) ([]string, error) {
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.ProjectService/ListProjects", map[string]any{})
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to list projects")
+ }
+ if resp.Status >= 400 {
+ return nil, errors.Errorf("failed to list projects: %s", parseError(resp.Body))
+ }
+ var result struct {
+ Projects []struct {
+ Name string `json:"name"`
+ } `json:"projects"`
+ }
+ if err := json.Unmarshal(resp.Body, &result); err != nil {
+ return nil, errors.Wrap(err, "failed to parse project list")
+ }
+ names := make([]string, 0, len(result.Projects))
+ for _, p := range result.Projects {
+ names = append(names, p.Name)
+ }
+ return names, nil
+}
+```
+
+**Step 2: Add `listDatabasesInProject` helper method**
+
+```go
+// listDatabasesInProject returns databases matching the filter in a project.
+func (s *Server) listDatabasesInProject(ctx context.Context, project, filter string) ([]databaseEntry, error) {
+ body := map[string]any{
+ "parent": project,
+ "filter": filter,
+ "pageSize": 1000,
+ }
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.DatabaseService/ListDatabases", body)
+ if err != nil {
+ return nil, err
+ }
+ // Permission denied on a project is not fatal — skip it.
+ if resp.Status >= 400 {
+ return nil, nil
+ }
+ var listResp listDatabasesResponse
+ if err := json.Unmarshal(resp.Body, &listResp); err != nil {
+ return nil, err
+ }
+ return listResp.Databases, nil
+}
+```
+
+**Step 3: Refactor `resolveDatabase`**
+
+Replace the body of `resolveDatabase` from the `workspaces/-` call through the `listResp` parsing with:
+
+```go
+func (s *Server) resolveDatabase(ctx context.Context, input QueryInput) (*resolvedDatabase, error) {
+ filter := buildDatabaseFilter(input)
+
+ var allDatabases []databaseEntry
+
+ if input.Project != "" {
+ // User specified a project — query it directly.
+ databases, err := s.listDatabasesInProject(ctx, "projects/"+input.Project, filter)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to list databases")
+ }
+ allDatabases = databases
+ } else {
+ // List user's projects, then query each for matching databases.
+ projects, err := s.listProjects(ctx)
+ if err != nil {
+ return nil, err
+ }
+ for _, project := range projects {
+ databases, err := s.listDatabasesInProject(ctx, project, filter)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to list databases")
+ }
+ allDatabases = append(allDatabases, databases...)
+ }
+ }
+
+ // ... rest of tiered matching unchanged ...
+}
+```
+
+**Step 4: Remove `project` from `buildDatabaseFilter`**
+
+Since project filtering is now handled by the `parent` field (querying per-project), remove the `project` filter clause from `buildDatabaseFilter`. Keep `instance` filter.
+
+**Step 5: Run tests, lint, verify**
+
+Run: `go test -count=1 ./backend/api/mcp/...`
+Run: `golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: Tests will fail because the mock server doesn't handle ListProjects. Fix in Task 2.
+
+---
+
+### Task 2: Update test mocks for project-scoped resolution
+
+**Files:**
+- Modify: `backend/api/mcp/tool_query_test.go`
+
+**Step 1: Update `mockListDatabases` to handle both endpoints**
+
+The mock needs to serve `ListProjects` (returns a single test project) and `ListDatabases` (existing filter-aware logic), routing by URL path.
+
+```go
+func mockListDatabases(databases []map[string]any) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/bytebase.v1.ProjectService/ListProjects":
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "projects": []map[string]any{{"name": "projects/test-project"}},
+ })
+ case "/bytebase.v1.DatabaseService/ListDatabases":
+ // existing filter logic unchanged
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+ })
+}
+```
+
+**Step 2: Update `mockQueryServer` if needed**
+
+`mockQueryServer` delegates to `mockListDatabases` for non-Query paths, so it should work automatically once `mockListDatabases` is updated.
+
+**Step 3: Run all tests and lint**
+
+Run: `go test -v -count=1 ./backend/api/mcp/...`
+Run: `golangci-lint run --allow-parallel-runners ./backend/api/mcp/...`
+
+Expected: All tests pass, 0 lint issues.
+
+---
+
+### Task 3: Commit, push, verify CI
+
+**Step 1: Commit**
+
+```
+fix(mcp): use project-scoped queries for database resolution
+
+The default WorkspaceMember role doesn't have bb.databases.list
+at workspace scope. List user's projects first, then query databases
+per project with the existing CEL filter.
+```
+
+**Step 2: Push and verify CI**
+
+Run: `git push`
+Check: golangci-lint, SonarCloud, go-tests all pass.
+
+---
+
+## Summary of changes
+
+| Action | File |
+|--------|------|
+| Modify | `backend/api/mcp/tool_query.go` — add `listProjects`, `listDatabasesInProject`, refactor `resolveDatabase`, update `buildDatabaseFilter` |
+| Modify | `backend/api/mcp/tool_query_test.go` — update mocks to handle ListProjects endpoint |