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 get_schema tool for single-call database inspection (#19916)
Vincent Huangddaaf9ff96e5
diff --git a/backend/api/mcp/server.go b/backend/api/mcp/server.goindex 1c3f10580e..6ab387d5bf 100644--- a/backend/api/mcp/server.go+++ b/backend/api/mcp/server.go@@ -61,6 +61,7 @@ func (s *Server) registerTools() {s.registerCallTool()s.registerSkillTool()s.registerQueryTool()+ s.registerSchemaTool()}// authMiddleware validates OAuth2 bearer tokens for MCP requests.diff --git a/backend/api/mcp/skills/query.md b/backend/api/mcp/skills/query.mdindex daa5bf5333..4691886dfd 100644--- a/backend/api/mcp/skills/query.md+++ b/backend/api/mcp/skills/query.md@@ -9,6 +9,8 @@ description: Use when running SQL queries, executing SELECT/INSERT/UPDATE/DELETERun SQL queries against databases managed by Bytebase.+**Before writing SQL, call `get_schema(database=...)` to see the current shape.**+## Prerequisites- Know the instance and database namediff --git a/backend/api/mcp/tool_resolve.go b/backend/api/mcp/tool_resolve.goindex 4e8b9a3747..8166aca4af 100644--- a/backend/api/mcp/tool_resolve.go+++ b/backend/api/mcp/tool_resolve.go@@ -26,9 +26,11 @@ type Candidate struct {type resolvedDatabase struct {resourceName stringdataSourceID string+ engine stringambiguous boolcandidates []CandidatedataSourceIDs map[string]string // resourceName -> dataSourceID (populated when ambiguous)+ engines map[string]string // resourceName -> engine (populated when ambiguous)}// listDatabasesResponse is the typed response from ListDatabases API.@@ -153,6 +155,7 @@ func matchDatabases(databases []databaseEntry, database, instance, project strinreturn &resolvedDatabase{resourceName: db.Name,dataSourceID: selectDataSource(db.InstanceResource.DataSources),+ engine: db.InstanceResource.Engine,}, nil}@@ -160,6 +163,7 @@ func matchDatabases(databases []databaseEntry, database, instance, project strinfunc buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {candidates := make([]Candidate, 0, len(matches))dsIDs := make(map[string]string, len(matches))+ engines := make(map[string]string, len(matches))for _, db := range matches {candidates = append(candidates, Candidate{Database: db.Name,@@ -168,8 +172,14 @@ func buildAmbiguousResult(matches []databaseEntry) *resolvedDatabase {Engine: db.InstanceResource.Engine,})dsIDs[db.Name] = selectDataSource(db.InstanceResource.DataSources)+ engines[db.Name] = db.InstanceResource.Engine+ }+ return &resolvedDatabase{+ ambiguous: true,+ candidates: candidates,+ dataSourceIDs: dsIDs,+ engines: engines,}- return &resolvedDatabase{ambiguous: true, candidates: candidates, dataSourceIDs: dsIDs}}// resolveDatabase resolves a database name to a unique resource using tiered matching.@@ -185,6 +195,10 @@ func (s *Server) resolveDatabase(ctx context.Context, database, instance, projec// using MCP elicitation. Returns an error if elicitation is unsupported, the user// cancels/declines, or the selection is invalid.func (*Server) elicitDatabaseChoice(ctx context.Context, req *mcp.CallToolRequest, resolved *resolvedDatabase) (*resolvedDatabase, error) {+ if req == nil || req.Session == nil {+ return nil, errors.New("elicitation unsupported: no session")+ }+// Build enum values and a lookup map from display label to resource name.enumValues := make([]any, 0, len(resolved.candidates))resourceByLabel := make(map[string]string, len(resolved.candidates))@@ -229,6 +243,7 @@ func (*Server) elicitDatabaseChoice(ctx context.Context, req *mcp.CallToolRequesreturn &resolvedDatabase{resourceName: resourceName,dataSourceID: resolved.dataSourceIDs[resourceName],+ engine: resolved.engines[resourceName],}, nil}diff --git a/backend/api/mcp/tool_schema.go b/backend/api/mcp/tool_schema.gonew file mode 100644index 0000000000..d00fd28b49--- /dev/null+++ b/backend/api/mcp/tool_schema.go@@ -0,0 +1,776 @@+package mcp++import (+ "context"+ "encoding/json"+ "fmt"+ "net/http"+ "slices"+ "strings"+ "time"++ "github.com/modelcontextprotocol/go-sdk/mcp"+ "github.com/pkg/errors"+)++const (+ schemaFetchTimeout = 30 * time.Second+ // schemaTableLimit is the user-facing cap on tables returned per schema in+ // bulk modes (columns/details). The server is asked for limit+1 so that+ // returning exactly `limit` vs. truncated-at-limit can be disambiguated.+ schemaTableLimit = 200+ // schemaCandidateFetchLimit bounds the second (no-filter) fetch used to build+ // candidate suggestions on TABLE_NOT_FOUND. Large enough to surface any reasonable+ // typo, small enough to cap wire payload.+ schemaCandidateFetchLimit = 500+ // schemaCandidateResultCap is the max number of candidate names returned in the+ // TABLE_NOT_FOUND error body.+ schemaCandidateResultCap = 10+)++// Detail levels for the `include` parameter.+const (+ schemaIncludeSummary = "summary"+ schemaIncludeColumns = "columns"+ schemaIncludeDetails = "details"+)++// multiSchemaEngines lists database engines that expose multiple user-visible+// schemas under a single database. On all other engines the schema name is+// empty (MySQL/TiDB/etc.), so a non-empty `schema == "..."` server-side filter+// would produce an exact-match failure and return zero tables. For those+// engines we drop the schema filter client-side before calling the backend.+//+// The backend enforces `schema == "X"` as an exact match in+// convertStoreDatabaseMetadata (see database_converter.go). Adding a new+// multi-schema engine requires updating this set.+var multiSchemaEngines = map[string]bool{+ "POSTGRES": true,+ "COCKROACHDB": true,+ "MSSQL": true,+ "ORACLE": true,+ "SNOWFLAKE": true,+ "REDSHIFT": true,+ "DATABRICKS": true,+ "TRINO": true,+ "SPANNER": true,+ "HIVE": true,+}++// engineSupportsSchemas reports whether the given engine exposes named schemas+// to users. An empty engine string (unknown) is treated as single-schema for+// safety — the caller drops the filter and emits a note rather than risking+// zero tables from an exact-match miss.+func engineSupportsSchemas(engine string) bool {+ return multiSchemaEngines[engine]+}++// SchemaInput is the input for the get_schema tool.+type SchemaInput struct {+ // Database is the database name or substring to match (same rules as query_database).+ Database string `json:"database"`+ // Instance narrows database resolution to a specific instance.+ Instance string `json:"instance,omitempty"`+ // Project narrows database resolution to a specific project.+ Project string `json:"project,omitempty"`+ // Schema filters to a single PostgreSQL/MSSQL schema; ignored on engines without schemas.+ Schema string `json:"schema,omitempty"`+ // Table filters to a single table; implies include="details" when Include is empty.+ Table string `json:"table,omitempty"`+ // Include controls output detail level: "summary" (default), "columns", or "details".+ Include string `json:"include,omitempty"`+}++// SchemaOutput is the output for the get_schema tool.+type SchemaOutput struct {+ Database string `json:"database"` // full resource name+ Engine string `json:"engine"`+ Schemas []SchemaSection `json:"schemas,omitempty"` // used when Table is empty+ Table *TableDetail `json:"table,omitempty"` // used when Table is set+}++// SchemaSection holds per-schema metadata.+type SchemaSection struct {+ Name string `json:"name"` // "public" or "" for MySQL+ Tables []TableEntry `json:"tables"`+ Views []string `json:"views,omitempty"`+ FunctionCount int `json:"functionCount,omitempty"`+ ProcedureCount int `json:"procedureCount,omitempty"`+ Truncated bool `json:"truncated,omitempty"` // true when len(Tables) hit the per-schema limit+ TablesShown int `json:"tablesShown,omitempty"` // == len(Tables) when Truncated; omitted otherwise+}++// TableEntry describes a table. Which fields are populated depends on the include level.+type TableEntry struct {+ Name string `json:"name"`+ RowCount int64 `json:"rowCount"`+ ColumnCount int `json:"columnCount,omitempty"` // summary only; in columns/details modes, len(Columns) is the count+ Comment string `json:"comment,omitempty"`+ Columns []ColumnEntry `json:"columns,omitempty"` // columns++ Indexes []IndexEntry `json:"indexes,omitempty"` // details++ ForeignKeys []FKEntry `json:"foreignKeys,omitempty"` // details++}++// ColumnEntry describes a single column.+type ColumnEntry struct {+ Name string `json:"name"`+ Type string `json:"type"`+ Nullable bool `json:"nullable"`+ PrimaryKey bool `json:"primaryKey,omitempty"`+ Default string `json:"default,omitempty"` // details++ Comment string `json:"comment,omitempty"` // details++}++// IndexEntry describes an index on a table.+type IndexEntry struct {+ Name string `json:"name"`+ Type string `json:"type"`+ Unique bool `json:"unique"`+ Columns []string `json:"columns"`+}++// FKEntry describes a foreign key constraint.+type FKEntry struct {+ Name string `json:"name"`+ Columns []string `json:"columns"`+ ReferencedTable string `json:"referencedTable"`+ ReferencedColumns []string `json:"referencedColumns"`+}++// TableDetail is an alias for a details-level TableEntry used when the caller drills+// into a specific table.+type TableDetail = TableEntry++// --- Proto response types (decoded from GetDatabaseMetadata) ---+//+// These mirror the fields we consume from the DatabaseMetadata protobuf. We only+// decode what the tool actually needs; extra fields are ignored by json.Unmarshal.++type databaseMetadata struct {+ Name string `json:"name"`+ Schemas []schemaMetadata `json:"schemas"`+}++type schemaMetadata struct {+ Name string `json:"name"`+ Tables []tableMetadata `json:"tables"`+ Views []viewMetadata `json:"views"`+ Functions []namedMetadata `json:"functions"`+ Procedures []namedMetadata `json:"procedures"`+}++type tableMetadata struct {+ Name string `json:"name"`+ Columns []columnMetadata `json:"columns"`+ Indexes []indexMetadata `json:"indexes"`+ RowCount json.Number `json:"rowCount"`+ Comment string `json:"comment"`+ ForeignKeys []foreignKeyMetadata `json:"foreignKeys"`+}++type columnMetadata struct {+ Name string `json:"name"`+ Type string `json:"type"`+ Nullable bool `json:"nullable"`+ Default string `json:"default"`+ Comment string `json:"comment"`+}++type indexMetadata struct {+ Name string `json:"name"`+ Expressions []string `json:"expressions"`+ Type string `json:"type"`+ Unique bool `json:"unique"`+ Primary bool `json:"primary"`+}++type foreignKeyMetadata struct {+ Name string `json:"name"`+ Columns []string `json:"columns"`+ ReferencedTable string `json:"referencedTable"`+ ReferencedColumns []string `json:"referencedColumns"`+}++type viewMetadata struct {+ Name string `json:"name"`+}++type namedMetadata struct {+ Name string `json:"name"`+}++// getSchemaDescription is the description for the get_schema tool.+const getSchemaDescription = `Inspect a Bytebase database's schema.++| Parameter | Required | Description |+|-----------|----------|-------------|+| database | Yes | Database name or substring (e.g., "employee_db" or "employee") |+| instance | No | Instance name to narrow resolution |+| project | No | Project name to narrow resolution |+| schema | No | Schema name for multi-schema engines (PG/MSSQL/Oracle/Snowflake/Redshift/CockroachDB/Databricks/Trino/Spanner/Hive); ignored with a note on MySQL/TiDB/etc. |+| table | No | Drill into a single table; implies include="details" |+| include | No | Detail level: "summary" (default), "columns", "details" |++**Usage:**+- First call: get_schema(database="employee") → compact overview+- Drill down: get_schema(database="employee", table="orders") → full table detail+- Write a query: get_schema(database="employee", include="columns") → all tables with columns++**Notes:**+- Metadata is auto-synced on access. The first call to a stale database may take longer.+- For databases with many tables, columns/details modes return up to 200 tables PER SCHEMA.+ Use schema= or table= to narrow further.+- Column masking metadata is only returned when table= is set.+- Requires bb.databases.getSchema permission.`++func (s *Server) registerSchemaTool() {+ mcp.AddTool(s.mcpServer, &mcp.Tool{+ Name: "get_schema",+ Description: getSchemaDescription,+ }, s.handleGetSchema)+}++func (s *Server) handleGetSchema(ctx context.Context, req *mcp.CallToolRequest, input SchemaInput) (*mcp.CallToolResult, any, error) {+ if input.Database == "" {+ return nil, nil, errors.New("database is required")+ }++ include, err := resolveIncludeLevel(input)+ if err != nil {+ return nil, nil, err+ }++ resolved, resolveResult := s.resolveSchemaTarget(ctx, req, input)+ if resolveResult != nil {+ return resolveResult, nil, nil+ }++ // On engines that don't expose named schemas (MySQL, TiDB, ClickHouse, etc.),+ // drop the schema filter and note the drop. The backend applies `schema == "..."`+ // as an exact match, so passing a non-empty hint like "public" on MySQL would+ // filter out every table. Results are still returned; the note tells the caller+ // why the parameter was ignored.+ var warnings []string+ schemaHint := input.Schema+ if schemaHint != "" && !engineSupportsSchemas(resolved.engine) {+ warnings = append(warnings, fmt.Sprintf("schema parameter ignored — %s does not use named schemas", resolved.engine))+ schemaHint = ""+ }++ // Fetch metadata with server-side filter + limit.+ fetchCtx, fetchCancel := context.WithTimeout(ctx, schemaFetchTimeout)+ defer fetchCancel()++ metadata, err := s.fetchMetadata(fetchCtx, resolved.resourceName, buildMetadataFilter(schemaHint, input.Table), limitForInclude(include, input.Table))+ if err != nil {+ return formatToolError(err), nil, nil+ }++ if input.Table != "" {+ result, output := s.renderTableResult(fetchCtx, resolved, input, schemaHint, metadata, include, warnings)+ return result, output, nil+ }+ result, output := renderSchemasResult(resolved, metadata, include, warnings)+ return result, output, nil+}++// resolveIncludeLevel normalizes and validates the `include` parameter.+// When empty, it defaults to "details" if a table was requested and "summary" otherwise.+func resolveIncludeLevel(input SchemaInput) (string, error) {+ include := input.Include+ if include == "" {+ if input.Table != "" {+ return schemaIncludeDetails, nil+ }+ return schemaIncludeSummary, nil+ }+ if include != schemaIncludeSummary && include != schemaIncludeColumns && include != schemaIncludeDetails {+ return "", errors.Errorf("invalid include value %q (must be summary|columns|details)", input.Include)+ }+ return include, nil+}++// resolveSchemaTarget runs the shared database resolver and handles the ambiguous+// case with elicitation fallback. Returns either a resolved database (on success)+// or a non-nil CallToolResult describing the error for the caller to return.+func (s *Server) resolveSchemaTarget(ctx context.Context, req *mcp.CallToolRequest, input SchemaInput) (*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+}++// renderTableResult dispatches the `table=` drill-down path: it picks the unique+// match (or returns an appropriate error result) and renders it as TableDetail.+// schemaHint is the engine-adjusted schema filter (empty when dropped for+// single-schema engines) and is used for the candidate-lookup refetch too.+func (s *Server) renderTableResult(ctx context.Context, resolved *resolvedDatabase, input SchemaInput, schemaHint string, metadata *databaseMetadata, include string, warnings []string) (*mcp.CallToolResult, any) {+ matches := findTableMatches(metadata, input.Table)+ switch {+ case len(matches) == 0:+ // Re-fetch without table filter to surface candidates.+ candidates := s.lookupTableCandidates(ctx, resolved.resourceName, schemaHint, input.Table)+ return formatTableNotFound(input.Database, input.Table, candidates), nil+ case len(matches) > 1:+ // Same table name in multiple schemas. Don't silently pick one.+ schemas := make([]string, 0, len(matches))+ for _, m := range matches {+ schemas = append(schemas, m.schema)+ }+ return formatAmbiguousTable(input.Database, input.Table, schemas), nil+ }+ entry := buildTableEntry(matches[0].table, schemaIncludeDetails)+ output := &SchemaOutput{+ Database: resolved.resourceName,+ Engine: resolved.engine,+ Table: &entry,+ }+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: formatSchemaOutput(output, include, warnings)}},+ }, output+}++// renderSchemasResult handles the bulk schema listing path (no table drill-down).+func renderSchemasResult(resolved *resolvedDatabase, metadata *databaseMetadata, include string, warnings []string) (*mcp.CallToolResult, any) {+ output := &SchemaOutput{+ Database: resolved.resourceName,+ Engine: resolved.engine,+ Schemas: transformSchemas(metadata, include),+ }+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: formatSchemaOutput(output, include, warnings)}},+ }, output+}++// buildMetadataFilter builds a CEL filter string for GetDatabaseMetadataRequest.+// Returns the empty string when no narrowing is needed.+func buildMetadataFilter(schema, table string) string {+ var parts []string+ if schema != "" {+ parts = append(parts, fmt.Sprintf("schema == %q", schema))+ }+ if table != "" {+ parts = append(parts, fmt.Sprintf("table == %q", table))+ }+ return strings.Join(parts, " && ")+}++// limitForInclude returns the per-schema `limit` value to send to the server.+// Summary and single-table modes don't need a limit. Bulk modes request+// schemaTableLimit+1 so the client can disambiguate exactly-200 from+// truncated-at-200.+func limitForInclude(include, table string) int32 {+ if table != "" {+ return 0+ }+ if include == schemaIncludeColumns || include == schemaIncludeDetails {+ return int32(schemaTableLimit + 1)+ }+ return 0+}++// fetchMetadata calls DatabaseService/GetDatabaseMetadata and decodes the response.+func (s *Server) fetchMetadata(ctx context.Context, resourceName, filter string, limit int32) (*databaseMetadata, error) {+ body := map[string]any{+ "name": resourceName + "/metadata",+ }+ if filter != "" {+ body["filter"] = filter+ }+ if limit > 0 {+ body["limit"] = limit+ }++ resp, err := s.apiRequest(ctx, "/bytebase.v1.DatabaseService/GetDatabaseMetadata", body)+ if err != nil {+ return nil, &toolError{+ Code: "SCHEMA_FETCH_ERROR",+ Message: fmt.Sprintf("metadata request failed: %s", err.Error()),+ Suggestion: "check network connectivity and try again",+ }+ }++ if resp.Status >= 400 {+ return nil, translateMetadataError(resp)+ }++ var metadata databaseMetadata+ if err := json.Unmarshal(resp.Body, &metadata); err != nil {+ return nil, errors.Wrap(err, "failed to parse database metadata")+ }+ return &metadata, nil+}++// translateMetadataError maps GetDatabaseMetadata HTTP errors into toolError codes.+func translateMetadataError(resp *apiResponse) error {+ errMsg := parseError(resp.Body)+ switch resp.Status {+ case http.StatusNotFound:+ return &toolError{+ Code: "DATABASE_NOT_FOUND",+ Message: "database not found",+ Suggestion: "check the database name or use search_api to list available databases",+ }+ case http.StatusForbidden, http.StatusUnauthorized:+ return &toolError{+ Code: "PERMISSION_DENIED",+ Message: "you don't have permission to read this database's schema",+ Suggestion: "ask your workspace admin to grant you the bb.databases.getSchema permission",+ }+ case http.StatusInternalServerError:+ suggestion := "check instance connectivity in the Bytebase UI"+ if errMsg != "" {+ suggestion = fmt.Sprintf("%s; backend error: %s", suggestion, errMsg)+ }+ return &toolError{+ Code: "SCHEMA_SYNC_FAILED",+ Message: "the database is reachable but the schema sync failed",+ Suggestion: suggestion,+ }+ default:+ if errMsg == "" {+ errMsg = fmt.Sprintf("HTTP %d", resp.Status)+ }+ return &toolError{+ Code: "SCHEMA_FETCH_ERROR",+ Message: errMsg,+ Suggestion: "check the database name and try again",+ }+ }+}++// tableMatch holds a single (schema, table) match found during lookup.+type tableMatch struct {+ schema string+ table *tableMetadata+}++// findTableMatches returns every (schema, table) pair whose table name equals+// the requested name. The caller decides how to handle 0, 1, or multiple matches.+func findTableMatches(metadata *databaseMetadata, table string) []tableMatch {+ var matches []tableMatch+ for i := range metadata.Schemas {+ schema := &metadata.Schemas[i]+ for j := range schema.Tables {+ t := &schema.Tables[j]+ if t.Name == table {+ matches = append(matches, tableMatch{schema: schema.Name, table: t})+ }+ }+ }+ return matches+}++// lookupTableCandidates issues a second GetDatabaseMetadata call (no table filter)+// to build a list of candidate table names for a TABLE_NOT_FOUND error.+// Bounded by schemaCandidateFetchLimit per schema on the wire and+// schemaCandidateResultCap on the returned slice.+func (s *Server) lookupTableCandidates(ctx context.Context, resourceName, schemaFilter, missing string) []string {+ filter := buildMetadataFilter(schemaFilter, "")+ metadata, err := s.fetchMetadata(ctx, resourceName, filter, int32(schemaCandidateFetchLimit))+ if err != nil || metadata == nil {+ return nil+ }+ var candidates []string+ for _, schema := range metadata.Schemas {+ for _, t := range schema.Tables {+ if tableNameMatches(t.Name, missing) {+ candidates = append(candidates, t.Name)+ if len(candidates) >= schemaCandidateResultCap {+ return candidates+ }+ }+ }+ }+ return candidates+}++// tableNameMatches returns true if `name` is a plausible candidate for a typo of+// `missing`. A name matches if it contains the input as a (case-insensitive)+// substring, or if it shares a sufficiently long common prefix (useful for typos+// like "orderz" → "orders", "order_items").+func tableNameMatches(name, missing string) bool {+ n := strings.ToLower(name)+ m := strings.ToLower(missing)+ if m == "" {+ return false+ }+ if strings.Contains(n, m) {+ return true+ }+ // Require a shared prefix of at least 4 chars (or the full input if shorter).+ prefixLen := min(4, len(m))+ if len(n) < prefixLen {+ return false+ }+ return n[:prefixLen] == m[:prefixLen]+}++// transformSchemas converts decoded metadata into the response shape for the+// given include level. Applies sorting and per-schema truncation.+func transformSchemas(metadata *databaseMetadata, include string) []SchemaSection {+ // Only bulk-detail modes ask the server for limit+1 and need the "trim to+ // schemaTableLimit and flag Truncated" dance. Summary mode is designed to+ // return every table because the per-table payload is tiny — applying the+ // cap there would silently drop tables from agents' view.+ applyTruncation := include == schemaIncludeColumns || include == schemaIncludeDetails++ sections := make([]SchemaSection, 0, len(metadata.Schemas))+ for i := range metadata.Schemas {+ schema := &metadata.Schemas[i]++ // Sort tables alphabetically by name.+ slices.SortStableFunc(schema.Tables, func(a, b tableMetadata) int {+ return strings.Compare(a.Name, b.Name)+ })++ truncated := false+ tablesShown := 0+ if applyTruncation && len(schema.Tables) > schemaTableLimit {+ // Drop the sentinel 201st entry.+ schema.Tables = schema.Tables[:schemaTableLimit]+ truncated = true+ tablesShown = schemaTableLimit+ }++ tables := make([]TableEntry, 0, len(schema.Tables))+ for j := range schema.Tables {+ tables = append(tables, buildTableEntry(&schema.Tables[j], include))+ }++ views := make([]string, 0, len(schema.Views))+ for _, v := range schema.Views {+ views = append(views, v.Name)+ }+ slices.Sort(views)++ sections = append(sections, SchemaSection{+ Name: schema.Name,+ Tables: tables,+ Views: views,+ FunctionCount: len(schema.Functions),+ ProcedureCount: len(schema.Procedures),+ Truncated: truncated,+ TablesShown: tablesShown,+ })+ }++ // Sort schemas alphabetically by name (empty string sorts first → MySQL friendly).+ slices.SortStableFunc(sections, func(a, b SchemaSection) int {+ return strings.Compare(a.Name, b.Name)+ })+ return sections+}++// buildTableEntry converts a single tableMetadata into the response shape at the+// requested detail level.+func buildTableEntry(t *tableMetadata, include string) TableEntry {+ rowCount, _ := t.RowCount.Int64()+ entry := TableEntry{+ Name: t.Name,+ RowCount: rowCount,+ Comment: t.Comment,+ }++ if include == schemaIncludeSummary {+ entry.ColumnCount = len(t.Columns)+ return entry+ }++ // Derive primary-key columns from indexes (ColumnMetadata has no primary_key field).+ pkColumns := primaryKeyColumns(t.Indexes)++ entry.Columns = make([]ColumnEntry, 0, len(t.Columns))+ for _, c := range t.Columns {+ col := ColumnEntry{+ Name: c.Name,+ Type: c.Type,+ Nullable: c.Nullable,+ PrimaryKey: pkColumns[c.Name],+ }+ if include == schemaIncludeDetails {+ col.Default = c.Default+ col.Comment = c.Comment+ }+ entry.Columns = append(entry.Columns, col)+ }++ if include == schemaIncludeDetails {+ entry.Indexes = make([]IndexEntry, 0, len(t.Indexes))+ for _, idx := range t.Indexes {+ entry.Indexes = append(entry.Indexes, IndexEntry{+ Name: idx.Name,+ Type: idx.Type,+ Unique: idx.Unique,+ Columns: append([]string{}, idx.Expressions...),+ })+ }+ slices.SortStableFunc(entry.Indexes, func(a, b IndexEntry) int {+ return strings.Compare(a.Name, b.Name)+ })++ entry.ForeignKeys = make([]FKEntry, 0, len(t.ForeignKeys))+ for _, fk := range t.ForeignKeys {+ entry.ForeignKeys = append(entry.ForeignKeys, FKEntry{+ Name: fk.Name,+ Columns: append([]string{}, fk.Columns...),+ ReferencedTable: fk.ReferencedTable,+ ReferencedColumns: append([]string{}, fk.ReferencedColumns...),+ })+ }+ slices.SortStableFunc(entry.ForeignKeys, func(a, b FKEntry) int {+ return strings.Compare(a.Name, b.Name)+ })+ }++ return entry+}++// primaryKeyColumns scans indexes for the primary-key index and returns the set+// of column names it covers.+//+// Note: IndexMetadata.expressions may contain expressions rather than column+// names for expression indexes (e.g. PostgreSQL CREATE INDEX ON users+// (LOWER(email))). PostgreSQL does not currently allow expression indexes as+// primary keys (PK columns must be real NOT NULL columns), so matching+// expression text against column name is correct today. Revisit if PG ever+// allows expression PKs; silent misses are preferred over flagging the wrong column.+func primaryKeyColumns(indexes []indexMetadata) map[string]bool {+ result := map[string]bool{}+ for _, idx := range indexes {+ if !idx.Primary {+ continue+ }+ for _, expr := range idx.Expressions {+ result[expr] = true+ }+ }+ return result+}++// formatSchemaOutput produces a text header + JSON body (same pattern as query_database).+func formatSchemaOutput(output *SchemaOutput, include string, warnings []string) string {+ var sb strings.Builder++ for _, w := range warnings {+ fmt.Fprintf(&sb, "Note: %s\n", w)+ }++ fmt.Fprintf(&sb, "Database: %s (%s)\n", output.Database, output.Engine)++ if output.Table != nil {+ writeTableHeader(&sb, output.Table)+ } else {+ writeSchemasHeader(&sb, output.Schemas, include)+ }++ sb.WriteString("\n")+ jsonBytes, _ := json.Marshal(output)+ sb.Write(jsonBytes)++ return sb.String()+}++// writeTableHeader writes the single-table header line.+func writeTableHeader(sb *strings.Builder, t *TableDetail) {+ fmt.Fprintf(sb, "Table: %s (%d rows, %d columns, %d indexes, %d foreign keys)\n",+ t.Name, t.RowCount, len(t.Columns), len(t.Indexes), len(t.ForeignKeys))+}++// writeSchemasHeader writes the multi-schema overview header lines.+func writeSchemasHeader(sb *strings.Builder, sections []SchemaSection, include string) {+ stats := summarizeSchemas(sections)+ if len(stats.schemaNames) > 0 {+ fmt.Fprintf(sb, "Schemas: %d (%s)\n", len(sections), strings.Join(stats.schemaNames, ", "))+ }+ switch include {+ case schemaIncludeColumns:+ fmt.Fprintf(sb, "Tables: %d (showing columns) | Views: %d\n", stats.totalTables, stats.totalViews)+ case schemaIncludeDetails:+ fmt.Fprintf(sb, "Tables: %d (showing details) | Views: %d\n", stats.totalTables, stats.totalViews)+ default:+ fmt.Fprintf(sb, "Tables: %d | Views: %d | Functions: %d\n", stats.totalTables, stats.totalViews, stats.totalFunctions)+ }+ if stats.truncatedAny {+ fmt.Fprintf(sb, "Truncated: some schemas hit the %d-table limit per schema. Use schema= or table= to narrow.\n", schemaTableLimit)+ }+}++// schemaStats aggregates per-schema counters for header rendering.+type schemaStats struct {+ schemaNames []string+ totalTables int+ totalViews int+ totalFunctions int+ truncatedAny bool+}++func summarizeSchemas(sections []SchemaSection) schemaStats {+ stats := schemaStats{schemaNames: make([]string, 0, len(sections))}+ for _, section := range sections {+ if section.Name != "" {+ stats.schemaNames = append(stats.schemaNames, section.Name)+ }+ stats.totalTables += len(section.Tables)+ stats.totalViews += len(section.Views)+ stats.totalFunctions += section.FunctionCount+ if section.Truncated {+ stats.truncatedAny = true+ }+ }+ return stats+}++// formatTableNotFound returns an MCP result for the TABLE_NOT_FOUND error path.+func formatTableNotFound(database, table string, candidates []string) *mcp.CallToolResult {+ result := struct {+ Code string `json:"code"`+ Message string `json:"message"`+ Suggestion string `json:"suggestion"`+ Candidates []string `json:"candidates,omitempty"`+ }{+ Code: "TABLE_NOT_FOUND",+ Message: fmt.Sprintf("no table matching %q in %s", table, database),+ Suggestion: "call get_schema without table= to see available tables",+ Candidates: candidates,+ }++ jsonBytes, _ := json.MarshalIndent(result, "", " ")+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},+ IsError: true,+ }+}++// formatAmbiguousTable returns an MCP result when the requested table name+// exists in multiple schemas. The caller must pick a schema.+func formatAmbiguousTable(database, table string, schemas []string) *mcp.CallToolResult {+ result := struct {+ Code string `json:"code"`+ Message string `json:"message"`+ Suggestion string `json:"suggestion"`+ Schemas []string `json:"schemas"`+ }{+ Code: "AMBIGUOUS_TABLE",+ Message: fmt.Sprintf("table %q exists in multiple schemas of %s", table, database),+ Suggestion: fmt.Sprintf("re-run with schema= set to one of: %s", strings.Join(schemas, ", ")),+ Schemas: schemas,+ }++ jsonBytes, _ := json.MarshalIndent(result, "", " ")+ return &mcp.CallToolResult{+ Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},+ IsError: true,+ }+}diff --git a/backend/api/mcp/tool_schema_test.go b/backend/api/mcp/tool_schema_test.gonew file mode 100644index 0000000000..068d1ed68c--- /dev/null+++ b/backend/api/mcp/tool_schema_test.go@@ -0,0 +1,906 @@+package mcp++import (+ "context"+ "encoding/json"+ "fmt"+ "net/http"+ "strings"+ "sync"+ "sync/atomic"+ "testing"++ mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"+ "github.com/stretchr/testify/require"+)++// --- Fixture builders (mirror the JSON wire format of DatabaseMetadata proto) ---++func makeMetadataResponse(schemas ...map[string]any) map[string]any {+ return map[string]any{+ "name": "instances/prod-pg/databases/employee_db/metadata",+ "schemas": schemas,+ }+}++func makeSchema(name string, tables ...map[string]any) map[string]any {+ return map[string]any{+ "name": name,+ "tables": tables,+ }+}++func makeSchemaWithViews(name string, views []string, tables ...map[string]any) map[string]any {+ viewList := make([]map[string]any, 0, len(views))+ for _, v := range views {+ viewList = append(viewList, map[string]any{"name": v})+ }+ return map[string]any{+ "name": name,+ "tables": tables,+ "views": viewList,+ }+}++func makeTable(name string, rowCount int64, columns []map[string]any, indexes []map[string]any) map[string]any {+ t := map[string]any{+ "name": name,+ "rowCount": fmt.Sprintf("%d", rowCount),+ "columns": columns,+ }+ if len(indexes) > 0 {+ t["indexes"] = indexes+ }+ return t+}++func makeColumn(name, typ string, nullable bool) map[string]any {+ return map[string]any{+ "name": name,+ "type": typ,+ "nullable": nullable,+ }+}++func makeColumnWithDefault(name, typ, defaultVal, comment string) map[string]any {+ c := makeColumn(name, typ, false)+ c["default"] = defaultVal+ c["comment"] = comment+ return c+}++func makePrimaryKeyIndex(name string, columns []string) map[string]any {+ return map[string]any{+ "name": name,+ "expressions": columns,+ "type": "btree",+ "unique": true,+ "primary": true,+ }+}++func makeIndex(name string, unique bool, columns []string) map[string]any {+ return map[string]any{+ "name": name,+ "expressions": columns,+ "type": "btree",+ "unique": unique,+ "primary": false,+ }+}++// --- Request capture / metadata mock ---++// capturedRequest stores a single GetDatabaseMetadata request body for assertions.+type capturedRequest struct {+ Name string `json:"name"`+ Filter string `json:"filter"`+ Limit int32 `json:"limit"`+}++// metadataMock is a stateful mock that records GetDatabaseMetadata calls and+// returns a scripted response (or a response per-call for the candidate refetch case).+type metadataMock struct {+ databases []map[string]any+ responses []map[string]any // scripted responses; indexed by call count+ calls int32+ capturedMu sync.Mutex+ capturedCalls []capturedRequest+}++func newMetadataMock(databases []map[string]any, responses ...map[string]any) *metadataMock {+ return &metadataMock{databases: databases, responses: responses}+}++func (m *metadataMock) handler() http.Handler {+ listHandler := mockListDatabases(m.databases)+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if strings.Contains(r.URL.Path, "DatabaseService/GetDatabaseMetadata") {+ var captured capturedRequest+ _ = json.NewDecoder(r.Body).Decode(&captured)++ m.capturedMu.Lock()+ m.capturedCalls = append(m.capturedCalls, captured)+ m.capturedMu.Unlock()++ idx := int(atomic.AddInt32(&m.calls, 1)) - 1+ var resp map[string]any+ if idx < len(m.responses) {+ resp = m.responses[idx]+ } else if len(m.responses) > 0 {+ // Reuse last response for additional calls.+ resp = m.responses[len(m.responses)-1]+ }+ if resp == nil {+ resp = map[string]any{"name": "", "schemas": []any{}}+ }++ w.Header().Set("Content-Type", "application/json")+ w.WriteHeader(http.StatusOK)+ _ = json.NewEncoder(w).Encode(resp)+ return+ }+ listHandler.ServeHTTP(w, r)+ })+}++func (m *metadataMock) lastCall() capturedRequest {+ m.capturedMu.Lock()+ defer m.capturedMu.Unlock()+ if len(m.capturedCalls) == 0 {+ return capturedRequest{}+ }+ return m.capturedCalls[len(m.capturedCalls)-1]+}++func (m *metadataMock) callAt(idx int) capturedRequest {+ m.capturedMu.Lock()+ defer m.capturedMu.Unlock()+ if idx >= len(m.capturedCalls) {+ return capturedRequest{}+ }+ return m.capturedCalls[idx]+}++func (m *metadataMock) callCount() int {+ return int(atomic.LoadInt32(&m.calls))+}++// mockMetadataServer returns a ready-to-use mock server that handles both+// ListDatabases and GetDatabaseMetadata calls.+func mockMetadataServer(t *testing.T, databases []map[string]any, responses ...map[string]any) (*Server, *metadataMock) {+ t.Helper()+ mock := newMetadataMock(databases, responses...)+ return newTestServerWithMock(t, mock.handler()), mock+}++// employeeDB returns a standard single-database fixture (POSTGRES, employee_db).+func employeeDB() []map[string]any {+ return []map[string]any{+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),+ }+}++// --- Tests ---++func TestGetSchema_Summary(t *testing.T) {+ usersTable := makeTable("users", 10432,+ []map[string]any{+ makeColumn("id", "int4", false),+ makeColumn("email", "varchar(255)", false),+ },+ []map[string]any{makePrimaryKeyIndex("users_pkey", []string{"id"})},+ )+ ordersTable := makeTable("orders", 182394,+ []map[string]any{+ makeColumn("id", "int8", false),+ makeColumn("user_id", "int4", false),+ },+ []map[string]any{makePrimaryKeyIndex("orders_pkey", []string{"id"})},+ )+ // Intentionally out of order to verify sorting.+ resp := makeMetadataResponse(makeSchemaWithViews("public", []string{"active_users", "recent_orders"}, ordersTable, usersTable))++ s, _ := mockMetadataServer(t, employeeDB(), resp)++ result, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.Equal(t, "POSTGRES", output.Engine)+ require.Len(t, output.Schemas, 1)+ section := output.Schemas[0]+ require.Equal(t, "public", section.Name)+ require.Len(t, section.Tables, 2)+ // Tables sorted alphabetically.+ require.Equal(t, "orders", section.Tables[0].Name)+ require.Equal(t, "users", section.Tables[1].Name)+ // Summary mode has no column details but includes column count.+ require.Equal(t, 2, section.Tables[0].ColumnCount)+ require.Equal(t, int64(182394), section.Tables[0].RowCount)+ require.Empty(t, section.Tables[0].Columns)+ // Views sorted alphabetically.+ require.Equal(t, []string{"active_users", "recent_orders"}, section.Views)++ // Text header mentions schema and tables.+ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "Database: instances/prod-pg/databases/employee_db (POSTGRES)")+ require.Contains(t, text, "Schemas: 1 (public)")+ require.Contains(t, text, "Tables: 2")+}++func TestGetSchema_IncludeColumns(t *testing.T) {+ usersTable := makeTable("users", 10432,+ []map[string]any{+ makeColumn("id", "int4", false),+ makeColumn("email", "varchar(255)", false),+ makeColumn("created_at", "timestamptz", true),+ },+ []map[string]any{makePrimaryKeyIndex("users_pkey", []string{"id"})},+ )+ resp := makeMetadataResponse(makeSchema("public", usersTable))++ s, mock := mockMetadataServer(t, employeeDB(), resp)++ result, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "columns",+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ users := output.Schemas[0].Tables[0]+ require.Len(t, users.Columns, 3)+ // Proto order preserved (id, email, created_at) — NOT alphabetized.+ require.Equal(t, "id", users.Columns[0].Name)+ require.Equal(t, "int4", users.Columns[0].Type)+ require.False(t, users.Columns[0].Nullable)+ require.True(t, users.Columns[0].PrimaryKey)+ require.Equal(t, "email", users.Columns[1].Name)+ require.False(t, users.Columns[1].PrimaryKey)+ require.Equal(t, "created_at", users.Columns[2].Name)+ require.True(t, users.Columns[2].Nullable)+ // columns mode has no defaults/comments populated.+ require.Empty(t, users.Columns[0].Default)+ require.Empty(t, users.Columns[0].Comment)+ // No indexes or FKs in columns mode.+ require.Empty(t, users.Indexes)+ require.Empty(t, users.ForeignKeys)++ // Request includes limit=201.+ require.Equal(t, int32(201), mock.lastCall().Limit)+}++func TestGetSchema_IncludeDetails(t *testing.T) {+ ordersTable := map[string]any{+ "name": "orders",+ "rowCount": "182394",+ "comment": "Customer orders",+ "columns": []map[string]any{+ makeColumnWithDefault("id", "int8", "", "Order ID"),+ makeColumnWithDefault("user_id", "int4", "", "Customer ref"),+ makeColumnWithDefault("status", "varchar(32)", "'pending'", "Status flag"),+ },+ "indexes": []map[string]any{+ // Intentionally out of order.+ makeIndex("orders_user_id_idx", false, []string{"user_id"}),+ makePrimaryKeyIndex("orders_pkey", []string{"id"}),+ },+ "foreignKeys": []map[string]any{+ {+ "name": "orders_user_id_fkey",+ "columns": []string{"user_id"},+ "referencedTable": "users",+ "referencedColumns": []string{"id"},+ },+ },+ }+ resp := makeMetadataResponse(makeSchema("public", ordersTable))++ s, _ := mockMetadataServer(t, employeeDB(), resp)++ result, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "details",+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ orders := output.Schemas[0].Tables[0]+ require.Equal(t, "Customer orders", orders.Comment)+ // Column defaults and comments populated.+ require.Equal(t, "'pending'", orders.Columns[2].Default)+ require.Equal(t, "Status flag", orders.Columns[2].Comment)+ // Indexes sorted alphabetically.+ require.Len(t, orders.Indexes, 2)+ require.Equal(t, "orders_pkey", orders.Indexes[0].Name)+ require.Equal(t, "orders_user_id_idx", orders.Indexes[1].Name)+ // FKs present.+ require.Len(t, orders.ForeignKeys, 1)+ require.Equal(t, "orders_user_id_fkey", orders.ForeignKeys[0].Name)+ require.Equal(t, "users", orders.ForeignKeys[0].ReferencedTable)+}++func TestGetSchema_TableFilter_ServerSideFilter(t *testing.T) {+ ordersTable := makeTable("orders", 182394,+ []map[string]any{+ makeColumn("id", "int8", false),+ makeColumn("user_id", "int4", false),+ },+ []map[string]any{makePrimaryKeyIndex("orders_pkey", []string{"id"})},+ )+ resp := makeMetadataResponse(makeSchema("public", ordersTable))++ s, mock := mockMetadataServer(t, employeeDB(), resp)++ _, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Table: "orders",+ })+ require.NoError(t, err)++ require.Equal(t, `table == "orders"`, mock.lastCall().Filter)+ // table= mode should NOT include a limit.+ require.Equal(t, int32(0), mock.lastCall().Limit)+}++func TestGetSchema_TableImpliesDetails(t *testing.T) {+ ordersTable := map[string]any{+ "name": "orders",+ "rowCount": "182394",+ "comment": "Customer orders",+ "columns": []map[string]any{+ makeColumnWithDefault("id", "int8", "", "Order ID"),+ },+ "indexes": []map[string]any{makePrimaryKeyIndex("orders_pkey", []string{"id"})},+ "foreignKeys": []map[string]any{+ {+ "name": "orders_user_id_fkey",+ "columns": []string{"user_id"},+ "referencedTable": "users",+ "referencedColumns": []string{"id"},+ },+ },+ }+ resp := makeMetadataResponse(makeSchema("public", ordersTable))++ s, _ := mockMetadataServer(t, employeeDB(), resp)++ result, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Table: "orders",+ // Include not set → should default to details.+ })+ require.NoError(t, err)+ require.False(t, result.IsError)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.NotNil(t, output.Table)+ // Details level: indexes and FKs are populated.+ require.NotEmpty(t, output.Table.Indexes)+ require.NotEmpty(t, output.Table.ForeignKeys)+ // Column comment (details-only field) populated.+ require.Equal(t, "Order ID", output.Table.Columns[0].Comment)+}++func TestGetSchema_TableNotFound_RefetchesForCandidates(t *testing.T) {+ // First call: server-side filter returns nothing.+ emptyResp := makeMetadataResponse(makeSchema("public"))+ // Second call: no filter, returns candidates.+ ordersTable := makeTable("orders", 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ orderItemsTable := makeTable("order_items", 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ unrelatedTable := makeTable("invoices", 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ fullResp := makeMetadataResponse(makeSchema("public", ordersTable, orderItemsTable, unrelatedTable))++ s, mock := mockMetadataServer(t, employeeDB(), emptyResp, fullResp)++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Table: "orderz",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ // Two metadata calls: filtered + candidate lookup.+ require.Equal(t, 2, mock.callCount())+ require.Equal(t, `table == "orderz"`, mock.callAt(0).Filter)+ require.Equal(t, "", mock.callAt(1).Filter)+ require.Equal(t, int32(schemaCandidateFetchLimit), mock.callAt(1).Limit)++ // Error body has candidates.+ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "TABLE_NOT_FOUND")+ require.Contains(t, text, "orders")+ require.Contains(t, text, "order_items")+ require.NotContains(t, text, "invoices")+}++func TestGetSchema_SchemaFilter_Postgres_ServerSideFilter(t *testing.T) {+ resp := makeMetadataResponse(makeSchema("public",+ makeTable("users", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))+ s, mock := mockMetadataServer(t, employeeDB(), resp)++ _, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "public",+ })+ require.NoError(t, err)+ require.Equal(t, `schema == "public"`, mock.lastCall().Filter)+}++func TestGetSchema_SchemaAndTableFilter(t *testing.T) {+ resp := makeMetadataResponse(makeSchema("public",+ makeTable("orders", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))+ s, mock := mockMetadataServer(t, employeeDB(), resp)++ _, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "public",+ Table: "orders",+ })+ require.NoError(t, err)+ require.Equal(t, `schema == "public" && table == "orders"`, mock.lastCall().Filter)+}++func TestGetSchema_SchemaFilter_MySQL_DroppedClientSide(t *testing.T) {+ // MySQL has an empty schema name. The backend applies `schema == "X"` as an+ // exact match, which would filter out every table. The MCP layer must drop+ // the schema filter before calling the backend on single-schema engines.+ databases := []map[string]any{+ makeDatabase("instances/prod-mysql/databases/employee_db", "instances/prod-mysql", "projects/hr-system", "MYSQL", "ds-admin-1"),+ }+ resp := makeMetadataResponse(makeSchema("",+ makeTable("users", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))+ s, mock := mockMetadataServer(t, databases, resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "anything",+ })+ require.NoError(t, err)+ // The schema filter is dropped client-side — the backend sees an empty filter.+ require.Equal(t, "", mock.lastCall().Filter)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.Len(t, output.Schemas, 1)+ require.Len(t, output.Schemas[0].Tables, 1)+}++func TestGetSchema_SchemaFilter_PassedThroughOnMultiSchemaEngines(t *testing.T) {+ // Spot-check a few known multi-schema engines to confirm the allowlist.+ for _, engine := range []string{"POSTGRES", "MSSQL", "ORACLE", "SNOWFLAKE", "REDSHIFT", "COCKROACHDB", "DATABRICKS", "TRINO", "SPANNER", "HIVE"} {+ t.Run(engine, func(t *testing.T) {+ databases := []map[string]any{+ makeDatabase("instances/prod/databases/employee_db", "instances/prod", "projects/hr-system", engine, "ds-1"),+ }+ resp := makeMetadataResponse(makeSchema("public",+ makeTable("users", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))+ s, mock := mockMetadataServer(t, databases, resp)++ _, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "public",+ })+ require.NoError(t, err)+ require.Equal(t, `schema == "public"`, mock.lastCall().Filter)+ })+ }+}++func TestGetSchema_SchemaFilter_DroppedOnSingleSchemaEngines(t *testing.T) {+ // Spot-check a few known single-schema engines.+ for _, engine := range []string{"MYSQL", "TIDB", "MARIADB", "CLICKHOUSE", "SQLITE"} {+ t.Run(engine, func(t *testing.T) {+ databases := []map[string]any{+ makeDatabase("instances/prod/databases/employee_db", "instances/prod", "projects/hr-system", engine, "ds-1"),+ }+ resp := makeMetadataResponse(makeSchema("",+ makeTable("users", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))+ s, mock := mockMetadataServer(t, databases, resp)++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "something",+ })+ require.NoError(t, err)+ require.Equal(t, "", mock.lastCall().Filter, "engine %s should drop the schema filter", engine)++ // The response should include a note about the dropped parameter.+ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "schema parameter ignored", "engine %s should annotate the dropped schema filter", engine)+ require.Contains(t, text, "does not use named schemas", "engine %s note should explain why", engine)+ })+ }+}++func TestGetSchema_PrimaryKeyDerivation(t *testing.T) {+ usersTable := makeTable("users", 10,+ []map[string]any{+ makeColumn("id", "int4", false),+ makeColumn("email", "varchar(255)", false),+ makeColumn("created_at", "timestamptz", false),+ },+ []map[string]any{+ makePrimaryKeyIndex("users_pkey", []string{"id"}),+ makeIndex("users_email_idx", true, []string{"email"}), // unique but NOT primary+ },+ )+ resp := makeMetadataResponse(makeSchema("public", usersTable))+ s, _ := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "columns",+ })+ require.NoError(t, err)+ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ cols := output.Schemas[0].Tables[0].Columns+ require.True(t, cols[0].PrimaryKey, "id should be a PK (primary index)")+ require.False(t, cols[1].PrimaryKey, "email should NOT be a PK (unique only)")+ require.False(t, cols[2].PrimaryKey, "created_at should NOT be a PK")+}++func TestGetSchema_LimitForBulkModes(t *testing.T) {+ resp := makeMetadataResponse(makeSchema("public",+ makeTable("users", 10, []map[string]any{makeColumn("id", "int4", false)}, nil),+ ))++ // columns → limit=201+ s, mock := mockMetadataServer(t, employeeDB(), resp)+ _, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db", Include: "columns"})+ require.NoError(t, err)+ require.Equal(t, int32(201), mock.lastCall().Limit)++ // details → limit=201+ s2, mock2 := mockMetadataServer(t, employeeDB(), resp)+ _, _, err = s2.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db", Include: "details"})+ require.NoError(t, err)+ require.Equal(t, int32(201), mock2.lastCall().Limit)++ // summary → no limit+ s3, mock3 := mockMetadataServer(t, employeeDB(), resp)+ _, _, err = s3.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db"})+ require.NoError(t, err)+ require.Equal(t, int32(0), mock3.lastCall().Limit)++ // table= → no limit+ s4, mock4 := mockMetadataServer(t, employeeDB(), resp)+ _, _, err = s4.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db", Table: "users"})+ require.NoError(t, err)+ require.Equal(t, int32(0), mock4.lastCall().Limit)+}++func TestGetSchema_NotTruncatedAtExactly200(t *testing.T) {+ tables := make([]map[string]any, schemaTableLimit)+ for i := range tables {+ tables[i] = makeTable(fmt.Sprintf("t%03d", i), 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ }+ resp := makeMetadataResponse(makeSchema("public", tables...))+ s, _ := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "columns",+ })+ require.NoError(t, err)+ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ section := output.Schemas[0]+ require.Len(t, section.Tables, schemaTableLimit)+ require.False(t, section.Truncated)+ require.Equal(t, 0, section.TablesShown)+}++func TestGetSchema_TruncatedAt201(t *testing.T) {+ // Build 201 tables; the 201st sorted entry should be dropped.+ tables := make([]map[string]any, schemaTableLimit+1)+ for i := range tables {+ tables[i] = makeTable(fmt.Sprintf("t%03d", i), 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ }+ resp := makeMetadataResponse(makeSchema("public", tables...))+ s, _ := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "columns",+ })+ require.NoError(t, err)+ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ section := output.Schemas[0]+ require.Len(t, section.Tables, schemaTableLimit)+ require.True(t, section.Truncated)+ require.Equal(t, schemaTableLimit, section.TablesShown)+ // The names are t000..t200; sorted alphabetically the 201st (last) is t200,+ // which should be dropped. Remaining last table is t199.+ require.Equal(t, "t199", section.Tables[schemaTableLimit-1].Name)+}++func TestGetSchema_PerSchemaLimitSemantics(t *testing.T) {+ // Build 3 schemas with 201 tables each (enough to trigger truncation in each).+ makeBigSchema := func(name string) map[string]any {+ tables := make([]map[string]any, schemaTableLimit+1)+ for i := range tables {+ tables[i] = makeTable(fmt.Sprintf("t%03d", i), 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ }+ return makeSchema(name, tables...)+ }+ resp := makeMetadataResponse(makeBigSchema("schema_a"), makeBigSchema("schema_b"), makeBigSchema("schema_c"))+ s, _ := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Include: "columns",+ })+ require.NoError(t, err)+ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.Len(t, output.Schemas, 3)+ totalTables := 0+ for _, section := range output.Schemas {+ require.True(t, section.Truncated)+ require.Len(t, section.Tables, schemaTableLimit)+ totalTables += len(section.Tables)+ }+ require.Equal(t, 3*schemaTableLimit, totalTables)+}++func TestGetSchema_DatabaseNotFound(t *testing.T) {+ s := newTestServerWithMock(t, mockListDatabases(employeeDB()))++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "nonexistent",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "DATABASE_NOT_FOUND")+}++func TestGetSchema_AmbiguousDatabase(t *testing.T) {+ databases := []map[string]any{+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),+ makeDatabase("instances/staging-mysql/databases/employee_db", "instances/staging-mysql", "projects/hr-system", "MYSQL", "ds-admin-2"),+ }+ s := newTestServerWithMock(t, mockListDatabases(databases))++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "AMBIGUOUS_TARGET")+}++func TestGetSchema_SchemaSyncFailed(t *testing.T) {+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if strings.Contains(r.URL.Path, "DatabaseService/GetDatabaseMetadata") {+ w.Header().Set("Content-Type", "application/json")+ w.WriteHeader(http.StatusInternalServerError)+ _ = json.NewEncoder(w).Encode(map[string]any{+ "message": "sync timeout after 30s",+ "code": "INTERNAL",+ })+ return+ }+ mockListDatabases(employeeDB()).ServeHTTP(w, r)+ })+ s := newTestServerWithMock(t, handler)++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "SCHEMA_SYNC_FAILED")+ require.Contains(t, text, "sync timeout after 30s")+}++func TestGetSchema_PermissionDenied(t *testing.T) {+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if strings.Contains(r.URL.Path, "DatabaseService/GetDatabaseMetadata") {+ w.Header().Set("Content-Type", "application/json")+ w.WriteHeader(http.StatusForbidden)+ _ = json.NewEncoder(w).Encode(map[string]any{+ "message": "permission denied",+ "code": "PERMISSION_DENIED",+ })+ return+ }+ mockListDatabases(employeeDB()).ServeHTTP(w, r)+ })+ s := newTestServerWithMock(t, handler)++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ })+ 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.databases.getSchema")+}++func TestGetSchema_InvalidIncludeValue(t *testing.T) {+ s := newTestServerWithMock(t, http.NotFoundHandler())++ _, _, err := s.handleGetSchema(context.Background(), nil, SchemaInput{+ Database: "employee_db",+ Include: "everything",+ })+ require.Error(t, err)+ require.Contains(t, err.Error(), "summary|columns|details")+}++func TestGetSchema_MissingDatabase(t *testing.T) {+ s := newTestServerWithMock(t, http.NotFoundHandler())+ _, _, err := s.handleGetSchema(context.Background(), nil, SchemaInput{})+ require.Error(t, err)+ require.Contains(t, err.Error(), "database is required")+}++func TestGetSchema_StableSortOrder(t *testing.T) {+ // Two schemas (out of order), each with a few tables (out of order).+ schemaB := makeSchema("schema_b",+ makeTable("zz", 0, []map[string]any{makeColumn("id", "int4", false)}, nil),+ makeTable("aa", 0, []map[string]any{makeColumn("id", "int4", false)}, nil),+ )+ schemaA := makeSchema("schema_a",+ makeTable("yy", 0, []map[string]any{makeColumn("id", "int4", false)}, nil),+ makeTable("bb", 0, []map[string]any{makeColumn("id", "int4", false)}, nil),+ )+ resp := makeMetadataResponse(schemaB, schemaA)++ s1, _ := mockMetadataServer(t, employeeDB(), resp)+ _, structured1, err := s1.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db"})+ require.NoError(t, err)++ s2, _ := mockMetadataServer(t, employeeDB(), resp)+ _, structured2, err := s2.handleGetSchema(testContext(), nil, SchemaInput{Database: "employee_db"})+ require.NoError(t, err)++ json1, _ := json.Marshal(structured1)+ json2, _ := json.Marshal(structured2)+ require.Equal(t, string(json1), string(json2))++ // Explicit ordering assertions.+ output, ok := structured1.(*SchemaOutput)+ require.True(t, ok)+ require.Equal(t, "schema_a", output.Schemas[0].Name)+ require.Equal(t, "schema_b", output.Schemas[1].Name)+ require.Equal(t, "bb", output.Schemas[0].Tables[0].Name)+ require.Equal(t, "yy", output.Schemas[0].Tables[1].Name)+ require.Equal(t, "aa", output.Schemas[1].Tables[0].Name)+ require.Equal(t, "zz", output.Schemas[1].Tables[1].Name)+}++// TestGetSchema_SummaryDoesNotTruncate verifies the P1 fix: summary mode must+// return every table in a schema even when there are more than schemaTableLimit+// of them, because summary is designed to fit large catalogs (per-table payload+// is tiny) and the server isn't asked to limit in summary mode.+func TestGetSchema_SummaryDoesNotTruncate(t *testing.T) {+ // Build 250 tables — well over schemaTableLimit (200).+ tableCount := schemaTableLimit + 50+ tables := make([]map[string]any, tableCount)+ for i := range tables {+ tables[i] = makeTable(fmt.Sprintf("t%03d", i), 0, []map[string]any{makeColumn("id", "int4", false)}, nil)+ }+ resp := makeMetadataResponse(makeSchema("public", tables...))+ s, mock := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ // No Include set → defaults to summary.+ })+ require.NoError(t, err)+ // Summary mode does not send a server-side limit.+ require.Equal(t, int32(0), mock.lastCall().Limit)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.Len(t, output.Schemas, 1)+ section := output.Schemas[0]+ require.Len(t, section.Tables, tableCount, "summary mode must not truncate")+ require.False(t, section.Truncated)+ require.Equal(t, 0, section.TablesShown)+}++// TestGetSchema_AmbiguousTableAcrossSchemas verifies the P2 fix: when the same+// table name exists in multiple schemas and the caller did not specify schema=,+// the tool must return an AMBIGUOUS_TABLE error instead of silently picking the+// first match.+func TestGetSchema_AmbiguousTableAcrossSchemas(t *testing.T) {+ usersPublic := makeTable("users", 10,+ []map[string]any{makeColumn("id", "int4", false)},+ []map[string]any{makePrimaryKeyIndex("users_pkey", []string{"id"})},+ )+ usersAnalytics := makeTable("users", 20,+ []map[string]any{makeColumn("uid", "int4", false)},+ []map[string]any{makePrimaryKeyIndex("users_pkey", []string{"uid"})},+ )+ resp := makeMetadataResponse(+ makeSchema("analytics", usersAnalytics),+ makeSchema("public", usersPublic),+ )+ s, _ := mockMetadataServer(t, employeeDB(), resp)++ result, _, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Table: "users",+ // No Schema set → both matches are visible.+ })+ require.NoError(t, err)+ require.True(t, result.IsError)++ text := result.Content[0].(*mcpsdk.TextContent).Text+ require.Contains(t, text, "AMBIGUOUS_TABLE")+ require.Contains(t, text, "analytics")+ require.Contains(t, text, "public")+ require.Contains(t, text, "schema=")+}++// TestGetSchema_TableInSpecificSchema verifies the happy path for the P2 fix:+// with a schema= hint, a single match proceeds normally.+func TestGetSchema_TableInSpecificSchema(t *testing.T) {+ usersPublic := makeTable("users", 10,+ []map[string]any{makeColumn("id", "int4", false)},+ []map[string]any{makePrimaryKeyIndex("users_pkey", []string{"id"})},+ )+ // Simulate a server that honors the schema filter: only `public` is returned.+ resp := makeMetadataResponse(makeSchema("public", usersPublic))+ s, mock := mockMetadataServer(t, employeeDB(), resp)++ _, structured, err := s.handleGetSchema(testContext(), nil, SchemaInput{+ Database: "employee_db",+ Schema: "public",+ Table: "users",+ })+ require.NoError(t, err)+ require.Equal(t, `schema == "public" && table == "users"`, mock.lastCall().Filter)++ output, ok := structured.(*SchemaOutput)+ require.True(t, ok)+ require.NotNil(t, output.Table)+ require.Equal(t, "users", output.Table.Name)+}++func TestBuildMetadataFilter(t *testing.T) {+ tests := []struct {+ name string+ schema string+ table string+ want string+ }{+ {"empty", "", "", ""},+ {"schema only", "public", "", `schema == "public"`},+ {"table only", "", "orders", `table == "orders"`},+ {"both", "public", "orders", `schema == "public" && table == "orders"`},+ }+ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ require.Equal(t, tc.want, buildMetadataFilter(tc.schema, tc.table))+ })+ }+}