fix: automatically detect and handle legacy vs Kubernetes-style dashboard APIs

[sd2k]

This adds the core infrastructure for detecting whether a Grafana instance
supports kubernetes-style APIs (/apis) vs legacy APIs (/api).

Then, updates the dashboard tools to use capability detection for automatic
fallback from legacy APIs to kubernetes-style APIs when the legacy API
returns a 406 error.

Lastly it updates the explore deeplink generation to support the new schemaVersion=1
format used by Grafana 10+, while maintaining backward compatibility with
the legacy 'left=' parameter format.

---

Note

Medium Risk
Touches core Grafana request plumbing and changes how dashboards are fetched based on runtime error handling/caching, which could affect compatibility across Grafana versions. Behavior is guarded by fallback logic and covered by new unit/integration tests, but mis-detection or conversion issues could break dashboard retrieval.

Overview
Adds capability discovery/caching (/apis probing) and a new GrafanaInstance wrapper to track per-API-group mode (legacy vs kubernetes) and fetch dashboards via kubernetes-style endpoints when needed.

Updates the dashboard tool to try legacy first but on legacy 406 Not Acceptable parses the suggested /apis/... path, switches future calls to kubernetes for the dashboard API group, and converts kubernetes dashboard responses back into the legacy model for compatibility. Also updates explore deeplink generation to default to Grafana 10+ schemaVersion=1&panes=... URLs with optional legacy left= fallback, and adds comprehensive unit/integration tests around these behaviors.

^{Written by Cursor Bugbot for commit d97f3cf. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issues.}

[cursor]

Capability cache ignores TTL for per-group

Medium Severity

CapabilityCache.GetAPICapability returns cached perAPICapability values without checking whether the entry has expired via ttl. This can cause ShouldUseKubernetesAPI to keep forcing kubernetes-style endpoints even after cache expiry, while other capability lookups re-discover via Get/DiscoverCapabilities.

 

[cursor]

Kubernetes dashboard UID derived from name

Medium Severity

convertKubernetesDashboardToLegacy populates dashboardJSON["uid"] from k8sDashboard.Metadata.Name when missing, ignoring k8sDashboard.Metadata.UID. If metadata.name differs from the Grafana dashboard UID, the converted legacy payload can contain an incorrect uid, breaking links and subsequent API calls that rely on the UID.

 

[cursor]

Bugbot Autofix determined this is a false positive.

In Grafana's kubernetes-style API, metadata.name IS the dashboard UID (used as resource identifier in URL path), while metadata.uid is a Kubernetes resource UUID unrelated to the Grafana dashboard UID.

[cursor]

Integration test reads cache with wrong key

Low Severity

TestDiscoverAPIs_Integration calls instance.cache.Get(config.URL), but the cache is populated using g.baseURL (trimmed URL) in DiscoverCapabilities. If config.URL contains a trailing slash or differs in normalization, this lookup returns nil and makes the test incorrectly fail.

 

[cursor]

Bugbot Autofix prepared fixes for 2 of the 3 bugs found in the latest run.

• ✅ Fixed: Capability cache ignores TTL for per-group
  • Added TTL expiration check to GetAPICapability method so it returns APICapabilityUnknown when the cache entry has expired, consistent with the Get method.
• ✅ Fixed: Integration test reads cache with wrong key
  • Changed test to use instance.BaseURL() instead of config.URL for cache lookup, ensuring consistency with how DiscoverCapabilities stores the normalized URL key.

Or push these changes by commenting:

@cursor push 3cfc6293d3

Preview (3cfc6293d3)

diff --git a/capability.go b/capability.go
--- a/capability.go
+++ b/capability.go
@@ -168,7 +168,7 @@
 }
 
 // GetAPICapability returns the capability for a specific API group.
-// Returns APICapabilityUnknown if not set.
+// Returns APICapabilityUnknown if not set or if the cache entry has expired.
 func (c *CapabilityCache) GetAPICapability(grafanaURL, apiGroup string) APICapability {
 	c.mu.RLock()
 	defer c.mu.RUnlock()
@@ -178,6 +178,11 @@
 		return APICapabilityUnknown
 	}
 
+	// Check if entry has expired
+	if time.Since(entry.detectedAt) > c.ttl {
+		return APICapabilityUnknown
+	}
+
 	if entry.perAPICapability == nil {
 		return APICapabilityUnknown
 	}

diff --git a/capability_integration_test.go b/capability_integration_test.go
--- a/capability_integration_test.go
+++ b/capability_integration_test.go
@@ -107,7 +107,7 @@
 	err := instance.DiscoverCapabilities(ctx)
 	require.NoError(t, err)
 
-	entry := instance.cache.Get(config.URL)
+	entry := instance.cache.Get(instance.BaseURL())
 	require.NoError(t, err)
 	require.NotNil(t, entry)

[sd2k]

This really needs better e2e tests, ideally against a Grafana instance with only the new k8s style APIs.

[github-actions]

MCP Token Analysis

✅ Passed

Metric	Value
Baseline	14264 tokens
Current	14341 tokens
Change	+77 (+0.5%)

Tool Changes

Tool	Change	Tokens
generate_deeplink	✏️ Modified	+77