modelrisk-mcp 0.3.0a5__tar.gz

modelrisk_mcp-0.3.0a5/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# uv
+# (uv.lock IS committed)
+
+# Build artefacts
+build/
+dist/
+*.exe
+*.spec.bak
+
+# PyInstaller
+*.manifest
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Local
+*.log
+.env
+.env.local

modelrisk_mcp-0.3.0a5/CHANGELOG.md

@@ -0,0 +1,236 @@
+# Changelog
+
+All notable changes to ModelRisk MCP. Follows [Keep a Changelog](https://keepachangelog.com/) and [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0-alpha.5] — 2026-05-21
+
+First publish-ready release. Adds the tornado chart writer, fixes a real `discover_inputs` scoring bug, closes the security verification loop on the obfuscated activation key, and refreshes internal docs to match v0.3 architecture.
+
+### Added
+
+- `create_tornado_chart(output_name, workbook_name?, sheet_name?)` — renders a SensitivityRanking as a native Excel BarClustered chart on a new sheet (`Tornado_<output_name>` by default, truncated to Excel's 31-char limit). Sheet has a sorted data table (Input | Spearman correlation | |corr| sort key | Regression coefficient) plus the chart with inverted category axis so the largest-magnitude input is at the top — the tornado convention. Idempotent: existing sheets with the target name are replaced, so it's safe to re-run after each new simulation.
+- `bridge/charts.py::TornadoChartWriter` — first member of the chart-writer family. Future siblings: RiskProfileChartWriter (cumulative + density), HistogramWriter, ScenarioComparisonWriter.
+- `scripts/scan_exe_for_key.py` — paranoid scan of a built PyInstaller exe for every encoding of the plain activation key (ASCII decimal, UTF-16 LE wide string, little-endian int64 bytes, big-endian int64 bytes, 8-byte compact form, hex string both cases, and composite first4+last4 across printable runs). Exits non-zero on any hit; wired into `release.yml` as a release-blocker step before the PyPI upload so a regression in the obfuscation can't ship.
+
+### Fixed
+
+- `discover_inputs` no longer over-scores zero-valued cells. The `value not in (0, 1)` exclusion was guarding only the multiple-of-10 bonus; the multiple-of-100 and multiple-of-1000 bonuses still fired for `value=0` because `0 % n == 0`. Result: a cell holding 0 scored 2.0, identical to a cell holding 100 — flags tied with real scenario assumptions. Also added an explicit `not isinstance(value, bool)` guard so `False` cells don't take the same code path (Python's `isinstance(True, int)` is True).
+
+### Verified
+
+- v0.3.0-alpha.5 builds — wheel (~17 KB), sdist (~140 KB), and PyInstaller exe (~39 MB) — and the exe scan returns clean across every encoding tested. Even the obfuscated base85 blobs from `_keymat.py` aren't directly findable in the binary because PyInstaller compresses bundled Python into a PYZ archive; the source-level base85 strings become compiled `.pyc` bytecode constants. A reverse-engineer would need to extract the PYZ, decompress the bytecode, and reimplement the XOR decoder by hand. Casual `strings`-based extraction yields nothing actionable.
+
+### Docs
+
+- `docs/architecture.md` and `docs/com-surface.md` rewritten to match the v0.3 stack (MRService.dll via ctypes + XLL `Application.Run` for simulation kickoff; no ATL CoClass dispatch).
+
+### Tests
+
+303 unit tests pass (was 290 at alpha.4): +11 chart writer tests + 2 regression tests for the discover_inputs zero-value scoring fix.
+
+## [0.3.0-alpha.4] — 2026-05-21
+
+Four feature additions in one batch: read-path completeness, a one-call session-start tool, deterministic scenario sweeps, and 5 new audit rules. Tool count grows 30 → 34, audit rules 6 → 11. No breaking changes.
+
+### Added
+
+- `list_vmrs_variables(workbook_name?)` — enumerates VoseInput / VoseOutput names that exist in the active `.vmrs`. Workbook drives the candidate list (the SDK exposes no name-enumeration call against a `.vmrs` directly — `MRVarsGetModelVarsNames` takes a different ModelID and access-violates against `OpenSimulationModel`'s pointer).
+- `get_samples(output_name, max_n=10000, workbook_name?)` — raw per-iteration sample array for one variable. Unlocks custom histograms, arbitrary percentiles, and any downstream analysis the aggregate-only `get_simulation_results` couldn't cover. Capped at 10 000 by default to stay under MCP-wire budget; configurable up to 1 000 000.
+- `diagnose_workbook(workbook_name?)` — one-call session-start introspection. Returns Excel connection state, MRService activation, active workbook + sheets, input/output/distribution/formula counts, sibling `.vmrs` path + modification timestamp, audit-log location, and an `issues[]` list with human-readable strings flagging anything that would block downstream operations. Saves 4-5 individual tool calls per session. Short-circuits cleanly on Excel-not-reachable.
+- `run_scenarios(sheet, cell, values, samples?, seed?, workbook_name?)` — sweep an input cell across deterministic values, running a full simulation at each, returning per-output P5/P50/P95/mean for every scenario. The cell's original formula is always restored afterwards, even when a scenario raises mid-sweep. `values` capped at 1-20 entries to prevent runaway compute.
+- 5 new audit rules:
+  - **VOSE-007** `risk_event_degenerate_probability` — `VoseRiskEvent` with literal probability of 0 or 1 (wrapper is degenerate).
+  - **VOSE-008** `voseoutput_missing_name` — `VoseOutput()` with no name or empty-string name.
+  - **VOSE-009** `duplicate_output_names` — same `VoseOutput("X")` declared on multiple cells.
+  - **VOSE-010** `input_wrapper_without_distribution` — `VoseInput` wrapper but no distribution → input won't vary across iterations.
+  - **VOSE-011** `high_volatility_normal_positive_mean` — `VoseNormal(mu, sigma)` with `mu > 0` and `sigma > mu/2` (~16% negative samples; lognormal probably wanted).
+- `docs/authoring-audit-rules.md` — guide for adding new rules. Three-file pattern (YAML + detector + tests), worked example using VOSE-007, when-not-to-add-a-rule discussion.
+
+### Bridge / schema changes
+
+- `bridge/results.py::ResultsReader.list_variables()` and `.get_samples()` — new methods consumed by the new MCP tools.
+- `bridge/modelrisk.py::ModelRiskBridge.run_scenarios()` — orchestrates Excel write + sim + read with guaranteed cell-state restoration in a `try/finally`.
+- New schemas in `schemas/results.py`: `ScenarioOutcome`, `ScenarioRun`, `ScenarioSweepResult`, `VmrsVariableEntry`.
+
+### Tests
+
+290 unit tests pass (was 256 at start of alpha.4 work). 34 new tests across the four features: 5 for read-path tools, 6 for `diagnose_workbook`, 6 for scenario sweeps, 17 for the new audit detectors (positive + negative cases per rule, plus threshold-boundary tests for VOSE-011).
+
+### Notes
+
+False-positive avoidance pattern adopted in the new audit rules: numeric-threshold rules skip cell-reference args (e.g. `VoseRiskEvent(B5, ...)` is NOT flagged because we can't statically know what's in B5). Static analysis should be conservative when it lacks information.
+
+## [0.3.0-alpha.3] — 2026-05-21
+
+End-user-frictionless activation + obfuscation so the bundled MRService.dll key isn't grep-able from the wheel, plus 50 new MCP-wrapper tests that were missing since the v0.3 refactor.
+
+### Added
+
+- Bundled MRService.dll activation. The DLL needs per-process activation to open `.vmrs` files; we now ship a Vose Software-owned key as a fallback in `bridge/mrservice.py::_activate()` so the read path works out of the box. Precedence: `MRSERVICE_ACTIVATION_KEY` env var → `MRSERVICE_ACTIVATION_KEY1`/`_2` env vars → bundled key. `MRSERVICE_DISABLE_BUNDLED_KEY=1` opts out.
+- `bridge/_keymat.py` + `scripts/encode_activation_key.py` — XOR-encoded + base85-stored key material so the literal int never appears in shipped source or `strings` output. Algorithm is public (Kerckhoffs); only the value is secret.
+- `tests/unit/test_tools_{reading,workflows,simulation,restore}_mocked.py` (50 tests) — MCP-tool wrappers were previously untested; these guard against bridge method-rename / kwarg-shape regressions that only surface at end-user runtime.
+- CI guard `test_no_literal_in_package_sources` recursively scans every shipped `.py` for the decoded key's decimal form; fails if anyone re-inlines it.
+
+### Verified
+
+- Wheel and sdist scans for the plain activation key return zero hits.
+- Bundled key activates the real MRService.dll end-to-end (smoke test in the bridge).
+
+### Tests
+
+256 unit tests pass (was 206). 50 new MCP-wrapper tests + 3 reworked activation tests.
+
+## [0.3.0-alpha.2] — 2026-05-20
+
+Adds programmatic simulation triggering via the XLL command surface (no ATL COM dispatch needed), graceful OneDrive path handling, and the missing `read_vmrs` / `set_active_vmrs` tools.
+
+### Added
+
+- `bridge/simulation.py` — `SimulationController` drives runs via plain `Application.Run("VoseStartSimulCustom12", options)` + `Application.Run("VoseGetDataSZ12", session, path)`, replicating exactly what the ATL does internally (`ModelRiskAtl/ModelRisk_Simulate.cpp:102`, `ModelRiskAtl/ModelRiskSimulationResults.cpp:1196`). No ATL Dispatch required, so cross-bitness automation works.
+- `SimulationOptions` dataclass reproduces `CSimulationOptions::PackToStringList` (`SimulationObj.cpp:94`) — `[Key]:Value` lines in exact field order.
+- New MCP tool `run_simulation(workbook_name?, samples=1000, seed=1, save_to?)` — blocks until the sim finishes, saves the `.vmrs` next to the workbook by default, and auto-pins it as the active results source.
+- New MCP tools `set_active_vmrs(path)` and `read_vmrs(path, output_names?)` — formerly referenced in error messages but not registered.
+
+### Changed
+
+- `ExcelBridge.get_active_workbook()` / `list_workbooks()` degrade gracefully when xlwings can't resolve OneDrive paths (`ONEDRIVE_COMMERCIAL_WIN` not set). Returns name-only `WorkbookInfo` with empty path; downstream name-based COM operations still work.
+- `SimulationController` falls back to saving in the user's Desktop folder when the workbook's folder can't be resolved (the OneDrive case).
+- `ModelRiskBridge.run_simulation()` calls `ResultsReader.set_active_vmrs()` automatically after a successful run, so the next `get_simulation_results` call doesn't need a sibling-discovery step.
+
+### Tests
+
+201 unit tests pass (was 182). New coverage: OneDrive path fallback (5), SimulationController options packing + Application.Run shape + session-name format + failure modes (14).
+
+## [0.2.0-alpha.2] — 2026-05-20
+
+Auto-activates the ModelRisk add-in inside Excel before reporting the COM surface unreachable. Closes the "modelrisk_loaded: false even though ModelRisk is installed" footgun.
+
+### Added
+
+- `ExcelBridge.list_com_addins() / list_excel_addins()` — enumerate Excel's COMAddIns and AddIns collections as plain dicts.
+- `ExcelBridge.enable_com_addin(predicate) / enable_excel_addin(predicate)` — flip `.Connect=True` / `.Installed=True` on matching entries, return the names of those actually flipped. Idempotent; no-op on already-on entries.
+- `ModelRiskBridge.ensure_modelrisk_active()` — scans both collections, enables any entry whose description / progid / name mentions ModelRisk or Vose, retries Dispatch, returns a diagnostic dict (`com_addins_enabled`, `excel_addins_enabled`, `com_addins_seen`, `excel_addins_seen`, `modelrisk_dispatchable`).
+- New MCP tool `ensure_modelrisk_active` — explicit invocation for debugging "COM unreachable" reports.
+- Simulation tools (`set_simulation_settings`, `run_simulation`) now call `ensure_modelrisk_active` transparently before touching COM. The LLM no longer needs to ask the user to manually load the add-in.
+
+### Changed
+
+- `ModelRiskBridge.is_modelrisk_loaded()` now attempts auto-activation if the first Dispatch fails. Returns True iff Dispatch works after activation.
+
+### Notes
+
+If auto-activation can't find a ModelRisk add-in to flip on, the diagnostic surfaces every COM and Excel add-in it *did* see — useful for ruling out bitness mismatches and broken installs.
+
+## [0.2.0-alpha.1] — 2026-05-20
+
+HTTP transport — unblocks Claude for Excel and other remote MCP clients that can't spawn local subprocesses.
+
+### Added
+
+- `--transport={stdio,streamable-http,sse}` CLI flag in `__main__.py`. stdio remains the default for backwards compatibility.
+- `--host`, `--port`, `--mount-path` flags for HTTP transports. Defaults to `127.0.0.1:8000`.
+- Bearer-token middleware (`http_auth.py`) — required on non-loopback HTTP binds, recommended even on loopback. Constant-time comparison via `hmac.compare_digest`. Token via `--token` or `MODELRISK_MCP_TOKEN` env var.
+- `docs/claude-for-excel.md` — wiring guide covering the Office.js sandbox / COM-bridge architectural story.
+- README section on HTTP transport with the strategic framing.
+- `tests/unit/test_cli.py` + `tests/unit/test_http_auth.py` — 14 new tests covering parser defaults, middleware reject/accept paths, RFC 6750 case-insensitivity of the Bearer keyword.
+
+### Changed
+
+- Spec §2.2 — "Hosting the MCP server remotely" no longer a non-goal.
+- README front-page table picks up a "Works with Claude for Excel" implication (no UI change needed — Claude for Excel was always in the compatible-clients list).
+
+## [0.1.0] — 2026-05-20
+
+Public v0.1 release. Repository goes public at this tag.
+
+### Added
+
+- Public-ready README leading with the strategic narrative (open, agentic, methodology-aware), feature comparison table, and full Safety by design section.
+- `docs/demo-script.md` — beat-by-beat recording guide for the README demo GIF.
+- `docs/community-submission.md` — drafted PR text for the modelcontextprotocol/servers directory.
+- Spec doc updated to v1.4 with the per-phase completion record.
+
+### Changed
+
+- `Development Status` classifier moved to `5 - Production/Stable`.
+
+## [0.1.0-rc.1] — 2026-05-20
+
+First release candidate. Feature surface matches the v0.1 spec. PyPI publication path and standalone `.exe` build pipeline both verified locally.
+
+### Added
+
+- Final `pyproject.toml` metadata: full PyPI classifiers, project URLs (Changelog, Documentation, Vose Software), wheel `force-include` for the four packaged YAML/JSON data files, sdist include list.
+- `.github/workflows/release.yml` — tag-triggered build of wheel, sdist, and standalone Windows `.exe`; uploads to PyPI via trusted publishing and to GitHub Releases.
+- `CHANGELOG.md` — this file. Phase-by-phase history.
+- Updated `modelrisk_mcp.spec` — PyInstaller bundle now declares hidden imports for every tool/resource/prompt module and ships the catalogue + rule YAML files alongside the `.exe`.
+
+## [0.1.0-beta.1] — 2026-05-20 (commit `d4431bc`)
+
+Phase 5 — workflows, resources, prompts.
+
+### Added
+
+- 4 workflow tools (`tools/workflows.py`): `propose_distributions_for_inputs`, `discover_inputs`, `audit_model`, `generate_executive_summary`.
+- Audit engine (`audit/engine.py`, `audit/rules.py`) with 6 detectors mapped to rules in `data/audit_rules.yaml`.
+- 7 resources under `modelrisk://`: `functions`, `functions/{name}`, `distributions`, `methodology`, `workbook/current`, `workbook/current/sheet/{name}`, `audit-rules`.
+- 5 prompt templates (slash commands): `/build-risk-model`, `/audit-model`, `/interpret-results`, `/add-uncertainty`, `/import-legacy-model`.
+- `data/distributions.yaml` — keyword-matched distribution selection guide.
+
+## [0.1.0-alpha.3] — 2026-05-20 (commit `464c5f3`)
+
+Phase 4 — simulation control.
+
+### Added
+
+- `bridge/simulation.py` with `SimulationController` and `SimulationCom` Protocol abstracting `ModelRiskSimulation` + `ModelRiskSimulationSettings`.
+- 4 simulation tools: `set_simulation_settings`, `run_simulation`, `stop_simulation` (registered stub raising `SimulationNotAvailableError`), `get_simulation_status` (in-process polling fallback).
+- `seed=42` auto-flips `use_fixed_seed=True` when the user doesn't pass it explicitly.
+
+## [0.1.0-alpha.2] — 2026-05-20 (commit `2cc7e6b`)
+
+Phase 3 — building tools and `restore_cell`.
+
+### Added
+
+- 10 building tools (`tools/building.py`): `insert_distribution`, `wrap_with_input`, `wrap_with_output`, `replace_constant_with_distribution`, `fit_distribution_to_data`, `create_aggregate_mc`, `create_risk_event`, `create_time_series`, `create_copula`, `set_named_range`. Every tool defaults `dry_run=True`.
+- `restore_cell` MCP tool (`tools/restore.py`) — restores any cell from the audit log.
+- `ModelRiskBridge.safe_write_cell` — every cell write goes through this and gets: writer-mutex acquisition, non-Vose-formula refusal via tokenised detection, audit-log append.
+- `ExcelBridge.set_named_range` + `ExcelBridge.undo` for the Excel-undo-stack acceptance test.
+
+## [0.1.0-alpha.1] — 2026-05-20 (commit `793a17c`)
+
+Phase 2 — reading tools.
+
+### Added
+
+- 12 reading tools (`tools/reading.py`): `list_open_workbooks`, `get_active_workbook`, `get_workbook_summary`, `list_modelrisk_inputs`, `list_modelrisk_outputs`, `list_distributions`, `get_cell`, `read_range`, `get_simulation_results`, `get_correlation_matrix`, `get_sensitivity_ranking`, `find_hard_coded_inputs`.
+- `bridge/results.py` — `ResultsReader` wrapping `ISimVariable.GetMean/Percentile/StDev/...`. Pearson + Spearman correlation and Spearman-based tornado computed in numpy from `GetSamples()`.
+- `docs/installation.md`, `docs/claude-desktop.md`, `docs/claude-code.md`.
+
+## [0.0.2] — 2026-05-19 (commit `c4fe8b5`)
+
+Phase 1 — bridge layer, safety mechanisms, function catalogue.
+
+### Added
+
+- 1417-entry function catalogue (`data/functions.json`) extracted from the ModelRisk IDL + XLL header.
+- `bridge/{catalogue,excel,formulas,modelrisk,progids}.py` — three-layer architecture.
+- `safety.py` — tokenised `is_vose_formula` detector, bulk-write guard, audit-log appender, Windows-named-mutex `WriterMutex`.
+- Pydantic v2 schemas for every tool input/output (`schemas/{workbook,distributions,results}.py`).
+- `data/optional_overrides.yaml` — flips `VoseModPERT.gamma` (and similar) to optional with their documented defaults.
+- Gated integration test infrastructure (`tests/integration/`) — skips cleanly when Excel isn't running.
+
+## [0.0.1] — 2026-05-19 (commit `3741386`)
+
+Phase 0 — scaffold.
+
+### Added
+
+- Empty FastMCP server that responds to `initialize` and returns an empty `tools/list`.
+- `pyproject.toml`, `LICENSE` (MIT), `.gitignore`, `.python-version`.
+- `.github/workflows/ci.yml` — ruff + mypy + pytest on Windows × Python 3.11/3.12/3.13.
+- `scripts/spike_com_surface.py` — probes ModelRisk's COM surface and writes `docs/com-surface.md`.
+- `modelrisk_mcp.spec` — PyInstaller spec used for the Phase 0 smoke build.

modelrisk_mcp-0.3.0a5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vose Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelrisk_mcp-0.3.0a5/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: modelrisk-mcp
+Version: 0.3.0a5
+Summary: Open MCP server bridging Anthropic Claude (and any MCP-compatible client) with the ModelRisk Excel add-in.
+Project-URL: Homepage, https://github.com/vosesoftware/modelrisk-mcp
+Project-URL: Repository, https://github.com/vosesoftware/modelrisk-mcp
+Project-URL: Issues, https://github.com/vosesoftware/modelrisk-mcp/issues
+Project-URL: Changelog, https://github.com/vosesoftware/modelrisk-mcp/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/vosesoftware/modelrisk-mcp/tree/main/docs
+Project-URL: Vose Software, https://www.vosesoftware.com
+Author-email: Vose Software <info@vosesoftware.com>
+Maintainer-email: Vose Software <info@vosesoftware.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,excel,mcp,modelrisk,monte-carlo,probability,risk-analysis,simulation,vose
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: xlwings>=0.31; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyinstaller>=6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ModelRisk MCP
+
+**An open Model Context Protocol server for [Vose Software's ModelRisk](https://www.vosesoftware.com).**
+
+Use it with Claude Desktop, Claude Code, Cursor, Zed, or any MCP-compliant client to read, build, fit, and run Monte Carlo risk models in Excel from a conversation.
+
+> ModelRisk MCP is an open MCP server on the standard Anthropic Model Context Protocol. No proprietary layer, no lock-in. The 1417-entry function catalogue, the Vose methodology principles, and the audit rule set are all included in the package — and editable.
+
+**Status: `0.3.0-alpha.5`** — programmatic simulation via the `run_simulation` tool wired end-to-end (XLL command surface, no fragile COM dispatch); `.vmrs` results read via the official ModelRisk SDK; activation ships bundled so no environment configuration is required. 35 tools across reading, building, simulation, scenario-sweep, restore, charting, audit, and workflow surfaces.
+
+---
+
+## What this does
+
+This server turns Claude (or any MCP client) into a methodology-aware co-pilot for ModelRisk. It can:
+
+- **Build** new Monte Carlo models from a description — insert distributions, fit families to data, build aggregates, copulas, time-series, risk events.
+- **Run** simulations from the conversation. `run_simulation` triggers the same XLL command the ribbon "Simulate" button uses, blocks until the run finishes, saves a `.vmrs` next to the workbook, and auto-pins it as the results source.
+- **Read** model structure and per-iteration results — inputs, outputs, percentiles, correlation matrices, tornado rankings — directly from `.vmrs` files via ModelRisk's official SDK (MRService.dll). No COM dispatch fragility.
+- **Audit** a workbook against Vose's methodology rules and propose fixes.
+- **Interpret** results into structured executive summaries with contingency analysis.
+
+Every formula written to Excel is validated against the ModelRisk function catalogue first — there's no path to a hallucinated function name reaching your workbook.
+
+---
+
+## Feature comparison
+
+| Capability | ModelRisk MCP | Closed alternatives |
+|---|:---:|:---:|
+| Read model structure (inputs, outputs, distributions) | ✓ | ✓ |
+| Read simulation results, percentiles, sensitivity | ✓ | ✓ |
+| Insert distributions into cells | ✓ | — |
+| Fit distributions from data | ✓ | — |
+| Build aggregate (frequency × severity) models | ✓ | — |
+| Build copulas / correlated inputs | ✓ | — |
+| Build time-series stochastic processes | ✓ | — |
+| Run simulations from the conversation | ✓ | — |
+| Audit model for common methodology mistakes | ✓ | — |
+| Works with Claude Desktop / Code / Cursor / Zed / any MCP client | ✓ | — |
+| Open source, MIT licensed | ✓ | — |
+| Local-only, no telemetry | ✓ | varies |
+| Default-safe (dry-run preview before every write) | ✓ | n/a |
+
+---
+
+## Install
+
+### Prerequisites
+
+- Windows 10 or 11, 64-bit
+- Excel 2019 or newer with the ModelRisk add-in installed and loaded
+- One of:
+  - Python 3.11+ (recommended via [`uv`](https://docs.astral.sh/uv/))
+  - Or the standalone `modelrisk-mcp.exe` from the [latest release](https://github.com/vosesoftware/modelrisk-mcp/releases/latest) — no Python knowledge required
+
+**Activation:** None required. MRService.dll (the SDK that reads `.vmrs` files) is activated automatically by a bundled offline key. Set `MRSERVICE_ACTIVATION_KEY` only if you want to override the default with your own.
+
+### From PyPI
+
+```powershell
+pip install modelrisk-mcp
+```
+
+### From source
+
+```powershell
+git clone https://github.com/vosesoftware/modelrisk-mcp
+cd modelrisk-mcp
+uv sync
+uv run python -m modelrisk_mcp     # speaks MCP over stdio
+```
+
+### Standalone `.exe`
+
+Download `modelrisk-mcp.exe` from [Releases](https://github.com/vosesoftware/modelrisk-mcp/releases/latest), drop it anywhere on disk, and point Claude Desktop at it. See [docs/claude-desktop.md](docs/claude-desktop.md).
+
+---
+
+## Wire into Claude Desktop
+
+Open `%APPDATA%\Claude\claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "modelrisk": {
+      "command": "python",
+      "args": ["-m", "modelrisk_mcp"]
+    }
+  }
+}
+```
+
+Or, if you downloaded the `.exe`:
+
+```json
+{
+  "mcpServers": {
+    "modelrisk": {
+      "command": "C:/path/to/modelrisk-mcp.exe"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The ModelRisk tools appear under the connections icon. Full guide: [docs/claude-desktop.md](docs/claude-desktop.md). Claude Code setup: [docs/claude-code.md](docs/claude-code.md).
+
+---
+
+## Wire into Claude for Excel (HTTP transport)
+
+Claude for Excel runs inside an Office.js sandbox and can't spawn subprocesses, so it talks to MCP servers over HTTP. Start the server in HTTP mode:
+
+```powershell
+$env:MODELRISK_MCP_TOKEN = [Guid]::NewGuid().ToString("N") * 2
+modelrisk-mcp --transport=streamable-http --port=8000 --token=$env:MODELRISK_MCP_TOKEN
+```
+
+Then in Claude for Excel: Settings → Connectors → Add MCP server, URL `http://127.0.0.1:8000/mcp`, paste the token. Full guide: [docs/claude-for-excel.md](docs/claude-for-excel.md).
+
+**Why this is interesting:** Claude for Excel's sandbox can't reach Excel's COM surface or the ModelRisk ribbon on its own. ModelRisk MCP runs outside the sandbox and bridges that gap — Claude for Excel can do things via this server it structurally can't do otherwise (run simulations, dispatch ModelRisk COM, write distributions through the safety pipeline).
+
+---
+
+## First conversation
+
+Open a workbook in Excel that has at least one Vose function — even a single `=VoseNormal(0,1)`. Then in Claude:
+
+> Summarise the active workbook's risk model — inputs, outputs, distributions.
+
+Or jump straight into building:
+
+> /build-risk-model
+
+This walks through 9 steps, from identifying outputs through running the simulation and interpreting results. See [the slash-command catalogue](src/modelrisk_mcp/prompts) for the other workflows.
+
+---
+
+## Safety by design
+
+The server can both read *and* modify your workbook — that's the central differentiator. We make that safe with nine layered mechanisms (spec §11):
+
+1. **`dry_run=True` is the default** on every building tool. Claude must explicitly pass `dry_run=False` to commit. Previewing comes free; a forgotten flag becomes a preview, never an overwrite.
+2. **Every write lands in Excel's native undo stack.** `Ctrl+Z` works exactly as you'd expect.
+3. **Bulk-write guard.** Tools writing >50 cells in one call require explicit `confirm_bulk=True`. Time-series and copula tools — which write contiguous ranges by design — are exempt.
+4. **No automatic saves.** The server never calls `Workbook.Save()`. You control `Ctrl+S`.
+5. **No overwriting non-Vose formulas.** A formula-tokenised detector (not a substring check) refuses to overwrite a cell whose existing formula uses non-Vose functions. The one tool explicitly allowed to do this is `replace_constant_with_distribution`, by design.
+6. **Audit log** of every write in `%LOCALAPPDATA%\VoseSoftware\modelrisk-mcp\writes.log` — timestamp, cell, before/after formulas, before value. JSONL, append-only.
+7. **Read-only mode.** Launch with `--read-only` to disable every building/simulation tool.
+8. **Single-writer mutex.** Two MCP server instances can't drive the same Excel concurrently — the second instance raises `ConcurrentWriterError` on any building tool call.
+9. **Restore from audit log.** The `restore_cell` tool reads writes.log and rewrites the pre-write formula — even after Excel's undo stack has been cleared.
+
+---
+
+## What's inside
+
+- **35 tools** — 16 reading (incl. `read_vmrs` / `set_active_vmrs` / `list_vmrs_variables` / `get_samples`), 10 building, 2 simulation (`run_simulation` + `run_scenarios`), 1 restore (`restore_cell`), 6 workflow (incl. `diagnose_workbook` + `create_tornado_chart`)
+- **7 resources** — `modelrisk://functions`, `modelrisk://functions/{name}`, `modelrisk://distributions`, `modelrisk://methodology`, `modelrisk://workbook/current`, `modelrisk://workbook/current/sheet/{name}`, `modelrisk://audit-rules`
+- **5 slash-command prompts** — `/build-risk-model`, `/audit-model`, `/interpret-results`, `/add-uncertainty`, `/import-legacy-model`
+- **1417-entry function catalogue** extracted directly from the ModelRisk IDL + XLL header
+- **11 audit rules** with editable severity in `data/audit_rules.yaml`; add your own with `docs/authoring-audit-rules.md`
+- **Methodology-grounded distribution selection guide** in `data/distributions.yaml`
+
+---
+
+## Methodology
+
+The server is opinionated about Monte Carlo methodology — fetch `modelrisk://methodology` from any MCP client to read the 8 core principles. Highlights:
+
+- Every uncertain input is a distribution. Treating a noisy input as deterministic understates total uncertainty by exactly the amount it could swing.
+- Distribution fits use `uncertainty=TRUE`. Carry parameter uncertainty through the simulation; don't pretend the best-fit parameters are exact.
+- Risk events use `VoseRiskEvent`, not `probability * impact`. The bimodal nature matters.
+- Correlated inputs use copulas. Independent inputs that are actually correlated produce artificially tight outputs.
+
+---
+
+## Architecture
+
+Three internal layers plus two external integration paths:
+
+```
+┌──────────────────────────────────┐
+│  MCP client                      │
+│  (Claude Desktop, Code, etc.)    │
+└────────────────┬─────────────────┘
+                 │ JSON-RPC / stdio (or HTTP)
+                 ▼
+┌──────────────────────────────────┐
+│  FastMCP layer (tools, resources,│
+│   prompts)                       │
+├──────────────────────────────────┤
+│  ModelRiskBridge (domain)        │
+│  + SimulationController          │
+│  + ResultsReader                 │
+├──────────────────────────────────┤
+│  ExcelBridge      MrServiceBridge│
+│  (xlwings)        (ctypes)       │
+└──────┬───────────────────┬───────┘
+       │ Application.Run   │ MRLIB_*
+       │ + cell I/O        │ (read .vmrs)
+       ▼                   ▼
+┌──────────────┐   ┌──────────────────┐
+│ Excel +      │   │  MRService.dll   │
+│ ModelRisk XLL│   │  (SDK)           │
+└──────────────┘   └──────────────────┘
+```
+
+Two integration paths, each chosen for what it does best:
+
+- **Builds + simulation trigger** → Excel COM via xlwings, plus `Application.Run("VoseStartSimulCustom12", …)` for the simulation kickoff. Mirrors what the ModelRisk ATL does internally; bypasses the fragile ATL CoClass Dispatch surface that doesn't expose IDispatch.
+- **Results read** → MRService.dll directly via ctypes. Vose's official SDK opens `.vmrs` files, returns sample arrays, computes statistics. No COM round-trips per output; per-iteration sample arrays available for arbitrary downstream analysis.
+
+More: [docs/architecture.md](docs/architecture.md), [docs/com-surface.md](docs/com-surface.md).
+
+## Known caveats
+
+- **OneDrive-hosted workbooks**: xlwings can fail to resolve the workbook's full path without `ONEDRIVE_COMMERCIAL_WIN` set. The bridge degrades gracefully — name-based operations still work, and `run_simulation` defaults the `.vmrs` save location to the user's Desktop when the workbook folder can't be resolved.
+- **Active simulation results**: `get_simulation_results` reads from the `.vmrs` file produced by the most recent `run_simulation` call, or the most recent sibling `.vmrs` next to the workbook. Use `set_active_vmrs(path)` or `read_vmrs(path)` to point at a specific file.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Links
+
+- **Vose Software**: <https://www.vosesoftware.com>
+- **ModelRisk product page**: <https://www.vosesoftware.com/products/modelrisk/>
+- **Source**: <https://github.com/vosesoftware/modelrisk-mcp>
+- **Releases**: <https://github.com/vosesoftware/modelrisk-mcp/releases>
+- **Issues**: <https://github.com/vosesoftware/modelrisk-mcp/issues>
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
+- **MCP spec**: <https://modelcontextprotocol.io>