feat: migrate dashboard tools to v2 perses APIs

.github/scripts/regenerate_dashboard_templates.py

@@ -5,7 +5,8 @@
     python3 .github/scripts/regenerate_dashboard_templates.py
 
 Walks the SigNoz/dashboards repo at the tip of `main`, locates each template
-JSON, extracts title/description/tags, and emits the bundled index at
+JSON, extracts the title/description (v6 `spec.display.*`, falling back to v1
+top-level fields) and tags, and emits the bundled index at
 internal/handler/tools/dashboard_templates.json.
 
 The runtime fetcher (signoz_import_dashboard) also reads from `main`, so the
@@ -105,11 +106,25 @@ def _build_entry(ref: str, path: str) -> dict[str, Any] | None:
     except json.JSONDecodeError:
         return None
 
-    title = data.get("title") or path.rsplit("/", 1)[-1].removesuffix(".json")
-    description = data.get("description") or ""
-    tags = data.get("tags") or []
-    if not isinstance(tags, list):
-        tags = []
+    # v6 puts the human title/description under spec.display; fall back to the
+    # v1 top-level fields so the catalog regenerates cleanly through the
+    # migration, then to the filename.
+    spec = data.get("spec") or {}
+    display = spec.get("display") or {}
+    title = display.get("name") or data.get("title") or path.rsplit("/", 1)[-1].removesuffix(".json")
+    description = display.get("description") or data.get("description") or ""
+
+    # Tags feed the keyword index only (the entry has no tags field). v6 tags
+    # are {key, value} objects, v1 tags are plain strings; flatten both to text
+    # so _derive_keywords can tokenize them, indexing key AND value for v6.
+    raw_tags = data.get("tags")
+    tags: list[str] = []
+    if isinstance(raw_tags, list):
+        for t in raw_tags:
+            if isinstance(t, dict):
+                tags.extend(str(v) for v in (t.get("key"), t.get("value")) if v)
+            elif isinstance(t, str):
+                tags.append(t)
 
     return {
         "id": path.split("/", 1)[0],

README.md

@@ -357,9 +357,10 @@ HTTP mode exposes unauthenticated probe endpoints. New Kubernetes deployments sh
 | `signoz_update_alert` | Fully replace an alert after fetching it and verifying notification-channel names |
 | `signoz_delete_alert` | Permanently delete a confirmed alert rule by UUIDv7 `id` |
 | `signoz_list_dashboards` | List tenant-dashboard summaries and discover UUIDs |
-| `signoz_get_dashboard` | Get one dashboard's full layout, variables, widgets, and queries |
-| `signoz_create_dashboard` | Create a custom multi-widget dashboard |
+| `signoz_get_dashboard` | Get one dashboard's full layout, variables, panels, and queries |
+| `signoz_create_dashboard` | Create a custom multi-panel dashboard |
 | `signoz_update_dashboard` | Fully replace a fetched dashboard while preserving unrequested fields |
+| `signoz_patch_dashboard` | Apply a partial RFC 6902 JSON Patch without resending the whole dashboard |
 | `signoz_delete_dashboard` | Permanently delete a confirmed dashboard by `id` |
 | `signoz_import_dashboard` | Create a dashboard from a known curated template path |
 | `signoz_list_dashboard_templates` | List curated templates and discover an import path |
@@ -386,7 +387,7 @@ HTTP mode exposes unauthenticated probe endpoints. New Kubernetes deployments sh
 
 For detailed usage and examples, see the [full documentation](https://signoz.io/docs/ai/signoz-mcp-server/).
 
-> **Resource deep links:** the resource read tools (`signoz_list_dashboards`, `signoz_get_dashboard`, `signoz_list_alerts`, `signoz_list_alert_rules`, `signoz_get_alert`, `signoz_list_services`, `signoz_search_traces`, `signoz_get_trace_details`) include a `webUrl` field — an absolute deep link to the resource in the SigNoz web UI (per result row for `signoz_search_traces`) — when the request carries a SigNoz instance URL.
+> **Resource deep links:** the resource read tools (`signoz_list_dashboards`, `signoz_get_dashboard`, `signoz_list_alerts`, `signoz_list_alert_rules`, `signoz_get_alert`, `signoz_list_services`, `signoz_search_traces`, `signoz_get_trace_details`) and the dashboard write tools (`signoz_create_dashboard`, `signoz_update_dashboard`, `signoz_patch_dashboard`) include a `webUrl` field — an absolute deep link to the resource in the SigNoz web UI (per result row for `signoz_search_traces`) — when the request carries a SigNoz instance URL.
 
 ### Agent Routing Guidance
 
@@ -514,29 +515,27 @@ Gets one alert rule's full definition (`GET /api/v2/rules/{id}`). Use `signoz_li
 
 #### `signoz_list_dashboards`
 
-Lists paginated tenant-dashboard summaries (name, UUID, description, tags, timestamps). Use `signoz_get_dashboard` for widget and query definitions, and follow `pagination.nextOffset` while `pagination.hasMore` is true before concluding a dashboard is absent.
+Lists paginated tenant-dashboard summaries (name, UUID, description, tags, timestamps). Use `signoz_get_dashboard` for panel and query definitions, and follow `pagination.nextOffset` while `pagination.hasMore` is true before concluding a dashboard is absent.
 
 #### `signoz_get_dashboard`
 
-Gets one known tenant dashboard's complete layout, variables, widgets, and queries. Use `signoz_list_dashboards` to discover the UUID.
+Gets one known tenant dashboard's complete layout, variables, panels, and queries. Use `signoz_list_dashboards` to discover the UUID.
 
 - **Parameters**: `id` (required) - Dashboard UUID
 
 #### `signoz_create_dashboard`
 
-Creates a custom multi-widget dashboard. Use `signoz_import_dashboard` when a curated template fits, or `signoz_create_view` to save one Explorer query. Read `signoz://dashboard/instructions`, `signoz://dashboard/widgets-instructions`, and `signoz://dashboard/widgets-examples` before composing the payload.
+Creates a custom multi-panel dashboard. Use `signoz_import_dashboard` when a curated template fits, or `signoz_create_view` to save one Explorer query. Read `signoz://dashboard/instructions`, `signoz://dashboard/widgets-instructions`, and `signoz://dashboard/widgets-examples` before composing the payload.
 
 - **Parameters:**
-  - `title` (required) – Dashboard name
-  - `description` (optional) – Short summary of what the dashboard shows
-  - `tags` (optional) – List of tags
-  - `layout` (required) – Widget positioning grid
-  - `variables` (optional) – Map of variables available for use in queries
-  - `widgets` (required) – List of widgets added to the dashboard
+  - `schemaVersion` (required) – Must be `"v6"`
+  - `name` (DNS-1123 label) or `generateName: true` to derive it from `spec.display.name`
+  - `tags` (required) – Array of key/value tags (may be empty)
+  - `spec` (required) – Perses spec: `display`, `variables` (array), `panels` (map keyed by panel id), `layouts` (array)
 
 #### `signoz_import_dashboard`
 
-Creates a dashboard from a curated template hosted in the [SigNoz/dashboards](https://github.com/SigNoz/dashboards) repo (`main` branch). The server fetches the template JSON, validates it, and creates the dashboard in one call.
+Creates a dashboard from a curated template hosted in the [SigNoz/dashboards](https://github.com/SigNoz/dashboards) repo (`main` branch). The server fetches the template JSON and creates the dashboard in one call.
 
 When the relative template path is unknown, call `signoz_list_dashboard_templates` first. Pass its `path`, not a URL or absolute path.
 
@@ -554,14 +553,16 @@ Returns the full bundled catalog of curated SigNoz dashboard templates (id, titl
 Fully replaces an existing dashboard. Fetch it with `signoz_get_dashboard`, merge only the requested changes, and preserve every other field. Use `signoz_update_view` for a saved Explorer query.
 
 - **Parameters:**
-  - `id` (required) – Unique identifier of the dashboard to update
-  - `dashboard` (required) – Complete dashboard object representing the post-update state
-    - `title` (required) – Dashboard name
-    - `description` (optional) – Short summary of what the dashboard shows
-    - `tags` (optional) – List of tags applied to the dashboard
-    - `layout` (required) – Full widget positioning grid
-    - `variables` (optional) – Map of variables available for use in queries
-    - `widgets` (required) – Complete set of widgets defining the updated dashboard
+  - `id` (required) – Dashboard id (the legacy `uuid` key is also accepted)
+  - `schemaVersion`, `name`, `tags`, `spec` – the complete post-update state (see the tool's JSON Schema)
+
+#### `signoz_patch_dashboard`
+
+Applies an RFC 6902 JSON Patch to a dashboard — a partial update without re-sending the entire dashboard. Prefer this over `signoz_update_dashboard` for targeted edits (rename, add/edit one panel or query, tweak a variable).
+
+- **Parameters:**
+  - `id` (required) – Dashboard id (the legacy `uuid` key is also accepted)
+  - `patch` (required) – Array of `{op, path, value}` operations; paths are JSON Pointers into the dashboard's postable shape, e.g. `/spec/display/name`, `/spec/panels/<panelId>`, `/tags/-`
 
 #### `signoz_list_services`
 
@@ -608,7 +609,7 @@ The response is `{ "status": "success", "data": { "items": [...], "total": <n>,
 
 #### `signoz_list_views`
 
-List saved Explorer views or discover a view UUID for one Logs, Traces, Metrics, or Cost Meter page. A view stores one reusable Explorer query; it is not a multi-widget dashboard. Apply name/category filters before pagination and follow `pagination.nextOffset` while `pagination.hasMore` is true.
+List saved Explorer views or discover a view UUID for one Logs, Traces, Metrics, or Cost Meter page. A view stores one reusable Explorer query; it is not a multi-panel dashboard. Apply name/category filters before pagination and follow `pagination.nextOffset` while `pagination.hasMore` is true.
 
 - **Parameters**:
   - `sourcePage` (required) - One of: `traces`, `logs`, `metrics`, `meter`. Cost Meter views are filed under `meter` (a distinct Explorer page), not `metrics`
@@ -644,7 +645,7 @@ Fetch one known official SigNoz docs page's full Markdown or a requested heading
 
 #### `signoz_create_view`
 
-Save one reusable Explorer query. Use `signoz_create_dashboard` for a multi-widget dashboard. Cost Meter views use `sourcePage="meter"` with `signal="metrics"` and `source="meter"` in builder specs.
+Save one reusable Explorer query. Use `signoz_create_dashboard` for a multi-panel dashboard. Cost Meter views use `sourcePage="meter"` with `signal="metrics"` and `source="meter"` in builder specs.
 
 - **Parameters**: JSON payload matching the `SavedView` schema.
 - **Required**: Read both MCP resources `signoz://view/instructions` and `signoz://view/examples` before composing any payload.

go.mod

@@ -5,6 +5,7 @@ go 1.25.5
 require (
 	github.com/SigNoz/signoz-otel-collector v0.129.12
 	github.com/blevesearch/bleve/v2 v2.5.4
+	github.com/google/jsonschema-go v0.4.2
 	github.com/google/uuid v1.6.0
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/mark3labs/mcp-go v0.56.0
@@ -59,7 +60,6 @@ require (
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/golang/snappy v1.0.0 // indirect
-	github.com/google/jsonschema-go v0.4.2 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.18.0 // indirect

internal/client/client.go

@@ -10,6 +10,7 @@ import (
 	"log/slog"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -580,74 +581,29 @@ func (s *SigNoz) GetAlertByRuleID(ctx context.Context, ruleID string) (json.RawM
 	return s.doRequest(ctx, http.MethodGet, reqURL, nil, DefaultQueryTimeout)
 }
 
-// ListDashboards filters data as it returns too much data even the ui tags
-// so we filter and only return required information which might help to get
-// detailed info of a dashboard.
-func (s *SigNoz) ListDashboards(ctx context.Context) (json.RawMessage, error) {
+// ListDashboards returns the v2 dashboard list (GET /api/v2/dashboards). The v2
+// API paginates server-side, so limit/offset are forwarded as query params and
+// the ListableDashboardV2 response ({dashboards, tags, total}) is passed through
+// verbatim.
+func (s *SigNoz) ListDashboards(ctx context.Context, limit, offset int) (json.RawMessage, error) {
 	ctx = s.ensureTenantContext(ctx)
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards", s.baseURL)
-	s.logger.DebugContext(ctx, "Fetching dashboards from SigNoz")
-
-	body, err := s.doRequest(ctx, http.MethodGet, reqURL, nil, DefaultQueryTimeout)
-	if err != nil {
-		return nil, err
-	}
-
-	var rawResponse map[string]interface{}
-	if err := json.Unmarshal(body, &rawResponse); err != nil {
-		return nil, fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	data, ok := rawResponse["data"].([]interface{})
-	if !ok {
-		return body, nil
-	}
-
-	simplifiedDashboards := make([]map[string]interface{}, 0, len(data))
-	for _, dashboard := range data {
-		dash, ok := dashboard.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		var (
-			name any
-			desc any
-			tags any
-		)
-		if v, ok := dash["data"].(map[string]interface{}); ok {
-			name = v["title"]
-			desc = v["description"]
-			tags = v["tags"]
-		}
-
-		simplifiedDashboards = append(simplifiedDashboards, map[string]interface{}{
-			"uuid":        dash["id"],
-			"name":        name,
-			"description": desc,
-			"tags":        tags,
-			"createdAt":   dash["createdAt"],
-			"updatedAt":   dash["updatedAt"],
-			"createdBy":   dash["createdBy"],
-			"updatedBy":   dash["updatedBy"],
-		})
+	params := url.Values{}
+	if limit > 0 {
+		params.Set("limit", strconv.Itoa(limit))
 	}
-
-	simplifiedResponse := map[string]interface{}{
-		"status": rawResponse["status"],
-		"data":   simplifiedDashboards,
+	if offset > 0 {
+		params.Set("offset", strconv.Itoa(offset))
 	}
-
-	simplifiedJSON, err := json.Marshal(simplifiedResponse)
-	if err != nil {
-		return nil, fmt.Errorf("failed to marshal simplified response: %w", err)
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards", s.baseURL)
+	if enc := params.Encode(); enc != "" {
+		reqURL += "?" + enc
 	}
-
-	s.logger.DebugContext(ctx, "Successfully retrieved and simplified dashboards", slog.Int("count", len(simplifiedDashboards)))
-	return simplifiedJSON, nil
+	s.logger.DebugContext(ctx, "Fetching dashboards from SigNoz (v2)")
+	return s.doRequest(ctx, http.MethodGet, reqURL, nil, DefaultQueryTimeout)
 }
 
 func (s *SigNoz) GetDashboard(ctx context.Context, uuid string) (json.RawMessage, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards/%s", s.baseURL, url.PathEscape(uuid))
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards/%s", s.baseURL, url.PathEscape(uuid))
 	s.logger.DebugContext(s.ensureTenantContext(ctx), "Fetching dashboard details", slog.String("uuid", uuid))
 	return s.doRequest(ctx, http.MethodGet, reqURL, nil, DefaultQueryTimeout)
 }
@@ -815,48 +771,35 @@ func (s *SigNoz) GetTraceDetails(ctx context.Context, traceID string, includeSpa
 	return s.QueryBuilderV5(ctx, queryJSON)
 }
 
-func (s *SigNoz) CreateDashboard(ctx context.Context, dashboard types.Dashboard) (json.RawMessage, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards", s.baseURL)
-	dashboardJSON, err := json.Marshal(dashboard)
-	if err != nil {
-		return nil, fmt.Errorf("marshal dashboard: %w", err)
-	}
-
-	s.logger.DebugContext(s.ensureTenantContext(ctx), "Creating dashboard")
-	return s.doRequest(ctx, http.MethodPost, reqURL, dashboardJSON, DashboardWriteTimeout)
-}
-
-func (s *SigNoz) UpdateDashboard(ctx context.Context, id string, dashboard types.Dashboard) error {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards/%s", s.baseURL, url.PathEscape(id))
-	dashboardJSON, err := json.Marshal(dashboard)
-	if err != nil {
-		return fmt.Errorf("marshal dashboard: %w", err)
-	}
-
-	s.logger.DebugContext(s.ensureTenantContext(ctx), "Updating dashboard", slog.String("id", id))
-	_, err = s.doRequest(ctx, http.MethodPut, reqURL, dashboardJSON, DashboardWriteTimeout)
-	return err
-}
-
-// CreateDashboardRaw creates a dashboard from pre-validated JSON bytes,
-// avoiding a round-trip through types.Dashboard.
+// CreateDashboardRaw creates a v2 (Perses) dashboard from raw JSON bytes.
+// The MCP server is a pass-through: the v2 API validates the payload
+// (schemaVersion, DisallowUnknownFields, panel/query rules), so the bytes are
+// forwarded as-is to POST /api/v2/dashboards.
 func (s *SigNoz) CreateDashboardRaw(ctx context.Context, dashboardJSON []byte) (json.RawMessage, error) {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards", s.baseURL)
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards", s.baseURL)
 	s.logger.DebugContext(s.ensureTenantContext(ctx), "Creating dashboard (raw)")
 	return s.doRequest(ctx, http.MethodPost, reqURL, dashboardJSON, DashboardWriteTimeout)
 }
 
-// UpdateDashboardRaw updates a dashboard from pre-validated JSON bytes,
-// avoiding a round-trip through types.Dashboard.
-func (s *SigNoz) UpdateDashboardRaw(ctx context.Context, id string, dashboardJSON []byte) error {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards/%s", s.baseURL, url.PathEscape(id))
+// UpdateDashboardRaw replaces a v2 dashboard via PUT /api/v2/dashboards/{id}.
+// The body is the full UpdatableDashboardV2 post-update state; the v2 API
+// rejects locked dashboards and treats name as immutable.
+func (s *SigNoz) UpdateDashboardRaw(ctx context.Context, id string, dashboardJSON []byte) (json.RawMessage, error) {
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards/%s", s.baseURL, url.PathEscape(id))
 	s.logger.DebugContext(s.ensureTenantContext(ctx), "Updating dashboard (raw)", slog.String("id", id))
-	_, err := s.doRequest(ctx, http.MethodPut, reqURL, dashboardJSON, DashboardWriteTimeout)
-	return err
+	return s.doRequest(ctx, http.MethodPut, reqURL, dashboardJSON, DashboardWriteTimeout)
+}
+
+// PatchDashboardRaw applies an RFC 6902 JSON Patch to a v2 dashboard via
+// PATCH /api/v2/dashboards/{id}. The body is the JSON Patch operation array.
+func (s *SigNoz) PatchDashboardRaw(ctx context.Context, id string, patchJSON []byte) (json.RawMessage, error) {
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards/%s", s.baseURL, url.PathEscape(id))
+	s.logger.DebugContext(s.ensureTenantContext(ctx), "Patching dashboard (raw)", slog.String("id", id))
+	return s.doRequest(ctx, http.MethodPatch, reqURL, patchJSON, DashboardWriteTimeout)
 }
 
 func (s *SigNoz) DeleteDashboard(ctx context.Context, id string) error {
-	reqURL := fmt.Sprintf("%s/api/v1/dashboards/%s", s.baseURL, url.PathEscape(id))
+	reqURL := fmt.Sprintf("%s/api/v2/dashboards/%s", s.baseURL, url.PathEscape(id))
 	s.logger.DebugContext(s.ensureTenantContext(ctx), "Deleting dashboard", slog.String("id", id))
 	_, err := s.doRequest(ctx, http.MethodDelete, reqURL, nil, DashboardWriteTimeout)
 	return err