ultraplot 2.6.0__tar.gz → 2.7.0__tar.gz

{ultraplot-2.6.0 → ultraplot-2.7.0}/.github/workflows/build-ultraplot.yml

@@ -53,9 +53,15 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: mamba-org/setup-micromamba@v3.1.0
+      - name: Prepare compatible test environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ inputs.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
+      - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
@@ -69,6 +75,14 @@ jobs:
       - name: Build Ultraplot
         run: |
           pip install --no-build-isolation --no-deps .
+          python - <<'PY'
+          import sys
+          import matplotlib, mpltern, pycirclize
+          assert sys.version_info[:2] == tuple(map(int, '${{ inputs.python-version }}'.split('.')))
+          assert matplotlib.__version__.startswith('${{ inputs.matplotlib-version }}.')
+          print('Python executable:', sys.executable)
+          print('Matplotlib:', matplotlib.__version__)
+          PY
 
   compare-baseline:
     name: Compare baseline Python ${{ inputs.python-version }} with MPL ${{ inputs.matplotlib-version }}
@@ -100,9 +114,15 @@ jobs:
 
       - uses: actions/checkout@v7
 
-      - uses: mamba-org/setup-micromamba@v3.1.0
+      - name: Prepare compatible test environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ inputs.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
+      - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
@@ -128,11 +148,26 @@ jobs:
           echo "base_sha=${BASE_SHA}" >> "${GITHUB_OUTPUT}"
           echo "Resolved baseline ref=${BASE_REF} sha=${BASE_SHA}"
 
+      - name: Check baseline version support
+        id: baseline-support
+        run: |
+          git show '${{ steps.baseline-ref.outputs.base_sha }}:pyproject.toml' > '${{ runner.temp }}/baseline-pyproject.toml'
+          python tools/ci/version_support.py \
+            --baseline-pyproject '${{ runner.temp }}/baseline-pyproject.toml' \
+            --python-version '${{ inputs.python-version }}' \
+            --matplotlib-version '${{ inputs.matplotlib-version }}' >> "$GITHUB_OUTPUT"
+
+      - name: Explain unavailable baseline
+        if: steps.baseline-support.outputs.baseline-supported != 'true'
+        run: |
+          echo '::notice::Image comparison skipped: the base commit does not support this Python/Matplotlib pair. PR tests still run in the coverage job.'
+          echo 'Image comparison skipped for Python ${{ inputs.python-version }} / Matplotlib ${{ inputs.matplotlib-version }}: base commit ${{ steps.baseline-ref.outputs.base_sha }} does not support this pair. The coverage job still tests the PR on this pair.' >> "$GITHUB_STEP_SUMMARY"
+
       # Cache Baseline Figures (Restore step)
       - name: Cache Baseline Figures
         id: cache-baseline
         uses: actions/cache@v6
-        if: ${{ env.IS_PR }}
+        if: env.IS_PR == 'true' && steps.baseline-support.outputs.baseline-supported == 'true'
         with:
           path: ./ultraplot/tests/baseline # The directory to cache
           # Key is based on OS, Python/Matplotlib versions, and the base commit SHA
@@ -143,7 +178,7 @@ jobs:
       # Conditional Baseline Generation (Only runs on cache miss)
       - name: Generate baseline from main
         # Skip this step if the cache was found (cache-hit is true)
-        if: steps.cache-baseline.outputs.cache-hit != 'true' || !env.IS_PR
+        if: steps.baseline-support.outputs.baseline-supported == 'true' && (steps.cache-baseline.outputs.cache-hit != 'true' || env.IS_PR != 'true')
         run: |
           mkdir -p ultraplot/tests/baseline
           echo "TEST_MODE=${TEST_MODE}"
@@ -219,6 +254,7 @@ jobs:
 
       # Image Comparison (Uses cached or newly generated baseline)
       - name: Image Comparison Ultraplot
+        if: steps.baseline-support.outputs.baseline-supported == 'true'
         run: |
           set -uo pipefail
           # This workflow runs in a login shell (bash -el), which executes

{ultraplot-2.6.0 → ultraplot-2.7.0}/.github/workflows/main.yml

@@ -22,6 +22,8 @@ jobs:
               - 'environment.yml'
               - '.github/workflows/**'
               - 'tools/ci/**'
+              - 'tools/expand_docstrings.py'
+              - 'setup.py'
 
   select-tests:
     runs-on: ubuntu-latest
@@ -50,7 +52,7 @@ jobs:
 
       - name: Build test map on cache miss
         if: steps.restore-map.outputs.cache-hit != 'true'
-        uses: mamba-org/setup-micromamba@v3.1.0
+        uses: mamba-org/setup-micromamba@v3.2.1
         with:
           environment-file: ./environment.yml
           init-shell: bash
@@ -99,6 +101,8 @@ jobs:
             --always-full 'pyproject.toml' \
             --always-full 'environment.yml' \
             --always-full 'ultraplot/__init__.py' \
+            --always-full 'tools/expand_docstrings.py' \
+            --always-full 'setup.py' \
             --ignore 'docs/**' \
             --ignore 'README.rst'
           echo "Selection output:"
@@ -138,12 +142,55 @@ jobs:
           echo "Detected test matrix: $(echo "$OUTPUT" | jq -c '.test_matrix')"
           python tools/ci/version_support.py --format github-output >> $GITHUB_OUTPUT
 
+  static-api:
+    name: Static API and installed docstrings
+    runs-on: ubuntu-latest
+    needs:
+      - run-if-changes
+    if: always() && needs.run-if-changes.outputs.run == 'true'
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install built package and check static API
+        run: |
+          pip install ".[typing]"
+          mkdir -p /tmp/ultraplot-static
+          cp tools/ci/static_consumer.py /tmp/ultraplot-static/consumer.py
+          cp tools/ci/check_installed_docstrings.py /tmp/ultraplot-static/check_docstrings.py
+          (
+            cd /tmp/ultraplot-static
+            basedpyright consumer.py --outputjson > basedpyright.json || true
+            python - <<'PY'
+          import json
+
+          report = json.load(open("/tmp/ultraplot-static/basedpyright.json", encoding="utf-8"))
+          summary = report["summary"]
+          print(
+              f"BasedPyright: {summary['errorCount']} errors, "
+              f"{summary['warningCount']} warnings"
+          )
+          if summary["errorCount"]:
+              raise SystemExit(1)
+          PY
+            python check_docstrings.py
+          )
+
   coverage:
-    name: Coverage
+    name: Coverage Python ${{ matrix.python-version }} / MPL ${{ matrix.matplotlib-version }}
     runs-on: ubuntu-latest
     needs:
       - run-if-changes
-    if: always() && needs.run-if-changes.outputs.run == 'true' && github.event_name == 'pull_request'
+      - get-versions
+    if: always() && needs.run-if-changes.outputs.run == 'true' && needs.get-versions.result == 'success' && github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.get-versions.outputs.test-matrix) }}
     defaults:
       run:
         shell: bash -el {0}
@@ -157,25 +204,41 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: mamba-org/setup-micromamba@v3.1.0
+      - name: Prepare compatible coverage environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ matrix.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
+      - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
           create-args: >-
             --verbose
-            python=3.10
-            matplotlib=3.9
+            python=${{ matrix.python-version }}
+            matplotlib=${{ matrix.matplotlib-version }}
           cache-environment: true
           cache-downloads: false
 
       - name: Build Ultraplot
         run: |
-          pip install --no-build-isolation --no-deps .
+          pip install --no-build-isolation ".[mcp]"
 
       - name: Run full coverage suite
         run: |
+          python - <<'PY'
+          import sys
+          from importlib.metadata import version
+          import matplotlib, mpltern, pycirclize
+          assert sys.version_info[:2] == tuple(map(int, '${{ matrix.python-version }}'.split('.')))
+          assert matplotlib.__version__.startswith('${{ matrix.matplotlib-version }}.')
+          print('Python executable:', sys.executable)
+          for package in ('matplotlib', 'mpltern', 'pycirclize', 'cartopy'):
+              print(f'{package}: {version(package)}')
+          PY
           pytest -q --tb=short --disable-warnings -n auto -p pytest_cov \
             --cov=ultraplot --cov-branch --cov-context=test \
             --cov-report=xml:coverage.xml --cov-report= \
@@ -186,7 +249,7 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
-          name: codecov-pr-python3.10-mpl3.9
+          name: codecov-pr-python${{ matrix.python-version }}-mpl${{ matrix.matplotlib-version }}
 
   build:
     needs:
@@ -212,7 +275,9 @@ jobs:
   build-success:
     needs:
       - build
+      - coverage
       - run-if-changes
+      - static-api
     if: always()
     runs-on: ubuntu-latest
     steps:
@@ -220,7 +285,7 @@ jobs:
           if [[ '${{ needs.run-if-changes.outputs.run }}' == 'false' ]]; then
             echo "No changes detected, tests skipped."
           else
-            if [[ '${{ needs.build.result }}' == 'success' ]]; then
+            if [[ '${{ needs.build.result }}' == 'success' && '${{ needs.static-api.result }}' == 'success' ]]; then
               echo "All tests passed successfully!"
             else
               echo "Tests failed!"

{ultraplot-2.6.0 → ultraplot-2.7.0}/.github/workflows/test-map.yml

@@ -23,7 +23,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: mamba-org/setup-micromamba@v3.1.0
+      - uses: mamba-org/setup-micromamba@v3.2.1
         with:
           environment-file: ./environment.yml
           init-shell: bash

{ultraplot-2.6.0 → ultraplot-2.7.0}/.gitignore

@@ -22,7 +22,12 @@ docs/_build
 docs/_static/ultraplotrc
 docs/_static/rctable.rst
 docs/_static/*
+!docs/_static/alias-explorer-v3.css
+!docs/_static/alias-explorer-v3.js
+!docs/_static/alias-map.svg
 !docs/_static/why_plots/
+!docs/_static/example_plots/
+!docs/_static/example_plots/data_aware_example.svg
 *.html
 docs/gallery/
 docs/sg_execution_times.rst

{ultraplot-2.6.0 → ultraplot-2.7.0}/.pre-commit-config.yaml

@@ -14,3 +14,11 @@ repos:
     rev: 26.5.1
     hooks:
       - id: black
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v1.5.2
+    hooks:
+      - id: tombi-format
+        args: ["--offline"]
+      - id: tombi-lint
+        args: ["--offline"]

{ultraplot-2.6.0 → ultraplot-2.7.0}/INSTALL.rst

@@ -10,13 +10,19 @@ with ``pip`` or ``conda`` as follows:
    pip install ultraplot
    conda install -c conda-forge ultraplot
 
-The default install includes optional features (for example, pyCirclize-based plots).
-For a minimal install, use ``--no-deps`` and install the core requirements:
+pyCirclize-based plots require the optional ``circos`` extra:
 
 .. code-block:: bash
 
-   pip install ultraplot --no-deps
-   pip install -r requirements-minimal.txt
+   pip install 'ultraplot[circos]'
+
+The ``docs`` extra also includes pyCirclize for building the documentation.
+
+To install all optional dependency groups (``circos``, ``docs``, and ``stats``):
+
+.. code-block:: bash
+
+   pip install 'ultraplot[all]'
 
 Likewise, an existing installation of ultraplot can be upgraded to the latest version with:
 

{ultraplot-2.6.0/ultraplot.egg-info → ultraplot-2.7.0}/PKG-INFO

@@ -1,48 +1,55 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.6.0
+Version: 2.7.0
 Summary: A succinct matplotlib wrapper for making beautiful, publication-quality graphics.
 Author-email: Casper van Elteren <caspervanelteren@gmail.com>, Luke Davis <lukelbd@gmail.com>
 Maintainer-email: Casper van Elteren <caspervanelteren@gmail.com>, "Matthew R. Becker" <becker.mr@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Documentation, https://ultraplot.readthedocs.io
 Project-URL: Issue Tracker, https://github.com/ultraplot/ultraplot/issues
 Project-URL: Source Code, https://github.com/ultraplot/ultraplot
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
+Classifier: Framework :: Matplotlib
 Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Classifier: Framework :: Matplotlib
 Requires-Python: <3.15,>=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
+Requires-Dist: matplotlib<3.12,>=3.9
 Requires-Dist: numpy>=1.26.0
-Requires-Dist: matplotlib<3.11,>=3.9
-Requires-Dist: pycirclize>=1.10.1
 Requires-Dist: typing-extensions; python_version < "3.12"
+Provides-Extra: all
+Requires-Dist: ultraplot[circos,docs,stats]; extra == "all"
+Provides-Extra: circos
+Requires-Dist: pycirclize>=1.10.1; extra == "circos"
 Provides-Extra: docs
 Requires-Dist: jupyter; extra == "docs"
 Requires-Dist: jupytext; extra == "docs"
 Requires-Dist: lxml-html-clean; extra == "docs"
 Requires-Dist: markdown; extra == "docs"
 Requires-Dist: mpltern; extra == "docs"
-Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: pycirclize>=1.10.1; extra == "docs"
+Requires-Dist: nbsphinx>=0.9.8; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx-autoapi; extra == "docs"
-Requires-Dist: sphinx-automodapi; extra == "docs"
+Requires-Dist: sphinx-automodapi>=0.22; extra == "docs"
 Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: sphinx-design>=0.7; extra == "docs"
 Requires-Dist: sphinx-gallery; extra == "docs"
 Requires-Dist: shibuya; extra == "docs"
 Requires-Dist: sphinx-sitemap; extra == "docs"
 Requires-Dist: typing-extensions; extra == "docs"
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.1; extra == "mcp"
 Provides-Extra: stats
 Requires-Dist: scipy; extra == "stats"
+Provides-Extra: typing
+Requires-Dist: basedpyright==1.31.4; extra == "typing"
 Dynamic: license-file
 
 .. image:: https://raw.githubusercontent.com/Ultraplot/ultraplot/refs/heads/main/UltraPlotLogo.svg
@@ -151,13 +158,19 @@ UltraPlot is published on `PyPi <https://pypi.org/project/ultraplot/>`__ and
    pip install ultraplot
    conda install -c conda-forge ultraplot
 
-The default install includes optional features (for example, pyCirclize-based plots).
-For a minimal install, use ``--no-deps`` and install the core requirements:
+pyCirclize-based plots require the optional ``circos`` extra:
 
 .. code-block:: bash
 
-   pip install ultraplot --no-deps
-   pip install -r requirements-minimal.txt
+   pip install 'ultraplot[circos]'
+
+The ``docs`` extra also includes pyCirclize for building the documentation.
+
+To install the ``circos``, ``docs``, and ``stats`` dependency groups together:
+
+.. code-block:: bash
+
+   pip install 'ultraplot[all]'
 
 Likewise, an existing installation of UltraPlot can be upgraded
 to the latest version with:
@@ -172,6 +185,113 @@ To install a development version of UltraPlot, you can use
 or clone the repository and run ``pip install -e .``
 inside the ``ultraplot`` folder.
 
+MCP server
+==========
+
+UltraPlot includes a Model Context Protocol (MCP) server that lets AI assistants
+search documentation and examples, inspect the live Python API, and read source
+code and release notes.
+
+Run directly with uvx
+---------------------
+
+With `uv <https://docs.astral.sh/uv/getting-started/installation/>`__ installed,
+your MCP client can launch the server with ``uvx``. uv installs the package and
+its dependencies in an isolated environment automatically, so you do not need
+to create a virtual environment or install UltraPlot separately.
+
+For a PyPI release containing the MCP server, the launch command is:
+
+.. code-block:: bash
+
+   uvx --from 'ultraplot[mcp]' ultraplot-mcp
+
+For clients that use an ``mcpServers`` configuration, add:
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "ultraplot": {
+         "command": "uvx",
+         "args": ["--from", "ultraplot[mcp]", "ultraplot-mcp"]
+       }
+     }
+   }
+
+The client starts the server when needed and communicates with it over stdio.
+Other clients may use a different configuration format; use the same command
+and arguments. ``uvx`` is equivalent to ``uv tool run``.
+
+Until the MCP server is released on PyPI, run it directly from the feature
+branch instead:
+
+.. code-block:: bash
+
+   uvx --from 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp' ultraplot-mcp
+
+For this development version, replace ``ultraplot[mcp]`` in the client
+configuration with
+``ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp``.
+
+Install persistently with uv
+----------------------------
+
+Alternatively, keep the executable on your ``PATH`` by installing it as a uv
+tool. For a PyPI release containing the MCP server:
+
+.. code-block:: bash
+
+   uv tool install 'ultraplot[mcp]'
+   ultraplot-mcp --help
+
+Before that release, install from the feature branch:
+
+.. code-block:: bash
+
+   uv tool install 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp'
+
+Then configure your client to launch ``ultraplot-mcp`` with no arguments.
+If uv reports that its executable directory is missing from ``PATH``, run
+``uv tool update-shell`` and restart your shell.
+
+Install from a checkout
+-----------------------
+
+From a checkout containing the MCP implementation, install the optional ``mcp``
+extra in the Python environment you want the server to use:
+
+.. code-block:: bash
+
+   pip install -e '.[mcp]'
+
+Connect an MCP client
+---------------------
+
+After installing persistently with uv or pip, register the server with an
+installed Codex CLI:
+
+.. code-block:: bash
+
+   ultraplot-mcp install codex
+
+Restart Codex after registration. Try asking it to search the UltraPlot
+examples for shared colorbars or inspect ``ultraplot.subplots``.
+
+For other MCP clients, configure a stdio server with ``ultraplot-mcp`` as the
+command and no arguments. Use the executable's absolute path if the client does
+not inherit your Python environment's ``PATH``. Running ``ultraplot-mcp`` starts
+the server; ``ultraplot-mcp --help`` lists the available commands.
+
+Documentation tools read the checkout's ``docs`` directory. Direct uvx and uv
+tool installations require a separate documentation checkout for these tools.
+If documentation lives elsewhere, set ``ULTRAPLOT_MCP_DOCS`` to its absolute path in the MCP
+client's server environment. Documentation is not currently bundled in the
+Python package; API and source inspection use the installed UltraPlot version.
+
+Citing UltraPlot
+================
+
 If you use UltraPlot in your research, please cite the latest release metadata in
 ``CITATION.cff``. GitHub can export this metadata as BibTeX from the
 repository's "Cite this repository" panel, and the Zenodo badge below points to

{ultraplot-2.6.0 → ultraplot-2.7.0}/README.rst

@@ -104,13 +104,19 @@ UltraPlot is published on `PyPi <https://pypi.org/project/ultraplot/>`__ and
    pip install ultraplot
    conda install -c conda-forge ultraplot
 
-The default install includes optional features (for example, pyCirclize-based plots).
-For a minimal install, use ``--no-deps`` and install the core requirements:
+pyCirclize-based plots require the optional ``circos`` extra:
 
 .. code-block:: bash
 
-   pip install ultraplot --no-deps
-   pip install -r requirements-minimal.txt
+   pip install 'ultraplot[circos]'
+
+The ``docs`` extra also includes pyCirclize for building the documentation.
+
+To install the ``circos``, ``docs``, and ``stats`` dependency groups together:
+
+.. code-block:: bash
+
+   pip install 'ultraplot[all]'
 
 Likewise, an existing installation of UltraPlot can be upgraded
 to the latest version with:
@@ -125,6 +131,113 @@ To install a development version of UltraPlot, you can use
 or clone the repository and run ``pip install -e .``
 inside the ``ultraplot`` folder.
 
+MCP server
+==========
+
+UltraPlot includes a Model Context Protocol (MCP) server that lets AI assistants
+search documentation and examples, inspect the live Python API, and read source
+code and release notes.
+
+Run directly with uvx
+---------------------
+
+With `uv <https://docs.astral.sh/uv/getting-started/installation/>`__ installed,
+your MCP client can launch the server with ``uvx``. uv installs the package and
+its dependencies in an isolated environment automatically, so you do not need
+to create a virtual environment or install UltraPlot separately.
+
+For a PyPI release containing the MCP server, the launch command is:
+
+.. code-block:: bash
+
+   uvx --from 'ultraplot[mcp]' ultraplot-mcp
+
+For clients that use an ``mcpServers`` configuration, add:
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "ultraplot": {
+         "command": "uvx",
+         "args": ["--from", "ultraplot[mcp]", "ultraplot-mcp"]
+       }
+     }
+   }
+
+The client starts the server when needed and communicates with it over stdio.
+Other clients may use a different configuration format; use the same command
+and arguments. ``uvx`` is equivalent to ``uv tool run``.
+
+Until the MCP server is released on PyPI, run it directly from the feature
+branch instead:
+
+.. code-block:: bash
+
+   uvx --from 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp' ultraplot-mcp
+
+For this development version, replace ``ultraplot[mcp]`` in the client
+configuration with
+``ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp``.
+
+Install persistently with uv
+----------------------------
+
+Alternatively, keep the executable on your ``PATH`` by installing it as a uv
+tool. For a PyPI release containing the MCP server:
+
+.. code-block:: bash
+
+   uv tool install 'ultraplot[mcp]'
+   ultraplot-mcp --help
+
+Before that release, install from the feature branch:
+
+.. code-block:: bash
+
+   uv tool install 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp'
+
+Then configure your client to launch ``ultraplot-mcp`` with no arguments.
+If uv reports that its executable directory is missing from ``PATH``, run
+``uv tool update-shell`` and restart your shell.
+
+Install from a checkout
+-----------------------
+
+From a checkout containing the MCP implementation, install the optional ``mcp``
+extra in the Python environment you want the server to use:
+
+.. code-block:: bash
+
+   pip install -e '.[mcp]'
+
+Connect an MCP client
+---------------------
+
+After installing persistently with uv or pip, register the server with an
+installed Codex CLI:
+
+.. code-block:: bash
+
+   ultraplot-mcp install codex
+
+Restart Codex after registration. Try asking it to search the UltraPlot
+examples for shared colorbars or inspect ``ultraplot.subplots``.
+
+For other MCP clients, configure a stdio server with ``ultraplot-mcp`` as the
+command and no arguments. Use the executable's absolute path if the client does
+not inherit your Python environment's ``PATH``. Running ``ultraplot-mcp`` starts
+the server; ``ultraplot-mcp --help`` lists the available commands.
+
+Documentation tools read the checkout's ``docs`` directory. Direct uvx and uv
+tool installations require a separate documentation checkout for these tools.
+If documentation lives elsewhere, set ``ULTRAPLOT_MCP_DOCS`` to its absolute path in the MCP
+client's server environment. Documentation is not currently bundled in the
+Python package; API and source inspection use the installed UltraPlot version.
+
+Citing UltraPlot
+================
+
 If you use UltraPlot in your research, please cite the latest release metadata in
 ``CITATION.cff``. GitHub can export this metadata as BibTeX from the
 repository's "Cite this repository" panel, and the Zenodo badge below points to