modelchoice-mcp 0.0.1__py3-none-any.whl

modelchoice_mcp/__init__.py

@@ -0,0 +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"

modelchoice_mcp/__main__.py

@@ -0,0 +1,40 @@
+"""ModelChoice MCP server entrypoint.
+
+    python -m modelchoice_mcp                              # stdio (default)
+    python -m modelchoice_mcp --transport=streamable-http  # HTTP, 127.0.0.1:8000
+    python -m modelchoice_mcp --transport=sse --port=9000
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Literal, cast
+
+from modelchoice_mcp.server import mcp
+
+Transport = Literal["stdio", "streamable-http", "sse"]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="modelchoice-mcp")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http", "sse"],
+        default="stdio",
+        help="MCP transport (default: stdio).",
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+
+    transport = cast(Transport, args.transport)
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+        mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    main()

modelchoice_mcp/bridge.py

@@ -0,0 +1,135 @@
+"""Excel bridge for ModelChoice — read decision trees from a workbook.
+
+Phase 0 is read-only. ModelChoice exposes no COM object model, but the
+full tree model is persisted as JSON in the very-hidden ``_MC_Store``
+worksheet (see :mod:`modelchoice_mcp.store`). We read that sheet's row-1
+content (chunked across columns) via xlwings, parse each tree, and roll
+it back in pure Python — so the add-in need not even be loaded.
+
+The bridge deliberately does NOT unhide or modify ``_MC_Store``; it
+reads cell values only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modelchoice_mcp.store import STORE_SHEET_NAME, parse_store, reassemble_chunks
+from modelchoice_mcp.tree import DecisionTree, RollupResult, parse_model, rollup
+
+
+class ModelChoiceNotFoundError(RuntimeError):
+    """The workbook contains no ModelChoice tree store (`_MC_Store`)."""
+
+
+class ExcelNotRunningError(RuntimeError):
+    """No running Excel instance could be attached."""
+
+
+class ModelChoiceBridge:
+    """Attach to a running Excel and read ModelChoice trees from a
+    workbook's very-hidden ``_MC_Store`` sheet."""
+
+    def __init__(self) -> None:
+        self._xw: Any = None
+
+    def _load_xw(self) -> Any:
+        if self._xw is None:
+            import xlwings  # imported lazily so the package is importable without Excel
+
+            self._xw = xlwings
+        return self._xw
+
+    def _book(self, workbook: str | None) -> Any:
+        xw = self._load_xw()
+        app = xw.apps.active
+        if app is None:
+            raise ExcelNotRunningError(
+                "No running Excel instance found. Open the workbook in Excel first."
+            )
+        if workbook is None:
+            return app.books.active
+        for b in app.books:
+            if b.name == workbook:
+                return b
+        raise ModelChoiceNotFoundError(f"Workbook {workbook!r} is not open.")
+
+    def read_store_raw(self, workbook: str | None = None) -> str:
+        """Return the reassembled ``_MC_Store`` A1 payload, or '' if the
+        sheet is absent."""
+        book = self._book(workbook)
+        try:
+            sheet = book.sheets[STORE_SHEET_NAME]
+        except Exception:
+            return ""
+        # Read row 1 across enough columns to cover the chunk limit.
+        row = sheet.range((1, 1), (1, 100)).value
+        if not isinstance(row, list):
+            row = [row]
+        cells = [None if v is None else str(v) for v in row]
+        return reassemble_chunks(cells)
+
+    def list_trees(self, workbook: str | None = None) -> dict[str, str]:
+        """Return a mapping of tree-sheet-name → model JSON string."""
+        raw = self.read_store_raw(workbook)
+        if not raw:
+            raise ModelChoiceNotFoundError(
+                "Workbook has no ModelChoice tree store (_MC_Store sheet)."
+            )
+        return parse_store(raw)
+
+    def get_tree(self, sheet_name: str | None = None, workbook: str | None = None) -> DecisionTree:
+        """Parse one tree (by its sheet name, or the first/only tree)."""
+        trees = self.list_trees(workbook)
+        if not trees:
+            raise ModelChoiceNotFoundError("No trees stored in this workbook.")
+        if sheet_name is None:
+            sheet_name = next(iter(trees))
+        if sheet_name not in trees:
+            raise ModelChoiceNotFoundError(
+                f"Tree {sheet_name!r} not found. Available: {', '.join(trees)}."
+            )
+        return parse_model(trees[sheet_name])
+
+    def roll_up(self, sheet_name: str | None = None, workbook: str | None = None) -> RollupResult:
+        """Read a tree and return its rolled-back EV + optimal policy."""
+        return rollup(self.get_tree(sheet_name, workbook))
+
+    def read_node_values(self, workbook: str | None = None) -> dict[str, float]:
+        """Read the rolled-back expected values ModelChoice itself wrote
+        into the ``MC_V_<nodeId>`` named ranges on the rendered tree
+        sheet(s). Returns ``{nodeId: value}``. These are the add-in's own
+        rollback numbers — comparing them to our Python rollback proves
+        the two agree. Returns an empty dict if the tree hasn't been
+        rendered (named ranges only exist after a render)."""
+        book = self._book(workbook)
+        prefix = "MC_V_"
+        out: dict[str, float] = {}
+
+        name_objs: list[Any] = []
+        try:
+            name_objs.extend(list(book.names))
+        except Exception:
+            pass
+        for sht in book.sheets:
+            try:
+                name_objs.extend(list(sht.names))
+            except Exception:
+                pass
+
+        for nm in name_objs:
+            try:
+                full = str(nm.name)  # may be "MC_V_D" or "Sheet!MC_V_D"
+            except Exception:
+                continue
+            idx = full.find(prefix)
+            if idx < 0:
+                continue
+            node_id = full[idx + len(prefix):]
+            try:
+                val = nm.refers_to_range.value
+            except Exception:
+                continue
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                out[node_id] = float(val)
+        return out

modelchoice_mcp/schemas.py

@@ -0,0 +1,95 @@
+"""Pydantic response schemas for the MCP tools."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class BranchView(BaseModel):
+    name: str
+    child_id: str
+    value: float = Field(description="Branch/option value added along the path.")
+    probability: float | None = Field(
+        default=None, description="Probability (chance branches only; null for decision options)."
+    )
+
+
+class NodeView(BaseModel):
+    id: str
+    name: str
+    kind: str = Field(description="'decision', 'chance', or 'terminal'.")
+    value: float = Field(default=0.0, description="Terminal node's own value (0 otherwise).")
+    branches: list[BranchView] = Field(default_factory=list)
+
+
+class TreeSummary(BaseModel):
+    name: str = Field(description="Tree sheet name (e.g. 'MC_Tree_1').")
+    model_name: str
+    root_id: str
+    root_name: str
+    node_count: int
+    decision_count: int
+    chance_count: int
+    terminal_count: int
+
+
+class TreeList(BaseModel):
+    workbook: str | None = None
+    count: int
+    trees: list[TreeSummary]
+
+
+class TreeStructure(BaseModel):
+    name: str
+    model_name: str
+    root_id: str
+    maximize: bool = Field(description="True = the tree maximizes EV; False = minimizes.")
+    node_count: int
+    nodes: list[NodeView]
+
+
+class NodeResultView(BaseModel):
+    id: str
+    name: str
+    kind: str
+    expected_value: float
+    optimal_branch_name: str | None = Field(
+        default=None, description="At a decision node, the option chosen by rollback."
+    )
+
+
+class RollupResponse(BaseModel):
+    name: str
+    model_name: str
+    maximize: bool
+    expected_value: float = Field(description="Rolled-back expected value at the root.")
+    optimal_path: list[str] = Field(
+        description="The decisions taken under the optimal policy, from the root."
+    )
+    recommendation: str = Field(description="Plain-English decision recommendation.")
+    nodes: list[NodeResultView]
+
+
+class NodeDiff(BaseModel):
+    node_id: str
+    name: str
+    computed: float = Field(description="Our Python rollback EV for this node.")
+    cell: float = Field(description="The MC_V_<nodeId> value ModelChoice wrote.")
+    diff: float = Field(description="computed - cell.")
+
+
+class RollbackVerification(BaseModel):
+    """Cross-check of our Python rollback against the EVs ModelChoice
+    itself wrote into the MC_V_<nodeId> named ranges."""
+
+    name: str
+    rendered: bool = Field(
+        description="True if the tree has MC_V_ cells (i.e. it has been rendered by the add-in)."
+    )
+    compared_count: int = Field(description="Nodes present in both our rollback and the cells.")
+    matches: int
+    max_abs_diff: float = Field(description="Largest |computed - cell| across compared nodes.")
+    mismatches: list[NodeDiff] = Field(
+        default_factory=list, description="Nodes whose values differ beyond the tolerance."
+    )
+    verdict: str

modelchoice_mcp/server.py

@@ -0,0 +1,29 @@
+"""FastMCP server entrypoint.
+
+Constructs the ``mcp`` instance and triggers tool registration by
+importing ``modelchoice_mcp.tools`` (the tools attach via the
+``@mcp.tool`` decorator side-effect). Read-only in Phase 0/1.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from modelchoice_mcp import __version__
+
+mcp = FastMCP(
+    name="modelchoice-mcp",
+    instructions=(
+        "ModelChoice MCP exposes Vose Software's ModelChoice decision-tree "
+        "add-in for Excel. It reads decision trees stored in a workbook and "
+        "rolls them back to expected values and the optimal policy — the "
+        "decision recommendation — without needing the add-in loaded. Use "
+        "list_trees to discover trees, get_tree for structure, and roll_up "
+        "for the recommendation."
+    ),
+)
+
+# Side-effect import registers every @mcp.tool. Must come after `mcp`.
+from modelchoice_mcp import tools  # noqa: E402, F401
+
+__all__ = ["__version__", "mcp"]

modelchoice_mcp/store.py

@@ -0,0 +1,69 @@
+"""Read ModelChoice's per-workbook tree storage.
+
+ModelChoice persists every decision tree as JSON in a *very hidden*
+worksheet named ``_MC_Store`` (see ``TreeJsonStore.cs`` in the add-in).
+The payload lives in row 1, chunked across columns A1, B1, C1, … when it
+exceeds Excel's ~32k-character cell limit. The reassembled string is a
+v2 envelope::
+
+    {"_v": 2, "trees": {"<sheetName>": "<model-json-string>", ...}}
+
+where each *value* is itself a JSON string (the serialized
+``DecisionTreeModel``). A v1 legacy form stored the raw model JSON
+directly (detected by a top-level ``RootId``), keyed as ``MC_TreeView``.
+
+This module is pure: it turns the raw cell string(s) into a mapping of
+sheet-name → model-JSON-string. The Excel/COM reading lives in the
+bridge so this stays unit-testable without Excel.
+"""
+
+from __future__ import annotations
+
+import json
+
+STORE_SHEET_NAME = "_MC_Store"
+_LEGACY_TREE_KEY = "MC_TreeView"
+
+
+def parse_store(raw: str) -> dict[str, str]:
+    """Parse the reassembled ``_MC_Store`` A1 payload into a mapping of
+    sheet name → model JSON string. Mirrors ``TreeJsonStore.ParseStorageFormat``.
+
+    Returns an empty dict for empty input.
+    """
+    if not raw or not raw.strip():
+        return {}
+
+    try:
+        root = json.loads(raw)
+    except json.JSONDecodeError:
+        # Not valid JSON at all — treat the whole thing as a single v1 model.
+        return {_LEGACY_TREE_KEY: raw}
+
+    if isinstance(root, dict):
+        # v2 envelope: {"_v": >=2, "trees": {...}}
+        v = root.get("_v")
+        trees = root.get("trees")
+        if isinstance(v, int) and v >= 2 and isinstance(trees, dict):
+            return {
+                k: (val if isinstance(val, str) else json.dumps(val))
+                for k, val in trees.items()
+            }
+
+        # v1: raw model JSON (has a RootId / rootId but no envelope).
+        if "RootId" in root or "rootId" in root:
+            return {_LEGACY_TREE_KEY: raw}
+
+    # Fallback: opaque content, treat as a single model.
+    return {_LEGACY_TREE_KEY: raw}
+
+
+def reassemble_chunks(cells: list[str | None]) -> str:
+    """Reassemble the chunked A1, B1, C1, … payload. Stops at the first
+    empty cell. Mirrors ``TreeJsonStore.ReadChunkedContent``."""
+    parts: list[str] = []
+    for c in cells:
+        if c is None or c == "":
+            break
+        parts.append(c)
+    return "".join(parts)

modelchoice_mcp/tools.py

@@ -0,0 +1,255 @@
+"""MCP tools (Phase 1, read-only) over the ModelChoice bridge.
+
+Each tool obtains a process-global :class:`ModelChoiceBridge` via
+``get_bridge()`` (lazy — the first call attaches to Excel). Tests inject
+a fake with ``set_bridge_for_testing`` to avoid touching COM.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+from modelchoice_mcp.bridge import ModelChoiceBridge
+from modelchoice_mcp.schemas import (
+    BranchView,
+    NodeDiff,
+    NodeResultView,
+    NodeView,
+    RollbackVerification,
+    RollupResponse,
+    TreeList,
+    TreeStructure,
+    TreeSummary,
+)
+from modelchoice_mcp.server import mcp
+from modelchoice_mcp.tree import DecisionTree, parse_model, rollup
+
+_bridge: ModelChoiceBridge | None = None
+
+
+def get_bridge() -> ModelChoiceBridge:
+    global _bridge
+    if _bridge is None:
+        _bridge = ModelChoiceBridge()
+    return _bridge
+
+
+def set_bridge_for_testing(bridge: ModelChoiceBridge | None) -> None:
+    global _bridge
+    _bridge = bridge
+
+
+def _counts(tree: DecisionTree) -> tuple[int, int, int]:
+    d = sum(1 for n in tree.nodes.values() if n.kind == "decision")
+    c = sum(1 for n in tree.nodes.values() if n.kind == "chance")
+    t = sum(1 for n in tree.nodes.values() if n.kind == "terminal")
+    return d, c, t
+
+
+@mcp.tool(
+    description=(
+        "ModelChoice: List the decision trees stored in a workbook, with a "
+        "summary of each (model name, root node, and node-type counts). Trees "
+        "live in the workbook's hidden ModelChoice store; the add-in does not "
+        "need to be loaded. Omit workbook_name for the active workbook."
+    )
+)
+def list_trees(workbook_name: str | None = None) -> TreeList:
+    trees = get_bridge().list_trees(workbook_name)
+    summaries: list[TreeSummary] = []
+    for name, model_json in trees.items():
+        t = parse_model(model_json)
+        d, c, term = _counts(t)
+        root = t.nodes[t.root_id]
+        summaries.append(
+            TreeSummary(
+                name=name,
+                model_name=t.model_name,
+                root_id=t.root_id,
+                root_name=root.name,
+                node_count=len(t.nodes),
+                decision_count=d,
+                chance_count=c,
+                terminal_count=term,
+            )
+        )
+    return TreeList(workbook=workbook_name, count=len(summaries), trees=summaries)
+
+
+@mcp.tool(
+    description=(
+        "ModelChoice: Read the full structure of one decision tree — every "
+        "node (decision / chance / terminal) with its branches, probabilities, "
+        "and branch values. Pass tree_name to pick a specific tree, else the "
+        "first/active one. Read-only."
+    )
+)
+def get_tree(
+    tree_name: Annotated[
+        str | None, Field(description="Tree sheet name, e.g. 'MC_Tree_1'. Omit for the first tree.")
+    ] = None,
+    workbook_name: str | None = None,
+) -> TreeStructure:
+    bridge = get_bridge()
+    trees = bridge.list_trees(workbook_name)
+    if tree_name is None:
+        tree_name = next(iter(trees))
+    t = parse_model(trees[tree_name])
+    nodes = [
+        NodeView(
+            id=n.id,
+            name=n.name,
+            kind=n.kind,
+            value=n.value,
+            branches=[
+                BranchView(
+                    name=b.name, child_id=b.child_id, value=b.value, probability=b.probability
+                )
+                for b in n.branches
+            ],
+        )
+        for n in t.nodes.values()
+    ]
+    return TreeStructure(
+        name=tree_name,
+        model_name=t.model_name,
+        root_id=t.root_id,
+        maximize=t.maximize,
+        node_count=len(t.nodes),
+        nodes=nodes,
+    )
+
+
+@mcp.tool(
+    description=(
+        "ModelChoice: Roll a decision tree back to its expected values and "
+        "OPTIMAL POLICY — the decision recommendation. Returns the root "
+        "expected value, the optimal sequence of decisions, a plain-English "
+        "recommendation, and the per-node expected values. Computed directly "
+        "from the stored model (terminal payoff = accumulated branch values; "
+        "chance = probability-weighted EV; decision = best EV by maximize/"
+        "minimize) — reproduces ModelChoice's rollback without the add-in."
+    )
+)
+def roll_up(
+    tree_name: Annotated[
+        str | None, Field(description="Tree sheet name. Omit for the first tree.")
+    ] = None,
+    workbook_name: str | None = None,
+) -> RollupResponse:
+    bridge = get_bridge()
+    trees = bridge.list_trees(workbook_name)
+    if tree_name is None:
+        tree_name = next(iter(trees))
+    t = parse_model(trees[tree_name])
+    r = rollup(t)
+
+    direction = "maximize" if t.maximize else "minimize"
+    if r.optimal_path:
+        choices = " → ".join(r.optimal_path)
+        rec = (
+            f"Optimal decision ({direction} EV): take {choices}. "
+            f"Expected value {r.expected_value:,.2f}."
+        )
+    else:
+        rec = (
+            f"No decision nodes to optimize; expected value {r.expected_value:,.2f} "
+            f"({direction})."
+        )
+
+    nodes = [
+        NodeResultView(
+            id=nr.id,
+            name=nr.name,
+            kind=nr.kind,
+            expected_value=nr.expected_value,
+            optimal_branch_name=nr.optimal_branch_name,
+        )
+        for nr in r.node_results.values()
+    ]
+    return RollupResponse(
+        name=tree_name,
+        model_name=t.model_name,
+        maximize=t.maximize,
+        expected_value=r.expected_value,
+        optimal_path=r.optimal_path,
+        recommendation=rec,
+        nodes=nodes,
+    )
+
+
+@mcp.tool(
+    description=(
+        "ModelChoice: Cross-check our rollback against ModelChoice's own. The "
+        "add-in writes each node's rolled-back EV into an MC_V_<nodeId> named "
+        "range when it renders a tree; this compares those cells to our Python "
+        "rollback and reports any node that differs beyond `tolerance`. A clean "
+        "result is strong evidence the read+rollback is faithful. If the tree "
+        "hasn't been rendered (no MC_V_ cells), `rendered` is false — open the "
+        "tree in ModelChoice so it renders, then re-run."
+    )
+)
+def verify_rollback(
+    tree_name: Annotated[
+        str | None, Field(description="Tree sheet name. Omit for the first tree.")
+    ] = None,
+    workbook_name: str | None = None,
+    tolerance: Annotated[
+        float, Field(gt=0, description="Max allowed |computed - cell| difference. Default 0.01.")
+    ] = 0.01,
+) -> RollbackVerification:
+    bridge = get_bridge()
+    trees = bridge.list_trees(workbook_name)
+    if tree_name is None:
+        tree_name = next(iter(trees))
+    r = rollup(parse_model(trees[tree_name]))
+    cells = bridge.read_node_values(workbook_name)
+
+    common = [nid for nid in r.node_results if nid in cells]
+    mismatches: list[NodeDiff] = []
+    max_abs = 0.0
+    for nid in common:
+        computed = r.node_results[nid].expected_value
+        cell = cells[nid]
+        diff = computed - cell
+        max_abs = max(max_abs, abs(diff))
+        if abs(diff) > tolerance:
+            mismatches.append(
+                NodeDiff(
+                    node_id=nid, name=r.node_results[nid].name,
+                    computed=computed, cell=cell, diff=diff,
+                )
+            )
+
+    rendered = len(cells) > 0
+    matches = len(common) - len(mismatches)
+    if not rendered:
+        verdict = "Tree not rendered — no MC_V_ cells found. Open it in ModelChoice first."
+    elif not common:
+        verdict = "No overlapping node IDs between the model and the rendered cells."
+    elif not mismatches:
+        verdict = f"Rollback verified: all {matches} compared nodes match (max diff {max_abs:.2g})."
+    else:
+        verdict = f"{len(mismatches)} of {len(common)} nodes differ beyond {tolerance}."
+
+    return RollbackVerification(
+        name=tree_name,
+        rendered=rendered,
+        compared_count=len(common),
+        matches=matches,
+        max_abs_diff=max_abs,
+        mismatches=mismatches,
+        verdict=verdict,
+    )
+
+
+__all__ = [
+    "get_bridge",
+    "get_tree",
+    "list_trees",
+    "roll_up",
+    "set_bridge_for_testing",
+    "verify_rollback",
+]

modelchoice_mcp/tree.py

@@ -0,0 +1,227 @@
+"""Parse and roll back a ModelChoice decision tree from its model JSON.
+
+The JSON schema is defined by ``DecisionTreeModel`` / the polymorphic
+``NodeDefinitionJsonConverter`` in ModelChoice.Core:
+
+- Top level: ``{"RootId": str, "Nodes": {id: nodeObj}, "Settings": {...}}``
+- Each node has a ``"type"`` discriminator: ``"terminal" | "chance" | "decision"``.
+  - terminal: ``{"value": float}``
+  - chance:   ``{"branches": [{"name", "probability", "childId", "value"?}]}``
+  - decision: ``{"options":  [{"name", "childId", "value"?}]}``
+- ``Settings``: ``Maximize`` (true→max EV), ``ChanceProbabilities`` (AutoNormalize
+  by default), ``CalculationMethod`` (Cumulative by default).
+
+Rollback mirrors ``DecisionTreeModel.Compile`` + ``TreeNode.Rollback``:
+terminal payoff = accumulated branch values along the path (+ the
+terminal's own value in classic/Cumulative mode); chance EV = the
+(optionally normalized) probability-weighted child EVs; decision EV =
+the max (or min) child EV, and the winning option is the optimal policy.
+This reproduces ModelChoice's `MC_V_<id>` rollback values in pure Python
+— no add-in required.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class TreeParseError(ValueError):
+    """The model JSON could not be parsed into a valid tree."""
+
+
+@dataclass(frozen=True)
+class Branch:
+    name: str
+    child_id: str
+    value: float = 0.0
+    probability: float | None = None  # None for decision options
+
+
+@dataclass(frozen=True)
+class Node:
+    id: str
+    name: str
+    kind: str  # "terminal" | "chance" | "decision"
+    value: float = 0.0  # terminal's own value
+    branches: list[Branch] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class DecisionTree:
+    root_id: str
+    nodes: dict[str, Node]
+    maximize: bool = True
+    auto_normalize: bool = True
+    cumulative: bool = True
+    model_name: str = "Untitled"
+
+
+@dataclass(frozen=True)
+class NodeResult:
+    id: str
+    name: str
+    kind: str
+    expected_value: float
+    optimal_child_id: str | None = None  # for decision nodes: the chosen option's child
+    optimal_branch_name: str | None = None
+
+
+@dataclass(frozen=True)
+class RollupResult:
+    root_id: str
+    expected_value: float
+    optimal_path: list[str]  # branch/option names from root along the optimal policy
+    node_results: dict[str, NodeResult]
+
+
+def _as_float(v: Any, default: float = 0.0) -> float:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_model(model_json: str) -> DecisionTree:
+    """Parse a serialized ``DecisionTreeModel`` JSON string into a
+    :class:`DecisionTree`. Property lookups are case-insensitive on the
+    top-level keys (C# serializes PascalCase; we tolerate either)."""
+    try:
+        raw = json.loads(model_json)
+    except json.JSONDecodeError as exc:
+        raise TreeParseError(f"model JSON is not valid JSON: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise TreeParseError("model JSON root must be an object")
+
+    def get(d: dict[str, Any], *names: str, default: Any = None) -> Any:
+        lower = {k.lower(): v for k, v in d.items()}
+        for n in names:
+            if n.lower() in lower:
+                return lower[n.lower()]
+        return default
+
+    root_id = get(raw, "RootId")
+    nodes_raw = get(raw, "Nodes")
+    if not isinstance(root_id, str) or not isinstance(nodes_raw, dict):
+        raise TreeParseError("model JSON must have a string RootId and a Nodes object")
+
+    settings = get(raw, "Settings", default={}) or {}
+    maximize = bool(get(settings, "Maximize", default=True))
+    chance_mode = str(get(settings, "ChanceProbabilities", default="AutoNormalize"))
+    # enum may serialize as the name or its int (0=MustTotal100, 1=AutoNormalize)
+    auto_normalize = chance_mode.lower() in ("autonormalize", "1")
+    calc = str(get(settings, "CalculationMethod", default="Cumulative"))
+    cumulative = calc.lower() != "mcda"
+    model_name = str(get(settings, "ModelName", default="Untitled"))
+
+    nodes: dict[str, Node] = {}
+    for nid, n in nodes_raw.items():
+        if not isinstance(n, dict):
+            raise TreeParseError(f"node {nid!r} is not an object")
+        kind = str(n.get("type", "")).lower()
+        name = str(n.get("name", nid))
+        if kind == "terminal":
+            nodes[nid] = Node(id=nid, name=name, kind="terminal", value=_as_float(n.get("value")))
+        elif kind == "chance":
+            branches = [
+                Branch(
+                    name=str(b.get("name", "")),
+                    child_id=str(b.get("childId", "")),
+                    value=_as_float(b.get("value")),
+                    probability=_as_float(b.get("probability")),
+                )
+                for b in n.get("branches", [])
+            ]
+            nodes[nid] = Node(id=nid, name=name, kind="chance", branches=branches)
+        elif kind == "decision":
+            options = [
+                Branch(
+                    name=str(o.get("name", "")),
+                    child_id=str(o.get("childId", "")),
+                    value=_as_float(o.get("value")),
+                    probability=None,
+                )
+                for o in n.get("options", [])
+            ]
+            nodes[nid] = Node(id=nid, name=name, kind="decision", branches=options)
+        else:
+            raise TreeParseError(f"node {nid!r} has unsupported type {kind!r}")
+
+    if root_id not in nodes:
+        raise TreeParseError(f"RootId {root_id!r} is not present in Nodes")
+    return DecisionTree(
+        root_id=root_id,
+        nodes=nodes,
+        maximize=maximize,
+        auto_normalize=auto_normalize,
+        cumulative=cumulative,
+        model_name=model_name,
+    )
+
+
+def rollup(tree: DecisionTree) -> RollupResult:
+    """Roll the tree back to expected values and the optimal policy.
+
+    Returns the root EV, the optimal path (the sequence of branch/option
+    names taken under the optimal policy, following the chosen option at
+    each decision and *all* branches at chance nodes is not a single
+    path — so the path lists decisions and, at the first chance node,
+    stops descending decisions only), and a per-node EV map.
+    """
+    node_results: dict[str, NodeResult] = {}
+
+    def ev(node_id: str, accumulated: float) -> float:
+        node = tree.nodes.get(node_id)
+        if node is None:
+            raise TreeParseError(f"missing child node {node_id!r}")
+
+        if node.kind == "terminal":
+            payoff = accumulated + (node.value if tree.cumulative else 0.0)
+            node_results[node_id] = NodeResult(node_id, node.name, "terminal", payoff)
+            return payoff
+
+        if node.kind == "chance":
+            total_p = sum((b.probability or 0.0) for b in node.branches)
+            normalize = tree.auto_normalize or abs(total_p - 1.0) > 1e-12
+            value = 0.0
+            for b in node.branches:
+                p = (b.probability or 0.0)
+                p = (p / total_p) if (normalize and total_p > 0) else p
+                value += p * ev(b.child_id, accumulated + b.value)
+            node_results[node_id] = NodeResult(node_id, node.name, "chance", value)
+            return value
+
+        # decision: pick the optimal option
+        best_ev: float | None = None
+        best: Branch | None = None
+        for o in node.branches:
+            child_ev = ev(o.child_id, accumulated + o.value)
+            if (
+                best_ev is None
+                or (tree.maximize and child_ev > best_ev)
+                or (not tree.maximize and child_ev < best_ev)
+            ):
+                best_ev, best = child_ev, o
+        if best is None or best_ev is None:
+            raise TreeParseError(f"decision node {node_id!r} has no options")
+        node_results[node_id] = NodeResult(
+            node_id, node.name, "decision", best_ev,
+            optimal_child_id=best.child_id, optimal_branch_name=best.name,
+        )
+        return best_ev
+
+    root_ev = ev(tree.root_id, 0.0)
+
+    # Build the optimal path: follow chosen options at decisions until a
+    # chance/terminal node ends the deterministic prefix.
+    path: list[str] = []
+    cur = tree.root_id
+    while True:
+        res = node_results.get(cur)
+        if res is None or res.kind != "decision" or res.optimal_child_id is None:
+            break
+        path.append(res.optimal_branch_name or "")
+        cur = res.optimal_child_id
+
+    return RollupResult(tree.root_id, root_ev, path, node_results)

modelchoice_mcp-0.0.1.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: modelchoice-mcp
+Version: 0.0.1
+Summary: An open Model Context Protocol server for Vose Software's ModelChoice decision-tree add-in for Excel.
+Author: Vose Software
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: xlwings>=0.30
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ModelChoice MCP
+
+**An open Model Context Protocol server for [Vose Software's ModelChoice](https://www.vosesoftware.com) — the decision-tree add-in for Excel.**
+
+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.1` — Phase 1 MCP server (read-only).** Three tools (`list_trees`, `get_tree`, `roll_up`) over a proven read path. Building/analysis tools are on the roadmap below.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `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. |
+| `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 it: `uv run python -m modelchoice_mcp` (stdio), or wire `modelchoice-mcp` into Claude Desktop like any MCP server.
+
+## How it works
+
+ModelChoice is a C# .NET (Excel-DNA) add-in. Unlike ModelRisk it exposes **no COM object model and no compute worksheet functions** — but it persists the *entire* decision tree as JSON in a very-hidden worksheet (`_MC_Store`), and the rollback logic is fully captured in that model. So this server can:
+
+- **Read** every tree in a workbook by reassembling the `_MC_Store` payload (chunked across columns, v2-envelope or v1-legacy format) and parsing the model JSON.
+- **Roll back** each tree to its expected values and **optimal policy** in pure Python — reproducing ModelChoice's own rollback (terminal payoff = accumulated branch values; chance = auto-normalized probability-weighted EV; decision = max/min by `Maximize`). **No add-in needs to be loaded** — it reads the saved model directly.
+
+The Python roller is validated against ModelChoice's own authoritative C# test (`Model_Validate_Compile_Rollback_Works`): a decision/chance tree that rolls back to EV 50 with the optimal option selected — and matches exactly.
+
+## Roadmap
+
+- **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 3:** build/edit trees — write the model JSON into `_MC_Store` and trigger a re-render.
+
+## Architecture
+
+A separate server that reuses the patterns proven in `modelrisk-mcp` (xlwings bridge, dry-run-by-default safety on any future writes, packaging, MCP-registry flow). Decision analysis and Monte Carlo are distinct domains, so they ship as distinct servers.
+
+## Development
+
+```powershell
+uv sync --extra dev
+uv run pytest        # parser/roller + store-format tests (no Excel needed)
+```
+
+MIT licensed.

modelchoice_mcp-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+modelchoice_mcp/__init__.py,sha256=jwiYZp-EYnQNMn9unwEzyjS_XWB_UzRAWlTYcH3lDVQ,151
+modelchoice_mcp/__main__.py,sha256=LwnQdGyoVrH4YDA5VZt1sTDNROjBZm2yg1pWlRU7HEc,1125
+modelchoice_mcp/bridge.py,sha256=01rbSiOqlglGU8DLd4hTX97aYn6o23YisYRS_6EzyVs,5155
+modelchoice_mcp/schemas.py,sha256=VKkw5WzoNFShNW6frPOh6EaMIYlcAxz58aBAdfpM68U,2896
+modelchoice_mcp/server.py,sha256=iA_UWtLpatxGtmHwWXDkT-YXG2u8W895FQ9ddEcamWs,995
+modelchoice_mcp/store.py,sha256=9vjHLo2fxzTWN-TJLs6N08dXghei7Hk6CG3k7PXdUwQ,2391
+modelchoice_mcp/tools.py,sha256=hLoqq31Ei9B5qlEoWvEJ9o6m1vljOjjCnVo53OmFXf8,8197
+modelchoice_mcp/tree.py,sha256=x4aAPo__fLAb63JgjOrR__piDMpMFHxu-8ngmfkmOgw,8526
+modelchoice_mcp-0.0.1.dist-info/METADATA,sha256=dXKlSLvIUOI7KVt-KgkK4gpBFP_Rsqfl_0gIKvhNM_E,4333
+modelchoice_mcp-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modelchoice_mcp-0.0.1.dist-info/entry_points.txt,sha256=e4Xtf5NiIewfKAfcPBoU9F6_h2ZgABDVgBVf5JWlzKY,66
+modelchoice_mcp-0.0.1.dist-info/RECORD,,

modelchoice_mcp-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

modelchoice_mcp-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modelchoice-mcp = modelchoice_mcp.__main__:main