README
On PyPI
sdv-doc-waterloo is the published PyPI package that contains the Waterloo
Python package, the Sphinx extension, the MCP server, and the supporting
tooling.
Install it from PyPI:
pip install sdv-doc-waterloo
If you want to build the documentation with the Sphinx extension, install
the optional extra that provides the external sphinx dependency:
pip install "sdv-doc-waterloo[sphinx]"
Current status
Waterloo is under active development. Recent milestones include:
- MCP-Service with bearer-token authentication
Current work focuses on the MCP server:
- Authorizing JSON - generating docstring from special JSON data, for LLMs.
- Administration tooling
Quick tutorials
waterlint
waterlint is the main command-line tool for Waterloo Docstrings.
It validates docstrings, renders Waterloo JSON, generates helper output, and
supports the MCP-related workflows in this project.
Its JSON diagnostics are machine-readable and therefore well suited for CI
pipelines and GitHub workflows.
Start with the general help:
waterlint -h
For topic-specific help, use for example:
waterlint help --topic validate
waterlint help --topic render-json
waterlint help --topic render-docker
One important waterlint output path is the MCP server setup: the tool can
validate the server configuration and generate a Docker build script when you
want to package the server as an image.
Running the MCP server
The MCP server exposes Waterloo documentation data through the Model Context Protocol. It is tightly bound to the Waterloo JSON schema and provides tools that help generate and inspect Waterloo docstrings. It serves the bundled roots, object details, examples, references, and prompt templates so clients can inspect the documentation structure without parsing the JSON documents directly.
After installation, start the server in a terminal with:
wtrl_mcp
This launches the MCP server with the bundled default configuration. The
package installs a ready-to-use wtrl_mcp.toml next to the server code inside
site-packages/sdv/doc/waterloo/mcp/, so the default startup command works
without any repository checkout.
If you want to inspect or customize the configuration, point --config to a
copy of that file and adjust the roots, host, port, and allowed origins as
needed.
Registering the MCP server in Codex or Claude Code
Once the server is running, register it in your CLI client so it can reach the server without manual setup every time. The exact subcommand syntax depends on the CLI version, but the pattern is the same:
codex
codex mcp add myserver --url http://127.0.0.1:13316/mcp
claude
claude mcp add --transport http myserver http://127.0.0.1:13316/mcp
If you prefer localhost, use that host name instead of 127.0.0.1.
If the agent itself runs inside a container or on another host, replace the
address with the one that matches your deployment. The server name is only an
identifier for the client, so you can choose any name that is convenient for
you.
Rendering a Docker setup from the MCP configuration
If you want to ship the MCP server as a container, waterlint can generate a
Docker build script from the MCP configuration. For example:
waterlint render-docker --in src/sdv/doc/waterloo/mcp/wtrl_mcp.toml --out /tmp/myserver.docker
The generated script contains the Docker build steps and the runtime command line. It also prints a few practical hints, such as which port mapping to use and which host names should be allowed for the resulting server. After that, you can build the image with the generated script and run it in Docker.
Projects using Waterloo Docstrings
The following projects use Waterloo Docstrings in practice.
Human-readable HTML
3DE4 Python Scripting Interface
Interactive HTML documentation.
LLM-ready JSON
3DE4 Python Scripting Interface
Waterloo JSON documentation with examples.
1 maintainer
Metadata
1 maintainer
Release files for sdv-doc-waterloo 0.25.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sdv_doc_waterloo-0.25.0.tar.gz | 436.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sdv_doc_waterloo-0.25.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 941.1 kB
Release files / sdv_doc_waterloo-0.25.0.tar.gz
| Download URL | sdv_doc_waterloo-0.25.0.tar.gz |
|---|---|
| Size | 436.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8676f94d43fe167060aa8b63e24593f9fd0fc6448acd4b4c76ac4dc0537c66f6
|
|
BLAKE2b-256 checksum How to use checksums |
0aa446fa58ee95cbc81622517211b1b27a07999852c3d2d71b7e221967cea649
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / sdv_doc_waterloo-0.25.0-py3-none-any.whl
| Download URL | sdv_doc_waterloo-0.25.0-py3-none-any.whl |
|---|---|
| Size | 504.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a794e15ab8a6759af6420cc20b9cc7d4cd1146121557d618a85ba702390553e5
|
|
BLAKE2b-256 checksum How to use checksums |
f54f864b0531b3958f786ac0667c900c1adb969aa5084f63216d703c9c65c37e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
