docs(notebook): add guided tour of the IoT MCP tools

[MannXo]

Description

A single notebook that walks a first-time user through every tool on the IoT MCP server, using the ToolUniverse three-step contract. Aimed at the KDD tutorial audience described in #452: someone who has Docker and the default dataset up and wants to understand what the IoT server can actually do.

notebook/showcase_iot_mcp_tools.ipynb, 41 cells:

1. Connect — init → load_tools → run, namespacing, why the first call is slow
2. Discovery — list_tools, find_tools, tool_specification
3. Sites and assets — sites, asset_ids, assets (with the assettype filter), asset_detail
4. Sensor inventory — installed_sensors vs measured_sensors, sensor_coverage, and the reverse lookup find_assets_by_sensors
5. The data — stream_extent first (so a history call is never a surprise), then latest_reading, sensor_stats, and paginated history
6. Plot — a sensor trace through pandas and matplotlib
7. Workflow — chaining five tools into one asset_snapshot registered with tu.register_workflow() and invoked through the same tu.run() entrypoint
8. Cleanup and a tool-reference table

All 12 tools are covered. docs/tool_universe.md gets a one-line pointer so the notebook is findable.

The section on installed_sensors vs measured_sensors sweeps the whole site rather than one asset, because the default dataset happens to contain two genuinely different disagreements worth teaching:

• Motor_01 has Vibration_X in the registry that never reports
• Chiller 6 has matching counts but mismatched names: Oil Pressure in the registry, Run Status in the telemetry

Changes

• Dependency update (uv lock)
• Documentation / Tutorial update
• Refactoring (no logic change)

Related: Refs #452

Verification

Executed end to end against a real local stack, not written from the source alone:

uv sync
docker compose -f src/couchdb/docker-compose.yaml up -d
cp .env.public .env
uv run python src/couchdb/init_data.py     # 10,217 iot docs, 6 assets, sites MAIN + NORTH
uv run jupyter nbconvert --to notebook --execute --inplace notebook/showcase_iot_mcp_tools.ipynb
# → 0 errors across 25 code cells, 1 plot rendered

Running it caught two cells that would have shipped looking correct and teaching nothing:

• the pagination cell read page["cursor"], but HistoryResult exposes next_cursor with has_more, so it always took the "no more pages" branch. It now prints two distinct pages of timestamps.
• the sensor-gap cell drilled into one auto-selected asset, which turned out to have no gap at all. Hence the site-wide sweep described above.

Gates:

• ruff check notebook/showcase_iot_mcp_tools.ipynb — all checks passed
• gitleaks detect --source . --redact --verbose — no leaks found
• detect-secrets scan against the new file — no findings
• nbformat.validate — valid

Checklist

• I have signed off my commits (DCO).

Notes and open questions

A few judgment calls, each easy to reverse if you would rather go the other way:

1. Outputs are stripped. 8 of the 10 notebooks already in notebook/ are committed without outputs, and CONTRIBUTING prefers small PRs, so stripping keeps the diff at 742 lines instead of 1532. For a tutorial that people may read on GitHub without running, the executed version is arguably more useful. Say the word and I will push it with outputs.

2. I did not run ruff format on the notebook. It wants to expand every tu.run({...}) call across roughly eight lines, which reads poorly in a teaching notebook. Worth knowing that all 10 existing notebooks also fail ruff format --check today, and no workflow in .github/workflows/ runs ruff, so this is consistent with the repo as it stands rather than a new exception. Happy to format it if you want the notebooks brought into line.

3. This is not a hosted-Colab notebook. Helpter Notebook to Understand MCP Tools and Agents #452 asks for Colab, but also says to assume Docker and data are set up locally, and hosted Colab cannot reach a CouchDB on localhost. I wrote it for local Jupyter and said so explicitly in the header. If you want a true Colab variant, that needs a reachable CouchDB (or a bundled sample extract) and I would rather agree the approach than guess.

4. 748 lines total, over the 300-line preference. Most of it is prose and JSON scaffolding rather than code; I could not see a way to cover 12 tools in one notebook and stay under it.

Two things I noticed but deliberately left alone, since they are outside this issue:

• src/mcphub/workflows.py has REGISTERED = [] and both chiller_triage and sensor_inventory_gap raise, guarded by a comment saying the IoT server "exposes only registry discovery tools". That is no longer true: it exposes history, latest_reading, sensor_stats, sensor_coverage, stream_extent and measured_sensors. Re-enabling them looks feasible now. Happy to open a separate issue or PR.
• CONTRIBUTING points at uv run pytest tests/unit and ./scripts/run_tests.sh, but neither tests/ nor that script exists in the repo, so I could not run them. scripts/ contains only check_couchdb_data.sh.