graphein-mcp 0.16.2 → 0.18.0

package/dist/chunk-5LAUAUAW.js

@@ -0,0 +1,646 @@
+// src/tabular.ts
+var TabularParseError = class extends Error {
+  /** Create a parse error with a human-readable message. */
+  constructor(message) {
+    super(message);
+    this.name = "TabularParseError";
+  }
+};
+function detectDelimiter(text2) {
+  let comma = 0;
+  let tab = 0;
+  let quoted = false;
+  for (let i = 0; i < text2.length; i++) {
+    const ch = text2[i];
+    if (ch === '"') {
+      if (quoted && text2[i + 1] === '"') {
+        i++;
+      } else {
+        quoted = !quoted;
+      }
+    } else if (!quoted && (ch === "\n" || ch === "\r")) {
+      break;
+    } else if (!quoted && ch === ",") {
+      comma++;
+    } else if (!quoted && ch === "	") {
+      tab++;
+    }
+  }
+  return tab > comma ? "	" : ",";
+}
+function coerce(value) {
+  const trimmed = value.trim();
+  if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(trimmed)) {
+    const n = Number(trimmed);
+    if (Number.isFinite(n)) return n;
+  }
+  return value;
+}
+function parseRecords(text2, delimiter) {
+  const records = [];
+  let record = [];
+  let value = "";
+  let quoted = false;
+  let afterQuote = false;
+  const pushCell = () => {
+    record.push({ value });
+    value = "";
+    afterQuote = false;
+  };
+  const pushRecord = () => {
+    pushCell();
+    records.push(record);
+    record = [];
+  };
+  for (let i = 0; i < text2.length; i++) {
+    const ch = text2[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (text2[i + 1] === '"') {
+          value += '"';
+          i++;
+        } else {
+          quoted = false;
+          afterQuote = true;
+        }
+      } else {
+        value += ch;
+      }
+      continue;
+    }
+    if (afterQuote && ch !== delimiter && ch !== "\n" && ch !== "\r") {
+      if (/\s/.test(ch)) continue;
+      throw new TabularParseError(`Unexpected character '${ch}' after closing quote.`);
+    }
+    if (ch === '"') {
+      if (value.length > 0) throw new TabularParseError("Unexpected quote in an unquoted field.");
+      quoted = true;
+    } else if (ch === delimiter) {
+      pushCell();
+    } else if (ch === "\n") {
+      pushRecord();
+    } else if (ch === "\r") {
+      pushRecord();
+      if (text2[i + 1] === "\n") i++;
+    } else {
+      value += ch;
+    }
+  }
+  if (quoted) throw new TabularParseError("Unclosed quoted field.");
+  if (value.length > 0 || record.length > 0 || text2.endsWith(String(delimiter))) pushRecord();
+  return records.filter((r) => r.some((cell) => cell.value.length > 0));
+}
+function parseTabularText(text2) {
+  const trimmed = text2.replace(/^\uFEFF/, "");
+  const delimiter = detectDelimiter(trimmed);
+  const records = parseRecords(trimmed, delimiter);
+  if (records.length === 0) return [];
+  const headers = records[0].map((cell) => cell.value.trim());
+  if (headers.some((h) => h.length === 0)) {
+    throw new TabularParseError("CSV/TSV header row must not contain empty column names.");
+  }
+  if (new Set(headers).size !== headers.length) {
+    throw new TabularParseError("CSV/TSV header row must not contain duplicate column names.");
+  }
+  return records.slice(1).map((record, rowIndex) => {
+    if (record.length !== headers.length) {
+      throw new TabularParseError(
+        `Row ${rowIndex + 2} has ${record.length} cells, expected ${headers.length}.`
+      );
+    }
+    const row = {};
+    for (let i = 0; i < headers.length; i++) row[headers[i]] = coerce(record[i].value);
+    return row;
+  });
+}
+function parseInlineData(value) {
+  if (Array.isArray(value)) return value.map(parseInlineData);
+  if (typeof value !== "object" || value === null) return value;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    out[key] = key === "data" && typeof child === "string" ? parseTabularText(child) : parseInlineData(child);
+  }
+  return out;
+}
+
+// src/handlers.ts
+import {
+  validateSpec,
+  repairSpec,
+  recommendChart,
+  listChartTypes,
+  summarize
+} from "graphein";
+import { renderChart } from "@graphein/node";
+function text(value) {
+  return { type: "text", text: value };
+}
+function json(value) {
+  return text(JSON.stringify(value, null, 2));
+}
+function specType(spec) {
+  return typeof spec === "object" && spec !== null && "type" in spec ? String(spec.type) : "(missing)";
+}
+function isRecommendIntent(value) {
+  return value === void 0 || value === "trend" || value === "comparison" || value === "distribution" || value === "relationship" || value === "composition";
+}
+function parseErrorResult(e) {
+  return {
+    isError: true,
+    content: [
+      json({
+        ok: false,
+        stage: "parse-data",
+        message: e instanceof Error ? e.message : String(e)
+      })
+    ]
+  };
+}
+function specWithParsedData(spec) {
+  return parseInlineData(spec);
+}
+function rowsWithParsedData(data) {
+  return typeof data === "string" ? parseTabularText(data) : data;
+}
+function tidyError(e) {
+  const out = { path: e.path, message: e.message };
+  if (e.rule) out.rule = e.rule;
+  if (e.severity) out.severity = e.severity;
+  if (e.fix) out.fix = e.fix;
+  if (e.suggestion) out.suggestion = e.suggestion;
+  return out;
+}
+function renderChartHandler(args) {
+  const { spec, width, height, dpr, repair = true } = args;
+  let working;
+  try {
+    working = specWithParsedData(spec);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  let validation = validateSpec(working);
+  let repairs = [];
+  if (!validation.valid && repair) {
+    const repaired = repairSpec(working);
+    if (repaired.applied.length > 0) {
+      working = repaired.spec;
+      repairs = repaired.applied;
+      validation = validateSpec(working);
+    }
+  }
+  if (!validation.valid) {
+    return {
+      isError: true,
+      content: [
+        json({
+          ok: false,
+          rendered: false,
+          stage: "validate",
+          type: specType(working),
+          errors: validation.errors.map(tidyError),
+          lint: validation.warnings.map(tidyError),
+          repairsApplied: repairs,
+          hint: "Apply each error.fix JSON Patch (or the repair_chart tool), then call render_chart again. See the graphein://agent-guide and graphein://schema resources."
+        })
+      ]
+    };
+  }
+  const type = specType(working);
+  try {
+    const { png, report, width: pxW, height: pxH } = renderChart(working, {
+      width,
+      height,
+      dpr
+    });
+    return {
+      isError: false,
+      content: [
+        { type: "image", data: png.toString("base64"), mimeType: "image/png" },
+        json({
+          ok: report.ok,
+          rendered: true,
+          type,
+          pixelSize: { width: pxW, height: pxH },
+          summary: report.summary,
+          marks: report.markCount,
+          series: report.seriesCount,
+          colors: report.colorCount,
+          diagnostics: report.diagnostics,
+          lint: validation.warnings.map(tidyError),
+          repairsApplied: repairs
+        })
+      ]
+    };
+  } catch (e) {
+    return {
+      isError: true,
+      content: [
+        json({
+          ok: false,
+          rendered: false,
+          stage: "render",
+          type,
+          message: e instanceof Error ? e.message : String(e),
+          summary: summarize(working) || void 0,
+          repairsApplied: repairs
+        })
+      ]
+    };
+  }
+}
+function critiqueChartHandler(args) {
+  const { spec, width, height, dpr, repair = true } = args;
+  let working;
+  try {
+    working = specWithParsedData(spec);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  let validation = validateSpec(working);
+  let repairs = [];
+  if (!validation.valid && repair) {
+    const repaired = repairSpec(working);
+    if (repaired.applied.length > 0) {
+      working = repaired.spec;
+      repairs = repaired.applied;
+      validation = validateSpec(working);
+    }
+  }
+  if (!validation.valid) {
+    return {
+      isError: true,
+      content: [
+        json({
+          ok: false,
+          rendered: false,
+          stage: "validate",
+          type: specType(working),
+          errors: validation.errors.map(tidyError),
+          lint: validation.warnings.map(tidyError),
+          repairsApplied: repairs,
+          hint: "Apply each error.fix JSON Patch (or the repair_chart tool), then call critique_chart again."
+        })
+      ]
+    };
+  }
+  const type = specType(working);
+  try {
+    const { report, width: pxW, height: pxH } = renderChart(working, { width, height, dpr });
+    return {
+      isError: false,
+      content: [
+        json({
+          ok: report.ok,
+          rendered: true,
+          type,
+          pixelSize: { width: pxW, height: pxH },
+          summary: report.summary,
+          report,
+          lint: validation.warnings.map(tidyError),
+          repairsApplied: repairs
+        })
+      ]
+    };
+  } catch (e) {
+    return {
+      isError: true,
+      content: [
+        json({
+          ok: false,
+          rendered: false,
+          stage: "render",
+          type,
+          message: e instanceof Error ? e.message : String(e),
+          summary: summarize(working) || void 0,
+          repairsApplied: repairs
+        })
+      ]
+    };
+  }
+}
+function validateChartHandler(args) {
+  let spec;
+  try {
+    spec = specWithParsedData(args.spec);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  const result = validateSpec(spec);
+  return {
+    isError: false,
+    content: [
+      json({
+        valid: result.valid,
+        type: specType(spec),
+        errors: result.errors.map(tidyError),
+        warnings: result.warnings.map(tidyError)
+      })
+    ]
+  };
+}
+function recommendChartHandler(args) {
+  if (!isRecommendIntent(args.intent)) {
+    return {
+      isError: true,
+      content: [
+        json({
+          ok: false,
+          message: "Unsupported intent. Expected trend, comparison, distribution, relationship, or composition."
+        })
+      ]
+    };
+  }
+  let data;
+  try {
+    data = rowsWithParsedData(args.data);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  return {
+    isError: false,
+    content: [
+      json({
+        ok: true,
+        recommendations: recommendChart(data, { intent: args.intent, maxResults: args.maxResults })
+      })
+    ]
+  };
+}
+function listChartTypesHandler() {
+  return {
+    isError: false,
+    content: [
+      json({
+        ok: true,
+        chartTypes: listChartTypes()
+      })
+    ]
+  };
+}
+function repairChartHandler(args) {
+  let input;
+  try {
+    input = specWithParsedData(args.spec);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  const { spec, applied, appliedDetails, remaining } = repairSpec(input, { level: args.level ?? "safe" });
+  return {
+    isError: false,
+    content: [
+      json({
+        valid: remaining.length === 0,
+        level: args.level ?? "safe",
+        applied,
+        appliedDetails,
+        remaining: remaining.map(tidyError),
+        spec
+      })
+    ]
+  };
+}
+function summarizeChartHandler(args) {
+  let spec;
+  try {
+    spec = specWithParsedData(args.spec);
+  } catch (e) {
+    return parseErrorResult(e);
+  }
+  const result = validateSpec(spec);
+  if (!result.valid) {
+    return {
+      isError: true,
+      content: [
+        json({
+          summary: null,
+          reason: "Spec is invalid; fix it first (validate_chart / repair_chart).",
+          errors: result.errors.map(tidyError)
+        })
+      ]
+    };
+  }
+  const summary = summarize(spec);
+  return {
+    isError: false,
+    content: [
+      text(summary || `(No narrative summary is available for a '${specType(args.spec)}' chart.)`)
+    ]
+  };
+}
+
+// src/resources.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+var RESOURCES = [
+  {
+    name: "schema",
+    uri: "graphein://schema",
+    title: "Graphein ChartSpec JSON Schema",
+    description: "The machine-readable JSON Schema for every Graphein ChartSpec and DashboardSpec field \u2014 chart types, channels, transforms, annotations, and required properties. Generate or check a spec against this.",
+    mimeType: "application/json",
+    file: "chart-spec.schema.json"
+  },
+  {
+    name: "agent-guide",
+    uri: "graphein://agent-guide",
+    title: "Graphein Agent Guide",
+    description: "A task-oriented guide for producing correct Graphein charts: the one-rule workflow, choosing a chart type, encodings, transforms, the validate \u2192 repair \u2192 render \u2192 critique loop, and worked recipes. Read this first.",
+    mimeType: "text/markdown",
+    file: "agent-guide.md"
+  },
+  {
+    name: "spec-reference",
+    uri: "graphein://spec-reference",
+    title: "Graphein Spec Reference",
+    description: "The exhaustive field-by-field reference for every chart type, channel, transform, annotation, and modifier. Consult this for the precise shape of a specific field.",
+    mimeType: "text/markdown",
+    file: "spec-reference.md"
+  }
+];
+var cache = /* @__PURE__ */ new Map();
+function readResourceFile(file) {
+  const hit = cache.get(file);
+  if (hit !== void 0) return hit;
+  const url = new URL(`../resources/${file}`, import.meta.url);
+  const text2 = readFileSync(fileURLToPath(url), "utf8");
+  cache.set(file, text2);
+  return text2;
+}
+function resourceByUri(uri) {
+  return RESOURCES.find((r) => r.uri === uri);
+}
+
+// src/create-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var VERSION = "0.3.0";
+var SERVER_INSTRUCTIONS = `Graphein is an agent-first data-visualization library: you describe a chart as one JSON ChartSpec ({ type, data, encoding, ... }) and it renders. This server lets you build correct charts without prior knowledge of the API.
+
+Workflow:
+1. Call list_chart_types to see every supported chart type with required channels and starter specs; read graphein://agent-guide (and graphein://schema for exact fields) only when you need deeper detail.
+2. Shape data as tidy rows \u2014 one row per observation, one column per variable. Tools that accept rows also accept CSV/TSV text with a header row.
+3. Use recommend_chart when you want ranked specs from data, or start from a list_chart_types starter.
+4. Emit a ChartSpec and call critique_chart for report-only diagnostics, or render_chart when you need the PNG plus critique. Both validate, auto-repair safe mistakes, render headlessly, and return lint/report feedback.
+5. If a spec is invalid, validate_chart, critique_chart, and render_chart return structured errors with JSON-Patch fixes. Apply them or call repair_chart; use repair_chart level "data" to infer missing encodings or close field-name typos from the spec's own data.
+Use summarize_chart for deterministic alt-text. Every type rasterizes headlessly, including kpi, table, matrix, slicers and dashboard (static canvas snapshots).`;
+var specSchema = z.record(z.string(), z.unknown()).describe(
+  'A Graphein ChartSpec or DashboardSpec object, e.g. { "type": "line", "data": [...], "encoding": {...} }. Any data property may be tidy rows or CSV/TSV text with a header row. See the graphein://schema and graphein://agent-guide resources.'
+);
+var dataRowsSchema = z.union([
+  z.array(z.record(z.string(), z.any())),
+  z.string().describe("CSV or TSV text with a header row; quoted delimiters, quotes, and newlines are supported.")
+]);
+var intentSchema = z.enum(["trend", "comparison", "distribution", "relationship", "composition"]).optional().describe(
+  "Optional analytical intent used to rank recommendations: trend, comparison, distribution, relationship, or composition."
+);
+function createServer() {
+  const server = new McpServer(
+    { name: "graphein-mcp", version: VERSION },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+  server.registerTool(
+    "render_chart",
+    {
+      title: "Render a Graphein chart",
+      description: "The one-call loop: validate a ChartSpec, auto-repair safe mistakes, render it to a PNG, and return the image plus a vision-free critique (render report, lint warnings, repairs applied). If the spec cannot be made valid, returns structured errors with JSON-Patch fixes instead of an image. Every type rasterizes headlessly \u2014 kpi, table, matrix, slicers and dashboard render static canvas snapshots.",
+      inputSchema: {
+        spec: specSchema,
+        width: z.number().int().positive().optional().describe("Logical width in CSS px (default 800)."),
+        height: z.number().int().positive().optional().describe("Logical height in CSS px (default 500)."),
+        dpr: z.number().positive().optional().describe("Device pixel ratio for crisp output (default 2)."),
+        repair: z.boolean().optional().describe("Auto-apply safe repairs before rendering when the spec is invalid (default true).")
+      }
+    },
+    async (args) => renderChartHandler(args)
+  );
+  server.registerTool(
+    "critique_chart",
+    {
+      title: "Critique a Graphein chart without an image",
+      description: "Validate a ChartSpec, auto-repair safe mistakes, render it headlessly, and return only the RenderReport, deterministic summary, lint warnings, and repairs applied \u2014 no base64 PNG. Use this when you need diagnostics but not an image.",
+      inputSchema: {
+        spec: specSchema,
+        width: z.number().int().positive().optional().describe("Logical width in CSS px (default 800)."),
+        height: z.number().int().positive().optional().describe("Logical height in CSS px (default 500)."),
+        dpr: z.number().positive().optional().describe("Device pixel ratio for layout parity (default 2)."),
+        repair: z.boolean().optional().describe("Auto-apply safe repairs before rendering when the spec is invalid (default true).")
+      }
+    },
+    async (args) => critiqueChartHandler(args)
+  );
+  server.registerTool(
+    "validate_chart",
+    {
+      title: "Validate a Graphein chart spec",
+      description: 'Validate a ChartSpec without rendering. Returns structural errors (each with a JSON-Patch `fix` when unambiguous, plus "did you mean" suggestions) and best-practice lint warnings. Fast feedback before rendering.',
+      inputSchema: { spec: specSchema }
+    },
+    async (args) => validateChartHandler(args)
+  );
+  server.registerTool(
+    "recommend_chart",
+    {
+      title: "Recommend Graphein chart specs",
+      description: "Profile tidy rows and return ranked, ready-to-render ChartSpecs with rationale. Use this before guessing a chart type or encoding.",
+      inputSchema: {
+        data: dataRowsSchema,
+        intent: intentSchema,
+        maxResults: z.number().int().positive().optional()
+      }
+    },
+    async (args) => recommendChartHandler(args)
+  );
+  server.registerTool(
+    "repair_chart",
+    {
+      title: "Repair a Graphein chart spec",
+      description: `Apply Graphein repairs and return the corrected spec, JSON Patch ops, per-patch rationales, and whether it is now valid. The default safe level applies validator-provided fixes; level "data" may infer missing encodings and field-name typo fixes from the spec's own data.`,
+      inputSchema: {
+        spec: specSchema,
+        level: z.enum(["safe", "data"]).optional().describe('Repair aggressiveness. "safe" is default; "data" also infers from the spec data.')
+      }
+    },
+    async (args) => repairChartHandler(args)
+  );
+  server.registerTool(
+    "list_chart_types",
+    {
+      title: "List Graphein chart types",
+      description: "Return every supported chart type with its purpose, required channels/properties, and a minimal runnable starter spec. Use this before reading the full schema when you just need to know what chart families exist.",
+      inputSchema: {}
+    },
+    async () => listChartTypesHandler()
+  );
+  server.registerTool(
+    "summarize_chart",
+    {
+      title: "Summarize a Graphein chart",
+      description: `Return a deterministic, plain-English description of what the chart's data shows (e.g. "Users grew 46% over six months, peaking in June"). Doubles as alt-text; needs no LLM.`,
+      inputSchema: { spec: specSchema }
+    },
+    async (args) => summarizeChartHandler(args)
+  );
+  for (const r of RESOURCES) {
+    server.registerResource(
+      r.name,
+      r.uri,
+      { title: r.title, description: r.description, mimeType: r.mimeType },
+      async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: r.mimeType, text: readResourceFile(r.file) }]
+      })
+    );
+  }
+  server.registerPrompt(
+    "create_chart",
+    {
+      title: "Create a Graphein chart",
+      description: "Scaffold the workflow for building a validated Graphein chart from a goal (and optional data).",
+      argsSchema: {
+        goal: z.string().describe('What the chart should show, e.g. "monthly active users over the last year".'),
+        data: z.string().optional().describe("Optional: the data as a JSON array, or a description of the columns available.")
+      }
+    },
+    ({ goal, data }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Build a Graphein chart for this goal:
+
+${goal}
+${data ? `
+Data:
+${data}
+` : ""}
+Steps:
+1. Call list_chart_types for available chart families and starter specs; read graphein://agent-guide or graphein://schema only for deeper details.
+2. Shape the data as tidy rows \u2014 one row per observation, one column per variable. CSV/TSV text with a header row is accepted anywhere data rows are accepted.
+3. Choose a chart type (or call recommend_chart) and write a single ChartSpec ({ type, data, encoding, title }).
+4. Call critique_chart for report-only feedback or render_chart when you need the PNG too. Read the returned render report + lint to confirm it looks right.
+5. If it reports errors, apply each error.fix patch (or call repair_chart, using level "data" when field/encoding inference from data is useful) and render again \u2014 do not regenerate from scratch.`
+          }
+        }
+      ]
+    })
+  );
+  return server;
+}
+
+export {
+  TabularParseError,
+  parseTabularText,
+  parseInlineData,
+  renderChartHandler,
+  critiqueChartHandler,
+  validateChartHandler,
+  listChartTypesHandler,
+  repairChartHandler,
+  summarizeChartHandler,
+  RESOURCES,
+  readResourceFile,
+  resourceByUri,
+  VERSION,
+  createServer
+};
+//# sourceMappingURL=chunk-5LAUAUAW.js.map