jira-dash-mcp 1.0.0

package/vendor/grafana-server.js

@@ -0,0 +1,911 @@
+#!/usr/bin/env node
+/**
+ * Jira Grafana Dashboard MCP Server
+ *
+ * Self-contained stdio MCP server for Grafana dashboard operations.
+ * No npm dependencies are required. Requires Node.js >= 18 for global fetch.
+ *
+ * Main tool: update_dashboard
+ * - Full dashboard create/update through Grafana HTTP API
+ * - Patch-style update: fetch dashboard by uid, apply JSON Patch-like operations, write back
+ */
+
+const VERSION = "1.4.1";
+const fs = require("fs");
+const path = require("path");
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+
+const env = process.env;
+const GRAFANA_URL = normalizeBaseUrl(env.GRAFANA_URL || env.GRAFANA_BASE_URL || "");
+const GRAFANA_TOKEN = env.GRAFANA_TOKEN || env.GRAFANA_SERVICE_ACCOUNT_TOKEN || env.GRAFANA_API_TOKEN || "";
+const DEFAULT_FOLDER_UID = env.GRAFANA_FOLDER_UID || "";
+const DEFAULT_DATASOURCE_UID = env.GRAFANA_DATASOURCE_UID || "";
+const STATE_FILE = env.DASHBOARD_STATE_FILE || path.join(process.cwd(), ".runtime", "last-dashboard.json");
+
+function normalizeBaseUrl(url) {
+  return String(url || "").replace(/\/+$/, "");
+}
+
+function requireGrafanaConfig() {
+  const missing = [];
+  if (!GRAFANA_URL) missing.push("GRAFANA_URL");
+  if (!GRAFANA_TOKEN) missing.push("GRAFANA_TOKEN or GRAFANA_SERVICE_ACCOUNT_TOKEN");
+  if (missing.length) {
+    throw new Error(`Missing required Grafana config: ${missing.join(", ")}`);
+  }
+}
+
+async function grafanaRequest(method, path, body) {
+  requireGrafanaConfig();
+  const url = `${GRAFANA_URL}${path}`;
+  const headers = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${GRAFANA_TOKEN}`,
+  };
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  let data = null;
+  if (text) {
+    try { data = JSON.parse(text); }
+    catch { data = { raw: text }; }
+  }
+  if (!res.ok) {
+    const msg = data && (data.message || data.error) ? (data.message || data.error) : text;
+    throw new Error(`Grafana API ${method} ${path} failed: HTTP ${res.status} ${res.statusText}${msg ? ` - ${msg}` : ""}`);
+  }
+  return data;
+}
+
+function encodeQuery(params) {
+  const q = new URLSearchParams();
+  Object.entries(params || {}).forEach(([k, v]) => {
+    if (v !== undefined && v !== null && String(v) !== "") q.set(k, String(v));
+  });
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+
+function slugify(title) {
+  return String(title || "dashboard")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9\u4e00-\u9fa5-]+/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "dashboard";
+}
+
+function dashboardUrl(uid, title) {
+  return `${GRAFANA_URL}/d/${encodeURIComponent(uid)}/${encodeURIComponent(slugify(title))}`;
+}
+
+function folderUrl(folderUid, title) {
+  return `${GRAFANA_URL}/dashboards/f/${encodeURIComponent(folderUid)}/${encodeURIComponent(slugify(title || folderUid))}`;
+}
+
+function summarizePanel(panel) {
+  return {
+    id: panel.id,
+    title: panel.title || "",
+    type: panel.type || "",
+    gridPos: panel.gridPos || null,
+    datasource: panel.datasource || null,
+    targets: Array.isArray(panel.targets)
+      ? panel.targets.map((t) => ({
+          refId: t.refId,
+          datasource: t.datasource || panel.datasource || null,
+          rawSql: t.rawSql,
+          format: t.format,
+        }))
+      : [],
+  };
+}
+
+function summarizeDashboard(payload) {
+  const d = payload.dashboard || payload;
+  const meta = payload.meta || {};
+  return {
+    uid: d.uid,
+    id: d.id,
+    title: d.title,
+    url: meta.url ? `${GRAFANA_URL}${meta.url}` : (d.uid ? dashboardUrl(d.uid, d.title) : null),
+    folderUid: meta.folderUid || DEFAULT_FOLDER_UID || null,
+    folderTitle: meta.folderTitle || null,
+    tags: d.tags || [],
+    timezone: d.timezone || "browser",
+    time: d.time || null,
+    refresh: d.refresh || null,
+    schemaVersion: d.schemaVersion,
+    variables: d.templating && Array.isArray(d.templating.list)
+      ? d.templating.list.map((v) => ({ name: v.name, type: v.type, label: v.label, query: v.query, current: v.current }))
+      : [],
+    panelCount: Array.isArray(d.panels) ? d.panels.length : 0,
+    panels: Array.isArray(d.panels) ? d.panels.map(summarizePanel) : [],
+  };
+}
+
+function decodePointerSegment(s) {
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function pointerParts(path) {
+  if (path === "" || path === "/") return [];
+  if (!path.startsWith("/")) throw new Error(`JSON pointer must start with '/': ${path}`);
+  return path.slice(1).split("/").map(decodePointerSegment);
+}
+
+function getAtPath(root, parts) {
+  let cur = root;
+  for (const part of parts) {
+    if (cur === undefined || cur === null) return undefined;
+    if (Array.isArray(cur)) {
+      const idx = Number(part);
+      if (!Number.isInteger(idx)) throw new Error(`Invalid array index '${part}'`);
+      cur = cur[idx];
+    } else {
+      cur = cur[part];
+    }
+  }
+  return cur;
+}
+
+function setAtPath(root, parts, value, mode) {
+  if (parts.length === 0) {
+    if (mode === "add" || mode === "replace") return value;
+    throw new Error("Cannot remove document root");
+  }
+  const parentParts = parts.slice(0, -1);
+  const key = parts[parts.length - 1];
+  const parent = getAtPath(root, parentParts);
+  if (parent === undefined || parent === null) throw new Error(`Parent path not found: /${parentParts.join("/")}`);
+  if (Array.isArray(parent)) {
+    if (key === "-" && mode === "add") {
+      parent.push(value);
+      return root;
+    }
+    const idx = Number(key);
+    if (!Number.isInteger(idx)) throw new Error(`Invalid array index '${key}'`);
+    if (mode === "add") parent.splice(idx, 0, value);
+    else if (mode === "replace") {
+      if (idx < 0 || idx >= parent.length) throw new Error(`Array index out of range: ${idx}`);
+      parent[idx] = value;
+    } else if (mode === "remove") {
+      if (idx < 0 || idx >= parent.length) throw new Error(`Array index out of range: ${idx}`);
+      parent.splice(idx, 1);
+    }
+    return root;
+  }
+  if (mode === "add" || mode === "replace") {
+    if (mode === "replace" && !(key in parent)) throw new Error(`Path not found for replace: /${parts.join("/")}`);
+    parent[key] = value;
+  } else if (mode === "remove") {
+    if (!(key in parent)) throw new Error(`Path not found for remove: /${parts.join("/")}`);
+    delete parent[key];
+  }
+  return root;
+}
+
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+function ensureDirForFile(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function readStateFile() {
+  try {
+    if (!fs.existsSync(STATE_FILE)) return null;
+    return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+  } catch (err) {
+    throw new Error(`Failed to read dashboard state file ${STATE_FILE}: ${err.message}`);
+  }
+}
+
+function writeStateFile(state) {
+  try {
+    ensureDirForFile(STATE_FILE);
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+    return state;
+  } catch (err) {
+    throw new Error(`Failed to write dashboard state file ${STATE_FILE}: ${err.message}`);
+  }
+}
+
+function stripSqlComments(sql) {
+  return String(sql || "")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/--[^\n\r]*/g, " ")
+    .trim();
+}
+
+function validateSqlText(sql) {
+  const errors = [];
+  const warnings = [];
+  const raw = String(sql || "");
+  const text = stripSqlComments(raw);
+  if (!text) {
+    errors.push("SQL is empty");
+    return { valid: false, errors, warnings };
+  }
+  const lowered = text.toLowerCase();
+  if (!/^\s*(select|with)\b/.test(lowered)) {
+    errors.push("Only SELECT/WITH read-only SQL is allowed");
+  }
+  if (/;\s*\S/.test(text)) {
+    errors.push("Multiple SQL statements are not allowed");
+  }
+  if (/\b(insert|update|delete|drop|alter|truncate|create|replace|grant|revoke|call|exec|merge|load|outfile|infile)\b/i.test(text)) {
+    errors.push("Unsafe SQL verb detected; only read-only SELECT/WITH queries are allowed");
+  }
+  if (/\bfrom\s+([`\w.]+)/ig.test(text) || /\bjoin\s+([`\w.]+)/ig.test(text)) {
+    const refs = [...text.matchAll(/\b(?:from|join)\s+([`\w.]+)/ig)].map(m => m[1].replace(/`/g, ""));
+    for (const ref of refs) {
+      const table = ref.split(".").pop();
+      if (table && !table.startsWith("cdc_") && !["information_schema", "dual"].includes(table.toLowerCase())) {
+        warnings.push(`Table '${ref}' is outside the expected Jira cdc_* table set; confirm it is intentional`);
+      }
+    }
+  }
+  if (!/\$__time(Filter|Group|GroupAlias)\(/.test(text) && /\b(issue_created|issue_updated|resolutiondate|start_date|end_date)\b/i.test(text)) {
+    warnings.push("Time field is used without Grafana $__timeFilter/$__timeGroup macro; confirm time range behavior");
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function collectSqlTargets(dashboard) {
+  const out = [];
+  const panels = Array.isArray(dashboard && dashboard.panels) ? dashboard.panels : [];
+  for (const panel of panels) {
+    if (!Array.isArray(panel.targets)) continue;
+    for (const target of panel.targets) {
+      if (target && typeof target.rawSql === "string") {
+        out.push({ panelId: panel.id, panelTitle: panel.title || "", refId: target.refId || "", rawSql: target.rawSql });
+      }
+    }
+  }
+  return out;
+}
+
+function replaceEnvPlaceholders(value) {
+  if (Array.isArray(value)) return value.map(replaceEnvPlaceholders);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = replaceEnvPlaceholders(v);
+    return out;
+  }
+  if (typeof value !== "string") return value;
+  return value
+    .replace(/\$\{GRAFANA_DATASOURCE_UID\}/g, DEFAULT_DATASOURCE_UID || "")
+    .replace(/__GRAFANA_DATASOURCE_UID__/g, DEFAULT_DATASOURCE_UID || "")
+    .replace(/\$\{GRAFANA_FOLDER_UID\}/g, DEFAULT_FOLDER_UID || "")
+    .replace(/__GRAFANA_FOLDER_UID__/g, DEFAULT_FOLDER_UID || "");
+}
+
+function ensurePanelIds(panels) {
+  if (!Array.isArray(panels)) return [];
+  const used = new Set();
+  let next = 1;
+  for (const panel of panels) {
+    if (!panel || typeof panel !== "object") continue;
+    if (Number.isInteger(panel.id) && panel.id > 0 && !used.has(panel.id)) {
+      used.add(panel.id);
+      continue;
+    }
+    while (used.has(next)) next++;
+    panel.id = next;
+    used.add(next);
+    next++;
+  }
+  return panels;
+}
+
+function collectDatasourceRefs(node, refs = []) {
+  if (Array.isArray(node)) {
+    node.forEach((x) => collectDatasourceRefs(x, refs));
+  } else if (node && typeof node === "object") {
+    if (node.datasource && typeof node.datasource === "object") refs.push(node.datasource);
+    Object.values(node).forEach((x) => collectDatasourceRefs(x, refs));
+  }
+  return refs;
+}
+
+function validateDashboardObject(dashboard) {
+  const errors = [];
+  const warnings = [];
+  const d = dashboard || {};
+  if (!d.title || typeof d.title !== "string") errors.push("dashboard.title is required");
+  if (!Array.isArray(d.panels)) errors.push("dashboard.panels must be an array");
+  if (!d.time || !d.time.from || !d.time.to) warnings.push("dashboard.time is missing; default now-30d to now will be used");
+  if (!DEFAULT_DATASOURCE_UID) warnings.push("GRAFANA_DATASOURCE_UID is not set; dashboard queries must explicitly include a datasource uid");
+
+  const panels = Array.isArray(d.panels) ? d.panels : [];
+  const panelIds = new Set();
+  for (const panel of panels) {
+    if (!panel || typeof panel !== "object") {
+      errors.push("panel must be an object");
+      continue;
+    }
+    if (!panel.title) warnings.push(`panel id ${panel.id || "unknown"} has no title`);
+    if (panel.id && panelIds.has(panel.id)) warnings.push(`duplicate panel id ${panel.id}; ids will be normalized`);
+    if (panel.id) panelIds.add(panel.id);
+    if (Array.isArray(panel.targets)) {
+      for (const target of panel.targets) {
+        if (target && target.rawSql && typeof target.rawSql === "string") {
+          const sqlCheck = validateSqlText(target.rawSql);
+          for (const e of sqlCheck.errors) errors.push(`unsafe SQL in panel '${panel.title || panel.id}' target '${target.refId || ""}': ${e}`);
+          for (const w of sqlCheck.warnings) warnings.push(`SQL warning in panel '${panel.title || panel.id}' target '${target.refId || ""}': ${w}`);
+        }
+      }
+    }
+  }
+
+  for (const ref of collectDatasourceRefs(d)) {
+    if (ref.uid === "${GRAFANA_DATASOURCE_UID}" || ref.uid === "__GRAFANA_DATASOURCE_UID__") {
+      warnings.push("datasource uid placeholder detected; it will be replaced from GRAFANA_DATASOURCE_UID");
+    }
+    if (DEFAULT_DATASOURCE_UID && ref.type === "mysql" && !ref.uid) {
+      warnings.push("mysql datasource object has no uid; default uid will be injected where possible");
+    }
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function applyOperations(root, operations) {
+  let doc = root;
+  for (const op of operations || []) {
+    if (!op || !op.op || typeof op.path !== "string") throw new Error(`Invalid operation: ${JSON.stringify(op)}`);
+    const parts = pointerParts(op.path);
+    if (op.op === "add") doc = setAtPath(doc, parts, deepClone(op.value), "add");
+    else if (op.op === "replace") doc = setAtPath(doc, parts, deepClone(op.value), "replace");
+    else if (op.op === "remove") doc = setAtPath(doc, parts, undefined, "remove");
+    else if (op.op === "test") {
+      const actual = getAtPath(doc, parts);
+      if (JSON.stringify(actual) !== JSON.stringify(op.value)) throw new Error(`JSON patch test failed at ${op.path}`);
+    } else {
+      throw new Error(`Unsupported operation '${op.op}'. Supported: add, replace, remove, test`);
+    }
+  }
+  return doc;
+}
+
+function queryJsonPath(obj, expression) {
+  if (!expression || expression === "$") return obj;
+  let expr = expression.trim();
+  if (!expr.startsWith("$")) throw new Error("JSONPath must start with $");
+  expr = expr.slice(1);
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    if (expr[i] === ".") {
+      i++;
+      let name = "";
+      while (i < expr.length && /[A-Za-z0-9_$-]/.test(expr[i])) name += expr[i++];
+      if (!name) throw new Error(`Invalid JSONPath near '${expr.slice(i)}'`);
+      tokens.push(name);
+    } else if (expr[i] === "[") {
+      const end = expr.indexOf("]", i);
+      if (end === -1) throw new Error("Unclosed JSONPath bracket");
+      let inner = expr.slice(i + 1, end).trim();
+      if ((inner.startsWith("'") && inner.endsWith("'")) || (inner.startsWith('"') && inner.endsWith('"'))) {
+        inner = inner.slice(1, -1);
+      }
+      tokens.push(inner);
+      i = end + 1;
+    } else {
+      throw new Error(`Unsupported JSONPath syntax near '${expr.slice(i)}'. Supported: $.a.b[0].c and $['a']`);
+    }
+  }
+  let cur = obj;
+  for (const t of tokens) {
+    if (cur === undefined || cur === null) return null;
+    if (Array.isArray(cur)) {
+      const idx = Number(t);
+      if (!Number.isInteger(idx)) throw new Error(`Invalid array index '${t}'`);
+      cur = cur[idx];
+    } else {
+      cur = cur[t];
+    }
+  }
+  return cur === undefined ? null : cur;
+}
+
+async function listDatasources() {
+  const data = await grafanaRequest("GET", "/api/datasources");
+  return data.map((d) => ({ id: d.id, uid: d.uid, name: d.name, type: d.type, access: d.access, isDefault: d.isDefault }));
+}
+
+async function getDatasource(args) {
+  if (args.uid) return await grafanaRequest("GET", `/api/datasources/uid/${encodeURIComponent(args.uid)}`);
+  if (args.name) return await grafanaRequest("GET", `/api/datasources/name/${encodeURIComponent(args.name)}`);
+  if (DEFAULT_DATASOURCE_UID) return await grafanaRequest("GET", `/api/datasources/uid/${encodeURIComponent(DEFAULT_DATASOURCE_UID)}`);
+  throw new Error("Provide uid or name, or set GRAFANA_DATASOURCE_UID");
+}
+
+async function searchFolders(args) {
+  const params = encodeQuery({ type: "dash-folder", query: args.query || "", limit: args.limit || 50 });
+  return await grafanaRequest("GET", `/api/search${params}`);
+}
+
+async function searchDashboards(args) {
+  const params = encodeQuery({
+    type: "dash-db",
+    query: args.query || "",
+    folderUIDs: args.folderUid || args.folderUIDs || DEFAULT_FOLDER_UID || undefined,
+    limit: args.limit || 50,
+  });
+  return await grafanaRequest("GET", `/api/search${params}`);
+}
+
+async function getDashboardByUid(args) {
+  if (!args.uid) throw new Error("uid is required");
+  return await grafanaRequest("GET", `/api/dashboards/uid/${encodeURIComponent(args.uid)}`);
+}
+
+async function getDashboardSummary(args) {
+  const payload = await getDashboardByUid(args);
+  return summarizeDashboard(payload);
+}
+
+async function getDashboardProperty(args) {
+  const payload = await getDashboardByUid(args);
+  const root = args.root === "response" ? payload : payload.dashboard;
+  return {
+    uid: payload.dashboard && payload.dashboard.uid,
+    title: payload.dashboard && payload.dashboard.title,
+    expression: args.expression,
+    value: queryJsonPath(root, args.expression || "$"),
+  };
+}
+
+function normalizeDashboardForWrite(dashboard, args) {
+  let d = deepClone(dashboard || {});
+  d = replaceEnvPlaceholders(d);
+  if (!d.title) throw new Error("dashboard.title is required");
+  if (!Array.isArray(d.panels)) d.panels = [];
+  d.panels = ensurePanelIds(d.panels);
+  d.time = d.time || { from: "now-30d", to: "now" };
+  d.timezone = d.timezone || "browser";
+  d.refresh = d.refresh === undefined ? "" : d.refresh;
+  d.schemaVersion = d.schemaVersion || 39;
+  d.version = args.resetVersion ? 0 : (d.version || 0);
+  if (DEFAULT_DATASOURCE_UID) {
+    // Best-effort datasource UID injection for MySQL panels/targets missing uid.
+    const refs = collectDatasourceRefs(d);
+    for (const ref of refs) {
+      if ((ref.type === "mysql" || !ref.type) && !ref.uid) ref.uid = DEFAULT_DATASOURCE_UID;
+    }
+  }
+  return d;
+}
+
+async function getConfig() {
+  return {
+    grafanaUrl: GRAFANA_URL || null,
+    hasToken: Boolean(GRAFANA_TOKEN),
+    defaultFolderUid: DEFAULT_FOLDER_UID || null,
+    defaultDatasourceUid: DEFAULT_DATASOURCE_UID || null,
+    serverVersion: VERSION,
+    stateFile: STATE_FILE,
+  };
+}
+
+async function validateDashboard(args) {
+  if (!args.dashboard || typeof args.dashboard !== "object") throw new Error("dashboard object is required");
+  const dashboard = normalizeDashboardForWrite(args.dashboard, { resetVersion: args.resetVersion });
+  const validation = validateDashboardObject(dashboard);
+  return { ...validation, dashboard };
+}
+
+async function updateDashboard(args) {
+  const overwrite = args.overwrite !== false;
+  const message = args.message || "Updated by Jira Grafana Dashboard MCP";
+  const folderUid = args.folderUid || args.folderUID || DEFAULT_FOLDER_UID || undefined;
+
+  let dashboard;
+  let mode;
+
+  if (args.uid && Array.isArray(args.operations)) {
+    mode = "patch";
+    const current = await getDashboardByUid({ uid: args.uid });
+    dashboard = deepClone(current.dashboard);
+    dashboard = applyOperations(dashboard, args.operations);
+    dashboard.version = current.dashboard.version;
+    if (!dashboard.uid) dashboard.uid = args.uid;
+  } else if (args.dashboard && typeof args.dashboard === "object") {
+    dashboard = args.dashboard;
+    mode = dashboard && dashboard.uid ? "replace" : "create_or_replace";
+  } else {
+    throw new Error("update_dashboard requires either { dashboard } or { uid, operations }");
+  }
+
+  dashboard = normalizeDashboardForWrite(dashboard, args);
+  const validation = validateDashboardObject(dashboard);
+  if (!validation.valid) {
+    throw new Error(`Dashboard validation failed: ${validation.errors.join("; ")}`);
+  }
+  const sqlTargets = collectSqlTargets(dashboard);
+  const summary = summarizeDashboard({ dashboard, meta: { folderUid } });
+  if (args.dryRun) {
+    return {
+      status: "dry_run",
+      mode,
+      wouldWrite: false,
+      folderUid: folderUid || null,
+      summary,
+      sqlTargetCount: sqlTargets.length,
+      warnings: validation.warnings,
+    };
+  }
+  const body = {
+    dashboard,
+    folderUid,
+    overwrite,
+    message,
+  };
+  const result = await grafanaRequest("POST", "/api/dashboards/db", body);
+  const uid = result.uid || dashboard.uid;
+  const url = result.url ? `${GRAFANA_URL}${result.url}` : dashboardUrl(uid, dashboard.title);
+  const state = writeStateFile({
+    uid,
+    title: dashboard.title,
+    url,
+    folderUid: folderUid || null,
+    projectKey: args.projectKey || "",
+    userRequest: args.userRequest || "",
+    updatedAt: new Date().toISOString(),
+    serverVersion: VERSION,
+  });
+  return {
+    status: result.status || "success",
+    mode,
+    uid,
+    id: result.id,
+    version: result.version,
+    slug: result.slug || slugify(dashboard.title),
+    url,
+    folderUid: folderUid || null,
+    message: result.message || message,
+    warnings: validation.warnings,
+    stateSaved: true,
+    stateFile: STATE_FILE,
+    lastDashboard: state,
+  };
+}
+
+
+async function getLastDashboard(args) {
+  const state = readStateFile();
+  if (!state) return { found: false, stateFile: STATE_FILE };
+  if (args && args.projectKey && state.projectKey && args.projectKey !== state.projectKey) {
+    return { found: false, stateFile: STATE_FILE, reason: `last dashboard projectKey is ${state.projectKey}, not ${args.projectKey}`, last: state };
+  }
+  return { found: true, stateFile: STATE_FILE, dashboard: state };
+}
+
+async function saveDashboardState(args) {
+  if (!args.uid) throw new Error("uid is required");
+  const now = new Date().toISOString();
+  const state = {
+    uid: args.uid,
+    title: args.title || args.dashboardTitle || "",
+    url: args.url || (args.uid ? dashboardUrl(args.uid, args.title || "dashboard") : ""),
+    folderUid: args.folderUid || DEFAULT_FOLDER_UID || "",
+    projectKey: args.projectKey || "",
+    userRequest: args.userRequest || "",
+    updatedAt: now,
+    serverVersion: VERSION,
+  };
+  return { saved: true, stateFile: STATE_FILE, dashboard: writeStateFile(state) };
+}
+
+async function clearDashboardState() {
+  if (fs.existsSync(STATE_FILE)) fs.unlinkSync(STATE_FILE);
+  return { cleared: true, stateFile: STATE_FILE };
+}
+
+async function validateSql(args) {
+  if (!args.sql || typeof args.sql !== "string") throw new Error("sql string is required");
+  return validateSqlText(args.sql);
+}
+
+async function generateDeeplink(args) {
+  if (args.type === "folder") {
+    const uid = args.uid || args.folderUid || DEFAULT_FOLDER_UID;
+    if (!uid) throw new Error("folder uid is required");
+    return { url: folderUrl(uid, args.title || args.slug || uid) };
+  }
+  const uid = args.uid || args.dashboardUid;
+  if (!uid) throw new Error("dashboard uid is required");
+  return { url: dashboardUrl(uid, args.title || args.slug || "dashboard") };
+}
+
+async function healthcheck() {
+  const res = { ok: true, grafanaUrl: GRAFANA_URL, defaultFolderUid: DEFAULT_FOLDER_UID, defaultDatasourceUid: DEFAULT_DATASOURCE_UID };
+  const org = await grafanaRequest("GET", "/api/org");
+  res.org = org;
+  if (DEFAULT_DATASOURCE_UID) {
+    res.datasource = await getDatasource({ uid: DEFAULT_DATASOURCE_UID });
+  }
+  return res;
+}
+
+const tools = [
+  {
+    name: "get_config",
+    description: "Return non-secret Grafana MCP runtime config, including default datasource UID and folder UID.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: getConfig,
+  },
+  {
+    name: "get_last_dashboard",
+    description: "Return the last dashboard written by update_dashboard, used to locate the previous dashboard during multi-turn iteration.",
+    inputSchema: { type: "object", properties: { projectKey: { type: "string" } }, additionalProperties: false },
+    handler: getLastDashboard,
+  },
+  {
+    name: "save_dashboard_state",
+    description: "Manually save the active dashboard UID/title/url for later iteration when update_dashboard was not the last action.",
+    inputSchema: {
+      type: "object",
+      required: ["uid"],
+      properties: { uid: { type: "string" }, title: { type: "string" }, dashboardTitle: { type: "string" }, url: { type: "string" }, folderUid: { type: "string" }, projectKey: { type: "string" }, userRequest: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: saveDashboardState,
+  },
+  {
+    name: "clear_dashboard_state",
+    description: "Clear the saved last-dashboard pointer.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: clearDashboardState,
+  },
+  {
+    name: "validate_sql",
+    description: "Validate one SQL query before embedding it in a dashboard. Enforces read-only SELECT/WITH and warns about non-cdc tables and missing Grafana time macros.",
+    inputSchema: { type: "object", required: ["sql"], properties: { sql: { type: "string" } }, additionalProperties: false },
+    handler: validateSql,
+  },
+  {
+    name: "validate_dashboard",
+    description: "Validate and normalize a dashboard JSON before calling update_dashboard. It checks required fields, panel ids, datasource placeholders, and unsafe SQL verbs.",
+    inputSchema: {
+      type: "object",
+      required: ["dashboard"],
+      properties: { dashboard: { type: "object" }, resetVersion: { type: "boolean" } },
+      additionalProperties: false,
+    },
+    handler: validateDashboard,
+  },
+  {
+    name: "list_datasources",
+    description: "List Grafana datasources. Use this to discover the MySQL datasource UID before generating dashboard JSON.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: listDatasources,
+  },
+  {
+    name: "get_datasource",
+    description: "Get a Grafana datasource by UID or name. If no argument is given, uses GRAFANA_DATASOURCE_UID.",
+    inputSchema: {
+      type: "object",
+      properties: { uid: { type: "string" }, name: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: getDatasource,
+  },
+  {
+    name: "search_folders",
+    description: "Search Grafana folders by query string.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" }, limit: { type: "number" } },
+      additionalProperties: false,
+    },
+    handler: searchFolders,
+  },
+  {
+    name: "search_dashboards",
+    description: "Search dashboards, optionally restricted to a folder UID.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" }, folderUid: { type: "string" }, limit: { type: "number" } },
+      additionalProperties: false,
+    },
+    handler: searchDashboards,
+  },
+  {
+    name: "get_dashboard_by_uid",
+    description: "Get full dashboard JSON by uid. Avoid this unless full JSON is needed.",
+    inputSchema: { type: "object", required: ["uid"], properties: { uid: { type: "string" } }, additionalProperties: false },
+    handler: getDashboardByUid,
+  },
+  {
+    name: "get_dashboard_summary",
+    description: "Get a compact summary of a dashboard without returning full JSON. Prefer this before dashboard edits.",
+    inputSchema: { type: "object", required: ["uid"], properties: { uid: { type: "string" } }, additionalProperties: false },
+    handler: getDashboardSummary,
+  },
+  {
+    name: "get_dashboard_property",
+    description: "Extract a dashboard property using a simple JSONPath expression. Expressions apply to dashboard root by default, e.g. $.panels[0].title.",
+    inputSchema: {
+      type: "object",
+      required: ["uid", "expression"],
+      properties: {
+        uid: { type: "string" },
+        expression: { type: "string" },
+        root: { type: "string", enum: ["dashboard", "response"] },
+      },
+      additionalProperties: false,
+    },
+    handler: getDashboardProperty,
+  },
+  {
+    name: "update_dashboard",
+    description: "Create/update a Grafana dashboard. Supports full dashboard JSON or patch-style update with uid plus operations. Patch operations are applied to the dashboard JSON root.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dashboard: { type: "object", description: "Full Grafana dashboard JSON for create or full replacement." },
+        uid: { type: "string", description: "Existing dashboard UID for patch updates." },
+        operations: {
+          type: "array",
+          description: "JSON Patch-like operations applied to dashboard JSON root. Supports add, replace, remove, test.",
+          items: {
+            type: "object",
+            required: ["op", "path"],
+            properties: {
+              op: { type: "string", enum: ["add", "replace", "remove", "test"] },
+              path: { type: "string" },
+              value: {},
+            },
+          },
+        },
+        folderUid: { type: "string", description: "Target Grafana folder UID. Defaults to GRAFANA_FOLDER_UID." },
+        overwrite: { type: "boolean", description: "Whether to overwrite existing dashboard. Defaults to true." },
+        message: { type: "string", description: "Dashboard version message." },
+        resetVersion: { type: "boolean", description: "Force dashboard.version=0 for full replacement. Defaults to false." },
+        dryRun: { type: "boolean", description: "Validate and preview the normalized dashboard without writing to Grafana." },
+        projectKey: { type: "string", description: "Optional Jira project key saved into last-dashboard state for future iteration." },
+        userRequest: { type: "string", description: "Optional user request summary saved into last-dashboard state." },
+      },
+      additionalProperties: false,
+    },
+    handler: updateDashboard,
+  },
+  {
+    name: "generate_deeplink",
+    description: "Generate a Grafana dashboard or folder URL from UID and title.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: ["dashboard", "folder"] },
+        uid: { type: "string" },
+        dashboardUid: { type: "string" },
+        folderUid: { type: "string" },
+        title: { type: "string" },
+        slug: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    handler: generateDeeplink,
+  },
+];
+
+const toolMap = new Map(tools.map((t) => [t.name, t]));
+
+function response(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorResponse(id, code, message, data) {
+  return { jsonrpc: "2.0", id, error: { code, message, data } };
+}
+
+async function handleMessage(msg) {
+  try {
+    if (!msg || msg.jsonrpc !== "2.0") return null;
+    const { id, method, params } = msg;
+
+    if (method === "initialize") {
+      return response(id, {
+        protocolVersion: (params && params.protocolVersion) || DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "jira-grafana-dashboard-mcp", version: VERSION },
+      });
+    }
+
+    if (method === "notifications/initialized") return null;
+
+    if (method === "ping") return response(id, {});
+
+    if (method === "tools/list") {
+      return response(id, {
+        tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+      });
+    }
+
+    if (method === "tools/call") {
+      const name = params && params.name;
+      const args = (params && params.arguments) || {};
+      const tool = toolMap.get(name);
+      if (!tool) throw new Error(`Unknown tool: ${name}`);
+      const result = await tool.handler(args);
+      return response(id, {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        isError: false,
+      });
+    }
+
+    return errorResponse(id, -32601, `Method not found: ${method}`);
+  } catch (err) {
+    return response(msg.id, {
+      content: [{ type: "text", text: `ERROR: ${err.message}` }],
+      isError: true,
+    });
+  }
+}
+
+function writeMessage(msg) {
+  if (!msg) return;
+  // MCP stdio transport uses newline-delimited JSON-RPC messages.
+  // Do not use LSP-style Content-Length framing here; Claude Code will wait forever.
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+let buffer = Buffer.alloc(0);
+function tryParseMessages() {
+  while (buffer.length > 0) {
+    const headerEnd = buffer.indexOf(Buffer.from("\r\n\r\n"));
+    if (headerEnd === -1) {
+      const nl = buffer.indexOf(Buffer.from("\n"));
+      // Fallback for newline-delimited JSON during manual testing.
+      if (nl !== -1 && buffer.slice(0, nl).toString("utf8").trim().startsWith("{")) {
+        const line = buffer.slice(0, nl).toString("utf8").trim();
+        buffer = buffer.slice(nl + 1);
+        handleMessage(JSON.parse(line)).then(writeMessage);
+        continue;
+      }
+      return;
+    }
+    const header = buffer.slice(0, headerEnd).toString("utf8");
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) throw new Error(`Invalid MCP header: ${header}`);
+    const length = Number(match[1]);
+    const bodyStart = headerEnd + 4;
+    const bodyEnd = bodyStart + length;
+    if (buffer.length < bodyEnd) return;
+    const body = buffer.slice(bodyStart, bodyEnd).toString("utf8");
+    buffer = buffer.slice(bodyEnd);
+    handleMessage(JSON.parse(body)).then(writeMessage).catch((err) => writeMessage(errorResponse(null, -32603, err.message)));
+  }
+}
+
+async function main() {
+  if (process.argv.includes("--healthcheck")) {
+    try {
+      const result = await healthcheck();
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    try { tryParseMessages(); }
+    catch (err) { writeMessage(errorResponse(null, -32700, err.message)); }
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});