Release v0.3.0-alpha.17: full bug-list sweep

Tackles every still-broken item from the running bug list — the
biggest correctness release since the v0.3 pivot.

Envelope sweep (#1, #2, validates #15)
Every list-returning MCP tool now wraps its response in a dict
envelope `{<noun>, count}` so FastMCP serialises as one structured
payload instead of exploding into N per-element content blocks.
Tools updated: list_open_workbooks, list_modelrisk_inputs,
list_modelrisk_outputs, list_distributions, get_simulation_results,
find_hard_coded_inputs, list_vmrs_variables, read_vmrs,
propose_distributions_for_inputs, discover_inputs. New
test_no_tool_returns_bare_list CI guard prevents regressions.

run_simulation post-condition verification (#20)
The "most important reliability bug" — run_simulation no longer
reports success when ModelRisk's post-simulation phase crashed
silently leaving an unusable .vmrs. The bridge captures expected
VoseOutput names before the sim and verifies at least one resolves
to a var_id in the produced .vmrs afterwards. On failure, raises
SimulationFailedError AND triggers auto-recovery via
restore_deterministic_state.

restore_deterministic_state tool (#21)
New MCP tool that recalculates the workbook to clear VoseOutput
cells stuck on per-iteration sample values. The recovery path
for the frozen-sample state.

MRService activation error message (#8)
Now lists both activation flavours (single-int64 + split-int64),
explains MRSERVICE_DISABLE_BUNDLED_KEY, points at docs URL.

Already fixed (acknowledged from list)
#4 wrap_with_output non-Vose: code already passes
allow_overwrite_non_vose=True.
#5 save_workbook_as: registered as MCP tool since alpha.2.
#6 set_cell_formula: exposed as write_formula since alpha.2.
#7 get_active_workbook OneDrive: graceful fallback already present.
#12 unsaved-workbook path: detected and zeroed out already.

Obsoleted by the v0.3 pivot
#10 use_vba_helper_for_simulation, #11 ensure_modelrisk_active —
both refer to code removed when MRService.dll replaced the VBA
helper approach.

398 tests pass (+5 in test_modelrisk_mocked covering #20 happy
path, #20 failure path, auto-restore on failure, #21 with explicit
workbook, #21 default active). Plus the new envelope CI guard.

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

Author: vosesoft

CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to ModelRisk MCP. Follows [Keep a Changelog](https://keepach
 
 ## [Unreleased]
 
+## [0.3.0-alpha.17] — 2026-05-22
+
+Full sweep against the running bug list — the biggest correctness release since the v0.3 pivot. Tackles every still-broken item: the response-envelope cross-cutting fix (#1, #2, validates #15), `run_simulation` false-positive reliability (#20), and the workbook-recovery tool (#21), plus a CI guard so the envelope category can't regress.
+
+### Fixed
+
+- **Envelope sweep across every list-returning MCP tool (#1, #2, validates #15).** FastMCP serialises a bare `list[T]` return as one MCP content block per element — which makes the LLM see N concatenated objects instead of a single array. Symptoms ranged from "list_modelrisk_outputs returns a single record" (#1) to "list_vmrs_variables returns concatenated JSON objects" (#2) to "get_samples wraps each float in a text-block dict" (#15, fixed in alpha.14). Fixed all of them in one pass by wrapping every list-typed response in a dict envelope with a semantic noun key: `list_open_workbooks` → `{workbooks, count}`, `list_modelrisk_inputs` → `{inputs, count}`, `list_modelrisk_outputs` → `{outputs, count}`, `list_distributions` → `{distributions, count}`, `get_simulation_results` → `{results, count}`, `find_hard_coded_inputs` → `{candidates, count}`, `list_vmrs_variables` → `{variables, count}`, `read_vmrs` → `{results, count}`, `propose_distributions_for_inputs` → `{proposals, count}`, `discover_inputs` → `{candidates, count}`. New CI guard test (`test_no_tool_returns_bare_list`) scans every tool module and fails if any uses `-> list[`, so the next instance of this category gets caught before merge.
+- **`run_simulation` no longer reports false-positive success (#20).** Previously the tool returned `samples: 10000` and a valid `.vmrs` path even when ModelRisk's post-simulation phase crashed silently — leaving the `.vmrs` without registered output metadata and every downstream reader unable to find anything. The "samples" number was just echoing the input parameter, not measuring actual completion. Fix: post-condition verification. Before running, the bridge captures the list of expected VoseOutput names. After the simulation returns, it opens the produced `.vmrs` and confirms at least one expected output resolves to a `var_id`. If none do, raises `SimulationFailedError` with an actionable message ("the simulation's post-sim phase failed to register outputs; run `restore_deterministic_state` to recover").
+- **`restore_deterministic_state` recovery tool (#21).** New MCP tool that recalculates the workbook to clear any VoseOutput cells stuck on per-iteration sample values from a previous run. Triggers `Application.CalculateFull` which re-evaluates every formula. Wired into the auto-recovery path on `run_simulation` post-condition failure — so the workbook is restored even if the user doesn't call the tool explicitly.
+- **MRService.dll activation error message (#8).** The "no key supplied" error now lists both activation flavours (single-int64 via `MRSERVICE_ACTIVATION_KEY`, split-int64 via `MRSERVICE_ACTIVATION_KEY1/2`), explains what `MRSERVICE_DISABLE_BUNDLED_KEY` does, and points at the activation docs URL.
+
+### Already fixed (acknowledged from the running bug list)
+
+- **#4 (`wrap_with_output` refuses non-Vose formulas)** — current code passes `allow_overwrite_non_vose=True` and an existing test covers the Workflow-1-Step-6 pattern. The bug was real in an earlier alpha; the current implementation is correct.
+- **#5 (`save_workbook_as` tool)** — registered as an MCP tool in `tools/building.py` since alpha.2.
+- **#6 (`set_cell_formula` / guarded write)** — exposed as `write_formula` in `tools/building.py` since alpha.2.
+- **#7 (`get_active_workbook` OneDrive)** — fallback path in `excel.py::get_active_workbook` already returns an empty path when xlwings' OneDrive resolution fails.
+- **#12 (unsaved-workbook path)** — `_workbook_info` detects path strings missing any separator (the unsaved-workbook signature) and returns empty path.
+
+### Obsoleted
+
+- **#10 (`use_vba_helper_for_simulation` hangs)** and **#11 (`ensure_modelrisk_active` overfit)** — both refer to code that was removed in the v0.3 MRService.dll pivot. The new architecture doesn't have a VBA helper or an add-in-activation gate; simulations run directly via `Application.Run` on the XLL command surface and `.vmrs` reads go through MRService.
+
+### New tools
+
+- `restore_deterministic_state(workbook_name?)` — workbook recovery from the frozen-sample state.
+
+### Tests
+
+398 unit tests pass (+5: post-condition happy path, post-condition fails when no output registered, auto-restore fires on post-condition failure, restore tool with explicit workbook, restore tool defaults to active). Plus the new envelope CI guard.
+
 ## [0.3.0-alpha.16] — 2026-05-22
 
 Two paired bugs in the report builders, both surfaced by the same end-user testing session — charts came out blank, and the staging data leaked onto the user-visible report sheet. Both `build_executive_report` and `build_drivers_report` are affected because they share the same chart-construction helpers.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelrisk-mcp"
-version = "0.3.0a16"
+version = "0.3.0a17"
 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.0a16",
+  "version": "0.3.0a17",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "modelrisk-mcp",
-      "version": "0.3.0a16",
+      "version": "0.3.0a17",
       "transport": {
         "type": "stdio"
       }

src/modelrisk_mcp/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.0a16"
+__version__ = "0.3.0a17"

src/modelrisk_mcp/bridge/excel.py

@@ -385,6 +385,27 @@ def undo(self) -> None:
         except Exception as exc:
             raise CellReferenceError(f"Excel.Undo() failed: {exc}") from exc
 
+    def recalculate_workbook(self, workbook: str) -> None:
+        """Force a full recalculation of `workbook`.
+
+        Used by `restore_deterministic_state` to recover a workbook
+        left with VoseOutput cells holding the last simulation sample
+        (the "frozen sample" symptom of bug #20). A full recalc
+        re-runs every formula in the book, which re-evaluates each
+        VoseOutput's underlying expression to its deterministic
+        value."""
+        book = self._get_book(workbook)
+        try:
+            # `FullCalculate` rebuilds the dependency tree as well as
+            # recomputing — more thorough than `Calculate`, and the
+            # right tool when ModelRisk may have left dependency
+            # tracking in an odd state.
+            book.api.Application.CalculateFull()
+        except Exception as exc:
+            raise CellReferenceError(
+                f"Excel.CalculateFull() failed on {workbook!r}: {exc}"
+            ) from exc
+
     def save_workbook_as(
         self, workbook: str, path: str, *, overwrite: bool = False,
     ) -> str:

src/modelrisk_mcp/bridge/modelrisk.py

@@ -40,7 +40,7 @@
     SimulationRunResult,
 )
 from modelrisk_mcp.config import Settings
-from modelrisk_mcp.errors import CellReferenceError
+from modelrisk_mcp.errors import CellReferenceError, SimulationFailedError
 from modelrisk_mcp.safety import (
     WriterMutex,
     append_write_log,
@@ -136,6 +136,27 @@ def run_simulation(
         seed: int = 1,
         save_to: str | None = None,
     ) -> SimulationRunResult:
+        # Bug #20 fix: capture the list of VoseOutput names BEFORE the
+        # simulation so we can verify at least one ended up registered
+        # in the .vmrs afterwards. Without this, run_simulation
+        # reports success on simulations where ModelRisk's
+        # post-simulation phase quietly failed — leaving the .vmrs
+        # missing output metadata and every downstream reader unable
+        # to find anything.
+        resolved_workbook = (
+            workbook if workbook else self._excel.get_active_workbook().name
+        )
+        expected_output_names: list[str] = []
+        try:
+            expected_output_names = [
+                o.name for o in self.list_outputs(resolved_workbook)
+            ]
+        except Exception:
+            # Scanner failure shouldn't abort the sim — but we lose
+            # the ability to verify outputs. The .vmrs-existence
+            # check downstream is still in force.
+            pass
+
         result = self._simulation.run_simulation(
             workbook_name=workbook,
             samples=samples,
@@ -144,8 +165,88 @@ def run_simulation(
         )
         # Pin the produced file so the existing reader tools find it.
         self._results.set_active_vmrs(result.vmrs_path)
+
+        # Post-condition verification — see _verify_simulation_post_conditions
+        # for the full criteria. If the .vmrs doesn't contain any of the
+        # expected output names, raise. On raise, attempt to restore the
+        # workbook to deterministic state (bug #21) so the user isn't
+        # left with VoseOutput cells stuck on sample values. The restore
+        # is best-effort; if it fails too, the original SimulationFailed
+        # propagates regardless.
+        if expected_output_names:
+            try:
+                self._verify_simulation_post_conditions(
+                    result.vmrs_path, expected_output_names,
+                )
+            except SimulationFailedError:
+                try:
+                    self._excel.recalculate_workbook(resolved_workbook)
+                except Exception:
+                    pass
+                raise
         return result
 
+    def _verify_simulation_post_conditions(
+        self, vmrs_path: str, expected_output_names: list[str],
+    ) -> None:
+        """Open the produced .vmrs and confirm at least one of the
+        workbook's VoseOutput names resolves to a var_id. That's the
+        cheapest available proof that ModelRisk's post-simulation
+        phase actually wrote output metadata (vs. the bug #20
+        symptom: sim completes, .vmrs is created, but no outputs are
+        registered)."""
+        try:
+            with self._mrservice.open_vmrs(vmrs_path) as handle:
+                for name in expected_output_names:
+                    try:
+                        if handle.lookup_var_id(name) is not None:
+                            return  # post-condition satisfied
+                    except SimulationFailedError:
+                        # lookup_var_id can raise on pathological names;
+                        # one bad name doesn't condemn the whole sim.
+                        continue
+        except SimulationFailedError:
+            raise
+        except Exception as exc:
+            raise SimulationFailedError(
+                f"Simulation completed but the produced .vmrs at "
+                f"{vmrs_path!r} could not be opened for verification: "
+                f"{exc!s}. The file may be incomplete or corrupt."
+            ) from exc
+        raise SimulationFailedError(
+            f"Simulation completed but the produced .vmrs at "
+            f"{vmrs_path!r} does not register any of the expected "
+            f"VoseOutput names: {expected_output_names!r}. This is the "
+            f"signature of ModelRisk's post-simulation phase crashing "
+            f"silently (the sim ran but the output metadata didn't "
+            f"persist). The workbook may also be left with VoseOutput "
+            f"cells stuck on sample values rather than deterministic "
+            f"ones — run `restore_deterministic_state` to recover, then "
+            f"retry the simulation."
+        )
+
+    def restore_deterministic_state(
+        self, workbook: str | None = None,
+    ) -> dict[str, Any]:
+        """Recalculate the workbook to clear any VoseOutput cells that
+        are stuck on sample values from a previous run.
+
+        Recovery path for bug #21: when `run_simulation` fails post-
+        condition (#20), the workbook's VoseOutput cells often retain
+        the final per-iteration sample instead of the deterministic
+        value. Subsequent reads (`list_modelrisk_outputs`,
+        `find_hard_coded_inputs`) would then return misleading
+        `current_value`s. A full recalculation restores the
+        deterministic state by re-evaluating every formula."""
+        resolved_workbook = (
+            workbook if workbook else self._excel.get_active_workbook().name
+        )
+        self._excel.recalculate_workbook(resolved_workbook)
+        return {
+            "workbook_name": resolved_workbook,
+            "recalculated": True,
+        }
+
     # ------------------------------------------------------------------
     # Environment checks
     # ------------------------------------------------------------------
@@ -419,7 +520,6 @@ def build_executive_report(
         stats = self._results.get_simulation_results(wb_path, all_outputs)
         results_by_name = {r.output_name: r for r in stats}
         if primary_output not in results_by_name:
-            from modelrisk_mcp.errors import SimulationFailedError
             raise SimulationFailedError(
                 f"Primary output {primary_output!r} not found in the "
                 "active simulation results. Run a simulation first or "

src/modelrisk_mcp/bridge/mrservice.py

@@ -331,10 +331,20 @@ def _activate(self) -> None:
                 "report this to the modelrisk-mcp maintainers."
             )
         raise SimulationFailedError(
-            "MRService.dll requires activation. Set MRSERVICE_ACTIVATION_KEY "
-            "(a single int64) or both MRSERVICE_ACTIVATION_KEY1 and "
-            "MRSERVICE_ACTIVATION_KEY2 (two int64s). MRSERVICE_DISABLE_"
-            "BUNDLED_KEY is set, so the bundled key was not tried."
+            "MRService.dll requires activation, but no key was supplied.\n\n"
+            "Two activation flavours exist:\n"
+            "  * Single-int64 key — set MRSERVICE_ACTIVATION_KEY to the\n"
+            "    integer Vose issued you. This is the common case.\n"
+            "  * Split-int64 key — set both MRSERVICE_ACTIVATION_KEY1 and\n"
+            "    MRSERVICE_ACTIVATION_KEY2 to the two halves. Used by the\n"
+            "    Ex2 activation API.\n\n"
+            "The bundled key normally covers the default install, but "
+            "MRSERVICE_DISABLE_BUNDLED_KEY=1 is currently set in your "
+            "environment, so it was skipped. Unset that variable to fall "
+            "back to the bundled key, or supply one of the env vars "
+            "above.\n\n"
+            "Docs: "
+            "https://github.com/vosesoftware/modelrisk-mcp/blob/main/docs/activation.md"
         )
 
     # ----- vmrs read API -------------------------------------------------

src/modelrisk_mcp/tools/reading.py

@@ -21,13 +21,9 @@
 from modelrisk_mcp.schemas.results import (
     CorrelationMatrix,
     SensitivityRanking,
-    SimulationResult,
 )
 from modelrisk_mcp.schemas.workbook import (
     CellInfo,
-    DistributionCell,
-    ModelRiskInput,
-    ModelRiskOutput,
     RangeInfo,
     WorkbookInfo,
     WorkbookSummary,
@@ -59,8 +55,13 @@ def set_bridge_for_testing(bridge: ModelRiskBridge | None) -> None:
 
 
 @mcp.tool(description="ModelRisk: List all Excel workbooks currently open.")
-def list_open_workbooks() -> list[WorkbookInfo]:
-    return get_bridge().excel.list_workbooks()
+def list_open_workbooks() -> dict[str, Any]:
+    # Envelope (vs bare `list[WorkbookInfo]`) avoids FastMCP's
+    # list-element expansion which serialises each element as its own
+    # MCP content block — see the module docstring for the full
+    # backstory (alpha.17 sweep).
+    workbooks = get_bridge().excel.list_workbooks()
+    return {"workbooks": workbooks, "count": len(workbooks)}
 
 
 @mcp.tool(description="ModelRisk: Get the name and path of the active workbook.")
@@ -91,8 +92,9 @@ def get_workbook_summary(
 )
 def list_modelrisk_inputs(
     workbook_name: str,
-) -> list[ModelRiskInput]:
-    return get_bridge().list_inputs(workbook_name)
+) -> dict[str, Any]:
+    inputs = get_bridge().list_inputs(workbook_name)
+    return {"inputs": inputs, "count": len(inputs)}
 
 
 @mcp.tool(
@@ -102,8 +104,9 @@ def list_modelrisk_inputs(
 )
 def list_modelrisk_outputs(
     workbook_name: str,
-) -> list[ModelRiskOutput]:
-    return get_bridge().list_outputs(workbook_name)
+) -> dict[str, Any]:
+    outputs = get_bridge().list_outputs(workbook_name)
+    return {"outputs": outputs, "count": len(outputs)}
 
 
 @mcp.tool(
@@ -117,8 +120,9 @@ def list_modelrisk_outputs(
 def list_distributions(
     workbook_name: str,
     sheet: str | None = None,
-) -> list[DistributionCell]:
-    return get_bridge().list_distributions(workbook_name, sheet=sheet)
+) -> dict[str, Any]:
+    distributions = get_bridge().list_distributions(workbook_name, sheet=sheet)
+    return {"distributions": distributions, "count": len(distributions)}
 
 
 @mcp.tool(
@@ -160,8 +164,9 @@ def read_range(
 def get_simulation_results(
     workbook_name: str,
     output_names: list[str] | None = None,
-) -> list[SimulationResult]:
-    return get_bridge().get_simulation_results(workbook_name, output_names)
+) -> dict[str, Any]:
+    results = get_bridge().get_simulation_results(workbook_name, output_names)
+    return {"results": results, "count": len(results)}
 
 
 @mcp.tool(
@@ -204,12 +209,12 @@ def get_sensitivity_ranking(
 )
 def find_hard_coded_inputs(
     workbook_name: str,
-) -> list[dict[str, str]]:
+) -> dict[str, Any]:
     refs = get_bridge().find_hard_coded_inputs(workbook_name)
-    # Return as plain dicts so the MCP JSON serialization is obvious.
-    return [
+    candidates = [
         {"workbook": r.workbook, "sheet": r.sheet, "cell": r.cell} for r in refs
     ]
+    return {"candidates": candidates, "count": len(candidates)}
 
 
 @mcp.tool(
@@ -226,8 +231,9 @@ def list_vmrs_variables(
         str | None,
         Field(description="Workbook name. Omit for the active workbook."),
     ] = None,
-) -> list[dict[str, str | int]]:
-    return get_bridge().list_vmrs_variables(workbook_name)
+) -> dict[str, Any]:
+    variables = get_bridge().list_vmrs_variables(workbook_name)
+    return {"variables": variables, "count": len(variables)}
 
 
 @mcp.tool(
@@ -303,10 +309,11 @@ def read_vmrs(
         str, Field(description="Absolute path to a .vmrs file.")
     ],
     output_names: list[str] | None = None,
-) -> list[SimulationResult]:
+) -> dict[str, Any]:
     reader = get_bridge().results
     reader.set_active_vmrs(path)
-    return reader.get_simulation_results(None, output_names)
+    results = reader.get_simulation_results(None, output_names)
+    return {"results": results, "count": len(results)}
 
 
 __all__ = [