Add run_evpi tool — first Phase 2 vertical slice (drives MC_EVPI_Auto)

Wires the MCP side of EVPI: run_evpi drives ModelChoice's headless
MC_EVPI_Auto command via Application.Run and reads the MC_EVPI result
sheet, returning the full-tree EVPI, optimal EV, value-with-perfect-
information, and a plain-English interpretation.

bridge.run_evpi activates the workbook, runs the command, and reads the
sheet (clear errors if the add-in isn't loaded or no tree is active).
New EvpiResult schema. Unit-tested with a fake bridge; live verification
needs a ModelChoice build that includes MC_EVPI_Auto (AB#2558, pending
that side shipping). 23 tests; ruff + mypy clean. Bumped to 0.0.2 (not
released — release waits on the ModelChoice command being deployed).

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

Author: vosesoft

README.md

@@ -14,6 +14,7 @@ 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 it: `uv run python -m modelchoice_mcp` (stdio), or wire `modelchoice-mcp` into Claude Desktop like any MCP server.
 
@@ -31,7 +32,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:** drive analyses. ModelChoice's analyses (sensitivity, EVPI, EVII, strategy table, robustness) are currently UI/modal-dialog only; the clean path — since we own the source — is to add headless `[ExcelCommand]` entry points mirroring the existing `MC_RiskProfile_Auto`, then invoke + read them via `Application.Run`.
+- **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 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.1"
+version = "0.0.2"
 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.1"
+__version__ = "0.0.2"

src/modelchoice_mcp/bridge.py

@@ -133,3 +133,44 @@ def read_node_values(self, workbook: str | None = None) -> dict[str, float]:
             if isinstance(val, (int, float)) and not isinstance(val, bool):
                 out[node_id] = float(val)
         return out
+
+    def run_evpi(self, workbook: str | None = None) -> dict[str, Any]:
+        """Drive ModelChoice's headless EVPI command and read its result.
+
+        Activates the workbook, calls ``Application.Run("MC_EVPI_Auto")``
+        — which computes full-tree EVPI for the active tree and writes the
+        ``MC_EVPI`` sheet — then reads that sheet back. Requires the
+        ModelChoice add-in to be loaded in Excel and a tree to be active.
+        Raises ``ModelChoiceNotFoundError`` if the command produced no
+        result sheet (add-in not loaded, or no active tree)."""
+        book = self._book(workbook)
+        try:
+            book.activate()
+        except Exception:
+            pass
+        try:
+            book.app.api.Run("MC_EVPI_Auto")
+        except Exception as exc:
+            raise ModelChoiceNotFoundError(
+                "MC_EVPI_Auto could not run — is the ModelChoice add-in loaded "
+                "in Excel, with a decision tree open?"
+            ) from exc
+        try:
+            sheet = book.sheets["MC_EVPI"]
+        except Exception as exc:
+            raise ModelChoiceNotFoundError(
+                "EVPI ran but wrote no MC_EVPI sheet — check that a tree is the "
+                "active ModelChoice model."
+            ) from exc
+
+        def _num(cell: str) -> float | None:
+            v = sheet.range(cell).value
+            return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
+
+        return {
+            "model_name": sheet.range("C4").value,
+            "objective": sheet.range("C5").value,
+            "optimal_ev": _num("C6"),
+            "evpi": _num("C7"),
+            "value_with_perfect_info": _num("C8"),
+        }

src/modelchoice_mcp/schemas.py

@@ -78,6 +78,25 @@ class NodeDiff(BaseModel):
     diff: float = Field(description="computed - cell.")
 
 
+class EvpiResult(BaseModel):
+    """Expected Value of Perfect Information for the active tree, produced
+    by ModelChoice's headless MC_EVPI_Auto command."""
+
+    model_name: str | None = None
+    objective: str | None = Field(default=None, description="'Maximize' or 'Minimize'.")
+    optimal_ev: float | None = Field(default=None, description="Rolled-back expected value.")
+    evpi: float | None = Field(
+        default=None,
+        description="Full-tree EVPI — the most you'd pay for perfect information.",
+    )
+    value_with_perfect_info: float | None = Field(
+        default=None, description="Optimal EV plus (or minus) the EVPI."
+    )
+    interpretation: str = Field(
+        description="Plain-English reading of the EVPI."
+    )
+
+
 class RollbackVerification(BaseModel):
     """Cross-check of our Python rollback against the EVs ModelChoice
     itself wrote into the MC_V_<nodeId> named ranges."""

src/modelchoice_mcp/tools.py

@@ -14,6 +14,7 @@
 from modelchoice_mcp.bridge import ModelChoiceBridge
 from modelchoice_mcp.schemas import (
     BranchView,
+    EvpiResult,
     NodeDiff,
     NodeResultView,
     NodeView,
@@ -245,11 +246,47 @@ def verify_rollback(
     )
 
 
+@mcp.tool(
+    description=(
+        "ModelChoice: Compute the Expected Value of Perfect Information (EVPI) "
+        "for the active decision tree — the most a decision-maker should pay "
+        "for perfect information about all uncertainties before deciding. "
+        "Drives ModelChoice's headless analysis (MC_EVPI_Auto) and reads the "
+        "result. Requires the ModelChoice add-in loaded in Excel with a tree "
+        "open. EVPI is not defined for MCDA models."
+    )
+)
+def run_evpi(workbook_name: str | None = None) -> EvpiResult:
+    r = get_bridge().run_evpi(workbook_name)
+    evpi = r.get("evpi")
+    if evpi is None:
+        interp = "EVPI could not be read."
+    elif evpi <= 1e-9:
+        interp = (
+            "EVPI is essentially zero — perfect information would not change the "
+            "optimal decision, so don't pay for more information."
+        )
+    else:
+        interp = (
+            f"Perfect information about all uncertainties is worth up to "
+            f"{evpi:,.2f}; that's the ceiling on what to spend gathering it."
+        )
+    return EvpiResult(
+        model_name=r.get("model_name"),
+        objective=r.get("objective"),
+        optimal_ev=r.get("optimal_ev"),
+        evpi=evpi,
+        value_with_perfect_info=r.get("value_with_perfect_info"),
+        interpretation=interp,
+    )
+
+
 __all__ = [
     "get_bridge",
     "get_tree",
     "list_trees",
     "roll_up",
+    "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.1"
+    assert __version__ == "0.0.2"
 
 
 def test_server_name() -> None:

tests/test_tools.py

@@ -10,6 +10,7 @@
 
 from modelchoice_mcp import tools
 from modelchoice_mcp.schemas import (
+    EvpiResult,
     RollbackVerification,
     RollupResponse,
     TreeList,
@@ -46,6 +47,15 @@ def list_trees(self, workbook: str | None = None) -> dict[str, str]:
     def read_node_values(self, workbook: str | None = None) -> dict[str, float]:
         return dict(self._node_values)
 
+    def run_evpi(self, workbook: str | None = None) -> dict[str, object]:
+        return {
+            "model_name": "Oil",
+            "objective": "Maximize",
+            "optimal_ev": 50.0,
+            "evpi": 25.0,
+            "value_with_perfect_info": 75.0,
+        }
+
 
 @pytest.fixture
 def bridge() -> Iterator[_FakeBridge]:
@@ -131,3 +141,11 @@ def test_verify_rollback_not_rendered() -> None:
         assert "not rendered" in out.verdict.lower()
     finally:
         tools.set_bridge_for_testing(None)
+
+
+def test_run_evpi(bridge: _FakeBridge) -> None:
+    out = tools.run_evpi()
+    assert isinstance(out, EvpiResult)
+    assert out.evpi == 25.0 and out.optimal_ev == 50.0
+    assert out.value_with_perfect_info == 75.0
+    assert "25" in out.interpretation