graphein-mcp 0.18.0 → 0.20.0

package/README.md

@@ -36,13 +36,66 @@ npm install -g graphein-mcp   # then: graphein-mcp
 | Tool | What it does |
 | --- | --- |
 | **`render_chart`** | The one-call loop. Validates a `ChartSpec`, auto-repairs safe mistakes, renders a PNG, and returns the **image** plus a **vision-free critique** (render report + lint warnings + repairs applied). If the spec can't be made valid, returns structured errors with JSON-Patch fixes instead of an image. |
+| **`critique_chart`** | Same validation/rendering policy, but report-only: no image block. |
+| **`recommend_chart`** | Profile tidy rows (or CSV/TSV) and return ranked specs with rationale and unresolved data decisions. |
+| **`list_chart_types`** | Every registered chart/slicer family with purpose, requirements, capabilities, and a runnable starter. Dashboards compose these visuals. |
 | **`validate_chart`** | Validate without rendering. Returns structural errors (each with a JSON-Patch `fix` when unambiguous, plus "did you mean" suggestions) and best-practice lint warnings. |
 | **`repair_chart`** | Apply every safe, unambiguous fix and return the corrected spec, the patch ops applied, and whether it's now valid. |
 | **`summarize_chart`** | Deterministic, plain-English description of what the data shows (doubles as alt-text; no LLM). |
 
-`render_chart` accepts `spec` plus optional `width`, `height`, `dpr`, and `repair`
-(default `true`). Every type rasterizes — kpi, table, matrix, slicers and dashboard render
+`render_chart` and `critique_chart` accept `spec` plus optional `width`, `height`,
+`dpr`, `repair` (default `true`), `repairLevel` (`'safe'` default; `'data'` explicitly
+permits data-aware authoring inference), and `quality`. Every type rasterizes — kpi, table, matrix, slicers and dashboard render
 a static canvas snapshot, so the whole catalog returns an image + report.
+`width`/`height` are limited to 1–8192 CSS pixels, `dpr` to 0.25–4, and the
+rasterized canvas to 67,108,864 pixels; invalid sizes return a structured tool
+error instead of allocating an unsafe canvas.
+CSV/TSV parsing keeps a column as strings unless every value converts losslessly,
+so leading-zero identifiers stay identifiers. Bundled resources are served only
+from the package's committed resource set.
+
+### Opt-in presentation improvement
+
+The default remains **one render**. Set `"quality":true` (or
+`"quality":{"maxPasses":3}`) to reuse core's bounded controller:
+
+- At most **three total whole-visual render attempts**, including initial and
+  restoration passes. Never per diagnostic or dashboard child.
+- Only absent, eligible presentation defaults can change. Explicit settings,
+  palettes/domains, encodings, and data are protected; semantic decisions stay with
+  the caller. `repair` / `repairLevel` remain separate authoring policies.
+- Every candidate validates; no progress, regressions, repeated actions, or failures
+  stop the loop. Mutable targets reserve a rollback pass, so `maxPasses:1` or `2`
+  only evaluate the initial render.
+- Opted-in results include **`effectiveSpec`** and **`quality`**
+  (`renderPasses`, `selectedPass`, `iterations`, `applied`, `rejected`, `stopReason`).
+  The PNG and full `report` match that selected spec. Remaining warnings and
+  incomplete evidence are not hidden.
+- **`authoring`** includes the core input-row `profile` and selected-family
+  `capabilities` when available. Dashboard `authoring.views` identifies own-data profiles and
+  shared-data inheritance. This is supplied-input evidence before transforms,
+  filters, or selection effects, distinct from the final report's effective-row/draw
+  evidence. Differing counts or invalid-value findings are expected after explicit
+  preparation; profiling does not execute that pipeline or invent an encoding.
+
+Rendering/critique responses expose the same JSON in the text block and MCP
+`structuredContent`; existing top-level counts/diagnostics on image results remain
+available. Invalid specs return structured validation errors and
+`quality.stopReason:'invalid-spec'` with zero render passes, not an image.
+
+### Data-driven authoring
+
+`recommend_chart` preserves its `recommendations` array and adds the shared core
+`profile`, `findings`, and `status` (`ready`, `needs-decision`, `no-candidate`).
+Candidates include evidence and alternatives; a valid candidate may still require
+a choice about duplicate positions, dates/identifiers, missing data, aggregation, or
+geometry. Optional `targetSize:{width,height}` guides recommendations without
+filtering/grouping rows. `list_chart_types` exposes each family's field roles,
+requirements, cardinality guidance, supported features, and actual aggregation
+semantics. Neither tool rewrites data to make a recommendation appear successful.
+Validation/rendering/critique warning payloads preserve exact per-field
+`evidence` counts and `requiresDecision`, so data-quality decisions are not lost
+when the core findings are sent through MCP.
 
 ### Example result