jira-dash-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Jira Grafana Dashboard MCP
+
+A single MCP server for Claude Code that combines:
+
+- read-only MySQL tools for Jira data synchronized into MySQL
+- Grafana dashboard tools for datasource discovery, dashboard validation, and `update_dashboard`
+
+This package contains **no company-specific configuration**. Runtime values are provided through environment variables in the caller's `.mcp.json`.
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code
+- A MySQL account with read-only access to the Jira synchronized database
+- A Grafana service account token with dashboard read/create/write permissions and datasource read permission
+
+## Claude `.mcp.json` example
+
+```json
+{
+  "mcpServers": {
+    "jira-grafana-dashboard-tools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "jira-dash-mcp@latest"
+      ],
+      "env": {
+        "MYSQL_HOST": "your-mysql-host",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "readonly_user",
+        "MYSQL_PASSWORD": "your-password",
+        "MYSQL_DATABASE": "your-database",
+        "MYSQL_DEFAULT_ROW_LIMIT": "200",
+        "MYSQL_MAX_ROW_LIMIT": "2000",
+        "MYSQL_QUERY_TIMEOUT_MS": "30000",
+
+        "GRAFANA_URL": "https://your-grafana.example.com",
+        "GRAFANA_TOKEN": "your-service-account-token",
+        "GRAFANA_DATASOURCE_UID": "your-mysql-datasource-uid",
+        "GRAFANA_FOLDER_UID": "your-target-folder-uid",
+        "DASHBOARD_STATE_FILE": ".runtime/last-dashboard.json"
+      }
+    }
+  }
+}
+```
+
+## Tool naming
+
+The package exposes one MCP server, with prefixed tools:
+
+MySQL tools:
+
+- `mysql_get_config`
+- `mysql_healthcheck`
+- `mysql_list_tables`
+- `mysql_describe_table`
+- `mysql_sample_rows`
+- `mysql_query`
+- `mysql_validate_sql`
+- `mysql_jira_schema_summary`
+
+Grafana tools:
+
+- `grafana_get_config`
+- `grafana_healthcheck`
+- `grafana_list_datasources`
+- `grafana_get_datasource`
+- `grafana_search_folders`
+- `grafana_search_dashboards`
+- `grafana_get_dashboard_by_uid`
+- `grafana_get_dashboard_summary`
+- `grafana_get_dashboard_property`
+- `grafana_validate_dashboard`
+- `grafana_update_dashboard`
+- `grafana_generate_deeplink`
+- `grafana_get_last_dashboard`
+- `grafana_save_dashboard_state`
+- `grafana_clear_dashboard_state`
+- `grafana_validate_sql`
+
+## Dependency behavior
+
+This package declares `mysql2` under `dependencies`, so users do **not** run `npm install mysql2` manually. When Claude runs this package through `npx`, npm resolves and installs runtime dependencies automatically.
+
+## Security notes
+
+- MySQL execution is read-only and validates SQL before execution.
+- `mysql_query` only allows read-only statements such as SELECT/WITH/SHOW/DESCRIBE/EXPLAIN.
+- Dashboard SQL is validated before write.
+- Do not publish `.env`, `.mcp.json`, real tokens, real database names, real IPs, or internal schema files to npm.
+
+## Local smoke test before publishing
+
+```bash
+npm install
+npm run smoke
+npm pack --dry-run
+```
+
+## Publish
+
+For a scoped public package:
+
+```bash
+npm login
+npm publish --access public
+```

package/bin/jira-grafana-dashboard-mcp.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Unified Jira Grafana Dashboard MCP Server
+ *
+ * This process exposes one MCP server to Claude Code and internally delegates to
+ * two self-contained child MCP servers:
+ * - vendor/mysql-server.js   -> tools are exposed as mysql_*
+ * - vendor/grafana-server.js -> tools are exposed as grafana_*
+ *
+ * It intentionally contains no company-specific configuration. All runtime
+ * configuration must be provided through environment variables in .mcp.json.
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+
+const VERSION = "1.0.0";
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+
+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 } };
+}
+
+function writeMessage(msg) {
+  if (!msg) return;
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+class ChildMcpClient {
+  constructor({ name, prefix, script }) {
+    this.name = name;
+    this.prefix = prefix;
+    this.script = script;
+    this.proc = null;
+    this.buffer = Buffer.alloc(0);
+    this.nextId = 1;
+    this.pending = new Map();
+    this.initialized = false;
+    this.tools = null;
+    this.stderr = "";
+  }
+
+  start() {
+    if (this.proc) return;
+    this.proc = spawn(process.execPath, [this.script], {
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    this.proc.stdout.on("data", (chunk) => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      this.parseMessages();
+    });
+
+    this.proc.stderr.on("data", (chunk) => {
+      const text = chunk.toString("utf8");
+      this.stderr += text;
+      if (this.stderr.length > 4000) this.stderr = this.stderr.slice(-4000);
+    });
+
+    this.proc.on("exit", (code, signal) => {
+      const err = new Error(`${this.name} exited with code=${code} signal=${signal}${this.stderr ? ` stderr=${this.stderr}` : ""}`);
+      for (const { reject } of this.pending.values()) reject(err);
+      this.pending.clear();
+      this.proc = null;
+      this.initialized = false;
+      this.tools = null;
+    });
+  }
+
+  parseMessages() {
+    while (this.buffer.length > 0) {
+      const headerEnd = this.buffer.indexOf(Buffer.from("\r\n\r\n"));
+      if (headerEnd !== -1) {
+        const header = this.buffer.slice(0, headerEnd).toString("utf8");
+        const match = header.match(/Content-Length:\s*(\d+)/i);
+        if (!match) throw new Error(`Invalid ${this.name} MCP header: ${header}`);
+        const length = Number(match[1]);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (this.buffer.length < bodyEnd) return;
+        const body = this.buffer.slice(bodyStart, bodyEnd).toString("utf8");
+        this.buffer = this.buffer.slice(bodyEnd);
+        this.handleChildMessage(JSON.parse(body));
+        continue;
+      }
+
+      const nl = this.buffer.indexOf(Buffer.from("\n"));
+      if (nl === -1) return;
+      const line = this.buffer.slice(0, nl).toString("utf8").trim();
+      this.buffer = this.buffer.slice(nl + 1);
+      if (!line) continue;
+      if (!line.startsWith("{")) continue;
+      this.handleChildMessage(JSON.parse(line));
+    }
+  }
+
+  handleChildMessage(msg) {
+    if (!msg || msg.id === undefined || msg.id === null) return;
+    const entry = this.pending.get(msg.id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    this.pending.delete(msg.id);
+    if (msg.error) entry.reject(new Error(`${this.name}: ${msg.error.message || JSON.stringify(msg.error)}`));
+    else entry.resolve(msg.result);
+  }
+
+  request(method, params = {}, timeoutMs = 30000) {
+    this.start();
+    const id = this.nextId++;
+    const payload = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${this.name} MCP request timeout: ${method}${this.stderr ? ` stderr=${this.stderr}` : ""}`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.proc.stdin.write(JSON.stringify(payload) + "\n");
+    });
+  }
+
+  async ensureInitialized() {
+    if (this.initialized) return;
+    await this.request("initialize", {
+      protocolVersion: DEFAULT_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "jira-grafana-dashboard-mcp-wrapper", version: VERSION },
+    });
+    if (this.proc && this.proc.stdin.writable) {
+      this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }) + "\n");
+    }
+    this.initialized = true;
+  }
+
+  async listTools() {
+    await this.ensureInitialized();
+    if (!this.tools) {
+      const result = await this.request("tools/list", {});
+      this.tools = (result.tools || []).map((tool) => ({
+        ...tool,
+        name: `${this.prefix}_${tool.name}`,
+        description: `[${this.name}] ${tool.description || ""}`,
+      }));
+    }
+    return this.tools;
+  }
+
+  async callTool(prefixedName, args) {
+    await this.ensureInitialized();
+    const rawName = prefixedName.slice(this.prefix.length + 1);
+    return await this.request("tools/call", { name: rawName, arguments: args || {} }, Number(process.env.MCP_CHILD_TOOL_TIMEOUT_MS || 120000));
+  }
+
+  stop() {
+    if (this.proc) this.proc.kill();
+  }
+}
+
+const root = path.resolve(__dirname, "..");
+const children = [
+  new ChildMcpClient({
+    name: "mysql",
+    prefix: "mysql",
+    script: path.join(root, "vendor", "mysql-server.js"),
+  }),
+  new ChildMcpClient({
+    name: "grafana",
+    prefix: "grafana",
+    script: path.join(root, "vendor", "grafana-server.js"),
+  }),
+];
+
+function findChildForTool(name) {
+  return children.find((child) => name && name.startsWith(`${child.prefix}_`));
+}
+
+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") {
+      const lists = await Promise.all(children.map((child) => child.listTools()));
+      return response(id, { tools: lists.flat() });
+    }
+
+    if (method === "tools/call") {
+      const name = params && params.name;
+      const args = (params && params.arguments) || {};
+      const child = findChildForTool(name);
+      if (!child) throw new Error(`Unknown tool: ${name}`);
+      return response(id, await child.callTool(name, args));
+    }
+
+    return errorResponse(id, -32601, `Method not found: ${method}`);
+  } catch (err) {
+    return response(msg && msg.id, {
+      content: [{ type: "text", text: `ERROR: ${err.message}` }],
+      isError: true,
+    });
+  }
+}
+
+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 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)));
+      continue;
+    }
+
+    const nl = buffer.indexOf(Buffer.from("\n"));
+    if (nl === -1) return;
+    const line = buffer.slice(0, nl).toString("utf8").trim();
+    buffer = buffer.slice(nl + 1);
+    if (!line) continue;
+    if (!line.startsWith("{")) continue;
+    handleMessage(JSON.parse(line)).then(writeMessage).catch((err) => writeMessage(errorResponse(null, -32603, err.message)));
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  try { tryParseMessages(); }
+  catch (err) { writeMessage(errorResponse(null, -32700, err.message)); }
+});
+
+process.on("SIGINT", () => { children.forEach((child) => child.stop()); process.exit(0); });
+process.on("SIGTERM", () => { children.forEach((child) => child.stop()); process.exit(0); });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "jira-dash-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for read-only Jira MySQL data analysis and Grafana dashboard automation.",
+  "type": "commonjs",
+  "bin": {
+    "jira-dash-mcp": "bin/jira-grafana-dashboard-mcp.js"
+  },
+  "files": [
+    "bin",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "smoke": "node scripts/smoke-test.js",
+    "prepublishOnly": "node scripts/smoke-test.js && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mysql2": "^3.11.5"
+  },
+  "keywords": [
+    "mcp",
+    "jira",
+    "grafana",
+    "mysql",
+    "claude"
+  ],
+  "license": "MIT"
+}