feat: add MCP server for AI agent tool access

.gitignore

@@ -27,3 +27,4 @@ vendor/
 /config.yaml
 compass.yaml
 temp/
+.mcp.json

docker-compose.yaml

@@ -15,7 +15,7 @@ services:
   postgres:
     image: postgres:13
     ports:
-      - 5432:5432
+      - 5433:5432
     environment:
       POSTGRES_USER: compass
       POSTGRES_PASSWORD: compass_password

go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/jmoiron/sqlx v1.4.0
 	github.com/lestrrat-go/jwx/v2 v2.1.6
 	github.com/lib/pq v1.12.0
+	github.com/mark3labs/mcp-go v0.46.0
 	github.com/ory/dockertest/v3 v3.12.0
 	github.com/peterbourgon/mergemap v0.0.1
 	github.com/r3labs/diff/v3 v3.0.2
@@ -135,6 +136,7 @@ require (
 	github.com/go-playground/validator v9.31.0+incompatible // indirect
 	github.com/go-viper/mapstructure/v2 v2.1.0 // indirect
 	github.com/google/cel-go v0.26.1 // indirect
+	github.com/google/jsonschema-go v0.4.2 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
@@ -145,12 +147,13 @@ require (
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
-	github.com/spf13/cast v1.6.0 // indirect
+	github.com/spf13/cast v1.7.1 // indirect
 	github.com/spf13/viper v1.19.0 // indirect
 	github.com/stoewer/go-strcase v1.3.1 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.42.0 // indirect
 	go.opentelemetry.io/otel/metric v1.42.0 // indirect

go.sum

@@ -139,6 +139,8 @@ github.com/google/cel-go v0.26.1 h1:iPbVVEdkhTX++hpe3lzSk7D3G3QSYqLGoHOcEio+UXQ=
 github.com/google/cel-go v0.26.1/go.mod h1:A9O8OU9rdvrK5MQyrqfIxo1a0u4g3sF8KB6PUIaryMM=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -201,6 +203,8 @@ github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mark3labs/mcp-go v0.46.0 h1:8KRibF4wcKejbLsHxCA/QBVUr5fQ9nwz/n8lGqmaALo=
+github.com/mark3labs/mcp-go v0.46.0/go.mod h1:JKTC7R2LLVagkEWK7Kwu7DbmA6iIvnNAod6yrHiQMag=
 github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
 github.com/mattn/go-colorable v0.1.6/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
@@ -290,8 +294,8 @@ github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9yS
 github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
 github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
 github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY=
-github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
-github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
+github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y=
+github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
@@ -329,6 +333,8 @@ github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHo
 github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
 github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
 github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.3.3/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=

internal/mcp/format.go

@@ -0,0 +1,201 @@
+package mcp
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/raystack/compass/core/asset"
+)
+
+// formatAsset formats an asset as LLM-friendly markdown text.
+func formatAsset(a asset.Asset) string {
+	var b strings.Builder
+
+	fmt.Fprintf(&b, "## %s (%s)\n", a.Name, a.Type)
+	fmt.Fprintf(&b, "Service: %s | URN: %s\n", a.Service, a.URN)
+
+	if a.Description != "" {
+		fmt.Fprintf(&b, "Description: %s\n", a.Description)
+	}
+
+	if len(a.Owners) > 0 {
+		names := make([]string, 0, len(a.Owners))
+		for _, o := range a.Owners {
+			if o.Email != "" {
+				names = append(names, o.Email)
+			} else {
+				names = append(names, o.UUID)
+			}
+		}
+		fmt.Fprintf(&b, "Owners: %s\n", strings.Join(names, ", "))
+	}
+
+	if a.URL != "" {
+		fmt.Fprintf(&b, "URL: %s\n", a.URL)
+	}
+
+	if len(a.Labels) > 0 {
+		pairs := make([]string, 0, len(a.Labels))
+		for k, v := range a.Labels {
+			pairs = append(pairs, fmt.Sprintf("%s=%s", k, v))
+		}
+		fmt.Fprintf(&b, "Labels: %s\n", strings.Join(pairs, ", "))
+	}
+
+	formatAssetData(&b, a.Data)
+
+	return b.String()
+}
+
+// formatAssetData formats the Data map, extracting schema columns if present.
+func formatAssetData(b *strings.Builder, data map[string]interface{}) {
+	if data == nil {
+		return
+	}
+
+	// Extract schema/columns if present (common in table/topic assets)
+	if columns, ok := extractColumns(data); ok && len(columns) > 0 {
+		fmt.Fprintf(b, "\nColumns (%d):\n", len(columns))
+		for _, col := range columns {
+			name, _ := col["name"].(string)
+			dataType, _ := col["data_type"].(string)
+			desc, _ := col["description"].(string)
+
+			if desc != "" {
+				fmt.Fprintf(b, "  - %s (%s): %s\n", name, dataType, desc)
+			} else {
+				fmt.Fprintf(b, "  - %s (%s)\n", name, dataType)
+			}
+		}
+	}
+}
+
+// extractColumns tries to find column definitions in asset data.
+func extractColumns(data map[string]interface{}) ([]map[string]interface{}, bool) {
+	// Try common paths: data.columns, data.schema.columns
+	if cols, ok := data["columns"]; ok {
+		return toMapSlice(cols)
+	}
+	if schema, ok := data["schema"].(map[string]interface{}); ok {
+		if cols, ok := schema["columns"]; ok {
+			return toMapSlice(cols)
+		}
+	}
+	return nil, false
+}
+
+func toMapSlice(v interface{}) ([]map[string]interface{}, bool) {
+	slice, ok := v.([]interface{})
+	if !ok {
+		return nil, false
+	}
+	result := make([]map[string]interface{}, 0, len(slice))
+	for _, item := range slice {
+		if m, ok := item.(map[string]interface{}); ok {
+			result = append(result, m)
+		}
+	}
+	return result, len(result) > 0
+}
+
+// formatSearchResult formats a search result as a compact line.
+func formatSearchResult(sr asset.SearchResult) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "- **%s** (%s) — service: %s, urn: %s", sr.Title, sr.Type, sr.Service, sr.URN)
+	if sr.Description != "" {
+		desc := sr.Description
+		if len(desc) > 120 {
+			desc = desc[:120] + "..."
+		}
+		fmt.Fprintf(&b, "\n  %s", desc)
+	}
+	return b.String()
+}
+
+// formatSearchResults formats a list of search results.
+func formatSearchResults(results []asset.SearchResult) string {
+	if len(results) == 0 {
+		return "No assets found."
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "Found %d assets:\n\n", len(results))
+	for _, sr := range results {
+		b.WriteString(formatSearchResult(sr))
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+// formatLineage formats lineage data as readable text.
+func formatLineage(urn string, lineage asset.Lineage) string {
+	if len(lineage.Edges) == 0 {
+		return fmt.Sprintf("No lineage found for %s.", urn)
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "Lineage for %s (%d edges):\n\n", urn, len(lineage.Edges))
+
+	upstreams := make([]string, 0)
+	downstreams := make([]string, 0)
+
+	for _, edge := range lineage.Edges {
+		if edge.Target == urn {
+			upstreams = append(upstreams, edge.Source)
+		} else if edge.Source == urn {
+			downstreams = append(downstreams, edge.Target)
+		} else {
+			// Transitive edges
+			fmt.Fprintf(&b, "  %s → %s\n", edge.Source, edge.Target)
+		}
+	}
+
+	if len(upstreams) > 0 {
+		b.WriteString("Upstream (sources):\n")
+		for _, u := range upstreams {
+			fmt.Fprintf(&b, "  ← %s\n", u)
+		}
+	}
+
+	if len(downstreams) > 0 {
+		b.WriteString("Downstream (consumers):\n")
+		for _, d := range downstreams {
+			fmt.Fprintf(&b, "  → %s\n", d)
+		}
+	}
+
+	return b.String()
+}
+
+// formatTypes formats asset type counts.
+func formatTypes(types map[asset.Type]int) string {
+	if len(types) == 0 {
+		return "No asset types found."
+	}
+
+	var b strings.Builder
+	b.WriteString("Asset types:\n\n")
+	for t, count := range types {
+		fmt.Fprintf(&b, "- %s: %d assets\n", t, count)
+	}
+	return b.String()
+}
+
+// formatAssets formats a list of assets as a summary list.
+func formatAssets(assets []asset.Asset, total uint32) string {
+	if len(assets) == 0 {
+		return "No assets found."
+	}
+
+	var b strings.Builder
+	if total > 0 {
+		fmt.Fprintf(&b, "Showing %d of %d assets:\n\n", len(assets), total)
+	} else {
+		fmt.Fprintf(&b, "Found %d assets:\n\n", len(assets))
+	}
+
+	for _, a := range assets {
+		fmt.Fprintf(&b, "- **%s** (%s) — service: %s, urn: %s\n", a.Name, a.Type, a.Service, a.URN)
+	}
+	return b.String()
+}