[codex] Add experimental MCP rollout and demo notebook

.github/workflows/ci.yml

@@ -113,6 +113,9 @@ jobs:
           print(load_las, load_dlis, MatplotlibRenderer, PlotlyRenderer)
           PY
 
+      - name: Run MCP tests with optional dependencies
+        run: uv run python -m unittest tests.test_mcp_service tests.test_mcp_server -v
+
   package:
     name: Package Build and Wheel Smoke Test
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -82,6 +82,20 @@ jobs:
           MPLBACKEND: Agg
         run: ./.release-venv/bin/python scripts/smoke_installed_wheel.py
 
+      - name: Create clean MCP release-test environment
+        run: python -m venv .release-mcp-venv
+
+      - name: Install built wheel with MCP dependency into clean environment
+        run: |
+          ./.release-mcp-venv/bin/pip install --upgrade pip
+          ./.release-mcp-venv/bin/pip install dist/*.whl
+          ./.release-mcp-venv/bin/pip install "mcp>=1,<2"
+
+      - name: Run installed-wheel smoke test with MCP support
+        env:
+          MPLBACKEND: Agg
+        run: ./.release-mcp-venv/bin/python scripts/smoke_installed_wheel.py
+
       - name: Upload release artifacts
         uses: actions/upload-artifact@v7
         with:

CHANGELOG.md

@@ -23,6 +23,46 @@ This changelog tracks public release notes for the `wellplot` distribution.
 
 The entries below track public PyPI releases of the `wellplot` distribution.
 
+## [0.3.0] - 2026-04-28
+
+Experimental MCP support is now part of the public `wellplot` distribution.
+This release folds the planned scoped-preview and writable-authoring MCP slices
+into one publishable version.
+
+### Added
+
+- Optional `wellplot[mcp]` install extra and `wellplot-mcp` stdio entry point
+  for local MCP clients.
+- MCP tools for logfile validation, inspection, generic preview rendering,
+  explicit section/track/window PNG previews, explicit file rendering, example
+  bundle export, and canonical logfile YAML validation/format/save flows.
+- Packaged MCP resources for the logfile schema and curated production example
+  bundles, plus guided prompts for logfile review, preview, and example-based
+  starts.
+- Public MCP user documentation covering installation, client registration,
+  server-root policy, workflow usage, and API reference.
+
+### Changed
+
+- Release verification now smoke-tests both the base installed wheel and a
+  clean environment with the optional MCP dependency enabled.
+- Maintainer release guidance now includes MCP-specific preflight checks and a
+  TestPyPI rehearsal recommendation for releases that change the MCP surface or
+  verification path.
+
+### Fixed
+
+- Scoped section and track previews now preserve implicit bindings for
+  single-section savefiles, preventing filtered render failures during MCP
+  preview calls.
+
+### Notes
+
+- MCP remains experimental in this release.
+- `format_logfile_text(...)` and `save_logfile_text(...)` normalize the logfile
+  through the canonical serializer path; comments, anchors, and template
+  indirection are not preserved in the returned YAML text.
+
 ## [0.1.0] - 2026-04-22
 
 Initial public release of `wellplot` as an open-source Python toolkit for

README.md

@@ -16,6 +16,8 @@ This repository currently contains the current MVP baseline:
 - a physical page layout engine
 - optional `matplotlib` and `plotly` renderer backends
 - optional LAS and DLIS ingestion adapters
+- optional experimental MCP server support for local logfile validation,
+  previews, starter example export, and canonical YAML save workflows
 - DLIS VDL/WF1-style array support with derived micro-time sample axes
 - printable VDL density and waveform array rendering
 - scale-aware curve fills, including crossover, limit, and baseline modes
@@ -93,9 +95,10 @@ The intended workflow is:
 - render a full report or a partial view
 - optionally serialize the layout back to YAML
 
-The next development phase adds two public API surfaces on top of those layers:
-- dataset ingestion for computed numpy/pandas results
-- programmatic composition/rendering so users can build logs without hand-authoring YAML
+The public interaction layers now sit on top of that same render pipeline:
+- YAML templates and savefiles for declarative jobs
+- the Python surfaces exposed through `wellplot` and `wellplot.api`
+- the experimental stdio MCP server exposed through `wellplot[mcp]`
 
 Track types are explicit: `reference`, `normal`, `array`, and `annotation`
 (with compatibility aliases `depth`, `curve`, `image`).
@@ -128,6 +131,7 @@ python -m pip install "wellplot[dlis]"
 python -m pip install "wellplot[pandas]"
 python -m pip install "wellplot[interactive]"
 python -m pip install "wellplot[notebook]"
+python -m pip install "wellplot[mcp]"
 ```
 
 Common example-workflow installs:
@@ -138,6 +142,44 @@ python -m pip install "wellplot[dlis,notebook]"
 python -m pip install "wellplot[las,dlis,pandas,notebook,interactive,units]"
 ```
 
+## Experimental MCP Server
+
+The optional MCP surface is experimental and is exposed only through the
+optional dependency extra and the stdio entry point.
+
+Install it with:
+
+```bash
+python -m pip install "wellplot[mcp]"
+```
+
+The server root is fixed to the current working directory when `wellplot-mcp`
+starts. Logfile paths, referenced source data, exported example bundles, saved
+YAML files, and explicit render outputs must all resolve inside that root.
+
+Typical client registration:
+
+```json
+{
+  "mcpServers": {
+    "wellplot": {
+      "command": "wellplot-mcp",
+      "cwd": "/absolute/path/to/job-root"
+    }
+  }
+}
+```
+
+The MCP tool surface currently supports:
+- `validate_logfile` and `inspect_logfile`
+- `preview_logfile_png` plus explicit section/track/window preview tools
+- `render_logfile_to_file`
+- `export_example_bundle`
+- `validate_logfile_text`, `format_logfile_text`, and `save_logfile_text`
+
+Packaged example resources and guided prompts are also exposed for MCP-aware
+clients.
+
 ## Contributor Development Workflow
 
 This project uses `uv` for environment management and dependency resolution.
@@ -172,6 +214,7 @@ Run tests:
 
 ```bash
 uv run python -m unittest discover -s tests -v
+uv run --with mcp pytest tests/test_mcp_service.py tests/test_mcp_server.py
 ```
 
 Build and smoke-test the wheel:
@@ -183,6 +226,11 @@ python -m venv .smoke-venv
 ./.smoke-venv/bin/pip install dist/*.whl
 ./.smoke-venv/bin/wellplot --help
 MPLBACKEND=Agg ./.smoke-venv/bin/python scripts/smoke_installed_wheel.py
+
+python -m venv .smoke-venv-mcp
+./.smoke-venv-mcp/bin/pip install --upgrade pip
+./.smoke-venv-mcp/bin/pip install dist/*.whl "mcp>=1,<2"
+MPLBACKEND=Agg ./.smoke-venv-mcp/bin/python scripts/smoke_installed_wheel.py
 ```
 
 Format and lint:
@@ -250,6 +298,8 @@ Current examples:
 - [examples/api_partial_render_demo.py](examples/api_partial_render_demo.py)
 - [examples/api_notebook_bytes_demo.py](examples/api_notebook_bytes_demo.py)
 - [examples/api_serialize_demo.py](examples/api_serialize_demo.py)
+- [examples/mcp_workflow_demo.py](examples/mcp_workflow_demo.py)
+- [examples/notebooks/developer/mcp_workflow_demo.ipynb](examples/notebooks/developer/mcp_workflow_demo.ipynb)
 
 Important current boundary:
 - `document_*` helpers round-trip the normalized `LogDocument` template shape

docs/mcp-plan.md

@@ -0,0 +1,115 @@
+# MCP Rollout Status
+
+Last updated: 2026-04-28
+
+## Purpose
+
+This document is the live repo-local status document for the experimental
+`wellplot` MCP surface.
+
+The original extracted v1 plan has now been implemented and extended. This file
+tracks what is actually in the repository, what release it is being prepared
+for, and what still requires maintainer action outside the repo.
+
+## Release Status
+
+- Repo target version: `0.3.0`
+- Public status: experimental
+- Transport: stdio-first through `wellplot-mcp`
+- Packaging:
+  - optional extra: `wellplot[mcp]`
+  - console entry point: `wellplot-mcp`
+- Release note boundary:
+  - the originally planned scoped-preview slice and writable-authoring slice
+    landed together in the current tree and are being released together as
+    `0.3.0`
+
+## Implemented Surface
+
+### Tools
+
+- `validate_logfile(logfile_path)`
+- `inspect_logfile(logfile_path)`
+- `preview_logfile_png(...)`
+- `preview_section_png(logfile_path, section_id, page_index=0, dpi=144)`
+- `preview_track_png(logfile_path, section_id, track_ids, page_index=0, dpi=144, depth_range=None, depth_range_unit=None)`
+- `preview_window_png(logfile_path, depth_range, depth_range_unit=None, page_index=0, dpi=144, section_ids=None)`
+- `render_logfile_to_file(logfile_path, output_path, overwrite=False)`
+- `export_example_bundle(example_id, output_dir, overwrite=False)`
+- `validate_logfile_text(yaml_text, base_dir=None)`
+- `format_logfile_text(yaml_text, base_dir=None)`
+- `save_logfile_text(yaml_text, output_path, overwrite=False, base_dir=None)`
+
+### Resources
+
+- `wellplot://schema/logfile.json`
+- `wellplot://examples/production/index.json`
+- `wellplot://examples/production/{example_id}/README.md`
+- `wellplot://examples/production/{example_id}/base.template.yaml`
+- `wellplot://examples/production/{example_id}/full_reconstruction.log.yaml`
+- `wellplot://examples/production/{example_id}/data-notes.md`
+
+Packaged example ids:
+
+- `cbl_log_example`
+- `forge16b_porosity_example`
+
+### Prompts
+
+- `review_logfile(logfile_path)`
+- `preview_logfile(logfile_path, focus=None)`
+- `start_from_example(example_id, goal)`
+
+## Behavior and Safety Notes
+
+- The server root is the current working directory when `wellplot-mcp` starts.
+- File-based tools may only read from and write to paths that resolve inside
+  that root.
+- Preview tools are read-only and always return in-memory PNG content rendered
+  through Matplotlib.
+- Explicit writes only happen through:
+  - `render_logfile_to_file(...)`
+  - `export_example_bundle(...)`
+  - `save_logfile_text(...)`
+- `validate_logfile_text(...)`, `format_logfile_text(...)`, and
+  `save_logfile_text(...)` accept unsaved full logfile YAML text. When
+  `base_dir` is provided, relative template and data references are resolved
+  from that directory under the server root.
+- `format_logfile_text(...)` and `save_logfile_text(...)` normalize the logfile
+  through the canonical serializer path. They do not preserve comments,
+  anchors, original formatting, or template indirection.
+
+## Implementation Notes
+
+- `wellplot` and `wellplot.api` import surfaces remain unchanged.
+- The implementation lives in:
+  - `src/wellplot/mcp/server.py`
+  - `src/wellplot/mcp/service.py`
+  - packaged example assets under `src/wellplot/mcp/assets/`
+- Release verification now includes:
+  - base installed-wheel smoke coverage
+  - a second clean-environment smoke path with the optional MCP dependency
+    enabled
+- Scoped preview filtering now preserves implicit bindings for single-section
+  savefiles, which was necessary for reliable section/track MCP previews.
+
+## Verification In Repo
+
+Primary coverage now includes:
+
+- service-layer tests in `tests/test_mcp_service.py`
+- stdio integration and registration tests in `tests/test_mcp_server.py`
+- installed-wheel smoke coverage in `scripts/smoke_installed_wheel.py`
+- release workflow MCP verification in `.github/workflows/release.yml`
+- public documentation pages under `docs/site/`
+
+## Remaining Maintainer Actions
+
+The following actions are intentionally outside this repo-local implementation
+document and still need to happen through the normal release flow:
+
+1. Run the GitHub `Release` workflow with `publish_target=verify-only`.
+2. Run a TestPyPI rehearsal for `0.3.0`.
+3. Publish `0.3.0` to PyPI.
+4. Let the merged documentation changes publish through the normal docs path to
+   Read the Docs and the GitHub Pages mirror.

docs/release-process.md

@@ -23,7 +23,7 @@ The manual workflow accepts:
    - `testpypi`
    - `pypi`
 2. `expected_version`
-   - optional version guard such as `0.1.0`
+   - optional version guard such as `0.3.0`
    - if provided, the workflow checks it against `src/wellplot/_version.py`
 
 ## What The Workflow Does
@@ -34,11 +34,14 @@ The `build` job always runs first:
 2. sets up Python and `uv`
 3. optionally verifies the requested version
 4. runs `uv build`
-5. creates a clean virtual environment
+5. creates a clean virtual environment for the base wheel
 6. installs the built wheel into that clean environment
 7. verifies the `wellplot` console entry point
 8. runs `scripts/smoke_installed_wheel.py`
-9. uploads the built artifacts for later publish jobs
+9. creates a second clean virtual environment for MCP verification
+10. installs the built wheel plus `mcp>=1,<2`
+11. reruns `scripts/smoke_installed_wheel.py` with MCP support enabled
+12. uploads the built artifacts for later publish jobs
 
 Publishing jobs only run when selected:
 
@@ -76,12 +79,17 @@ Run the local validation path first:
 
 ```bash
 uv run ruff check .
-uv run python -m unittest discover -s tests -v
+uv run pytest tests/test_mcp_service.py tests/test_mcp_server.py tests/test_pipeline.py tests/test_cli.py tests/test_public_api.py
+uv run --with mcp pytest tests/test_mcp_server.py
+uv run --group docs mkdocs build --strict
 uv build
 uv venv /tmp/wellplot-release-check
 uv pip install --python /tmp/wellplot-release-check/bin/python dist/*.whl
 /tmp/wellplot-release-check/bin/wellplot --help
 MPLBACKEND=Agg /tmp/wellplot-release-check/bin/python scripts/smoke_installed_wheel.py
+uv venv /tmp/wellplot-release-check-mcp
+uv pip install --python /tmp/wellplot-release-check-mcp/bin/python dist/*.whl "mcp>=1,<2"
+MPLBACKEND=Agg /tmp/wellplot-release-check-mcp/bin/python scripts/smoke_installed_wheel.py
 ```
 
 ## Maintenance Release Sequence
@@ -92,7 +100,8 @@ MPLBACKEND=Agg /tmp/wellplot-release-check/bin/python scripts/smoke_installed_wh
 4. Trigger the `Release` workflow with:
    - `publish_target=verify-only`
    - `expected_version=<current version>`
-5. Optionally rehearse on TestPyPI if the workflow, metadata, or dependencies changed in a risky way.
+5. Rehearse on TestPyPI when the workflow, metadata, optional dependencies, or
+   MCP verification path changed in a risky way.
 6. Trigger the `Release` workflow with:
    - `publish_target=pypi`
    - `expected_version=<current version>`
@@ -106,6 +115,14 @@ python -m venv /tmp/wellplot-pypi-check
 /tmp/wellplot-pypi-check/bin/wellplot --help
 ```
 
+Experimental MCP install verification:
+
+```bash
+python -m venv /tmp/wellplot-pypi-check-mcp
+/tmp/wellplot-pypi-check-mcp/bin/pip install "wellplot[mcp]"
+/tmp/wellplot-pypi-check-mcp/bin/python scripts/smoke_installed_wheel.py
+```
+
 Optional TestPyPI install verification:
 
 ```bash
@@ -124,3 +141,5 @@ The first public PyPI release has been completed. Future work is maintenance:
 - keep trusted publishing claims aligned with repository and environment names
 - update the changelog before each release
 - verify the public PyPI install after each release
+- keep the optional MCP smoke path working whenever the experimental MCP
+  surface changes