stockscreen-mcp 0.1.0__tar.gz

stockscreen_mcp-0.1.0/.gitignore

@@ -0,0 +1 @@
+dist/

stockscreen_mcp-0.1.0/LICENSE

@@ -0,0 +1,203 @@
+Copyright 2026 xang1234
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 xang1234
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

stockscreen_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: stockscreen-mcp
+Version: 0.1.0
+Summary: MCP server for daily stock screens (Minervini, CANSLIM, VCP and more), RS ratings, market breadth and IBD-style group rankings across 12 markets. No API keys or setup.
+Project-URL: Homepage, https://github.com/xang1234/stock-screener/tree/main/stockscreen-mcp
+Project-URL: Repository, https://github.com/xang1234/stock-screener
+Project-URL: Issues, https://github.com/xang1234/stock-screener/issues
+Project-URL: Live demo, https://xang1234.github.io/stock-screener/
+Author: David Ten
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: canslim,market-breadth,mcp,minervini,relative-strength,stock-screener,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# stockscreen-mcp
+
+<!-- mcp-name: io.github.xang1234/stockscreen-mcp -->
+
+Daily stock screens, relative-strength ratings, market breadth and industry group rankings for **12 markets**, available to Claude, Cursor, VS Code or any other [MCP](https://modelcontextprotocol.io/) client.
+
+- No API keys and no server to run.
+- It reads the snapshot that the open-source [stock-screener](https://github.com/xang1234/stock-screener) project publishes after every market close.
+- That's the same data as the [live demo](https://xang1234.github.io/stock-screener/).
+
+```bash
+uvx stockscreen-mcp
+```
+
+**Markets:** United States, Canada, Germany, Hong Kong, mainland China, Japan, Korea, Taiwan, India, Singapore, Malaysia and Australia.
+
+## What you can ask
+
+- "Which stocks pass the Minervini trend template in the US today, and which of them are in top-20 industry groups?"
+- "Run the CANSLIM screen for Japan and show the five strongest by 3-month RS."
+- "How healthy is the US market right now? Exposure, distribution days, breadth."
+- "What are the leading industry groups this week, and which groups moved up the most?"
+- "Tell me everything the scan knows about NVDA, and which screens it passes."
+- "Find Hong Kong stocks with RS above 90, in stage 2, with quarterly EPS growth over 25%."
+
+## Tools
+
+All tools are read-only.
+
+| Tool | What it returns |
+|---|---|
+| `list_markets` | Markets in the current publish, with each one's data date, status and features |
+| `list_screens` | The 28 preset screens and their exact rules: Minervini, CANSLIM, VCP, cup with handle, high tight flag, momentum, IPOs and more |
+| `run_screen` | A preset and/or your own filters over every stock in a market's scan, sorted, with the match count. A preset returns exactly the stocks the website shows for it |
+| `get_stock` | One stock: RS ratings (overall, 1M, 3M, 12M), stage, screener scores, growth, group rank, setup and pattern fields, and the screens it passes |
+| `market_overview` | Exposure score and stance, distribution days, follow-through day, StockBee-style breadth (4% movers, 5/10-day ratios, T2108, 52-week highs/lows), key index moves, top groups |
+| `group_rankings` | IBD-style industry groups ranked by relative strength, with 1W/1M/3M/6M rank changes and weekly movers. Pass a group for its rank history and strongest stocks |
+
+### Reading the data
+
+- **RS ratings** (`rs_rating`, `rs_rating_1m/3m/12m`) are percentiles from 1 to 99 *within the stock's own market*, where 99 is the strongest.
+- **Group rank 1** is the strongest group.
+- **Every result has an `as_of_date`:** the last completed session the publish covers. This is end-of-day data with nothing intraday, and it is never fetched live from price providers.
+
+## Setup
+
+The server needs [uv](https://docs.astral.sh/uv/getting-started/installation/), which provides `uvx`.
+
+**Claude Code**
+
+```bash
+claude mcp add stockscreen -- uvx stockscreen-mcp
+```
+
+**Claude Desktop**: add to `claude_desktop_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "stockscreen": { "command": "uvx", "args": ["stockscreen-mcp"] }
+  }
+}
+```
+
+**Cursor**: add the same `mcpServers` entry to `~/.cursor/mcp.json`.
+
+**VS Code**: add to `.vscode/mcp.json`.
+
+```json
+{
+  "servers": {
+    "stockscreen": { "type": "stdio", "command": "uvx", "args": ["stockscreen-mcp"] }
+  }
+}
+```
+
+**Codex CLI**: add to `~/.codex/config.toml`.
+
+```toml
+[mcp_servers.stockscreen]
+command = "uvx"
+args = ["stockscreen-mcp"]
+```
+
+To run the newest version from `main` rather than the latest release, replace `stockscreen-mcp` in `args` with `--from`, `git+https://github.com/xang1234/stock-screener#subdirectory=stockscreen-mcp`, `stockscreen-mcp`.
+
+## How it works
+
+- **Data source:** the server reads the JSON that the static site publishes to GitHub Pages. The root `manifest.json` points at the current publish.
+- **Download and caching:** each market's scan is downloaded once, on first use (US is about 7 MB compressed), and kept in memory. The two most recently used markets stay cached, and the cache refreshes when a new publish appears.
+- **Data URL:** set `STOCKSCREEN_DATA_URL` to read from another publish, such as a fork's GitHub Pages site.
+
+## Development
+
+```bash
+cd stockscreen-mcp
+uv run pytest                                      # unit tests, no network
+STOCKSCREEN_LIVE=1 uv run pytest -m live           # against the real publish
+```
+
+## License and disclaimer
+
+Apache-2.0. This is screening data for education and research, **not investment advice**.

stockscreen_mcp-0.1.0/README.md

@@ -0,0 +1,103 @@
+# stockscreen-mcp
+
+<!-- mcp-name: io.github.xang1234/stockscreen-mcp -->
+
+Daily stock screens, relative-strength ratings, market breadth and industry group rankings for **12 markets**, available to Claude, Cursor, VS Code or any other [MCP](https://modelcontextprotocol.io/) client.
+
+- No API keys and no server to run.
+- It reads the snapshot that the open-source [stock-screener](https://github.com/xang1234/stock-screener) project publishes after every market close.
+- That's the same data as the [live demo](https://xang1234.github.io/stock-screener/).
+
+```bash
+uvx stockscreen-mcp
+```
+
+**Markets:** United States, Canada, Germany, Hong Kong, mainland China, Japan, Korea, Taiwan, India, Singapore, Malaysia and Australia.
+
+## What you can ask
+
+- "Which stocks pass the Minervini trend template in the US today, and which of them are in top-20 industry groups?"
+- "Run the CANSLIM screen for Japan and show the five strongest by 3-month RS."
+- "How healthy is the US market right now? Exposure, distribution days, breadth."
+- "What are the leading industry groups this week, and which groups moved up the most?"
+- "Tell me everything the scan knows about NVDA, and which screens it passes."
+- "Find Hong Kong stocks with RS above 90, in stage 2, with quarterly EPS growth over 25%."
+
+## Tools
+
+All tools are read-only.
+
+| Tool | What it returns |
+|---|---|
+| `list_markets` | Markets in the current publish, with each one's data date, status and features |
+| `list_screens` | The 28 preset screens and their exact rules: Minervini, CANSLIM, VCP, cup with handle, high tight flag, momentum, IPOs and more |
+| `run_screen` | A preset and/or your own filters over every stock in a market's scan, sorted, with the match count. A preset returns exactly the stocks the website shows for it |
+| `get_stock` | One stock: RS ratings (overall, 1M, 3M, 12M), stage, screener scores, growth, group rank, setup and pattern fields, and the screens it passes |
+| `market_overview` | Exposure score and stance, distribution days, follow-through day, StockBee-style breadth (4% movers, 5/10-day ratios, T2108, 52-week highs/lows), key index moves, top groups |
+| `group_rankings` | IBD-style industry groups ranked by relative strength, with 1W/1M/3M/6M rank changes and weekly movers. Pass a group for its rank history and strongest stocks |
+
+### Reading the data
+
+- **RS ratings** (`rs_rating`, `rs_rating_1m/3m/12m`) are percentiles from 1 to 99 *within the stock's own market*, where 99 is the strongest.
+- **Group rank 1** is the strongest group.
+- **Every result has an `as_of_date`:** the last completed session the publish covers. This is end-of-day data with nothing intraday, and it is never fetched live from price providers.
+
+## Setup
+
+The server needs [uv](https://docs.astral.sh/uv/getting-started/installation/), which provides `uvx`.
+
+**Claude Code**
+
+```bash
+claude mcp add stockscreen -- uvx stockscreen-mcp
+```
+
+**Claude Desktop**: add to `claude_desktop_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "stockscreen": { "command": "uvx", "args": ["stockscreen-mcp"] }
+  }
+}
+```
+
+**Cursor**: add the same `mcpServers` entry to `~/.cursor/mcp.json`.
+
+**VS Code**: add to `.vscode/mcp.json`.
+
+```json
+{
+  "servers": {
+    "stockscreen": { "type": "stdio", "command": "uvx", "args": ["stockscreen-mcp"] }
+  }
+}
+```
+
+**Codex CLI**: add to `~/.codex/config.toml`.
+
+```toml
+[mcp_servers.stockscreen]
+command = "uvx"
+args = ["stockscreen-mcp"]
+```
+
+To run the newest version from `main` rather than the latest release, replace `stockscreen-mcp` in `args` with `--from`, `git+https://github.com/xang1234/stock-screener#subdirectory=stockscreen-mcp`, `stockscreen-mcp`.
+
+## How it works
+
+- **Data source:** the server reads the JSON that the static site publishes to GitHub Pages. The root `manifest.json` points at the current publish.
+- **Download and caching:** each market's scan is downloaded once, on first use (US is about 7 MB compressed), and kept in memory. The two most recently used markets stay cached, and the cache refreshes when a new publish appears.
+- **Data URL:** set `STOCKSCREEN_DATA_URL` to read from another publish, such as a fork's GitHub Pages site.
+
+## Development
+
+```bash
+cd stockscreen-mcp
+uv run pytest                                      # unit tests, no network
+STOCKSCREEN_LIVE=1 uv run pytest -m live           # against the real publish
+```
+
+## License and disclaimer
+
+Apache-2.0. This is screening data for education and research, **not investment advice**.

stockscreen_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "stockscreen-mcp"
+dynamic = ["version"]
+description = "MCP server for daily stock screens (Minervini, CANSLIM, VCP and more), RS ratings, market breadth and IBD-style group rankings across 12 markets. No API keys or setup."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "David Ten" }]
+keywords = ["mcp", "stock-screener", "minervini", "canslim", "relative-strength", "market-breadth", "trading"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["mcp>=2.3,<3"]
+
+[project.urls]
+Homepage = "https://github.com/xang1234/stock-screener/tree/main/stockscreen-mcp"
+Repository = "https://github.com/xang1234/stock-screener"
+Issues = "https://github.com/xang1234/stock-screener/issues"
+"Live demo" = "https://xang1234.github.io/stock-screener/"
+
+[project.scripts]
+stockscreen-mcp = "stockscreen_mcp.server:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/stockscreen_mcp/__init__.py"
+
+[dependency-groups]
+dev = ["pytest>=8", "anyio>=4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: hits the published data on GitHub Pages (run with STOCKSCREEN_LIVE=1)"]

stockscreen_mcp-0.1.0/src/stockscreen_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server over the stock-screener project's published daily data."""
+
+__version__ = "0.1.0"

stockscreen_mcp-0.1.0/src/stockscreen_mcp/data.py

@@ -0,0 +1,182 @@
+"""Read-only access to the static site's published JSON, cached per publish."""
+
+from __future__ import annotations
+
+import gzip
+import http.client
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+import zlib
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://xang1234.github.io/stock-screener/static-data/"
+# GitHub Pages serves the data with Cache-Control: max-age=600.
+MANIFEST_TTL_SECONDS = 600
+# Chart series and per-field availability notes: large and unused by any tool.
+HEAVY_FIELDS = frozenset({"price_sparkline_data", "rs_sparkline_data", "field_availability"})
+# ponytail: pruned US rows are ~100 MB as Python objects (more while a chunk is parsed),
+# so keep only the most recently used markets' files; raise it or switch to columnar rows.
+MAX_CACHED_MARKETS = 2
+
+
+def fetch_json(url: str) -> Any:
+    request = urllib.request.Request(
+        url, headers={"Accept-Encoding": "gzip", "User-Agent": f"stockscreen-mcp/{__version__}"}
+    )
+    with urllib.request.urlopen(request, timeout=60) as response:
+        body = response.read()
+        if response.headers.get("Content-Encoding") == "gzip":
+            body = gzip.decompress(body)
+    return json.loads(body)
+
+
+def prune(value: Any) -> Any:
+    """Drop HEAVY_FIELDS at any depth (group files nest stock rows)."""
+    if isinstance(value, dict):
+        return {k: prune(v) for k, v in value.items() if k not in HEAVY_FIELDS}
+    if isinstance(value, list):
+        return [prune(v) for v in value]
+    return value
+
+
+class _GenerationReplaced(Exception):
+    """The publish this load started from was replaced mid-load."""
+
+
+class StaticData:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        fetch: Callable[[str], Any] = fetch_json,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        base = base_url or os.environ.get("STOCKSCREEN_DATA_URL") or DEFAULT_BASE_URL
+        self.base_url = base.rstrip("/") + "/"
+        self._fetch = fetch
+        self._clock = clock
+        # ponytail: one lock for every load; per-file locks if concurrent calls ever matter.
+        self._lock = threading.RLock()
+        self._manifest: dict[str, Any] | None = None
+        self._manifest_at = 0.0
+        self._cache: dict[tuple[str, str], Any] = {}
+        self._recent_markets: OrderedDict[str, None] = OrderedDict()
+
+    def _get(self, path: str) -> Any:
+        url = self.base_url + path
+        try:
+            return self._fetch(url)
+        except urllib.error.HTTPError:
+            raise
+        # OSError covers URLError and timeouts; ValueError bad JSON; the rest truncated bodies.
+        except (OSError, ValueError, EOFError, zlib.error, http.client.HTTPException) as exc:
+            raise ToolError(f"Could not reach the published data at {url}: {exc!r}") from exc
+
+    def manifest(self, *, refresh: bool = False) -> dict[str, Any]:
+        with self._lock:
+            stale = self._clock() - self._manifest_at > MANIFEST_TTL_SECONDS
+            if refresh or self._manifest is None or stale:
+                try:
+                    manifest = self._get("manifest.json")
+                except urllib.error.HTTPError as exc:
+                    raise ToolError(f"The published data manifest is unavailable ({exc.code}).") from exc
+                self._manifest, self._manifest_at = manifest, self._clock()
+                root = manifest["data_root"]
+                self._cache = {k: v for k, v in self._cache.items() if k[0] == root}
+            return self._manifest
+
+    def market(self, code: str) -> dict[str, Any]:
+        code = code.strip().upper()
+        manifest = self.manifest()
+        entry = manifest["markets"].get(code)
+        if entry is not None:
+            return entry
+        if code in manifest.get("unavailable_markets", []):
+            raise ToolError(f"{code} is not available in the current publish; try again after the next one.")
+        known = ", ".join(sorted(manifest["markets"]))
+        raise ToolError(f"Unknown market {code!r}. Available markets: {known}.")
+
+    def _touch_market(self, path: str) -> None:
+        """Mark a market's files as recently used, evicting the least recent beyond the cap."""
+        parts = path.split("/")
+        if len(parts) < 2 or parts[0] != "markets":
+            return
+        self._recent_markets.pop(parts[1], None)
+        self._recent_markets[parts[1]] = None
+        while len(self._recent_markets) > MAX_CACHED_MARKETS:
+            evicted, _ = self._recent_markets.popitem(last=False)
+            prefix = f"markets/{evicted}/"
+            self._cache = {k: v for k, v in self._cache.items() if not k[1].startswith(prefix)}
+
+    def _store(self, root: str, key: tuple[str, str], value: Any) -> None:
+        # A publish replaced mid-load is still read consistently, but never cached.
+        if root == self.manifest()["data_root"]:
+            self._cache[key] = value
+
+    def _load(self, path: str, root: str, *, cache: bool = True) -> Any:
+        """One file of the publish under `root` (pinned for the whole load)."""
+        key = (root, path)
+        self._touch_market(path)
+        if key in self._cache:
+            return self._cache[key]
+        try:
+            value = prune(self._get(root + path))
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404 and self.manifest(refresh=True)["data_root"] != root:
+                raise _GenerationReplaced from exc
+            raise ToolError(f"Published file {root}{path} is unavailable ({exc.code}).") from exc
+        if cache:
+            self._store(root, key, value)
+        return value
+
+    def _retrying(self, load: Callable[[str], Any]) -> Any:
+        """Run a load against one publish; only the newest is deployed, so restart on a new one."""
+        with self._lock:
+            for _ in range(2):
+                try:
+                    return load(self.manifest()["data_root"])
+                except _GenerationReplaced:
+                    continue
+            raise ToolError("The published data changed while loading; try again in a minute.")
+
+    def load(self, path: str) -> Any:
+        return self._retrying(lambda root: self._load(path, root))
+
+    def page(self, code: str, page: str) -> Any | None:
+        """A market page (home, breadth, groups, scan), or None if not published for it."""
+        entry = self.page_entry(code, page)
+        return None if entry is None else self.load(entry["path"])
+
+    def page_entry(self, code: str, page: str) -> dict[str, Any] | None:
+        return self.market(code).get("pages", {}).get(page)
+
+    def scan(self, code: str) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """The scan manifest and every row, initial rows and chunks merged by symbol."""
+        if self.page_entry(code, "scan") is None:
+            raise ToolError(f"Scan results are not published for {code.upper()}.")
+
+        def load_all(root: str) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+            scan_path = self.page_entry(code, "scan")["path"]
+            scan = self._load(scan_path, root)
+            # Lives under the market's prefix so eviction drops it with the market's files.
+            key = (root, scan_path.rsplit("/", 1)[0] + "/rows")
+            if key in self._cache:
+                return scan, self._cache[key]
+            merged = {row["symbol"]: row for row in scan.get("initial_rows", [])}
+            for chunk in scan.get("chunks", []):
+                for row in self._load(chunk["path"], root, cache=False)["rows"]:
+                    merged[row["symbol"]] = row
+            rows = list(merged.values())
+            self._store(root, key, rows)
+            return scan, rows
+
+        return self._retrying(load_all)