Add generic run_analysis + read_sheet — drive all headless ModelChoice analyses

Discovery: ModelChoice already ships headless MC_*_Auto ExcelCommands for
most analyses (MC_Robustness_Auto, MC_SensitivityAnalysis_Auto,
MC_ExportStrategyTable_Auto, MC_PolicySuggestion_Auto, MC_DecisionBrief_Auto,
MC_McdaReport_Auto, MC_RiskProfile_Auto). The earlier "UI-only" assessment
was stale. So Phase 2 is mostly an MCP-wiring exercise, not C# work — the
one real C# gap was a standalone EVPI command (added: MC_EVPI_Auto).

- run_analysis(analysis): maps a friendly name to the MC_*_Auto command,
  drives it via Application.Run, and reports the result sheets created.
- read_sheet(sheet): reads a result sheet's used range back as rows.
  Together these cover the whole analysis surface without per-sheet parsing.
- bridge.run_analysis / read_sheet; AnalysisRun + SheetData schemas.

Richer per-analysis result parsing (e.g. robustness verdict/distance) and
live verification (needs the add-in loaded with a tree) follow. 27 tests;
ruff + mypy clean. 0.0.3 (not released — waits on MC_EVPI_Auto deploy).

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

Author: vosesoft

README.md

@@ -14,7 +14,9 @@ A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): w
 | `get_tree` | Full structure of one tree — decision / chance / terminal nodes, branches, probabilities, values. |
 | `roll_up` | Roll the tree back to its expected values and **optimal policy** — the decision recommendation, in plain English. |
 | `verify_rollback` | Cross-check our rollback against the `MC_V_<id>` cells ModelChoice itself wrote — a correctness guarantee when the tree has been rendered. |
-| `run_evpi` | Expected Value of Perfect Information for the active tree — the most you'd pay for perfect information before deciding. Drives ModelChoice's headless `MC_EVPI_Auto`. *(Needs a ModelChoice build that includes that command — Phase 2.)* |
+| `run_evpi` | Expected Value of Perfect Information for the active tree — the most you'd pay for perfect information before deciding. Drives ModelChoice's headless `MC_EVPI_Auto`. |
+| `run_analysis` | Run any decision-analysis (`robustness`, `sensitivity`, `strategy_table`, `policy_suggestion`, `decision_brief`, `mcda_report`, `risk_profile`, `evpi`) and report the result sheets it produced. |
+| `read_sheet` | Read a result sheet's cells back (numbers / text), e.g. the robustness verdict or a sensitivity report. |
 
 Run it: `uv run python -m modelchoice_mcp` (stdio), or wire `modelchoice-mcp` into Claude Desktop like any MCP server.
 
@@ -32,7 +34,7 @@ The Python roller is validated against ModelChoice's own authoritative C# test (
 - **Phase 0 (done):** the read + rollback engine — parse `_MC_Store`, reconstruct each tree, roll back to EV + optimal policy. Validated against ModelChoice's own C# rollback test.
 - **Phase 1 (done):** the MCP server — `list_trees`, `get_tree`, `roll_up`, proven live against a real workbook.
 - **Phase 1b (done):** `verify_rollback` cross-checks our EVs against the `MC_V_<id>` named ranges; CI (ruff + mypy + pytest) and a tag-driven PyPI release pipeline; wheel + sdist build. *(First publish awaits a PyPI trusted-publisher; the live `MC_V_` cross-check awaits a real rendered tree.)*
-- **Phase 2 (in progress):** drive analyses. ModelChoice's analyses are UI/modal-dialog only; the clean path — since we own the source — is to add headless `[ExcelCommand]` entry points mirroring `MC_RiskProfile_Auto`, then invoke + read them via `Application.Run`. **EVPI** is the first vertical slice: `MC_EVPI_Auto` (ModelChoice, AB#2558) + the `run_evpi` tool here. Sensitivity, robustness, strategy table, and EVII follow.
+- **Phase 2 (in progress):** drive analyses. ModelChoice already ships headless `MC_*_Auto` ExcelCommands for most analyses (robustness, sensitivity, strategy table, policy, decision brief, MCDA, risk profile); `run_analysis` + `read_sheet` drive and read any of them. EVPI had no standalone command, so `MC_EVPI_Auto` was added (ModelChoice, AB#2558) with the `run_evpi` tool. Live verification + richer per-analysis result parsing are the remaining work.
 - **Phase 3:** build/edit trees — write the model JSON into `_MC_Store` and trigger a re-render.
 
 ## Architecture

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelchoice-mcp"
-version = "0.0.2"
+version = "0.0.3"
 description = "An open Model Context Protocol server for Vose Software's ModelChoice decision-tree add-in for Excel."
 readme = "README.md"
 requires-python = ">=3.11"

src/modelchoice_mcp/__init__.py

@@ -1,4 +1,4 @@
 """ModelChoice MCP — an open Model Context Protocol server for Vose
 Software's ModelChoice decision-tree add-in for Excel."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.3"

src/modelchoice_mcp/bridge.py

@@ -174,3 +174,53 @@ def _num(cell: str) -> float | None:
             "evpi": _num("C7"),
             "value_with_perfect_info": _num("C8"),
         }
+
+    def run_analysis(self, command_name: str, workbook: str | None = None) -> dict[str, Any]:
+        """Drive a ModelChoice headless analysis command (an ``MC_*_Auto``
+        ExcelCommand) via ``Application.Run`` and report which result
+        sheets it produced. Activates the workbook first; raises
+        ``ModelChoiceNotFoundError`` if the command can't run (add-in not
+        loaded, or no active tree)."""
+        book = self._book(workbook)
+        try:
+            book.activate()
+        except Exception:
+            pass
+        before = {s.name for s in book.sheets}
+        try:
+            book.app.api.Run(command_name)
+        except Exception as exc:
+            raise ModelChoiceNotFoundError(
+                f"{command_name} could not run — is the ModelChoice add-in loaded "
+                "in Excel, with a decision tree open?"
+            ) from exc
+        after = [s.name for s in book.sheets]
+        new = [n for n in after if n not in before]
+        return {"command": command_name, "new_sheets": new, "sheets": after}
+
+    def read_sheet(
+        self,
+        sheet_name: str,
+        workbook: str | None = None,
+        max_rows: int = 200,
+        max_cols: int = 20,
+    ) -> list[list[Any]]:
+        """Read a result sheet's used range (capped) as a list of rows."""
+        book = self._book(workbook)
+        try:
+            sheet = book.sheets[sheet_name]
+        except Exception as exc:
+            raise ModelChoiceNotFoundError(
+                f"No sheet named {sheet_name!r} in the workbook."
+            ) from exc
+        used = sheet.used_range
+        nrows = min(int(used.rows.count), max_rows)
+        ncols = min(int(used.columns.count), max_cols)
+        if nrows == 0 or ncols == 0:
+            return []
+        raw = sheet.range((1, 1), (nrows, ncols)).value
+        if not isinstance(raw, list):
+            return [[raw]]
+        if raw and not isinstance(raw[0], list):
+            return [raw] if ncols == 1 else [[v] for v in raw]
+        return [list(row) for row in raw]

src/modelchoice_mcp/schemas.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 from pydantic import BaseModel, Field
 
 
@@ -78,6 +80,27 @@ class NodeDiff(BaseModel):
     diff: float = Field(description="computed - cell.")
 
 
+class AnalysisRun(BaseModel):
+    """Result of driving a ModelChoice headless analysis command."""
+
+    analysis: str = Field(description="Friendly analysis name requested.")
+    command: str = Field(description="The MC_*_Auto ExcelCommand that was run.")
+    new_sheets: list[str] = Field(
+        description="Sheets the analysis created (read them with read_sheet)."
+    )
+    sheets: list[str] = Field(description="All sheets in the workbook afterwards.")
+    note: str
+
+
+class SheetData(BaseModel):
+    """A capped block of a worksheet's used range."""
+
+    sheet: str
+    row_count: int
+    rows: list[list[Any]] = Field(description="Cell values, row-major (numbers, text, or null).")
+    truncated: bool = Field(description="True if the sheet had more rows/cols than returned.")
+
+
 class EvpiResult(BaseModel):
     """Expected Value of Perfect Information for the active tree, produced
     by ModelChoice's headless MC_EVPI_Auto command."""

src/modelchoice_mcp/tools.py

@@ -13,20 +13,34 @@
 
 from modelchoice_mcp.bridge import ModelChoiceBridge
 from modelchoice_mcp.schemas import (
+    AnalysisRun,
     BranchView,
     EvpiResult,
     NodeDiff,
     NodeResultView,
     NodeView,
     RollbackVerification,
     RollupResponse,
+    SheetData,
     TreeList,
     TreeStructure,
     TreeSummary,
 )
 from modelchoice_mcp.server import mcp
 from modelchoice_mcp.tree import DecisionTree, parse_model, rollup
 
+# Friendly analysis name -> ModelChoice headless ExcelCommand.
+_ANALYSES: dict[str, str] = {
+    "risk_profile": "MC_RiskProfile_Auto",
+    "robustness": "MC_Robustness_Auto",
+    "sensitivity": "MC_SensitivityAnalysis_Auto",
+    "strategy_table": "MC_ExportStrategyTable_Auto",
+    "policy_suggestion": "MC_PolicySuggestion_Auto",
+    "decision_brief": "MC_DecisionBrief_Auto",
+    "mcda_report": "MC_McdaReport_Auto",
+    "evpi": "MC_EVPI_Auto",
+}
+
 _bridge: ModelChoiceBridge | None = None
 
 
@@ -281,11 +295,79 @@ def run_evpi(workbook_name: str | None = None) -> EvpiResult:
     )
 
 
+@mcp.tool(
+    description=(
+        "ModelChoice: Run a decision-analysis on the active tree and report the "
+        "result sheets it produced. `analysis` is one of: 'risk_profile', "
+        "'robustness' (how much inputs must change to flip the decision), "
+        "'sensitivity', 'strategy_table', 'policy_suggestion', 'decision_brief', "
+        "'mcda_report', 'evpi'. Drives ModelChoice's headless command and lists "
+        "the new sheets — read them with read_sheet. Requires the ModelChoice "
+        "add-in loaded in Excel with a tree open."
+    )
+)
+def run_analysis(
+    analysis: Annotated[
+        str, Field(description="One of: " + ", ".join(sorted(_ANALYSES)))
+    ],
+    workbook_name: str | None = None,
+) -> AnalysisRun:
+    key = analysis.lower()
+    if key not in _ANALYSES:
+        raise ValueError(
+            f"Unknown analysis {analysis!r}. Choose from: {', '.join(sorted(_ANALYSES))}."
+        )
+    command = _ANALYSES[key]
+    r = get_bridge().run_analysis(command, workbook_name)
+    new = r.get("new_sheets", [])
+    note = (
+        f"{analysis} wrote: {', '.join(new)} — read with read_sheet."
+        if new
+        else f"{analysis} ran but added no new sheet; it may have updated an existing one."
+    )
+    return AnalysisRun(
+        analysis=key,
+        command=command,
+        new_sheets=new,
+        sheets=r.get("sheets", []),
+        note=note,
+    )
+
+
+@mcp.tool(
+    description=(
+        "ModelChoice: Read a worksheet's used range (capped) as rows of cell "
+        "values — for pulling back the result sheet an analysis produced (e.g. "
+        "'MC_EVPI', 'MC_RB_Verdict', a sensitivity report). Returns numbers, "
+        "text, or null per cell."
+    )
+)
+def read_sheet(
+    sheet_name: Annotated[str, Field(description="Worksheet name to read.")],
+    workbook_name: str | None = None,
+    max_rows: Annotated[
+        int, Field(ge=1, le=2000, description="Max rows to return (default 200).")
+    ] = 200,
+    max_cols: Annotated[
+        int, Field(ge=1, le=100, description="Max columns to return (default 20).")
+    ] = 20,
+) -> SheetData:
+    rows = get_bridge().read_sheet(sheet_name, workbook_name, max_rows=max_rows, max_cols=max_cols)
+    return SheetData(
+        sheet=sheet_name,
+        row_count=len(rows),
+        rows=rows,
+        truncated=len(rows) >= max_rows,
+    )
+
+
 __all__ = [
     "get_bridge",
     "get_tree",
     "list_trees",
+    "read_sheet",
     "roll_up",
+    "run_analysis",
     "run_evpi",
     "set_bridge_for_testing",
     "verify_rollback",

tests/test_server.py

@@ -7,7 +7,7 @@
 
 
 def test_version_set() -> None:
-    assert __version__ == "0.0.2"
+    assert __version__ == "0.0.3"
 
 
 def test_server_name() -> None:

tests/test_tools.py

@@ -56,6 +56,18 @@ def run_evpi(self, workbook: str | None = None) -> dict[str, object]:
             "value_with_perfect_info": 75.0,
         }
 
+    def run_analysis(self, command_name: str, workbook: str | None = None) -> dict[str, object]:
+        self.last_command = command_name
+        return {
+            "command": command_name,
+            "new_sheets": ["MC_RB_Verdict"],
+            "sheets": ["MC_Tree_1", "MC_RB_Verdict"],
+        }
+
+    def read_sheet(self, sheet_name: str, workbook: str | None = None,
+                   max_rows: int = 200, max_cols: int = 20) -> list[list[object]]:
+        return [["Verdict", "Robust"], ["Distance", 0.42]]
+
 
 @pytest.fixture
 def bridge() -> Iterator[_FakeBridge]:
@@ -149,3 +161,28 @@ def test_run_evpi(bridge: _FakeBridge) -> None:
     assert out.evpi == 25.0 and out.optimal_ev == 50.0
     assert out.value_with_perfect_info == 75.0
     assert "25" in out.interpretation
+
+
+def test_run_analysis_maps_friendly_name(bridge: _FakeBridge) -> None:
+    out = tools.run_analysis("robustness")
+    assert out.command == "MC_Robustness_Auto"
+    assert out.new_sheets == ["MC_RB_Verdict"]
+    assert "read_sheet" in out.note
+    assert bridge.last_command == "MC_Robustness_Auto"
+
+
+def test_run_analysis_unknown_raises(bridge: _FakeBridge) -> None:
+    with pytest.raises(ValueError):
+        tools.run_analysis("teleport")
+
+
+def test_run_analysis_covers_all_known(bridge: _FakeBridge) -> None:
+    for name in ("risk_profile", "sensitivity", "strategy_table", "evpi"):
+        assert tools.run_analysis(name).command.startswith("MC_")
+
+
+def test_read_sheet(bridge: _FakeBridge) -> None:
+    out = tools.read_sheet("MC_RB_Verdict")
+    assert out.sheet == "MC_RB_Verdict" and out.row_count == 2
+    assert out.rows[1] == ["Distance", 0.42]
+    assert out.truncated is False