Phase 1: wire the read-only MCP server (list_trees, get_tree, roll_up)

Builds the FastMCP server on top of the Phase 0 read/rollback engine:

- server.py: FastMCP("modelchoice-mcp") + tool registration.
- schemas.py: pydantic response models (TreeList/TreeStructure/RollupResponse).
- tools.py: list_trees (summaries + node counts), get_tree (full structure),
  roll_up (EV + optimal policy + plain-English recommendation), with a
  get_bridge()/set_bridge_for_testing() seam.
- __main__.py: stdio (default) / streamable-http / sse entrypoint;
  console-script `modelchoice-mcp`.

Proven live end to end against a real workbook: list_trees -> get_tree ->
roll_up returns "Optimal decision (maximize EV): take Sell. Expected
value 50.00." 19 unit tests (incl. server boot + tool registration);
ruff + mypy(strict) clean.

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

Author: vosesoft

README.md

@@ -4,7 +4,17 @@
 
 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 0 (read-only) spike.** The core read path is proven end to end. Building/analysis tools are on the roadmap below.
+> **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. |
+
+Run it: `uv run python -m modelchoice_mcp` (stdio), or wire `modelchoice-mcp` into Claude Desktop like any MCP server.
 
 ## How it works
 
@@ -17,9 +27,11 @@ The Python roller is validated against ModelChoice's own authoritative C# test (
 
 ## Roadmap
 
-- **Phase 0 (done):** read-only — list trees, read structure, roll back to EV + optimal policy, cross-check against the `MC_V_<id>` named ranges.
-- **Phase 1:** 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:** build/edit trees — write the model JSON into `_MC_Store` and trigger a re-render.
+- **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:** cross-check rolled-back EVs against the `MC_V_<id>` named ranges; packaging + CI + PyPI; Claude Desktop wiring docs.
+- **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
 

pyproject.toml

@@ -12,6 +12,9 @@ dependencies = [
     "xlwings>=0.30",
 ]
 
+[project.scripts]
+modelchoice-mcp = "modelchoice_mcp.__main__:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",

src/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()

src/modelchoice_mcp/schemas.py

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

src/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"]

src/modelchoice_mcp/tools.py

@@ -0,0 +1,181 @@
+"""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,
+    NodeResultView,
+    NodeView,
+    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,
+    )
+
+
+__all__ = ["get_bridge", "get_tree", "list_trees", "roll_up", "set_bridge_for_testing"]

tests/test_server.py

@@ -0,0 +1,24 @@
+"""Server boot + tool-registration smoke tests."""
+
+from __future__ import annotations
+
+from modelchoice_mcp import __version__
+from modelchoice_mcp.server import mcp
+
+
+def test_version_set() -> None:
+    assert __version__ == "0.0.1"
+
+
+def test_server_name() -> None:
+    assert mcp.name == "modelchoice-mcp"
+
+
+async def test_read_tools_registered() -> None:
+    names = {t.name for t in await mcp.list_tools()}
+    assert {"list_trees", "get_tree", "roll_up"} <= names
+
+
+async def test_tool_descriptions_have_brand_prefix() -> None:
+    for t in await mcp.list_tools():
+        assert (t.description or "").startswith("ModelChoice:")