siemens-docs-mcp 0.1.0__tar.gz

siemens_docs_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Łukasz Czarnacki
+
+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.

siemens_docs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: siemens-docs-mcp
+Version: 0.1.0
+Summary: Search and read Siemens Fluid Topics documentation via MCP or export it to Markdown
+Author: Łukasz Czarnacki
+Project-URL: Homepage, https://github.com/Czarnak/siemens-docs-mcp
+Project-URL: Issues, https://github.com/Czarnak/siemens-docs-mcp/issues
+Keywords: mcp,siemens,tia-portal,fluid-topics,documentation
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: markdownify>=1.2.3
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: lxml>=6.1.3
+Requires-Dist: mcp<3,>=2.3.0
+Dynamic: license-file
+
+# Siemens Docs MCP
+
+An MCP server that lets an AI assistant search and read Siemens documentation live — any publication on `docs.tia.siemens.cloud` (TIA Portal, STEP 7, WinCC Unified, Openness, …) and `docs.industrial-operations-x.siemens.cloud` (Industrial Operations X) — plus a CLI that exports a whole publication to a tree of Markdown files.
+
+Built to solve the problem of documentation portals that only offer low-quality PDF exports or JavaScript-rendered web views, making the content difficult to search, reference, or feed to AI tools.
+
+---
+
+## Installation
+
+### PyPI
+
+```bash
+pip install siemens-docs-mcp
+```
+
+This installs two commands: `siemens-docs-mcp` (the MCP server) and `siemens-docs-export` (the Markdown exporter). Requires Python 3.11+.
+
+### From source
+
+```bash
+git clone https://github.com/Czarnak/siemens-docs-mcp
+cd siemens-docs-mcp
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+# development (pytest, ruff, pip-audit; needs pip >= 25.1):
+pip install -e . --group dev
+```
+
+---
+
+## MCP server
+
+The server speaks MCP over stdio. Register it with Claude Code:
+
+```bash
+# from PyPI, no manual install (needs uv)
+claude mcp add siemens-docs -- uvx siemens-docs-mcp
+
+# or an installed copy
+claude mcp add siemens-docs -- siemens-docs-mcp
+# from a source checkout: <repo>/.venv/Scripts/siemens-docs-mcp  (Linux/macOS: <repo>/.venv/bin/siemens-docs-mcp)
+```
+
+Pass settings with `-e`, e.g. `claude mcp add siemens-docs -e SIEMENS_DOCS_LOCALE=de-DE -- uvx siemens-docs-mcp`.
+
+Tools:
+
+| Tool                | Purpose                                                                   |
+|---------------------|---------------------------------------------------------------------------|
+| `search_docs`       | Full-text search (filter by `product`, `version`, `locale`, `host`).      |
+| `read_page`         | Read one page as Markdown; page through long pages with `offset`.         |
+| `get_toc`           | Table of contents of a publication or of the subtree under a topic URL.   |
+| `list_publications` | List publications; discover valid `product` / `version` values.           |
+
+Any reader URL returned by a tool (or copied from the browser) is valid input to `read_page` and `get_toc`.
+
+Environment variables:
+
+| Variable                     | Default  | Meaning                                                          |
+|------------------------------|----------|------------------------------------------------------------------|
+| `SIEMENS_DOCS_HOSTS`         | (none)   | Comma-separated extra hosts, appended to the built-in two (`docs.tia.siemens.cloud`, `docs.industrial-operations-x.siemens.cloud`). |
+| `SIEMENS_DOCS_LOCALE`        | `en-US`  | Default locale for search and listings.                          |
+| `SIEMENS_DOCS_MIN_INTERVAL`  | `0.3`    | Minimum seconds between requests to a host.                      |
+
+The publication catalog and TOCs are cached in memory (not on disk), so the first call per host takes a few seconds.
+
+---
+
+## Markdown export (CLI)
+
+Export a whole publication to Markdown — one file per page, folders mirroring the navigation hierarchy. Create a config with any reader URL of the publication (a topic URL exports the whole publication):
+
+```yaml
+# my_docs.yaml
+name: tia_openness_v21
+url: "https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows"
+output_dir: "output/tia_openness_v21"
+```
+
+```bash
+# Preview pages without writing files
+siemens-docs-export my_docs.yaml --dry-run
+
+# Export everything
+siemens-docs-export my_docs.yaml
+
+# Export a single page (for testing output quality)
+siemens-docs-export my_docs.yaml --page cybersecurity-information
+
+# Override the output directory / verbose logging
+siemens-docs-export my_docs.yaml --output /tmp/docs --verbose
+```
+
+A ready-made config lives in [`configs/`](https://github.com/Czarnak/siemens-docs-mcp/tree/main/configs) in the repository.
+
+### Output structure
+
+```
+output/tia_openness_v21/
+├── index.md                          ← root page
+├── cybersecurity-information.md
+├── what-s-new-in-tia-portal-openness.md
+├── basics/
+│   ├── basics.md
+│   └── ...
+├── tia-portal-openness-api/
+│   ├── tia-portal-openness-object/
+│   │   └── ...
+│   └── ...
+└── ...
+```
+
+### Configuration reference
+
+| Key          | Required | Description                                                                 |
+|--------------|----------|-----------------------------------------------------------------------------|
+| `name`       | No       | Human-readable label shown in log output.                                   |
+| `url`        | Yes*     | Any reader URL of the publication (resolved to its map automatically).      |
+| `api_base`   | Yes*     | Legacy: root URL of the Fluidtopics instance (use with `map_id`).           |
+| `map_id`     | Yes*     | Legacy: Fluidtopics map identifier (use with `api_base`).                   |
+| `output_dir` | Yes      | Directory where Markdown files will be written.                             |
+
+\* Either `url`, or `api_base` + `map_id`. If both are present, `url` wins.
+
+---
+
+## How it works
+
+Fluidtopics (the platform behind both portals) exposes a REST API that the browser SPA uses internally. This package calls that API directly — no browser automation:
+
+1. **Catalog** — `GET /api/khub/maps` lists every publication; reader URLs are resolved against it.
+2. **Search** — `POST /api/khub/clustered-search` with product/version/locale filters.
+3. **TOC** — `GET /api/khub/maps/{mapId}/pages` returns the navigation tree.
+4. **Content** — `GET /api/khub/maps/{mapId}/topics/{contentId}/content` returns raw HTML, converted to Markdown with [markdownify](https://github.com/matthewwithanm/python-markdownify).
+
+Requests are throttled per host and retried once on 401/403/429/5xx.
+
+> **Note:** Only Fluidtopics-based portals are supported. Other platforms (MadCap Flare, Paligo, etc.) would need a different adapter.
+
+---
+
+## Development
+
+```bash
+python -m pytest -q          # offline tests
+python -m pytest -m live -q  # live smoke tests against the real hosts
+ruff check .
+```
+
+---
+
+*Created with Claude AI*

siemens_docs_mcp-0.1.0/README.md

@@ -0,0 +1,154 @@
+# Siemens Docs MCP
+
+An MCP server that lets an AI assistant search and read Siemens documentation live — any publication on `docs.tia.siemens.cloud` (TIA Portal, STEP 7, WinCC Unified, Openness, …) and `docs.industrial-operations-x.siemens.cloud` (Industrial Operations X) — plus a CLI that exports a whole publication to a tree of Markdown files.
+
+Built to solve the problem of documentation portals that only offer low-quality PDF exports or JavaScript-rendered web views, making the content difficult to search, reference, or feed to AI tools.
+
+---
+
+## Installation
+
+### PyPI
+
+```bash
+pip install siemens-docs-mcp
+```
+
+This installs two commands: `siemens-docs-mcp` (the MCP server) and `siemens-docs-export` (the Markdown exporter). Requires Python 3.11+.
+
+### From source
+
+```bash
+git clone https://github.com/Czarnak/siemens-docs-mcp
+cd siemens-docs-mcp
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+# development (pytest, ruff, pip-audit; needs pip >= 25.1):
+pip install -e . --group dev
+```
+
+---
+
+## MCP server
+
+The server speaks MCP over stdio. Register it with Claude Code:
+
+```bash
+# from PyPI, no manual install (needs uv)
+claude mcp add siemens-docs -- uvx siemens-docs-mcp
+
+# or an installed copy
+claude mcp add siemens-docs -- siemens-docs-mcp
+# from a source checkout: <repo>/.venv/Scripts/siemens-docs-mcp  (Linux/macOS: <repo>/.venv/bin/siemens-docs-mcp)
+```
+
+Pass settings with `-e`, e.g. `claude mcp add siemens-docs -e SIEMENS_DOCS_LOCALE=de-DE -- uvx siemens-docs-mcp`.
+
+Tools:
+
+| Tool                | Purpose                                                                   |
+|---------------------|---------------------------------------------------------------------------|
+| `search_docs`       | Full-text search (filter by `product`, `version`, `locale`, `host`).      |
+| `read_page`         | Read one page as Markdown; page through long pages with `offset`.         |
+| `get_toc`           | Table of contents of a publication or of the subtree under a topic URL.   |
+| `list_publications` | List publications; discover valid `product` / `version` values.           |
+
+Any reader URL returned by a tool (or copied from the browser) is valid input to `read_page` and `get_toc`.
+
+Environment variables:
+
+| Variable                     | Default  | Meaning                                                          |
+|------------------------------|----------|------------------------------------------------------------------|
+| `SIEMENS_DOCS_HOSTS`         | (none)   | Comma-separated extra hosts, appended to the built-in two (`docs.tia.siemens.cloud`, `docs.industrial-operations-x.siemens.cloud`). |
+| `SIEMENS_DOCS_LOCALE`        | `en-US`  | Default locale for search and listings.                          |
+| `SIEMENS_DOCS_MIN_INTERVAL`  | `0.3`    | Minimum seconds between requests to a host.                      |
+
+The publication catalog and TOCs are cached in memory (not on disk), so the first call per host takes a few seconds.
+
+---
+
+## Markdown export (CLI)
+
+Export a whole publication to Markdown — one file per page, folders mirroring the navigation hierarchy. Create a config with any reader URL of the publication (a topic URL exports the whole publication):
+
+```yaml
+# my_docs.yaml
+name: tia_openness_v21
+url: "https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows"
+output_dir: "output/tia_openness_v21"
+```
+
+```bash
+# Preview pages without writing files
+siemens-docs-export my_docs.yaml --dry-run
+
+# Export everything
+siemens-docs-export my_docs.yaml
+
+# Export a single page (for testing output quality)
+siemens-docs-export my_docs.yaml --page cybersecurity-information
+
+# Override the output directory / verbose logging
+siemens-docs-export my_docs.yaml --output /tmp/docs --verbose
+```
+
+A ready-made config lives in [`configs/`](https://github.com/Czarnak/siemens-docs-mcp/tree/main/configs) in the repository.
+
+### Output structure
+
+```
+output/tia_openness_v21/
+├── index.md                          ← root page
+├── cybersecurity-information.md
+├── what-s-new-in-tia-portal-openness.md
+├── basics/
+│   ├── basics.md
+│   └── ...
+├── tia-portal-openness-api/
+│   ├── tia-portal-openness-object/
+│   │   └── ...
+│   └── ...
+└── ...
+```
+
+### Configuration reference
+
+| Key          | Required | Description                                                                 |
+|--------------|----------|-----------------------------------------------------------------------------|
+| `name`       | No       | Human-readable label shown in log output.                                   |
+| `url`        | Yes*     | Any reader URL of the publication (resolved to its map automatically).      |
+| `api_base`   | Yes*     | Legacy: root URL of the Fluidtopics instance (use with `map_id`).           |
+| `map_id`     | Yes*     | Legacy: Fluidtopics map identifier (use with `api_base`).                   |
+| `output_dir` | Yes      | Directory where Markdown files will be written.                             |
+
+\* Either `url`, or `api_base` + `map_id`. If both are present, `url` wins.
+
+---
+
+## How it works
+
+Fluidtopics (the platform behind both portals) exposes a REST API that the browser SPA uses internally. This package calls that API directly — no browser automation:
+
+1. **Catalog** — `GET /api/khub/maps` lists every publication; reader URLs are resolved against it.
+2. **Search** — `POST /api/khub/clustered-search` with product/version/locale filters.
+3. **TOC** — `GET /api/khub/maps/{mapId}/pages` returns the navigation tree.
+4. **Content** — `GET /api/khub/maps/{mapId}/topics/{contentId}/content` returns raw HTML, converted to Markdown with [markdownify](https://github.com/matthewwithanm/python-markdownify).
+
+Requests are throttled per host and retried once on 401/403/429/5xx.
+
+> **Note:** Only Fluidtopics-based portals are supported. Other platforms (MadCap Flare, Paligo, etc.) would need a different adapter.
+
+---
+
+## Development
+
+```bash
+python -m pytest -q          # offline tests
+python -m pytest -m live -q  # live smoke tests against the real hosts
+ruff check .
+```
+
+---
+
+*Created with Claude AI*

siemens_docs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=84.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "siemens-docs-mcp"
+version = "0.1.0"
+description = "Search and read Siemens Fluid Topics documentation via MCP or export it to Markdown"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Łukasz Czarnacki" }]
+keywords = ["mcp", "siemens", "tia-portal", "fluid-topics", "documentation"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Documentation",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "beautifulsoup4>=4.15.0",
+    "markdownify>=1.2.3",
+    "PyYAML>=6.0.3",
+    "lxml>=6.1.3",
+    "mcp>=2.3.0,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Czarnak/siemens-docs-mcp"
+Issues = "https://github.com/Czarnak/siemens-docs-mcp/issues"
+
+[project.scripts]
+siemens-docs-mcp = "siemens_docs_mcp.server:main"
+siemens-docs-export = "siemens_docs_mcp.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "pytest-cov>=7.1.0", "ruff>=0.16.10", "pip-audit>=2.10.1"]
+
+[tool.setuptools]
+packages = ["siemens_docs_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = '-m "not live"'
+markers = ["live: hits real Fluid Topics hosts (run with: pytest -m live)"]

siemens_docs_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

siemens_docs_mcp-0.1.0/siemens_docs_mcp/__init__.py

@@ -0,0 +1 @@
+"""siemens-docs-mcp — search, read and export Siemens Fluid Topics documentation."""

siemens_docs_mcp-0.1.0/siemens_docs_mcp/catalog.py

@@ -0,0 +1,254 @@
+"""Per-host catalog of publications (maps): listing, canonicalization, URL resolution, TOC cache."""
+from __future__ import annotations
+
+import difflib
+import logging
+import re
+import threading
+import time
+from collections import Counter
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Literal
+from urllib.parse import unquote, urlsplit
+
+from siemens_docs_mcp.client import FluidtopicsClient
+from siemens_docs_mcp.toc import TocPage, iter_pages, parse_toc
+
+log = logging.getLogger(__name__)
+
+TIA_VERSION_KEY = "tia:SoftwareVersionFilter"
+SW_VERSION_KEY = "SoftwareVersion"
+_VERSION_KEYS = (TIA_VERSION_KEY, SW_VERSION_KEY)
+_CONTENT_ID = re.compile(r"[\w~.-]+")
+
+
+class CatalogError(ValueError):
+    """Raised for unknown hosts, unresolvable URLs, and unknown filter values."""
+
+
+@dataclass(frozen=True)
+class MapInfo:
+    id: str
+    title: str
+    locale: str
+    product: str
+    version: str
+    version_key: str
+    pretty_url: str
+    cluster_id: str
+    last_publication: str
+
+
+@dataclass(frozen=True)
+class Resolved:
+    host: str
+    map_id: str
+    content_id: str | None
+
+
+def _meta(raw: dict) -> dict[str, list[str]]:
+    return {m["key"]: m.get("values") or [] for m in raw.get("metadata", [])}
+
+
+def _first(meta: dict[str, list[str]], key: str) -> str:
+    values = meta.get(key) or []
+    return values[0] if values else ""
+
+
+def _map_info(raw: dict) -> MapInfo:
+    meta = _meta(raw)
+    version_key = next((k for k in _VERSION_KEYS if _first(meta, k)), "")
+    return MapInfo(
+        id=raw["id"],
+        title=raw.get("title", ""),
+        locale=_first(meta, "ft:locale"),
+        product=_first(meta, "Product"),
+        version=_first(meta, version_key) if version_key else "",
+        version_key=version_key,
+        pretty_url=_first(meta, "ft:prettyUrl").removeprefix("/r/"),
+        cluster_id=_first(meta, "ft:clusterId"),
+        last_publication=_first(meta, "ft:lastPublication"),
+    )
+
+
+class Catalog:
+    def __init__(
+        self,
+        hosts: Sequence[str],
+        client_factory: Callable[[str], FluidtopicsClient],
+        ttl_seconds: float = 86400,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.hosts: tuple[str, ...] = tuple(h.lower() for h in hosts)
+        self._factory = client_factory
+        self._ttl = ttl_seconds
+        self._clock = clock
+        # ponytail: global lock serializes cold catalog loads across hosts; per-host locks if that hurts
+        self._lock = threading.RLock()  # re-entrant: maps()/toc() call client() while holding it
+        self._clients: dict[str, FluidtopicsClient] = {}
+        self._maps: dict[str, tuple[float, dict[str, MapInfo]]] = {}
+        # Raw distinct version values per host per key (a map can carry both keys).
+        self._versions: dict[str, dict[str, list[str]]] = {}
+        # Raw version values per host per map id per key, for filter().
+        self._map_versions: dict[str, dict[str, dict[str, str]]] = {}
+        self._tocs: dict[tuple[str, str], tuple[float, TocPage]] = {}
+        # Lower-cased pretty URLs carried by more than one map per host (ambiguous as reader URLs).
+        self._shared: dict[str, set[str]] = {}
+
+    def _check_host(self, host: str) -> str:
+        host = host.lower()
+        if host not in self.hosts:
+            raise CatalogError(f"Host {host!r} is not allowed. Allowed hosts: {list(self.hosts)}")
+        return host
+
+    def client(self, host: str) -> FluidtopicsClient:
+        host = self._check_host(host)
+        with self._lock:
+            if host not in self._clients:
+                self._clients[host] = self._factory(host)
+            return self._clients[host]
+
+    def _fresh(self, stamp: float) -> bool:
+        return self._clock() - stamp <= self._ttl
+
+    def maps(self, host: str) -> dict[str, MapInfo]:
+        host = self._check_host(host)
+        with self._lock:
+            cached = self._maps.get(host)
+            if cached and self._fresh(cached[0]):
+                return cached[1]
+            raws = self.client(host).list_maps()
+            infos = {m.id: m for m in map(_map_info, raws)}
+            versions: dict[str, list[str]] = {k: [] for k in _VERSION_KEYS}
+            per_map: dict[str, dict[str, str]] = {}
+            for raw in raws:
+                meta = _meta(raw)
+                per_map[raw["id"]] = {}
+                for key in _VERSION_KEYS:
+                    v = _first(meta, key)
+                    if v:
+                        per_map[raw["id"]][key] = v
+                        if v not in versions[key]:
+                            versions[key].append(v)
+            self._versions[host] = versions
+            self._map_versions[host] = per_map
+            counts = Counter(m.pretty_url.lower() for m in infos.values() if m.pretty_url)
+            self._shared[host] = {p for p, n in counts.items() if n > 1}
+            self._maps[host] = (self._clock(), infos)
+            return infos
+
+    @staticmethod
+    def _unknown(host: str, label: str, value: str, known: list[str]) -> CatalogError:
+        close = difflib.get_close_matches(value, known, n=5, cutoff=0.5)
+        return CatalogError(f"Unknown {label} {value!r} on {host}. Close matches: {close or known[:10]}")
+
+    def canonical(self, host: str, field: Literal["product", "locale"], value: str) -> str:
+        values = sorted({getattr(m, field) for m in self.maps(host).values()} - {""})
+        for v in values:
+            if v.lower() == value.lower():
+                return v
+        raise self._unknown(host, field, value, values)
+
+    def canonical_version(self, host: str, value: str) -> tuple[str, str]:
+        self.maps(host)
+        versions = self._versions[host.lower()]
+        for key in _VERSION_KEYS:
+            for v in versions[key]:
+                if v.lower() == value.lower():
+                    return key, v
+        known = sorted({v for vs in versions.values() for v in vs})
+        raise self._unknown(host, "version", value, known)
+
+    def filter(
+        self,
+        host: str,
+        product: str | None = None,
+        version: str | None = None,
+        locale: str | None = None,
+        title_contains: str | None = None,
+    ) -> list[MapInfo]:
+        result = list(self.maps(host).values())
+        if product is not None:
+            p = self.canonical(host, "product", product)
+            result = [m for m in result if m.product == p]
+        if locale is not None:
+            loc = self.canonical(host, "locale", locale)
+            result = [m for m in result if m.locale == loc]
+        if version is not None:
+            key, v = self.canonical_version(host, version)
+            per_map = self._map_versions[host.lower()]
+            result = [m for m in result if per_map[m.id].get(key) == v]
+        if title_contains:
+            needle = title_contains.lower()
+            result = [m for m in result if needle in m.title.lower()]
+        return sorted(result, key=lambda m: m.title)
+
+    def toc(self, host: str, map_id: str) -> TocPage:
+        key = (self._check_host(host), map_id)
+        with self._lock:
+            cached = self._tocs.get(key)
+            if cached and self._fresh(cached[0]):
+                return cached[1]
+            root = parse_toc(self.client(host).get_pages(map_id))
+            self._tocs[key] = (self._clock(), root)
+            return root
+
+    def resolve(self, url: str) -> Resolved:
+        failure = CatalogError(
+            f"Could not resolve {url}. Use search_docs or list_publications to find a valid reader URL."
+        )
+        parts = urlsplit(url.strip())
+        host = self._check_host(parts.hostname or "")
+        path = unquote(parts.path).rstrip("/")
+        if not path.startswith("/r/"):
+            raise failure
+        rel = path[3:]
+        segs = rel.split("/")
+        maps = self.maps(host)
+        if segs[0] in maps:
+            if len(segs) == 1:
+                return Resolved(host, segs[0], None)
+            if not _CONTENT_ID.fullmatch(segs[1]) or segs[1] in (".", ".."):
+                raise failure
+            return Resolved(host, segs[0], segs[1])
+        low = rel.lower()
+        # Several maps can share a pretty URL, and a longer prefix may lack the topic: try every
+        # matching map, longest prefix first (stable on ties), until one's TOC holds the topic.
+        matches = sorted(
+            (
+                m for m in maps.values()
+                if m.pretty_url
+                and (low == m.pretty_url.lower() or (low + "/").startswith(m.pretty_url.lower() + "/"))
+            ),
+            key=lambda m: len(m.pretty_url),
+            reverse=True,
+        )
+        target = "/r/" + low
+        for m in matches:
+            if low == m.pretty_url.lower():
+                return Resolved(host, m.id, None)
+            for page in iter_pages(self.toc(host, m.id)):
+                if page.pretty_url.lower() == target:
+                    return Resolved(host, m.id, page.content_id)
+        raise failure
+
+    def _pretty_ok(self, host: str, map_id: str) -> str:
+        """The map's pretty URL if it identifies the map unambiguously, else ""."""
+        info = self.maps(host).get(map_id)
+        if not info or not info.pretty_url or info.pretty_url.lower() in self._shared[host.lower()]:
+            return ""
+        return info.pretty_url
+
+    def map_url(self, host: str, map_id: str) -> str:
+        """Reader URL of a publication: its pretty URL, or the id form when missing or shared."""
+        host = self._check_host(host)
+        return f"https://{host}/r/{self._pretty_ok(host, map_id) or map_id}"
+
+    def reader_url(self, host: str, map_id: str, page: TocPage) -> str:
+        host = self._check_host(host)
+        if not page.content_id:  # synthetic root of a multi-section TOC = the publication itself
+            return self.map_url(host, map_id)
+        if page.pretty_url and self._pretty_ok(host, map_id):
+            return f"https://{host}{page.pretty_url}"
+        return f"https://{host}/r/{map_id}/{page.content_id}"