Skip to content

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

feat(mcp): add propose_database_change tool (#19963)

Vincent Huang34d53b3f12e9
diff --git a/backend/api/mcp/server.go b/backend/api/mcp/server.go
index 6ab387d5bf..5ab90e88f6 100644
--- a/backend/api/mcp/server.go
+++ b/backend/api/mcp/server.go
@@ -4,6 +4,7 @@ package mcp
import (
"net/http"
"strings"
+ "time"
"github.com/golang-jwt/jwt/v5"
"github.com/labstack/echo/v5"
@@ -23,6 +24,10 @@ type Server struct {
profile *config.Profile
secret string
openAPIIndex *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.md
index 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 plan
Plan 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 Errors
diff --git a/backend/api/mcp/tool_change.go b/backend/api/mcp/tool_change.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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 string
dataSourceID string
engine string
+ project string // "projects/{id}" from databaseEntry.Project
ambiguous bool
candidates []Candidate
dataSourceIDs 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 strin
resourceName: 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.CallToolReques
resourceName: 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.go
new file mode 100644
index 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.go
index 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(...)