Add open_workbook tool (0.0.26) — open a tree workbook from disk

Mirrors the new modelrisk-mcp open_workbook. open_workbook(path) opens an
.xlsx in the running Excel via the bridge (Workbooks.Open, behind the
GetActiveObject hardening), then reports the workbook's sheets and any
ModelChoice tree sheets in its _MC_Store — so you can tell at a glance whether
it's a decision-tree workbook. Reuses an already-open book of the same name;
raises for a missing file / open failure / no running Excel.

- bridge.open_workbook; schemas.OpenWorkbookResult; tools.open_workbook (+__all__).
- test_tools: fake-bridge open_workbook + a tool test. README/CHANGELOG; 23 tools.

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

Author: vosesoft

CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to `modelchoice-mcp`. Versions are tag-driven; pushing a
 `vX.Y.Z` tag publishes to PyPI via the release workflow.
 
+## 0.0.26
+- **`open_workbook`** — open a decision-tree workbook (.xlsx) from disk in the
+  running Excel so the other tools can act on it. Reports the workbook's sheets
+  and any ModelChoice tree sheets it contains; reuses an already-open workbook
+  of the same name. (Mirrors the new `open_workbook` in modelrisk-mcp.)
+
 ## 0.0.25
 - **`build_mcda` gains AHP weight elicitation (AB#2646)** — set
   `weight_source="ahp"` and pass an `ahp_matrix` (Saaty 1-9 pairwise comparisons,

README.md

@@ -4,7 +4,7 @@
 
 A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): where that server brings Monte Carlo risk modelling into a conversation, this one brings **decision analysis** — building, reading, rolling back, and analysing decision trees in Excel.
 
-> **Status: `0.0.25` — Phase 3 (build + drive).** 22 tools: build_tree / build_mcda / edit_tree (incl. add/remove options & outcomes) / set_input_distribution (put a Vose distribution on an input) / build_control_panel / export_tree_json / import_tree_json / import_precisiontree, read + roll + verify, run_scenarios (what-if comparison), plus run_evpi / run_evii / run_risk_profile / run_robustness / run_sensitivity / run_decision_report (strategy/policy/brief/mcda/force-to-outcome/two-way) / run_analysis / read_sheet over ModelChoice's headless commands.
+> **Status: `0.0.26` — Phase 3 (build + drive).** 23 tools: build_tree / build_mcda / edit_tree (incl. add/remove options & outcomes) / set_input_distribution (put a Vose distribution on an input) / build_control_panel / export_tree_json / import_tree_json / import_precisiontree, read + roll + verify, run_scenarios (what-if comparison), plus run_evpi / run_evii / run_risk_profile / run_robustness / run_sensitivity / run_decision_report (strategy/policy/brief/mcda/force-to-outcome/two-way) / run_analysis / read_sheet over ModelChoice's headless commands.
 
 ## Tools
 
@@ -17,6 +17,7 @@ A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): w
 | `build_control_panel` | **Lift the tree's inputs into a control panel** at the top of the sheet — every probability and cash flow as a labelled cell, with the tree linked back to it, so you drive the whole model from one input block. Drives `MC_BuildControlPanel_Auto`. |
 | `export_tree_json` / `import_tree_json` | Round-trip a tree's raw ModelChoice JSON — export to save/share/version, import (validated) to write it back into a workbook. |
 | `import_precisiontree` | Import a PrecisionTree workbook (.xls/.xlsx) into ModelChoice — converts a copy (original untouched). Drives `MC_ImportPrecisionTree_Auto`. |
+| `open_workbook` | **Open a workbook (.xlsx) from disk** in the running Excel so the other tools can act on it. Reports its sheets + any ModelChoice tree sheets; reuses an already-open workbook of the same name. |
 | `list_trees` | List the decision trees in a workbook with node-type counts. |
 | `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. |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelchoice-mcp"
-version = "0.0.25"
+version = "0.0.26"
 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.25"
+__version__ = "0.0.26"

src/modelchoice_mcp/bridge.py

@@ -13,6 +13,7 @@
 from __future__ import annotations
 
 import json
+import os
 from typing import Any, ClassVar
 
 from modelchoice_mcp.store import STORE_SHEET_NAME, parse_store, reassemble_chunks
@@ -59,6 +60,49 @@ def _book(self, workbook: str | None) -> Any:
                 return b
         raise ModelChoiceNotFoundError(f"Workbook {workbook!r} is not open.")
 
+    def open_workbook(self, path: str) -> dict[str, Any]:
+        """Open a workbook from disk in the running Excel and report its
+        sheets + any ModelChoice trees it contains. If a workbook with the
+        same file name is already open, that one is used (Excel won't open two
+        with the same name). Raises if Excel isn't running, the file is
+        missing, or Excel can't open it."""
+        xw = self._load_xw()
+        app = xw.apps.active
+        if app is None:
+            raise ExcelNotRunningError(
+                "No running Excel instance found. Open Excel (with the ModelChoice "
+                "add-in) first, then open the workbook."
+            )
+        self._harden_attach(app)
+        if not os.path.isfile(path):
+            raise ModelChoiceNotFoundError(f"File not found: {path!r}.")
+        name = os.path.basename(path)
+        book = None
+        for b in app.books:
+            try:
+                if str(b.name).lower() == name.lower():
+                    book = b
+                    break
+            except Exception:
+                continue
+        if book is None:
+            try:
+                book = app.books.open(path)
+            except Exception as exc:
+                raise ModelChoiceNotFoundError(f"Excel could not open {path!r}: {exc}") from exc
+        wb_name = str(book.name)
+        try:
+            sheets = [s.name for s in book.sheets]
+        except Exception:
+            sheets = []
+        # ModelChoice tree sheets, if this is a ModelChoice workbook.
+        try:
+            raw = self.read_store_raw(wb_name)
+            trees = list(parse_store(raw)) if raw else []
+        except Exception:
+            trees = []
+        return {"workbook": wb_name, "sheets": sheets, "trees": trees}
+
     @staticmethod
     def _harden_attach(app: Any) -> None:
         """Make the COM attach robust against a loaded ModelChoice add-in.

src/modelchoice_mcp/schemas.py

@@ -303,6 +303,17 @@ class InputDistributionResult(BaseModel):
     note: str
 
 
+class OpenWorkbookResult(BaseModel):
+    """Outcome of opening a workbook from disk in the running Excel."""
+
+    workbook: str = Field(description="The opened workbook's file name (now active).")
+    sheets: list[str] = Field(description="Worksheet names in the workbook.")
+    trees: list[str] = Field(
+        description="ModelChoice tree sheets found in the workbook (empty if none)."
+    )
+    note: str
+
+
 class TreeExport(BaseModel):
     """A tree's stored ModelChoice model JSON, for saving or sharing."""
 

src/modelchoice_mcp/tools.py

@@ -31,6 +31,7 @@
     NodeDiff,
     NodeResultView,
     NodeView,
+    OpenWorkbookResult,
     RiskProfileReport,
     RiskProfileSeries,
     RobustnessSummary,
@@ -536,6 +537,36 @@ def _counts(tree: DecisionTree) -> tuple[int, int, int]:
     return d, c, t
 
 
+@mcp.tool(
+    description=(
+        "ModelChoice: Open a workbook (.xlsx) from disk in the running Excel so "
+        "the other tools can act on it. Pass an absolute file path. Reports the "
+        "workbook's sheets and any ModelChoice tree sheets it contains (so you "
+        "can tell at a glance whether it's a decision-tree workbook). If a "
+        "workbook with the same file name is already open, that one is used. "
+        "Requires Excel running (with the ModelChoice add-in for rendering)."
+    )
+)
+def open_workbook(
+    path: Annotated[
+        str,
+        Field(description="Absolute path to the workbook, e.g. r'C:\\models\\oil.xlsx'."),
+    ],
+) -> OpenWorkbookResult:
+    r = get_bridge().open_workbook(path)
+    trees = r.get("trees", [])
+    wb = r.get("workbook", "")
+    note = (
+        f"Opened {wb!r} with {len(trees)} ModelChoice tree(s): {', '.join(trees)}."
+        if trees
+        else f"Opened {wb!r} — no ModelChoice trees found (it's not a ModelChoice workbook, "
+        "or the tree store is absent)."
+    )
+    return OpenWorkbookResult(
+        workbook=wb, sheets=r.get("sheets", []), trees=trees, note=note
+    )
+
+
 @mcp.tool(
     description=(
         "ModelChoice: List the decision trees stored in a workbook, with a "
@@ -1591,6 +1622,7 @@ def read_sheet(
     "import_precisiontree",
     "import_tree_json",
     "list_trees",
+    "open_workbook",
     "read_sheet",
     "roll_up",
     "run_analysis",

tests/test_server.py

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

tests/test_tools.py

@@ -141,6 +141,14 @@ def set_input_formula(self, named_range: str, formula: str,
         self.input_formula = (named_range, formula)
         return sheet_name or "MC_Tree_1"
 
+    def open_workbook(self, path: str) -> dict[str, object]:
+        self.opened_path = path
+        return {
+            "workbook": "oil.xlsx",
+            "sheets": ["MC_Tree_1", "_MC_Store"],
+            "trees": ["MC_Tree_1"],
+        }
+
     def write_tree(self, model_json: str, sheet_name: str | None = None,
                    workbook: str | None = None) -> str:
         self.written_json = model_json
@@ -282,6 +290,17 @@ def test_build_control_panel_parses_inputs(bridge: _FakeBridge) -> None:
     assert "persist across re-renders" in out.note
 
 
+def test_open_workbook(bridge: _FakeBridge) -> None:
+    from modelchoice_mcp.schemas import OpenWorkbookResult
+
+    out = tools.open_workbook(r"C:\models\oil.xlsx")
+    assert isinstance(out, OpenWorkbookResult)
+    assert bridge.opened_path == r"C:\models\oil.xlsx"
+    assert out.workbook == "oil.xlsx"
+    assert out.trees == ["MC_Tree_1"]
+    assert "MC_Tree_1" in out.note
+
+
 def test_set_input_distribution_value(bridge: _FakeBridge) -> None:
     from modelchoice_mcp.schemas import InputDistributionResult