Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
feat(mcp): add propose_database_change tool (#19963)
Vincent Huang34d53b3f12e9
diff --git a/backend/api/mcp/server.go b/backend/api/mcp/server.goindex 6ab387d5bf..5ab90e88f6 100644--- a/backend/api/mcp/server.go+++ b/backend/api/mcp/server.go@@ -4,6 +4,7 @@ package mcpimport ("net/http""strings"+ "time""github.com/golang-jwt/jwt/v5""github.com/labstack/echo/v5"@@ -23,6 +24,10 @@ type Server struct {profile *config.Profilesecret stringopenAPIIndex *OpenAPIIndex++ // planCheckPollBudgetOverride lets tests shorten the plan-check poll budget.+ // Zero means use the default (planCheckPollBudget).+ planCheckPollBudgetOverride time.Duration}// NewServer creates a new MCP server.@@ -62,6 +67,7 @@ func (s *Server) registerTools() {s.registerSkillTool()s.registerQueryTool()s.registerSchemaTool()+ s.registerChangeTool()}// authMiddleware validates OAuth2 bearer tokens for MCP requests.diff --git a/backend/api/mcp/skills/database-change.md b/backend/api/mcp/skills/database-change.mdindex 53318b7f43..91ca21ca31 100644--- a/backend/api/mcp/skills/database-change.md+++ b/backend/api/mcp/skills/database-change.md@@ -5,9 +5,11 @@ description: Use when making schema changes (DDL), data migrations, ALTER TABLE,# Database Change+> **STOP: For single-database changes, call `propose_database_change(database="...", sql="...", title="...")` directly.** It handles everything (sheet, plan, plan checks, issue) in one call with plain SQL — no base64, no manual steps. Only use the manual workflow below for **batch changes across multiple databases**.+## Overview-Create database changes (DDL/DML) through Bytebase's review workflow. Supports single database or batch changes across multiple databases.+Manual workflow for batch database changes (DDL/DML) across multiple databases through Bytebase's review workflow.## Prerequisites@@ -18,7 +20,7 @@ Create database changes (DDL/DML) through Bytebase's review workflow. Supports s### Step 1: Create sheet(s) with SQL-SQL content must be **base64 encoded**. Engine field is **required**.+SQL content must be **base64 encoded**.```search_api(operationId="SheetService/CreateSheet")@@ -27,8 +29,6 @@ search_api(operationId="SheetService/CreateSheet")call_api(operationId="SheetService/CreateSheet", body={"parent": "projects/{project-id}","sheet": {- "title": "Add users table",- "engine": "POSTGRES","content": "Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVkpOw=="}})@@ -36,8 +36,6 @@ call_api(operationId="SheetService/CreateSheet", body={Note: `Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVkpOw==` decodes to `CREATE TABLE users (id INT PRIMARY KEY);`-Use `search_api(schema="Engine")` to discover valid engine values.-### Step 2: Create a planPlan contains `specs` directly (not wrapped in "steps").@@ -55,8 +53,7 @@ call_api(operationId="PlanService/CreatePlan", body={"id": "spec-1","changeDatabaseConfig": {"targets": ["instances/{instance-id}/databases/{database-name}"],- "sheet": "projects/{project-id}/sheets/{sheet-id}",- "type": "MIGRATE"+ "sheet": "projects/{project-id}/sheets/{sheet-id}"}}]}@@ -74,16 +71,14 @@ call_api(operationId="PlanService/CreatePlan", body={"id": "spec-dev","changeDatabaseConfig": {"targets": ["instances/dev-pg/databases/mydb"],- "sheet": "projects/{project-id}/sheets/{sheet-id}",- "type": "MIGRATE"+ "sheet": "projects/{project-id}/sheets/{sheet-id}"}},{"id": "spec-prod","changeDatabaseConfig": {"targets": ["instances/prod-pg/databases/mydb"],- "sheet": "projects/{project-id}/sheets/{sheet-id}",- "type": "MIGRATE"+ "sheet": "projects/{project-id}/sheets/{sheet-id}"}}]@@ -134,10 +129,7 @@ call_api(operationId="RolloutService/CreateRollout", body={## Change Types-| Type | Use Case |-|------|----------|-| `MIGRATE` | Imperative schema/data changes (DDL and DML) |-| `SDL` | State-based declarative schema migration |+The backend auto-detects whether a change is imperative (DDL/DML) or SDL (declarative schema) from the sheet content. No `type` field is needed in the plan spec.## Common Errorsdiff --git a/backend/api/mcp/tool_change.go b/backend/api/mcp/tool_change.gonew file mode 100644index 0000000000..2f66a1eb11--- /dev/null+++ b/backend/api/mcp/tool_change.go@@ -0,0 +1,612 @@+package mcp++import (+ "context"+ "encoding/base64"+ "encoding/json"+ "fmt"+ "net/http"+ "strings"+ "time"++ "github.com/modelcontextprotocol/go-sdk/mcp"+ "github.com/pkg/errors"+)++const (+ reasonMaxLen = 1000+ planCheckPollBudget = 10 * time.Second+ planCheckPollInterval = 1 * time.Second+)++// Change types.+const (+ changeTypeMigrate = "MIGRATE"+ changeTypeSDL = "SDL"+)++// nextAction enum constants.+const (+ nextActionApproveIssue = "APPROVE_ISSUE"+ nextActionCreateRollout = "CREATE_ROLLOUT"+ nextActionMonitorRollout = "MONITOR_ROLLOUT"+ nextActionWaitPlanCheck = "WAIT_PLAN_CHECK"+ nextActionFixSQLRetry = "FIX_SQL_AND_RETRY"+)++// rolloutDeferredReason enum constants.+const (+ rolloutNotRequested = "NOT_REQUESTED"+ rolloutApprovalPending = "APPROVAL_PENDING"+ rolloutApprovalRejected = "APPROVAL_REJECTED"+ rolloutPlanCheckPending = "PLAN_CHECK_PENDING"+ rolloutPlanCheckError = "PLAN_CHECK_ERROR"+ rolloutCreateFailed = "ROLLOUT_CREATE_FAILED"+)++// planChecks.status enum constants.+const (+ planCheckDone = "DONE"+ planCheckRunning = "RUNNING"+ planCheckFailed = "FAILED"+)++// ChangeInput is the input for the propose_database_change tool.+type ChangeInput struct {+ Database string `json:"database"`+ SQL string `json:"sql"`+ Title string `json:"title"`+ Instance string `json:"instance,omitempty"`+ Project string `json:"project,omitempty"`+ ChangeType string `json:"changeType,omitempty"`+ CreateRollout bool `json:"createRollout,omitempty"`+ Reason string `json:"reason,omitempty"`+}++// ChangeOutput is the output for the propose_database_change tool.+type ChangeOutput struct {+ Database string `json:"database"`+ Project string `json:"project"`+ ResolvedChangeType string `json:"resolvedChangeType"`+ TargetCount int `json:"targetCount"`+ Sheet string `json:"sheet"`+ Plan string `json:"plan"`+ PlanChecks *PlanCheckInfo `json:"planChecks,omitempty"`+ Issue string `json:"issue"`+ RolloutCreated bool `json:"rolloutCreated"`+ Rollout string `json:"rollout,omitempty"`+ RolloutDeferredReason string `json:"rolloutDeferredReason,omitempty"`+ NextAction string `json:"nextAction"`+ Links ChangeLinks `json:"links"`+}++// PlanCheckInfo holds plan check status and results.+type PlanCheckInfo struct {+ Status string `json:"status"`+ Summary *PlanCheckSummary `json:"summary,omitempty"`+ Results []PlanCheckResult `json:"results,omitempty"`+ PlanCheckRun string `json:"planCheckRun,omitempty"`+}++// PlanCheckSummary holds error/warning counts.+type PlanCheckSummary struct {+ Error int `json:"error"`+ Warning int `json:"warning"`+}++// PlanCheckResult holds a single plan check result.+type PlanCheckResult struct {+ Type string `json:"type"`+ Message string `json:"message"`+}++// ChangeLinks holds URLs for created resources.+type ChangeLinks struct {+ Issue string `json:"issue"`+ Plan string `json:"plan"`+ Rollout string `json:"rollout,omitempty"`+}++// changeError is a structured error with partial refs for the change tool.+type changeError struct {+ Code string `json:"code"`+ Message string `json:"message"`+ Suggestion string `json:"suggestion,omitempty"`+ PartialRefs map[string]string `json:"partialRefs,omitempty"`+}++func (e *changeError) Error() string {+ return fmt.Sprintf("%s: %s", e.Code, e.Message)+}++// proposeChangeDescription is the description for the propose_database_change tool.+const proposeChangeDescription = `Run DDL/DML changes (ALTER TABLE, CREATE TABLE, INSERT, UPDATE, migrations) against a Bytebase database.++This is the primary tool for making database changes. Use this instead of manually calling CreateSheet/CreatePlan/CreateIssue via call_api.++Provide plain SQL — the tool handles database resolution, sheet creation, plan creation with automatic plan checks, and issue creation in one call. Optionally creates a rollout.++| Parameter | Required | Description |+|---------------|----------|-------------|+| database | Yes | Database name or substring |+| sql | Yes | SQL statement(s) in plain text (NOT base64) |+| title | Yes | Title for the issue/plan |+| instance | No | Narrow database resolution |+| project | No | Narrow to a specific project |+| changeType | No | "MIGRATE" (default) or "SDL" |+| createRollout | No | If true, attempts rollout creation after issue |+| reason | No | Context or ticket reference (max 1000 chars) |++**Examples:**+propose_database_change(database="app", sql="ALTER TABLE users ADD COLUMN status VARCHAR(20)", title="Add status column")+propose_database_change(database="app", sql="UPDATE orders SET status='shipped' WHERE id=42", title="Ship order 42", createRollout=true)++**Notes:**+- v1 supports single database targets only. For batch changes across multiple databases, use get_skill("database-change").+- Plan checks run automatically; results included in response when available.+- Requires bb.sheets.create, bb.plans.create, bb.issues.create permissions.+- If createRollout=true but policy gates aren't satisfied, returns success with rolloutCreated=false and a reason.`++func (s *Server) registerChangeTool() {+ mcp.AddTool(s.mcpServer, &mcp.Tool{+ Name: "propose_database_change",+ Description: proposeChangeDescription,+ }, s.handleChange)+}++func (s *Server) handleChange(ctx context.Context, req *mcp.CallToolRequest, input ChangeInput) (*mcp.CallToolResult, any, error) {+ // Step 1: Validate input.+ if input.Database == "" {+ return nil, nil, errors.New("database is required")+ }+ if input.SQL == "" {+ return nil, nil, errors.New("sql is required")+ }+ if input.Title == "" {+ return nil, nil, errors.New("title is required")+ }++ changeType := input.ChangeType+ if changeType == "" {+ changeType = changeTypeMigrate+ }+ if changeType != changeTypeMigrate && changeType != changeTypeSDL {+ return formatToolError(&toolError{+ Code: "INVALID_ARGUMENT",+ Message: fmt.Sprintf("invalid changeType %q", changeType),+ Suggestion: "allowed values: MIGRATE, SDL",+ }), nil, nil+ }++ var warnings []string+ reason := input.Reason+ runes := []rune(reason)+ if len(runes) > reasonMaxLen {+ reason = string(runes[:reasonMaxLen-3]) + "..."+ warnings = append(warnings, "reason truncated to 1000 chars")+ }++ // Step 2: Resolve database.+ resolved, resolveResult := s.resolveChangeTarget(ctx, req, input)+ if resolveResult != nil {+ return resolveResult, nil, nil+ }++ // Step 3: Use project from resolved database.+ // When input.Project is set, the resolver already filtered by it.+ project := resolved.project++ // Step 4: Create sheet.+ sheetName, err := s.createSheet(ctx, project, input.SQL)+ if err != nil {+ return formatChangeStepError(err, "SHEET_CREATE_FAILED", "bb.sheets.create", nil), nil, nil+ }++ // Step 5: Create plan.+ planName, err := s.createPlan(ctx, project, input.Title, resolved.resourceName, sheetName)+ if err != nil {+ return formatChangeStepError(err, "PLAN_CREATE_FAILED", "bb.plans.create", map[string]string{"sheet": sheetName}), nil, nil+ }++ // Step 6: Run plan checks (hybrid async, 10s budget).+ planChecks := s.runPlanChecks(ctx, planName)++ // Step 7: Create issue.+ issueName, approvalStatus, err := s.createIssue(ctx, project, input.Title, planName, reason)+ if err != nil {+ partialRefs := map[string]string{"sheet": sheetName, "plan": planName}+ // If plan checks had errors, enforceSqlReview may have blocked issue creation.+ suggestion := ""+ if planChecks != nil && planChecks.Status == planCheckDone && planChecks.Summary != nil && planChecks.Summary.Error > 0 {+ suggestion = "plan checks must pass before issue creation; fix SQL and retry"+ }+ return formatChangeStepErrorWithHint(err, "ISSUE_CREATE_FAILED", "bb.issues.create", partialRefs, suggestion), nil, nil+ }++ // Step 8: Determine nextAction from approvalStatus.+ nextAction := deriveNextAction(approvalStatus)++ // Step 9: Conditionally create rollout.+ rolloutCreated := false+ rolloutName := ""+ rolloutDeferredReason := ""++ switch {+ case !input.CreateRollout:+ rolloutDeferredReason = rolloutNotRequested+ case planChecks != nil && planChecks.Status == planCheckRunning:+ rolloutDeferredReason = rolloutPlanCheckPending+ nextAction = nextActionWaitPlanCheck+ case planChecksHaveErrors(planChecks):+ rolloutDeferredReason = rolloutPlanCheckError+ nextAction = nextActionFixSQLRetry+ case approvalStatus == "PENDING" || approvalStatus == "CHECKING":+ rolloutDeferredReason = rolloutApprovalPending+ nextAction = nextActionApproveIssue+ case approvalStatus == "REJECTED":+ rolloutDeferredReason = rolloutApprovalRejected+ nextAction = nextActionFixSQLRetry+ default:+ rolloutName, err = s.createRollout(ctx, planName)+ if err != nil {+ rolloutDeferredReason = rolloutCreateFailed+ warnings = append(warnings, fmt.Sprintf("rollout creation failed: %s", err.Error()))+ // Keep nextAction from step 8 — do NOT assume APPROVAL_PENDING.+ } else {+ rolloutCreated = true+ nextAction = nextActionMonitorRollout+ }+ }++ // Step 10: Build response.+ output := &ChangeOutput{+ Database: resolved.resourceName,+ Project: project,+ ResolvedChangeType: changeType,+ TargetCount: 1,+ Sheet: sheetName,+ Plan: planName,+ PlanChecks: planChecks,+ Issue: issueName,+ RolloutCreated: rolloutCreated,+ Rollout: rolloutName,+ RolloutDeferredReason: rolloutDeferredReason,+ NextAction: nextAction,+ Links: ChangeLinks{+ Issue: s.buildResourceURL(issueName),+ Plan: s.buildResourceURL(planName),+ },+ }+ if rolloutCreated {+ output.Links.Rollout = s.buildResourceURL(rolloutName)+ }++ text := formatChangeOutput(output, warnings)+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: text}},+ }, output, nil+}++// resolveChangeTarget runs the shared database resolver with elicitation fallback.+// The project parameter is passed to the server-side filter so it can disambiguate+// when the same database name exists in multiple projects.+func (s *Server) resolveChangeTarget(ctx context.Context, req *mcp.CallToolRequest, input ChangeInput) (*resolvedDatabase, *mcp.CallToolResult) {+ resolveCtx, resolveCancel := context.WithTimeout(ctx, resolveTimeout)+ defer resolveCancel()++ resolved, err := s.resolveDatabase(resolveCtx, input.Database, input.Instance, input.Project)+ if err != nil {+ return nil, formatToolError(err)+ }+ if !resolved.ambiguous {+ return resolved, nil+ }+ picked, elicitErr := s.elicitDatabaseChoice(ctx, req, resolved)+ if elicitErr != nil {+ return nil, formatAmbiguousResult(input.Database, resolved.candidates)+ }+ return picked, nil+}++// createSheet creates a sheet with base64-encoded SQL content.+func (s *Server) createSheet(ctx context.Context, project, sql string) (string, error) {+ return s.callAPI(ctx, "/bytebase.v1.SheetService/CreateSheet", "create sheets", "bb.sheets.create", map[string]any{+ "parent": project,+ "sheet": map[string]any{+ "content": base64.StdEncoding.EncodeToString([]byte(sql)),+ },+ })+}++// createPlan creates a plan with a single changeDatabaseConfig spec.+func (s *Server) createPlan(ctx context.Context, project, title, target, sheet string) (string, error) {+ return s.callAPI(ctx, "/bytebase.v1.PlanService/CreatePlan", "create plans", "bb.plans.create", map[string]any{+ "parent": project,+ "plan": map[string]any{+ "title": title,+ "specs": []map[string]any{+ {+ "id": "spec-1",+ "changeDatabaseConfig": map[string]any{+ "targets": []string{target},+ "sheet": sheet,+ },+ },+ },+ },+ })+}++// planCheckBudget returns the effective poll budget, allowing tests to override.+func (s *Server) planCheckBudget() time.Duration {+ if s.planCheckPollBudgetOverride > 0 {+ return s.planCheckPollBudgetOverride+ }+ return planCheckPollBudget+}++// runPlanChecks triggers plan checks and polls for results within the poll budget.+func (s *Server) runPlanChecks(ctx context.Context, planName string) *PlanCheckInfo {+ checkRunName := planName + "/planCheckRun"++ // Trigger plan checks. If this fails, still poll — CreatePlan already+ // initializes plan checks server-side, so they may be running regardless.+ _, _ = s.apiRequest(ctx, "/bytebase.v1.PlanService/RunPlanChecks", map[string]any{+ "name": planName,+ })++ pendingResult := &PlanCheckInfo{+ Status: planCheckRunning,+ PlanCheckRun: checkRunName,+ }++ // Poll for results. Transient errors (404 before row visible, brief 500)+ // are retried within the budget rather than bailing immediately.+ deadline := time.Now().Add(s.planCheckBudget())+ for time.Now().Before(deadline) {+ if ctx.Err() != nil {+ return pendingResult+ }++ pollResp, err := s.apiRequest(ctx, "/bytebase.v1.PlanService/GetPlanCheckRun", map[string]any{+ "name": checkRunName,+ })+ if err != nil || pollResp.Status >= 400 {+ time.Sleep(planCheckPollInterval)+ continue+ }++ var checkRun planCheckRunResponse+ if err := json.Unmarshal(pollResp.Body, &checkRun); err != nil {+ time.Sleep(planCheckPollInterval)+ continue+ }++ switch checkRun.Status {+ case "DONE":+ return buildPlanCheckInfo(checkRun)+ case "FAILED", "CANCELED":+ return &PlanCheckInfo{Status: planCheckFailed}+ default:+ // RUNNING or unknown — keep polling.+ }++ time.Sleep(planCheckPollInterval)+ }++ // Budget exhausted.+ return pendingResult+}++// planCheckRunResponse mirrors the PlanCheckRun proto response.+type planCheckRunResponse struct {+ Status string `json:"status"`+ Results []planCheckResultMessage `json:"results"`+}++// planCheckResultMessage mirrors a single result in PlanCheckRun.+type planCheckResultMessage struct {+ Status string `json:"status"` // SUCCESS, WARNING, ERROR+ Title string `json:"title"`+ Content string `json:"content"`+}++// buildPlanCheckInfo converts a completed plan check run into PlanCheckInfo.+func buildPlanCheckInfo(run planCheckRunResponse) *PlanCheckInfo {+ info := &PlanCheckInfo{+ Status: planCheckDone,+ Summary: &PlanCheckSummary{},+ }+ for _, r := range run.Results {+ msg := r.Title+ if msg == "" {+ msg = r.Content+ }+ switch r.Status {+ case "ERROR":+ info.Summary.Error+++ info.Results = append(info.Results, PlanCheckResult{Type: "ERROR", Message: msg})+ case "WARNING":+ info.Summary.Warning+++ info.Results = append(info.Results, PlanCheckResult{Type: "WARNING", Message: msg})+ default:+ // SUCCESS and other statuses are not included in the output.+ }+ }+ return info+}++// createIssue creates an issue linked to a plan.+func (s *Server) createIssue(ctx context.Context, project, title, planName, description string) (string, string, error) {+ issue := map[string]any{+ "title": title,+ "type": "DATABASE_CHANGE",+ "plan": planName,+ }+ if description != "" {+ issue["description"] = description+ }+ body := map[string]any{+ "parent": project,+ "issue": issue,+ }++ resp, err := s.apiRequest(ctx, "/bytebase.v1.IssueService/CreateIssue", body)+ if err != nil {+ return "", "", errors.Wrap(err, "issue creation request failed")+ }+ if err := checkAPIResponse(resp, "create issues", "bb.issues.create"); err != nil {+ return "", "", err+ }++ var result struct {+ Name string `json:"name"`+ ApprovalStatus string `json:"approvalStatus"`+ }+ if err := json.Unmarshal(resp.Body, &result); err != nil {+ return "", "", errors.Wrap(err, "failed to parse CreateIssue response")+ }+ return result.Name, result.ApprovalStatus, nil+}++// createRollout creates a rollout for a plan.+func (s *Server) createRollout(ctx context.Context, planName string) (string, error) {+ return s.callAPI(ctx, "/bytebase.v1.RolloutService/CreateRollout", "create rollouts", "bb.rollouts.create", map[string]any{+ "parent": planName,+ })+}++// deriveNextAction maps approvalStatus to the next agent action.+func deriveNextAction(approvalStatus string) string {+ switch approvalStatus {+ case "APPROVED", "SKIPPED":+ return nextActionCreateRollout+ case "REJECTED":+ return nextActionFixSQLRetry+ default: // PENDING, CHECKING, or unknown+ return nextActionApproveIssue+ }+}++// planChecksHaveErrors returns true if plan checks completed with errors or failed.+func planChecksHaveErrors(info *PlanCheckInfo) bool {+ if info == nil {+ return false+ }+ if info.Status == planCheckFailed {+ return true+ }+ if info.Status == planCheckDone && info.Summary != nil && info.Summary.Error > 0 {+ return true+ }+ return false+}++// buildResourceURL constructs a URL from externalURL and resource name.+func (s *Server) buildResourceURL(resourceName string) string {+ base := strings.TrimRight(s.profile.ExternalURL, "/")+ if base == "" {+ return resourceName+ }+ return base + "/" + resourceName+}++// formatChangeOutput produces a text header + JSON body.+func formatChangeOutput(output *ChangeOutput, warnings []string) string {+ var sb strings.Builder++ for _, w := range warnings {+ fmt.Fprintf(&sb, "Note: %s\n", w)+ }++ fmt.Fprintf(&sb, "Database: %s\n", output.Database)+ fmt.Fprintf(&sb, "Project: %s\n", output.Project)+ fmt.Fprintf(&sb, "Change: %s | Target count: %d\n", output.ResolvedChangeType, output.TargetCount)+ fmt.Fprintf(&sb, "Issue: %s | Next action: %s\n", output.Issue, output.NextAction)++ if output.RolloutCreated {+ fmt.Fprintf(&sb, "Rollout: %s (created)\n", output.Rollout)+ } else if output.RolloutDeferredReason != "" {+ fmt.Fprintf(&sb, "Rollout: deferred (%s)\n", output.RolloutDeferredReason)+ }++ sb.WriteString("\n")+ jsonBytes, _ := json.Marshal(output)+ sb.Write(jsonBytes)++ return sb.String()+}++// callAPI calls an API endpoint, checks the response, and extracts the resource name.+// Handles permission errors, HTTP errors, and JSON parsing in one place.+func (s *Server) callAPI(ctx context.Context, path, operation, permission string, body map[string]any) (string, error) {+ resp, err := s.apiRequest(ctx, path, body)+ if err != nil {+ return "", errors.Wrapf(err, "%s request failed", operation)+ }+ if err := checkAPIResponse(resp, operation, permission); err != nil {+ return "", err+ }+ var result struct {+ Name string `json:"name"`+ }+ if err := json.Unmarshal(resp.Body, &result); err != nil {+ return "", errors.Wrapf(err, "failed to parse %s response", operation)+ }+ return result.Name, nil+}++// checkAPIResponse checks an API response for permission or general errors.+// Returns nil if the response is OK, or a structured error otherwise.+func checkAPIResponse(resp *apiResponse, operation, permission string) error {+ if resp.Status == http.StatusForbidden || resp.Status == http.StatusUnauthorized {+ return &toolError{+ Code: "PERMISSION_DENIED",+ Message: fmt.Sprintf("you don't have permission to %s", operation),+ Suggestion: fmt.Sprintf("ask your workspace admin to grant you the %s permission", permission),+ }+ }+ if resp.Status >= 400 {+ return errors.Errorf("%s failed: HTTP %d: %s", operation, resp.Status, parseError(resp.Body))+ }+ return nil+}++// formatChangeError formats a changeError into an MCP error result.+func formatChangeError(err *changeError) *mcp.CallToolResult {+ jsonBytes, _ := json.MarshalIndent(err, "", " ")+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},+ IsError: true,+ }+}++// formatChangeStepError formats a step failure into an MCP error result.+// It detects permission errors and wraps them appropriately.+func formatChangeStepError(err error, defaultCode, permission string, partialRefs map[string]string) *mcp.CallToolResult {+ return formatChangeStepErrorWithHint(err, defaultCode, permission, partialRefs, "")+}++// formatChangeStepErrorWithHint is like formatChangeStepError but replaces the+// default suggestion with hint when non-empty, keeping the JSON shape intact.+func formatChangeStepErrorWithHint(err error, defaultCode, permission string, partialRefs map[string]string, hint string) *mcp.CallToolResult {+ var te *toolError+ if errors.As(err, &te) && te.Code == "PERMISSION_DENIED" {+ return formatChangeError(&changeError{+ Code: "PERMISSION_DENIED",+ Message: te.Message,+ Suggestion: fmt.Sprintf("ask your workspace admin to grant you the %s permission", permission),+ PartialRefs: partialRefs,+ })+ }+ suggestion := "check the error and retry"+ if hint != "" {+ suggestion = hint+ }+ return formatChangeError(&changeError{+ Code: defaultCode,+ Message: err.Error(),+ Suggestion: suggestion,+ PartialRefs: partialRefs,+ })+}diff --git a/backend/api/mcp/tool_change_test.go b/backend/api/mcp/tool_change_test.gonew file mode 100644index 0000000000..dc65a21575--- /dev/null+++ b/backend/api/mcp/tool_change_test.go@@ -0,0 +1,1058 @@+package mcp++import (+ "encoding/base64"+ "encoding/json"+ "net/http"+ "strings"+ "sync"+ "testing"+ "time"++ mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"+ "github.com/stretchr/testify/require"+)++// --- Change tool test infrastructure ---++// changeMock provides configurable mock handlers for all APIs used by propose_database_change.+type changeMock struct {+ databases []map[string]any++ // Per-step response configuration.+ sheetResponse map[string]any+ sheetStatus int+ planResponse map[string]any+ planStatus int+ runPlanChecksStatus int+ planCheckRunResponse map[string]any+ planCheckRunStatus int+ issueResponse map[string]any+ issueStatus int+ rolloutResponse map[string]any+ rolloutStatus int++ // Capture request bodies for assertions.+ mu sync.Mutex+ capturedSheet map[string]any+ capturedPlan map[string]any+ capturedIssue map[string]any+ capturedRollout map[string]any+}++func newChangeMock(databases []map[string]any) *changeMock {+ return &changeMock{+ databases: databases,+ sheetResponse: map[string]any{"name": "projects/hr-system/sheets/1001"},+ sheetStatus: http.StatusOK,+ planResponse: map[string]any{"name": "projects/hr-system/plans/2002"},+ planStatus: http.StatusOK,+ runPlanChecksStatus: http.StatusOK,+ planCheckRunResponse: defaultPlanCheckDone(),+ planCheckRunStatus: http.StatusOK,+ issueResponse: defaultIssueResponse("APPROVED"),+ issueStatus: http.StatusOK,+ rolloutResponse: map[string]any{"name": "projects/hr-system/rollouts/4004"},+ rolloutStatus: http.StatusOK,+ }+}++func defaultPlanCheckDone() map[string]any {+ return map[string]any{+ "status": "DONE",+ "results": []any{},+ }+}++func defaultIssueResponse(approvalStatus string) map[string]any {+ return map[string]any{+ "name": "projects/hr-system/issues/3003",+ "approvalStatus": approvalStatus,+ }+}++func (m *changeMock) handler() http.Handler {+ listHandler := mockListDatabases(m.databases)+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "application/json")++ switch {+ case strings.Contains(r.URL.Path, "SheetService/CreateSheet"):+ m.captureBody(r, &m.capturedSheet)+ w.WriteHeader(m.sheetStatus)+ _ = json.NewEncoder(w).Encode(m.sheetResponse)++ case strings.Contains(r.URL.Path, "PlanService/RunPlanChecks"):+ w.WriteHeader(m.runPlanChecksStatus)+ _ = json.NewEncoder(w).Encode(map[string]any{})++ case strings.Contains(r.URL.Path, "PlanService/GetPlanCheckRun"):+ w.WriteHeader(m.planCheckRunStatus)+ _ = json.NewEncoder(w).Encode(m.planCheckRunResponse)++ case strings.Contains(r.URL.Path, "PlanService/CreatePlan"):+ m.captureBody(r, &m.capturedPlan)+ w.WriteHeader(m.planStatus)+ _ = json.NewEncoder(w).Encode(m.planResponse)++ case strings.Contains(r.URL.Path, "IssueService/CreateIssue"):+ m.captureBody(r, &m.capturedIssue)+ w.WriteHeader(m.issueStatus)+ _ = json.NewEncoder(w).Encode(m.issueResponse)++ case strings.Contains(r.URL.Path, "RolloutService/CreateRollout"):+ m.captureBody(r, &m.capturedRollout)+ w.WriteHeader(m.rolloutStatus)+ _ = json.NewEncoder(w).Encode(m.rolloutResponse)++ case strings.Contains(r.URL.Path, "DatabaseService/ListDatabases"):+ listHandler.ServeHTTP(w, r)++ default:+ w.WriteHeader(http.StatusNotFound)+ _ = json.NewEncoder(w).Encode(map[string]any{"message": "unknown path"})+ }+ })+}++func (m *changeMock) captureBody(r *http.Request, target *map[string]any) {+ var body map[string]any+ _ = json.NewDecoder(r.Body).Decode(&body)+ m.mu.Lock()+ *target = body+ m.mu.Unlock()+}++func (m *changeMock) getCapturedSheet() map[string]any {+ m.mu.Lock()+ defer m.mu.Unlock()+ return m.capturedSheet+}++func (m *changeMock) getCapturedPlan() map[string]any {+ m.mu.Lock()+ defer m.mu.Unlock()+ return m.capturedPlan+}++func (m *changeMock) getCapturedIssue() map[string]any {+ m.mu.Lock()+ defer m.mu.Unlock()+ return m.capturedIssue+}++func (m *changeMock) getCapturedRollout() map[string]any {+ m.mu.Lock()+ defer m.mu.Unlock()+ return m.capturedRollout+}++func newChangeTestServer(t *testing.T, mock *changeMock) *Server {+ t.Helper()+ s := newTestServerWithMock(t, mock.handler())+ s.profile.ExternalURL = "https://bytebase.example.com"+ // Use a short poll budget to avoid 10s waits in tests.+ s.planCheckPollBudgetOverride = 100 * time.Millisecond+ return s+}++// --- Happy path tests ---++func TestChange_HappyPath_StopAtIssue(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("PENDING")+ s := newChangeTestServer(t, mock)++ result, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE users ADD COLUMN status VARCHAR(20)",+ Title: "Add status column",+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "instances/prod-pg/databases/employee_db", output.Database)+ require.Equal(t, "projects/hr-system", output.Project)+ require.Equal(t, "MIGRATE", output.ResolvedChangeType)+ require.Equal(t, 1, output.TargetCount)+ require.Equal(t, "projects/hr-system/sheets/1001", output.Sheet)+ require.Equal(t, "projects/hr-system/plans/2002", output.Plan)+ require.Equal(t, "projects/hr-system/issues/3003", output.Issue)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "NOT_REQUESTED", output.RolloutDeferredReason)+ require.Equal(t, "APPROVE_ISSUE", output.NextAction)+ require.Contains(t, output.Links.Issue, "projects/hr-system/issues/3003")+ require.Contains(t, output.Links.Plan, "projects/hr-system/plans/2002")+ require.Empty(t, output.Links.Rollout)+}++func TestChange_HappyPath_WithRollout(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ result, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE users ADD COLUMN status VARCHAR(20)",+ Title: "Add status column",+ CreateRollout: true,+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.True(t, output.RolloutCreated)+ require.Equal(t, "projects/hr-system/rollouts/4004", output.Rollout)+ require.Equal(t, "MONITOR_ROLLOUT", output.NextAction)+ require.Contains(t, output.Links.Rollout, "projects/hr-system/rollouts/4004")+}++func TestChange_SDL(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "CREATE TABLE users (id INT PRIMARY KEY);",+ Title: "SDL change",+ ChangeType: "SDL",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ // changeType is reflected in the response but not sent to the API+ // (the backend auto-detects MIGRATE vs SDL from sheet content).+ require.Equal(t, "SDL", output.ResolvedChangeType)++ // Verify plan spec does NOT include a type field (removed in migration 3.14).+ plan := mock.getCapturedPlan()+ planObj, ok := plan["plan"].(map[string]any)+ require.True(t, ok)+ specs, ok := planObj["specs"].([]any)+ require.True(t, ok)+ spec, ok := specs[0].(map[string]any)+ require.True(t, ok)+ cfg, ok := spec["changeDatabaseConfig"].(map[string]any)+ require.True(t, ok)+ _, hasType := cfg["type"]+ require.False(t, hasType, "type field should not be sent to the API")+}++func TestChange_ReasonIncluded(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE users ADD COLUMN x INT",+ Title: "Test",+ Reason: "INC-1234",+ })+ require.NoError(t, err)++ issue := mock.getCapturedIssue()+ issueObj, ok := issue["issue"].(map[string]any)+ require.True(t, ok)+ require.Equal(t, "INC-1234", issueObj["description"])+}++func TestChange_SQLBase64Encoded(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ sql := "ALTER TABLE users ADD COLUMN status VARCHAR(20)"+ _, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: sql,+ Title: "Test",+ })+ require.NoError(t, err)++ sheet := mock.getCapturedSheet()+ sheetObj, ok := sheet["sheet"].(map[string]any)+ require.True(t, ok)+ encoded, ok := sheetObj["content"].(string)+ require.True(t, ok)+ decoded, decodeErr := base64.StdEncoding.DecodeString(encoded)+ require.NoError(t, decodeErr)+ require.Equal(t, sql, string(decoded))+ // Sheet should not contain dead fields (title, engine removed from proto).+ _, hasTitle := sheetObj["title"]+ require.False(t, hasTitle)+ _, hasEngine := sheetObj["engine"]+ require.False(t, hasEngine)+}++// --- Defaults tests ---++func TestChange_Defaults_ChangeType(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "MIGRATE", output.ResolvedChangeType)+}++func TestChange_Defaults_CreateRollout(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "NOT_REQUESTED", output.RolloutDeferredReason)+ // No rollout request should have been made.+ require.Nil(t, mock.getCapturedRollout())+}++func TestChange_Defaults_NextAction_NoApproval(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "CREATE_ROLLOUT", output.NextAction)+}++func TestChange_Defaults_NextAction_ApprovalNeeded(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("PENDING")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "APPROVE_ISSUE", output.NextAction)+}++// --- Plan check variation tests ---++func TestChange_PlanChecks_DoneWithWarnings(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "DONE",+ "results": []any{+ map[string]any{"status": "WARNING", "title": "Column has no default", "content": "details"},+ },+ }+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ require.Equal(t, "DONE", output.PlanChecks.Status)+ require.Equal(t, 0, output.PlanChecks.Summary.Error)+ require.Equal(t, 1, output.PlanChecks.Summary.Warning)+ // Warnings don't block rollout.+ require.True(t, output.RolloutCreated)+}++func TestChange_PlanChecks_DoneWithErrors(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "DONE",+ "results": []any{+ map[string]any{"status": "ERROR", "title": "Syntax error near line 1"},+ map[string]any{"status": "ERROR", "title": "Invalid column type"},+ },+ }+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y BOGUS",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ require.Equal(t, "DONE", output.PlanChecks.Status)+ require.Equal(t, 2, output.PlanChecks.Summary.Error)+ // Errors block rollout.+ require.False(t, output.RolloutCreated)+ require.Equal(t, "PLAN_CHECK_ERROR", output.RolloutDeferredReason)+ require.Equal(t, "FIX_SQL_AND_RETRY", output.NextAction)+}++func TestChange_PlanChecks_StillRunning(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "RUNNING",+ "results": []any{},+ }+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ require.Equal(t, "RUNNING", output.PlanChecks.Status)+ require.NotEmpty(t, output.PlanChecks.PlanCheckRun)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "PLAN_CHECK_PENDING", output.RolloutDeferredReason)+ require.Equal(t, "WAIT_PLAN_CHECK", output.NextAction)+ // Issue should still be created.+ require.NotEmpty(t, output.Issue)+}++func TestChange_PlanChecks_Failed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "FAILED",+ "results": []any{},+ }+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ require.Equal(t, "FAILED", output.PlanChecks.Status)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "PLAN_CHECK_ERROR", output.RolloutDeferredReason)+ require.Equal(t, "FIX_SQL_AND_RETRY", output.NextAction)+}++func TestChange_PlanChecks_RunPlanChecksAPIFailure(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.runPlanChecksStatus = http.StatusInternalServerError+ // GetPlanCheckRun still works (CreatePlan auto-triggers checks).+ mock.planCheckRunResponse = defaultPlanCheckDone()+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ // RunPlanChecks failure is ignored; poll picks up results from CreatePlan-triggered checks.+ require.Equal(t, "DONE", output.PlanChecks.Status)+ // Issue still created.+ require.NotEmpty(t, output.Issue)+}++func TestChange_PlanChecks_PollFailure(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunStatus = http.StatusInternalServerError+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.NotNil(t, output.PlanChecks)+ require.Equal(t, "RUNNING", output.PlanChecks.Status)+ // Issue still created.+ require.NotEmpty(t, output.Issue)+}++// --- Rollout gating tests ---++func TestChange_Rollout_ApprovalPending(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("PENDING")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "APPROVAL_PENDING", output.RolloutDeferredReason)+ require.Equal(t, "APPROVE_ISSUE", output.NextAction)+}++func TestChange_Rollout_ApprovalSkipped(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("SKIPPED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.True(t, output.RolloutCreated)+ require.Equal(t, "MONITOR_ROLLOUT", output.NextAction)+}++func TestChange_Rollout_CreateFailed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("APPROVED")+ mock.rolloutStatus = http.StatusInternalServerError+ mock.rolloutResponse = map[string]any{"message": "internal error"}+ s := newChangeTestServer(t, mock)++ result, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "ROLLOUT_CREATE_FAILED", output.RolloutDeferredReason)+ // Should NOT be APPROVE_ISSUE — don't assume approval pending.+ require.NotEqual(t, "APPROVE_ISSUE", output.NextAction)+ // Backend error should be forwarded in the text output.+ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "rollout creation failed")+}++func TestChange_Rollout_GateOrder(t *testing.T) {+ // Plan checks have errors AND approval is pending.+ // PLAN_CHECK_ERROR should win (checked first).+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "DONE",+ "results": []any{+ map[string]any{"status": "ERROR", "title": "Bad SQL"},+ },+ }+ mock.issueResponse = defaultIssueResponse("PENDING")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y BOGUS",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "PLAN_CHECK_ERROR", output.RolloutDeferredReason)+ require.Equal(t, "FIX_SQL_AND_RETRY", output.NextAction)+}++func TestChange_Rollout_ApprovalRejected(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("REJECTED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.False(t, output.RolloutCreated)+ require.Equal(t, "APPROVAL_REJECTED", output.RolloutDeferredReason)+ require.Equal(t, "FIX_SQL_AND_RETRY", output.NextAction)+ // Rollout should NOT have been attempted.+ require.Nil(t, mock.getCapturedRollout())+}++func TestChange_Rollout_RequestShape(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ rollout := mock.getCapturedRollout()+ require.NotNil(t, rollout)+ // CreateRollout uses parent=<plan> with no rollout body payload.+ require.Equal(t, "projects/hr-system/plans/2002", rollout["parent"])+ _, hasRollout := rollout["rollout"]+ require.False(t, hasRollout, "CreateRollout should not have a rollout body field")+}++// --- Resolution and validation tests ---++func TestChange_DatabaseNotFound(t *testing.T) {+ mock := newChangeMock(nil) // no databases+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "nonexistent",+ SQL: "SELECT 1",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "DATABASE_NOT_FOUND")+}++func TestChange_AmbiguousDatabase_ElicitationCancelled(t *testing.T) {+ // Two databases with the same short name on different instances.+ databases := []map[string]any{+ makeDatabase("instances/prod-pg/databases/app", "instances/prod-pg", "projects/payments", "POSTGRES", "ds-1"),+ makeDatabase("instances/staging-pg/databases/app", "instances/staging-pg", "projects/staging", "POSTGRES", "ds-2"),+ }+ mock := newChangeMock(databases)+ s := newChangeTestServer(t, mock)++ // nil request means no session -> elicitation unavailable -> fallback to AMBIGUOUS_TARGET.+ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "app",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "AMBIGUOUS_TARGET")+ require.Contains(t, text, "prod-pg")+ require.Contains(t, text, "staging-pg")+}++func TestChange_ProjectDerived(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "projects/hr-system", output.Project)++ // All API calls use the correct project parent.+ sheet := mock.getCapturedSheet()+ require.Equal(t, "projects/hr-system", sheet["parent"])+ plan := mock.getCapturedPlan()+ require.Equal(t, "projects/hr-system", plan["parent"])+ issue := mock.getCapturedIssue()+ require.Equal(t, "projects/hr-system", issue["parent"])+}++func TestChange_ProjectWrongFilter(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ // Wrong project filters out the database at the server level.+ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ Project: "wrong-project",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "DATABASE_NOT_FOUND")+}++func TestChange_ProjectDisambiguates(t *testing.T) {+ // Same database name in two projects.+ databases := []map[string]any{+ makeDatabase("instances/prod-pg/databases/app", "instances/prod-pg", "projects/payments", "POSTGRES", "ds-1"),+ makeDatabase("instances/staging-pg/databases/app", "instances/staging-pg", "projects/staging", "POSTGRES", "ds-2"),+ }+ mock := newChangeMock(databases)+ mock.sheetResponse = map[string]any{"name": "projects/payments/sheets/1001"}+ mock.planResponse = map[string]any{"name": "projects/payments/plans/2002"}+ mock.issueResponse = map[string]any{"name": "projects/payments/issues/3003", "approvalStatus": "APPROVED"}+ s := newChangeTestServer(t, mock)++ // Providing project disambiguates without elicitation.+ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "app",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ Project: "payments",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "projects/payments", output.Project)+ require.Equal(t, "instances/prod-pg/databases/app", output.Database)+}++func TestChange_InvalidChangeType(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ ChangeType: "DML_FIX",+ })+ require.NoError(t, err)+ require.NotNil(t, result)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "INVALID_ARGUMENT")+ require.Contains(t, text, "MIGRATE")+ require.Contains(t, text, "SDL")+}++func TestChange_MissingRequiredFields(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ tests := []struct {+ name string+ input ChangeInput+ field string+ }{+ {+ name: "missing sql",+ input: ChangeInput{Database: "employee_db", Title: "Test"},+ field: "sql",+ },+ {+ name: "missing title",+ input: ChangeInput{Database: "employee_db", SQL: "SELECT 1"},+ field: "title",+ },+ {+ name: "missing database",+ input: ChangeInput{SQL: "SELECT 1", Title: "Test"},+ field: "database",+ },+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ _, _, err := s.handleChange(testContext(), nil, tc.input)+ require.Error(t, err)+ require.Contains(t, err.Error(), tc.field)+ })+ }+}++func TestChange_ReasonTruncation(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ longReason := strings.Repeat("x", 2000)+ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ Reason: longReason,+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "reason truncated to 1000 chars")++ // Issue description should be truncated.+ issue := mock.getCapturedIssue()+ issueObj, ok := issue["issue"].(map[string]any)+ require.True(t, ok)+ desc, ok := issueObj["description"].(string)+ require.True(t, ok)+ require.Len(t, desc, 1000) // 997 chars + "..."+}++// --- Partial failure tests ---++func TestChange_SheetCreateFailed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.sheetStatus = http.StatusInternalServerError+ mock.sheetResponse = map[string]any{"message": "internal error"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "SHEET_CREATE_FAILED")+ // No partialRefs since nothing was created.+ require.NotContains(t, text, "partialRefs")+}++func TestChange_PlanCreateFailed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planStatus = http.StatusInternalServerError+ mock.planResponse = map[string]any{"message": "internal error"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "PLAN_CREATE_FAILED")+ require.Contains(t, text, "sheets/1001") // partialRefs includes sheet+}++func TestChange_IssueCreateFailed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueStatus = http.StatusInternalServerError+ mock.issueResponse = map[string]any{"message": "internal error"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "ISSUE_CREATE_FAILED")+ require.Contains(t, text, "sheets/1001") // partialRefs+ require.Contains(t, text, "plans/2002") // partialRefs+}++func TestChange_IssueCreateFailed_SqlReview(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planCheckRunResponse = map[string]any{+ "status": "DONE",+ "results": []any{+ map[string]any{"status": "ERROR", "title": "SQL review failed"},+ },+ }+ mock.issueStatus = http.StatusBadRequest+ mock.issueResponse = map[string]any{"message": "enforceSqlReview: checks failed"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y BOGUS",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "ISSUE_CREATE_FAILED")+ require.Contains(t, text, "plan checks must pass")+ // Verify the output is valid JSON (guidance folded into suggestion, not appended as raw text).+ var parsed changeError+ require.NoError(t, json.Unmarshal([]byte(text), &parsed))+ require.Equal(t, "ISSUE_CREATE_FAILED", parsed.Code)+ require.Contains(t, parsed.Suggestion, "plan checks must pass")+}++// --- Permission tests ---++func TestChange_PermissionDenied_Sheet(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.sheetStatus = http.StatusForbidden+ mock.sheetResponse = map[string]any{"message": "permission denied"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "PERMISSION_DENIED")+ require.Contains(t, text, "bb.sheets.create")+}++func TestChange_PermissionDenied_Plan(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.planStatus = http.StatusForbidden+ mock.planResponse = map[string]any{"message": "permission denied"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "PERMISSION_DENIED")+ require.Contains(t, text, "bb.plans.create")+ require.Contains(t, text, "sheets/1001") // partialRefs+}++func TestChange_PermissionDenied_Issue(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueStatus = http.StatusForbidden+ mock.issueResponse = map[string]any{"message": "permission denied"}+ s := newChangeTestServer(t, mock)++ result, _, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "PERMISSION_DENIED")+ require.Contains(t, text, "bb.issues.create")+ require.Contains(t, text, "sheets/1001") // partialRefs+ require.Contains(t, text, "plans/2002") // partialRefs+}++// --- Link construction tests ---++func TestChange_Links_Constructed(t *testing.T) {+ mock := newChangeMock(employeeDB())+ mock.issueResponse = defaultIssueResponse("APPROVED")+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ CreateRollout: true,+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Equal(t, "https://bytebase.example.com/projects/hr-system/issues/3003", output.Links.Issue)+ require.Equal(t, "https://bytebase.example.com/projects/hr-system/plans/2002", output.Links.Plan)+ require.Equal(t, "https://bytebase.example.com/projects/hr-system/rollouts/4004", output.Links.Rollout)+}++func TestChange_Links_TrailingSlash(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)+ s.profile.ExternalURL = "https://bytebase.example.com/"++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ // No double slash.+ require.Equal(t, "https://bytebase.example.com/projects/hr-system/issues/3003", output.Links.Issue)+}++func TestChange_Links_RolloutOmitted(t *testing.T) {+ mock := newChangeMock(employeeDB())+ s := newChangeTestServer(t, mock)++ _, structured, err := s.handleChange(testContext(), nil, ChangeInput{+ Database: "employee_db",+ SQL: "ALTER TABLE x ADD COLUMN y INT",+ Title: "Test",+ })+ require.NoError(t, err)++ output, ok := structured.(*ChangeOutput)+ require.True(t, ok)+ require.Empty(t, output.Links.Rollout)+}diff --git a/backend/api/mcp/tool_resolve.go b/backend/api/mcp/tool_resolve.goindex 8166aca4af..971e5e27e3 100644--- a/backend/api/mcp/tool_resolve.go+++ b/backend/api/mcp/tool_resolve.go@@ -27,10 +27,12 @@ type resolvedDatabase struct {resourceName stringdataSourceID stringengine string+ project string // "projects/{id}" from databaseEntry.Projectambiguous boolcandidates []CandidatedataSourceIDs map[string]string // resourceName -> dataSourceID (populated when ambiguous)engines map[string]string // resourceName -> engine (populated when ambiguous)+ projects map[string]string // resourceName -> project (populated when ambiguous)}// listDatabasesResponse is the typed response from ListDatabases API.@@ -156,6 +158,7 @@ func matchDatabases(databases []databaseEntry, database, instance, project strinresourceName: db.Name,dataSourceID: selectDataSource(db.InstanceResource.DataSources),engine: db.InstanceResource.Engine,+ project: db.Project,}, nil}@@ -164,6 +167,7 @@ func buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {candidates := make([]Candidate, 0, len(matches))dsIDs := make(map[string]string, len(matches))engines := make(map[string]string, len(matches))+ projects := make(map[string]string, len(matches))for _, db := range matches {candidates = append(candidates, Candidate{Database: db.Name,@@ -173,12 +177,14 @@ func buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {})dsIDs[db.Name] = selectDataSource(db.InstanceResource.DataSources)engines[db.Name] = db.InstanceResource.Engine+ projects[db.Name] = db.Project}return &resolvedDatabase{ambiguous: true,candidates: candidates,dataSourceIDs: dsIDs,engines: engines,+ projects: projects,}}@@ -244,6 +250,7 @@ func (*Server) elicitDatabaseChoice(ctx context.Context, req *mcp.CallToolRequesresourceName: resourceName,dataSourceID: resolved.dataSourceIDs[resourceName],engine: resolved.engines[resourceName],+ project: resolved.projects[resourceName],}, nil}diff --git a/backend/api/mcp/tool_resolve_test.go b/backend/api/mcp/tool_resolve_test.gonew file mode 100644index 0000000000..218eb00486--- /dev/null+++ b/backend/api/mcp/tool_resolve_test.go@@ -0,0 +1,58 @@+package mcp++import (+ "testing"++ "github.com/stretchr/testify/require"+)++func TestResolve_ProjectPopulated(t *testing.T) {+ databases := []databaseEntry{+ {+ Name: "instances/prod-pg/databases/employee_db",+ Project: "projects/hr-system",+ InstanceResource: instanceResource{+ Name: "instances/prod-pg",+ Engine: "POSTGRES",+ DataSources: []dataSource{{ID: "ds-admin-1", Type: "ADMIN"}},+ },+ },+ }++ resolved, err := matchDatabases(databases, "employee_db", "", "")+ require.NoError(t, err)+ require.False(t, resolved.ambiguous)+ require.Equal(t, "projects/hr-system", resolved.project)+ require.Equal(t, "instances/prod-pg/databases/employee_db", resolved.resourceName)+ require.Equal(t, "POSTGRES", resolved.engine)+}++func TestResolve_ProjectInAmbiguous(t *testing.T) {+ databases := []databaseEntry{+ {+ Name: "instances/prod-pg/databases/app",+ Project: "projects/payments",+ InstanceResource: instanceResource{+ Name: "instances/prod-pg",+ Engine: "POSTGRES",+ DataSources: []dataSource{{ID: "ds-1", Type: "ADMIN"}},+ },+ },+ {+ Name: "instances/staging-pg/databases/app",+ Project: "projects/staging",+ InstanceResource: instanceResource{+ Name: "instances/staging-pg",+ Engine: "POSTGRES",+ DataSources: []dataSource{{ID: "ds-2", Type: "ADMIN"}},+ },+ },+ }++ resolved, err := matchDatabases(databases, "app", "", "")+ require.NoError(t, err)+ require.True(t, resolved.ambiguous)+ require.Len(t, resolved.candidates, 2)+ require.Equal(t, "projects/payments", resolved.projects["instances/prod-pg/databases/app"])+ require.Equal(t, "projects/staging", resolved.projects["instances/staging-pg/databases/app"])+}diff --git a/backend/api/mcp/tool_skill.go b/backend/api/mcp/tool_skill.goindex c5c84bc9c4..dbf73a78f8 100644--- a/backend/api/mcp/tool_skill.go+++ b/backend/api/mcp/tool_skill.go@@ -30,7 +30,7 @@ type skillMeta struct {// getSkillDescription is the description for the get_skill tool.const getSkillDescription = `Get step-by-step guides for Bytebase tasks.-**Tip:** Use query_database tool for SQL queries — it handles database resolution automatically.+**Tip:** Use query_database for SQL queries and propose_database_change for single-database DDL/DML — they handle resolution automatically.**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)