Add create_histogram_chart + create_cdf_chart tools (0.3.7)

Two new workflow tools render one output's simulation result
distribution as a native Excel chart on its own sheet — the
ModelRisk Results-Viewer view, persisted (linked) into the workbook:

- create_histogram_chart: frequency columns + cumulative-% overlay on
  a secondary axis, central-80% (P10-P90) band highlighted.
- create_cdf_chart: ascending cumulative-probability curve on its own.

Both read per-iteration samples from the active .vmrs (get_samples),
bin onto round boundaries (_nice_bins), and write a 3-column data
table + chart. New DistributionChartWriter in bridge/charts.py reuses
reports.py's chart builders (_add_histogram_chart + the bug-#18
bind-with-verification workaround) so a standalone chart is identical
to the same chart inside build_executive_report. Idempotent — target
sheet (Histogram_<output> / CDF_<output>) is replaced.

Bridge: create_histogram_chart / create_cdf_chart on ModelRiskBridge.
Tests: 12 new unit tests (mocked xlwings); 606 unit tests green,
ruff + mypy clean. Version bump 0.3.6 -> 0.3.7.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vosesoft

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to ModelRisk MCP. Follows [Keep a Changelog](https://keepach
 
 ## [Unreleased]
 
+## [0.3.7] — 2026-06-18
+
+### Distribution charts: `create_histogram_chart` + `create_cdf_chart`
+
+Two new tools render one output's **simulation result distribution** as a native Excel chart on its own sheet — the ModelRisk Results-Viewer view, persisted into the workbook (linked to the spreadsheet, not a screenshot):
+
+- **`create_histogram_chart`** — frequency columns with the cumulative-probability curve overlaid on a secondary % axis and the central-80% (P10-P90) band highlighted.
+- **`create_cdf_chart`** — the ascending cumulative-probability curve on its own ("what's the chance the output is below X").
+
+Both read the per-iteration samples from the active `.vmrs` (`get_samples`), bin onto round-number boundaries (`_nice_bins`), and write a 3-column data table (bin centre / frequency / cumulative %) plus the chart. They **reuse the executive report's chart builders** (`_add_histogram_chart` + the bug-#18 bind-with-verification workaround), so a standalone chart looks byte-for-byte identical to the same chart inside `build_executive_report`. Idempotent — a sheet with the target name (`Histogram_<output>` / `CDF_<output>`) is replaced, so re-running after a fresh simulation just refreshes it. The response carries the sheet/chart names plus mean and P10/P50/P90.
+
 ## [0.3.6] — 2026-06-16
 
 ### Fix: ModelRisk reported "not loaded" on comma-decimal locales (Russian, German, …)

README.md

@@ -234,7 +234,7 @@ The server can both read *and* modify your workbook — that's the central diffe
 
 ## What's inside
 
-- **50 tools** — 12 reading, 14 building (incl. `create_aggregate` for FFT / Panjer / MC frequency-severity methods), 5 simulation (incl. `run_simulation`, `run_scenarios`, `get_samples`, `restore_cell`, `restore_deterministic_state`), 8 analysis (`compute_distribution`, `fit_and_rank_distributions`, `get_tail_risk`, `fit_tail`, `compute_correlation_matrix`, `compare_distributions`, `backtest_output`, `decompose_uncertainty`), 8 workflow / reporting (incl. `plan_risk_model`, `audit_model`, `diagnose_workbook`, `create_tornado_chart`, `build_drivers_report`, `build_executive_report`, `generate_executive_summary`, `save_workbook_as`), 3 VMRS (`read_vmrs`, `set_active_vmrs`, `list_vmrs_variables`)
+- **52 tools** — 12 reading, 14 building (incl. `create_aggregate` for FFT / Panjer / MC frequency-severity methods), 5 simulation (incl. `run_simulation`, `run_scenarios`, `get_samples`, `restore_cell`, `restore_deterministic_state`), 8 analysis (`compute_distribution`, `fit_and_rank_distributions`, `get_tail_risk`, `fit_tail`, `compute_correlation_matrix`, `compare_distributions`, `backtest_output`, `decompose_uncertainty`), 10 workflow / reporting (incl. `plan_risk_model`, `audit_model`, `diagnose_workbook`, `create_tornado_chart`, `create_histogram_chart`, `create_cdf_chart`, `build_drivers_report`, `build_executive_report`, `generate_executive_summary`, `save_workbook_as`), 3 VMRS (`read_vmrs`, `set_active_vmrs`, `list_vmrs_variables`)
 - **5 resources** — `modelrisk://functions`, `modelrisk://distributions`, `modelrisk://methodology`, `modelrisk://workbook/current`, `modelrisk://audit-rules`
 - **5 slash-command prompts** — `/build-risk-model`, `/audit-model`, `/interpret-results`, `/add-uncertainty`, `/import-legacy-model`
 - **1417-entry function catalogue** extracted directly from the ModelRisk IDL + XLL header

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelrisk-mcp"
-version = "0.3.6"
+version = "0.3.7"
 description = "Open MCP server bridging Anthropic Claude (and any MCP-compatible client) with the ModelRisk Excel add-in."
 readme = "README.md"
 requires-python = ">=3.11"

server.json

@@ -3,12 +3,12 @@
   "name": "io.github.vosesoftware/modelrisk-mcp",
   "title": "ModelRisk",
   "description": "Read, build, fit, and run Monte Carlo risk models in Excel through Vose Software's ModelRisk.",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "modelrisk-mcp",
-      "version": "0.3.6",
+      "version": "0.3.7",
       "transport": {
         "type": "stdio"
       }

src/modelrisk_mcp/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.6"
+__version__ = "0.3.7"

src/modelrisk_mcp/bridge/charts.py

@@ -4,41 +4,72 @@
 - `TornadoChartWriter` — sorted bar chart of input sensitivity for one
   output. The standard Monte Carlo "what moves my output the most"
   visualization.
+- `DistributionChartWriter` — histogram (frequency + cumulative
+  overlay) or ascending-cumulative (CDF) chart of one output's
+  simulation sample distribution. The Results-Viewer "what does my
+  output's distribution look like" visualization, persisted as a native
+  Excel chart on its own sheet.
 
 Architecture:
 - All chart logic stays in this module so `ExcelBridge` doesn't sprawl.
 - The writer takes an opened workbook handle (via xlwings) and the
-  precomputed sensitivity data — it doesn't know anything about
-  MRService.dll or the simulation pipeline.
+  precomputed data — it doesn't know anything about MRService.dll or
+  the simulation pipeline.
 - Chart creation drops to the raw Excel COM API for things xlwings
   doesn't expose directly (axis inversion, point-by-point bar
   colouring). Each COM call is wrapped in best-effort try/except so
   that even if formatting fails, the underlying data table is still
   written and visible.
+- The distribution charts reuse the binning + chart-building helpers in
+  `reports.py` (`_nice_bins`, `_add_histogram_chart`, the
+  bind-with-verification workaround for bug #18) rather than
+  reimplementing the fragile COM, so the standalone tool and the
+  executive report render identical, style-guide-compliant charts.
 
-Future: RiskProfileChartWriter (cumulative + density), HistogramWriter,
-ScenarioComparisonWriter.
+Future: RiskProfileChartWriter (density overlay), ScenarioComparisonWriter.
 """
 
 from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from modelrisk_mcp.bridge.reports import (
+    _COLOR_CHART_LINE,
+    _XL_LINE_STYLE_NONE,
+    _XL_TICK_MARK_NONE,
+    _add_histogram_chart,
+    _axis_scale_format,
+    _bind_chart_to_range,
+    _nice_bins,
+    _percentile,
+    _style_chart_frame,
+    _write_histogram_data,
+)
+
 if TYPE_CHECKING:
     from modelrisk_mcp.schemas.results import SensitivityEntry
 
 
 # Excel chart-type constants. Picked here so the bridge layer can stay
 # numeric-literal-free.
 _XL_BAR_CLUSTERED = 57
+_XL_LINE = 4
+_XL_COLUMNS_PLOT_BY = 2  # SetSourceData PlotBy: series are columns
 
 # Layout — top-left corner of chart in points, plus dimensions.
 _CHART_LEFT = 300
 _CHART_TOP = 10
 _CHART_WIDTH = 480
 _CHART_HEIGHT = 360
 
+# Layout for the distribution charts (each on its own sheet). The 3-col
+# data table sits in A:C (~150pt); the chart starts past it.
+_DIST_CHART_LEFT = 230
+_DIST_CHART_TOP = 10
+_DIST_CHART_WIDTH = 560
+_DIST_CHART_HEIGHT = 360
+
 
 @dataclass(frozen=True)
 class TornadoChartResult:
@@ -201,4 +232,242 @@ def _default_sheet_name(output_name: str) -> str:
     return base[:31]
 
 
-__all__ = ["TornadoChartResult", "TornadoChartWriter"]
+# ---------------------------------------------------------------------------
+# Distribution charts — histogram + cumulative (the Results-Viewer view)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DistributionChartResult:
+    """What was created for a distribution chart. Returned to the MCP
+    layer so the response can carry the headline percentiles alongside
+    the sheet/chart identifiers."""
+
+    sheet_name: str
+    chart_name: str
+    output_name: str
+    chart_kind: str  # "histogram" | "cdf"
+    sample_count: int
+    bin_count: int
+    mean: float
+    p10: float
+    p50: float
+    p90: float
+
+
+class DistributionChartWriter:
+    """Renders one output's simulation-sample distribution as a native
+    Excel chart on its own sheet.
+
+    Two kinds:
+    - ``histogram`` — frequency columns with the cumulative-probability
+      line overlaid on a secondary % axis and the central-80% (P10-P90)
+      band highlighted. This is the full Results-Viewer histogram.
+    - ``cdf`` — the ascending cumulative-probability curve on its own
+      (the "what's the chance the output is below X" view).
+
+    The sheet holds a 3-column data table (bin centre / frequency /
+    cumulative %) plus the chart. Idempotent: a target sheet of the same
+    name is replaced, so the tool is re-runnable as the model evolves.
+
+    The binning and chart COM are reused from ``reports.py`` so the
+    output is byte-for-byte the same style the executive report uses."""
+
+    @staticmethod
+    def write(
+        book: Any,
+        output_name: str,
+        samples: list[float],
+        *,
+        chart_kind: str = "histogram",
+        sheet_name: str | None = None,
+    ) -> DistributionChartResult:
+        kind = chart_kind.lower().strip()
+        if kind not in ("histogram", "cdf"):
+            raise ValueError(
+                f"chart_kind must be 'histogram' or 'cdf', got {chart_kind!r}"
+            )
+
+        target_sheet = sheet_name or _distribution_sheet_name(output_name, kind)
+        DistributionChartWriter._remove_existing_sheet(book, target_sheet)
+        sheet = book.sheets.add(target_sheet, after=book.sheets[-1])
+
+        bins = _nice_bins(samples)
+        # Reuse the report's 3-column writer; the data table lives on the
+        # visible chart sheet itself (A1:C) so the numbers travel with the
+        # chart. The chart is placed past column C so they don't overlap.
+        _write_histogram_data(sheet, bins, anchor_col="A", anchor_row=1)
+        DistributionChartWriter._style_data_table(sheet, bins.n)
+
+        p10 = _percentile(samples, 0.10)
+        p50 = _percentile(samples, 0.50)
+        p90 = _percentile(samples, 0.90)
+        mean = sum(samples) / len(samples) if samples else 0.0
+
+        chart_name = ""
+        if bins.n:
+            if kind == "histogram":
+                title = f"Histogram — {output_name}"
+                ok = _add_histogram_chart(
+                    sheet, helper=sheet, helper_anchor_col="A", bins=bins,
+                    p10=p10, p90=p90, title=title,
+                    left=_DIST_CHART_LEFT, top=_DIST_CHART_TOP,
+                    width=_DIST_CHART_WIDTH, height=_DIST_CHART_HEIGHT,
+                )
+                if ok:
+                    chart_name = DistributionChartWriter._last_chart_name(sheet)
+            else:
+                title = f"Cumulative probability — {output_name}"
+                chart_name = _add_cdf_chart(
+                    sheet, helper=sheet, helper_anchor_col="A", bins=bins,
+                    title=title,
+                    left=_DIST_CHART_LEFT, top=_DIST_CHART_TOP,
+                    width=_DIST_CHART_WIDTH, height=_DIST_CHART_HEIGHT,
+                )
+
+        return DistributionChartResult(
+            sheet_name=target_sheet,
+            chart_name=chart_name,
+            output_name=output_name,
+            chart_kind=kind,
+            sample_count=len(samples),
+            bin_count=bins.n,
+            mean=mean,
+            p10=p10,
+            p50=p50,
+            p90=p90,
+        )
+
+    # ----- internal -------------------------------------------------------
+
+    @staticmethod
+    def _remove_existing_sheet(book: Any, name: str) -> None:
+        for sheet in list(book.sheets):
+            if sheet.name == name:
+                try:
+                    sheet.delete()
+                except Exception:
+                    pass
+                return
+
+    @staticmethod
+    def _style_data_table(sheet: Any, n: int) -> None:
+        try:
+            sheet.range("A1:C1").api.Font.Bold = True
+        except Exception:
+            pass
+        if n:
+            try:
+                sheet.range(f"C2:C{n + 1}").api.NumberFormat = "0.0%"
+            except Exception:
+                pass
+
+    @staticmethod
+    def _last_chart_name(sheet: Any) -> str:
+        """`_add_histogram_chart` names the chart itself but returns an
+        int flag, not the name. Read the most-recently-added chart's
+        name back off the sheet for the response."""
+        try:
+            charts = list(sheet.charts)
+            if charts:
+                return str(charts[-1].name)
+        except Exception:
+            pass
+        return ""
+
+
+def _add_cdf_chart(
+    sheet: Any,
+    *,
+    helper: Any,
+    helper_anchor_col: str,
+    bins: Any,
+    title: str,
+    left: int, top: int, width: int, height: int,
+) -> str:
+    """Add an ascending-cumulative (CDF) line chart on `sheet`, bound to
+    the cumulative-% column of the 3-column block at
+    `helper_anchor_col`. Returns the chart name on success, "" if the
+    chart couldn't be created or the COM bind failed.
+
+    Layout assumption mirrors `_write_histogram_data`: col[0] = bin
+    centres, col[1] = counts, col[2] = cumulative %, header at row 1.
+    Binds the cumulative column as the single series, then assigns the
+    bin centres as its X (category) values so the curve reads against
+    round-number output values, not the 1..N row index."""
+    if bins.n == 0:
+        return ""
+    try:
+        chart = sheet.charts.add(left=left, top=top, width=width, height=height)
+    except Exception:
+        return ""
+    bin_col = helper_anchor_col
+    cum_col = chr(ord(helper_anchor_col) + 2)
+    data_range = helper.range(f"{cum_col}1:{cum_col}{1 + bins.n}")
+    try:
+        chart_api = chart.api[1] if isinstance(chart.api, tuple) else chart.api
+        chart_api.ChartType = _XL_LINE
+    except Exception:
+        pass
+    bound = _bind_chart_to_range(chart, data_range, plot_by=_XL_COLUMNS_PLOT_BY)
+    if not bound:
+        return ""
+    x_range = helper.range(f"{bin_col}2:{bin_col}{1 + bins.n}")
+    try:
+        chart_api = chart.api[1] if isinstance(chart.api, tuple) else chart.api
+        chart_api.HasTitle = True
+        chart_api.ChartTitle.Text = title
+        try:
+            series = chart_api.SeriesCollection(1)
+            series.XValues = x_range.api
+            series.Format.Line.ForeColor.RGB = _COLOR_CHART_LINE
+            series.Format.Line.Weight = 2.25
+            try:
+                series.MarkerStyle = _XL_LINE_STYLE_NONE
+            except Exception:
+                pass
+        except Exception:
+            pass
+        _style_chart_frame(chart_api)
+        # X axis: round-number labels, thinned, no tick marks.
+        try:
+            xa = chart_api.Axes(1)
+            xa.TickLabels.NumberFormat = _axis_scale_format(bins.centres)
+            xa.TickLabels.Font.Size = 9
+            xa.TickLabelSpacing = bins.label_every
+            try:
+                xa.TickMarkSpacing = bins.label_every
+            except Exception:
+                pass
+            xa.MajorTickMark = _XL_TICK_MARK_NONE
+            xa.MinorTickMark = _XL_TICK_MARK_NONE
+        except Exception:
+            pass
+        # Y axis: cumulative probability, hard-capped 0..100%.
+        try:
+            ya = chart_api.Axes(2)
+            ya.MinimumScale = 0
+            ya.MaximumScale = 1.0
+            ya.MajorUnit = 0.2
+            ya.TickLabels.NumberFormat = "0%"
+            ya.TickLabels.Font.Size = 9
+        except Exception:
+            pass
+        chart.name = f"CDF_{title[:20]}"[:31]
+    except Exception:
+        pass
+    return str(chart.name)
+
+
+def _distribution_sheet_name(output_name: str, kind: str) -> str:
+    """Excel limits sheet names to 31 chars; truncate as needed."""
+    prefix = "Histogram_" if kind == "histogram" else "CDF_"
+    return f"{prefix}{output_name}"[:31]
+
+
+__all__ = [
+    "DistributionChartResult",
+    "DistributionChartWriter",
+    "TornadoChartResult",
+    "TornadoChartWriter",
+]