Skip to content

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

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.go
index 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.md
index 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/DELETE
Run 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 name
diff --git a/backend/api/mcp/tool_resolve.go b/backend/api/mcp/tool_resolve.go
index 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 string
dataSourceID string
+ engine string
ambiguous bool
candidates []Candidate
dataSourceIDs 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 strin
return &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 strin
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))
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.CallToolReques
return &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.go
new file mode 100644
index 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.go
new file mode 100644
index 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))
+ })
+ }
+}