rtings-mcp 0.2.1__tar.gz

rtings_mcp-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+# Trusted publishing (OIDC): no API token is stored anywhere. PyPI is told, once, that
+# releases of the project may come from this repository's `publish.yml` running in the
+# `pypi` environment; each run then mints a short-lived token for itself.
+#
+# Trigger: publishing a GitHub release whose tag is the version (`v0.2.1`). The tag must
+# match `src/rtings_mcp/__init__.py`, or the job refuses — one source of truth for the
+# version, and a release page that says one thing while the wheel says another is the
+# kind of quiet inconsistency the project spends its rules avoiding.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Lint and offline tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check src/ tests/
+      - name: Offline tests
+        run: uv run pytest tests/ -q
+
+  build:
+    name: Build sdist and wheel
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Release tag must match the package version
+        if: github.event_name == 'release'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(python3 -c "import re,pathlib; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('src/rtings_mcp/__init__.py').read_text()).group(1))")"
+          if [ "$tag" != "$version" ]; then
+            echo "release tag v$tag does not match __version__ $version" >&2
+            exit 1
+          fi
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/rtings-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

rtings_mcp-0.2.1/.gitignore

@@ -0,0 +1,41 @@
+# Delegated-review run artifacts: full prompts, stdout and rollouts of subagent runs.
+# They quote repo source verbatim and are per-machine scratch, never part of the project.
+.codex-dobby/
+
+# Browser-automation recon artifacts — contain analytics client IDs, coarse geo,
+# UA fingerprints and verbatim scrapes of third-party page content.
+.playwright-mcp/
+
+# Credentials and cache — never committed. The runtime cache legitimately holds
+# the user's own member data; the repo never does.
+.cache/
+session.json
+*.session.json
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Recon/scratch artifacts — screenshots and page captures contain third-party
+# content and browser fingerprints. Findings belong in RECON.md as text.
+*.png
+*.jpg
+*.har
+scratch/

rtings_mcp-0.2.1/LICENSE

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

rtings_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: rtings-mcp
+Version: 0.2.1
+Summary: MCP server exposing RTINGS.com test data as structured tools
+Project-URL: Homepage, https://github.com/Averyy/rtings-mcp
+Project-URL: Repository, https://github.com/Averyy/rtings-mcp
+Author: Avery Levitt
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,reviews,rtings,test-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Requires-Dist: mcp>=2.1.1
+Requires-Dist: wafer-py>=0.5.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.4; extra == 'dev'
+Requires-Dist: pytest>=9.1; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rtings-mcp
+
+> ### ⚠️ Not a paywall bypass
+> RTINGS gates some test values and scores server-side. This server reads what your own session
+> is already entitled to. On the categories that enforce the paywall, gated values come back
+> `null` without a membership. The tool can't unlock them, and it never estimates, interpolates
+> or infers them. For those numbers you have to pay RTINGS and sign in.
+
+An MCP server that exposes [RTINGS.com](https://www.rtings.com) test data as structured tools:
+0–10 scores, scalar measurements with units, specs, and the measurement curves behind them. It
+runs locally. Nothing is hosted and nothing is shared.
+
+RTINGS' JSON API is keyless and public, and a lot comes back anonymously. Signing in adds data on
+the 12 categories that gate.
+
+> **Status: working, anonymous and signed in.** All seven data tools run against the live API, and
+> two more connect a membership.
+> **A membership cookie does unblur the JSON API** — measured 2026-09-06 on a bought membership:
+> 588 of 588 withheld rows came back with real values where anonymous got none
+> ([`RECON.md`](RECON.md) §13). Member mode is on by default as of that measurement, so a
+> signed-in session caches its rows under their own tier; `RTINGS_MEMBER_MODE=0` pins everything
+> back to `anonymous`.
+> [`SPEC.md`](SPEC.md) is the design of record and [`RECON.md`](RECON.md) the measured evidence.
+
+## What anonymous gets
+
+An anonymous sweep of all 28 categories ([`RECON.md` §11](RECON.md)) found the rule:
+
+```
+blurred  ⇔  product.published == false          (Early Access, an Insider perk separate from the category paywall)
+         ∨  (test.insider_only  ∧  the CATEGORY enforces the paywall)
+```
+
+Enforcement is per-category and binary. 12 of 28 enforce, 16 don't.
+
+| | Categories | Anonymous gets |
+|---|---|---|
+| **Open (16)** | mattress, vacuum, air-purifier, air-fryer, refrigerator, microwave, toaster, toaster-oven, air-conditioner, dehumidifier, humidifier, blender, vpn, keyboard-switch, camera, running-shoes | test values, scores, ranking and comparison. The numbers are served. |
+| **Gated (12)** | tv, headphones, monitor, mouse, keyboard, soundbar, speaker, printer, laptop, robot-vacuum, projector, router | catalog, schema, search, **RTINGS' written verdicts, pros and cons**, review prose, ranked best-of lists, published curve data, and a handful of public spec fields with their scores |
+
+Every category reports `has_paywall: true`, so that flag carries no information. Only the served
+data shows the split. What decides it is unknown and it will change, so the server never hardcodes
+it; `rt_silos()` reports what your machine observed. The map is re-scanned before each release
+against [`docs/enforcement-snapshot.json`](docs/enforcement-snapshot.json) (baseline 2026-09-03,
+re-verified 2026-09-06: 12/16, unchanged — and re-verified *with* a membership stored, which the
+scan ignores by construction, so the map stays an anonymous measurement).
+
+## Honest nulls
+
+Gated values come back `null` with a typed output schema and structural `auth_state` /
+`data_tier` / `scores_available` fields. Every row says why it has no value: measured but hidden,
+not applicable, not tested, Early Access, or outside what the server can show it has fetched. An
+agent can't read "no member session" as "RTINGS did not test this."
+
+## Install
+
+From PyPI, with nothing to clone (`uvx` fetches and caches the package on first run):
+
+```bash
+claude mcp add rtings --scope user -- uvx rtings-mcp
+```
+
+For the in-conversation browser sign-in (`rt_sign_in`) install the `browser` extra instead:
+
+```bash
+claude mcp add rtings --scope user -- uvx --from "rtings-mcp[browser]" rtings-mcp
+```
+
+Or from a checkout, if you want to work on it:
+
+```bash
+git clone https://github.com/Averyy/rtings-mcp && cd rtings-mcp
+uv venv && uv pip install -e .
+claude mcp add rtings --scope user -- uv --directory /absolute/path/to/rtings-mcp run rtings-mcp
+```
+
+`--scope user` makes it available in every project. Drop it to scope the server to the current
+directory. Verify with:
+
+```bash
+claude mcp get rtings      # expect: Status: ✔ Connected
+```
+
+A connected server keeps running the code it started with, so restart the session after editing
+the source. `/reload-plugins` won't do it; it only handles servers bundled inside plugins.
+
+No configuration is needed to start. Anonymous is the default and never an error.
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `rt_silos(silos?)` | the 28 categories with **observed** paywall enforcement |
+| `rt_schema(silo, bench?, group?, find?)` | test/usage definitions: name, kind, unit, hierarchy, `insider_only`; `find` searches the bench by name |
+| `rt_ratings(silo, tests?, usages?, filters?, sort?, limit?)` | catalog + 0–10 usage scores, with an optional scalar projection; `filters.product_ids` for a head-to-head |
+| `rt_product(product, group?, tests?)` | one review: test results (bounded by `group` or `tests`), plus RTINGS' verdicts and pros/cons with `include_verdicts` (`include_results=false` for the words alone) |
+| `rt_graph(product, test)` | one test's measurement curve, resampled by selecting shipped points |
+| `rt_search(query)` | model name/number → candidates across all categories |
+| `rt_recommendations(silo, list?, limit?)` | the category's best-of lists, or one ranked list with reasoning |
+| `rt_sign_in(force?)` | opens a browser window on RTINGS' sign-in page and stores the resulting cookie |
+| `rt_auth_status(wait_s?)` | what credential is stored, and how a sign-in in progress is going |
+
+Results are compared within a **test bench**, RTINGS' version of its methodology. Cross-bench
+results come back nested in separate groups and `limit` applies within each.
+
+`filters` and `sort` take a test's id or its name, plus `brand`, `name_contains`, `published` and
+`variant`. `variant` is the size RTINGS tested, which is how you ask for 65-inch TVs, since most
+categories have no "Size" test. A field you filter or sort on is fetched for you. When one can't be
+compared the predicate is **not applied** and the response names why: gated for this session,
+absent from the bench queried, or measured-but-empty. Otherwise an empty result reads as "no
+product qualifies" when the truth is "you can't see it". Rows with no comparable value sort last in
+both directions.
+
+**On a gated category, ask for the verdicts.** `rt_product(url, include_verdicts=true)` returns
+RTINGS' per-usage judgement in their own words, their pros and cons, and how each usage score is
+composed. Those come through even where every measurement is null.
+
+⚠️ **`rt_product` can cost you something.** On a free account it hits the endpoint RTINGS meters,
+so each new review spends one of your limited previews. It refuses by default and requires an
+explicit `consume_preview=true`, reports how many remain, and never silently re-fetches a cached
+review.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `RTINGS_SESSION_COOKIE` | unset | your session cookie (see below) |
+| `RTINGS_CACHE_DIR` | `~/.cache/rtings-mcp` | cache location |
+| `RTINGS_CACHE_MAX_MB` | `1024` | cache ceiling, LRU-evicted |
+| `RTINGS_ENABLE_GRAPH` | `true` | set `false` to disable `rt_graph` entirely |
+| `RTINGS_RATE_INTERVAL_S` | `2.0` | seconds per token refilled into the rtings.com request budget |
+| `RTINGS_MIN_REQUEST_INTERVAL_S` | — | **deprecated**; pins `RTINGS_RATE_INTERVAL_S` and forces burst 1, i.e. the old flat interval. Warns when set |
+| `RTINGS_RATE_BURST` | `5` | requests available immediately after an idle period |
+| `RTINGS_MAX_PREVIEW_SPEND` | `1` | metered previews `rt_product` may spend per run; `0` forbids it |
+| `RTINGS_CONFIG_DIR` | `~/.config/rtings-mcp` | where the credential is stored |
+| `RTINGS_CACHE_TTL_DAYS` | `30` | TTL for measurements and reviews; routing data has its own shorter clocks |
+| `RTINGS_CONCURRENCY` | `1` | in-flight requests to rtings.com |
+| `RTINGS_GRAPH_MAX_POINTS` | `200` | default curve resampling target |
+| `RTINGS_MAX_RESPONSE_CHARS` | `40000` | `rt_ratings` trims each group's page to fit this many characters on the wire and says where to page from |
+| `RTINGS_CDN_RATE_INTERVAL_S` / `RTINGS_CDN_RATE_BURST` | `0.25` / `10` | the asset CDN's own budget |
+| `RTINGS_TELEMETRY` | `true` | append header-only request records to `telemetry/requests.jsonl` |
+| `RTINGS_MEMBER_MODE` | `true` | member-tier caching. Set `0` to pin every cached file to the `anonymous` tier — a signed-in session then serves its rows but cannot cache them |
+| `RTINGS_SESSION_OVERRIDE` | unset | `member`/`free`/`anonymous` — assert your own tier if the probe reads it wrong |
+
+## Signing in (optional, and only adds anything on the 12 gated categories)
+
+You supply your own RTINGS session. **No password is ever requested and login is never automated** —
+you type it into RTINGS' own page, and the server keeps the resulting cookie.
+
+**In a conversation** (works in Claude Desktop and Claude Code):
+
+> "sign me in to RTINGS"
+
+That calls `rt_sign_in`, which opens a browser window on the sign-in page and answers straight
+away; `rt_auth_status(wait_s=45)` waits for you to finish. It needs the browser extra:
+
+```bash
+uv sync --extra browser        # or: pip install "rtings-mcp[browser]"
+```
+
+**In a terminal**, the same capture without an MCP client:
+
+```bash
+.venv/bin/rtings-mcp auth --browser
+```
+
+**Without a browser at all**, paste one instead. `_rtings_session` is **HttpOnly**, so
+`document.cookie` can't read it and "Copy as cURL" is the only way to get it by hand: open
+rtings.com logged in → DevTools → Network → right-click any request → Copy → Copy as cURL, then:
+
+```bash
+.venv/bin/rtings-mcp auth     # paste, press Ctrl-D; it validates and tells you what you have
+```
+
+Every path validates the cookie against RTINGS before storing it. A session that doesn't come back
+signed in is discarded, which matters more than it sounds: RTINGS hands anonymous visitors a
+`_rtings_session` too, so "a cookie appeared" proves nothing on its own.
+
+The cookie is stored `0600` in your config dir, sent only to `www.rtings.com`, never written to
+the cache, never logged, never returned in tool output. It grants access to your account, so treat
+the file accordingly and revoke it by logging out of RTINGS. `--status` shows the current session
+and `--clear` removes the stored copy.
+
+You shouldn't have to do this again. RTINGS re-issues the cookie on every response with a fresh
+30-day expiry, so it's a sliding idle window rather than a deadline from login. The server persists
+each re-issued value that came back with your account signed in, and discards the one an anonymous
+request mints. `RTINGS_SESSION_COOKIE` can't be refreshed this way, so prefer `rtings-mcp auth` for
+anything long-running.
+
+Running an automated client against your own account is your call and carries whatever obligations
+your account does. The server is cache-first, rate-limited, and does no bulk crawling.
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+uv pip install -e ".[browser]"             # only to run the browser sign-in itself
+.venv/bin/pytest tests/ -q                 # offline (the default; no network)
+.venv/bin/pytest -m live -q                # live, anonymous, against the real API
+.venv/bin/pytest -m "live and slow" -q -s  # + the 28-category enforcement re-scan
+.venv/bin/ruff check src/ tests/
+```
+
+## Legal
+
+MIT licensed ([LICENSE](LICENSE)). Not affiliated with or endorsed by RTINGS.com.
+
+The server calls the same keyless public JSON API that rtings.com's own front end calls, reads
+only what that API returns to the caller, and never attempts to reveal anything the server
+withholds. All test data and measurements are RTINGS' own, subject to their
+[Terms of Use](https://www.rtings.com/company/terms-of-use). Cache locally, don't redistribute it.

rtings_mcp-0.2.1/README.md

@@ -0,0 +1,211 @@
+# rtings-mcp
+
+> ### ⚠️ Not a paywall bypass
+> RTINGS gates some test values and scores server-side. This server reads what your own session
+> is already entitled to. On the categories that enforce the paywall, gated values come back
+> `null` without a membership. The tool can't unlock them, and it never estimates, interpolates
+> or infers them. For those numbers you have to pay RTINGS and sign in.
+
+An MCP server that exposes [RTINGS.com](https://www.rtings.com) test data as structured tools:
+0–10 scores, scalar measurements with units, specs, and the measurement curves behind them. It
+runs locally. Nothing is hosted and nothing is shared.
+
+RTINGS' JSON API is keyless and public, and a lot comes back anonymously. Signing in adds data on
+the 12 categories that gate.
+
+> **Status: working, anonymous and signed in.** All seven data tools run against the live API, and
+> two more connect a membership.
+> **A membership cookie does unblur the JSON API** — measured 2026-09-06 on a bought membership:
+> 588 of 588 withheld rows came back with real values where anonymous got none
+> ([`RECON.md`](RECON.md) §13). Member mode is on by default as of that measurement, so a
+> signed-in session caches its rows under their own tier; `RTINGS_MEMBER_MODE=0` pins everything
+> back to `anonymous`.
+> [`SPEC.md`](SPEC.md) is the design of record and [`RECON.md`](RECON.md) the measured evidence.
+
+## What anonymous gets
+
+An anonymous sweep of all 28 categories ([`RECON.md` §11](RECON.md)) found the rule:
+
+```
+blurred  ⇔  product.published == false          (Early Access, an Insider perk separate from the category paywall)
+         ∨  (test.insider_only  ∧  the CATEGORY enforces the paywall)
+```
+
+Enforcement is per-category and binary. 12 of 28 enforce, 16 don't.
+
+| | Categories | Anonymous gets |
+|---|---|---|
+| **Open (16)** | mattress, vacuum, air-purifier, air-fryer, refrigerator, microwave, toaster, toaster-oven, air-conditioner, dehumidifier, humidifier, blender, vpn, keyboard-switch, camera, running-shoes | test values, scores, ranking and comparison. The numbers are served. |
+| **Gated (12)** | tv, headphones, monitor, mouse, keyboard, soundbar, speaker, printer, laptop, robot-vacuum, projector, router | catalog, schema, search, **RTINGS' written verdicts, pros and cons**, review prose, ranked best-of lists, published curve data, and a handful of public spec fields with their scores |
+
+Every category reports `has_paywall: true`, so that flag carries no information. Only the served
+data shows the split. What decides it is unknown and it will change, so the server never hardcodes
+it; `rt_silos()` reports what your machine observed. The map is re-scanned before each release
+against [`docs/enforcement-snapshot.json`](docs/enforcement-snapshot.json) (baseline 2026-09-03,
+re-verified 2026-09-06: 12/16, unchanged — and re-verified *with* a membership stored, which the
+scan ignores by construction, so the map stays an anonymous measurement).
+
+## Honest nulls
+
+Gated values come back `null` with a typed output schema and structural `auth_state` /
+`data_tier` / `scores_available` fields. Every row says why it has no value: measured but hidden,
+not applicable, not tested, Early Access, or outside what the server can show it has fetched. An
+agent can't read "no member session" as "RTINGS did not test this."
+
+## Install
+
+From PyPI, with nothing to clone (`uvx` fetches and caches the package on first run):
+
+```bash
+claude mcp add rtings --scope user -- uvx rtings-mcp
+```
+
+For the in-conversation browser sign-in (`rt_sign_in`) install the `browser` extra instead:
+
+```bash
+claude mcp add rtings --scope user -- uvx --from "rtings-mcp[browser]" rtings-mcp
+```
+
+Or from a checkout, if you want to work on it:
+
+```bash
+git clone https://github.com/Averyy/rtings-mcp && cd rtings-mcp
+uv venv && uv pip install -e .
+claude mcp add rtings --scope user -- uv --directory /absolute/path/to/rtings-mcp run rtings-mcp
+```
+
+`--scope user` makes it available in every project. Drop it to scope the server to the current
+directory. Verify with:
+
+```bash
+claude mcp get rtings      # expect: Status: ✔ Connected
+```
+
+A connected server keeps running the code it started with, so restart the session after editing
+the source. `/reload-plugins` won't do it; it only handles servers bundled inside plugins.
+
+No configuration is needed to start. Anonymous is the default and never an error.
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `rt_silos(silos?)` | the 28 categories with **observed** paywall enforcement |
+| `rt_schema(silo, bench?, group?, find?)` | test/usage definitions: name, kind, unit, hierarchy, `insider_only`; `find` searches the bench by name |
+| `rt_ratings(silo, tests?, usages?, filters?, sort?, limit?)` | catalog + 0–10 usage scores, with an optional scalar projection; `filters.product_ids` for a head-to-head |
+| `rt_product(product, group?, tests?)` | one review: test results (bounded by `group` or `tests`), plus RTINGS' verdicts and pros/cons with `include_verdicts` (`include_results=false` for the words alone) |
+| `rt_graph(product, test)` | one test's measurement curve, resampled by selecting shipped points |
+| `rt_search(query)` | model name/number → candidates across all categories |
+| `rt_recommendations(silo, list?, limit?)` | the category's best-of lists, or one ranked list with reasoning |
+| `rt_sign_in(force?)` | opens a browser window on RTINGS' sign-in page and stores the resulting cookie |
+| `rt_auth_status(wait_s?)` | what credential is stored, and how a sign-in in progress is going |
+
+Results are compared within a **test bench**, RTINGS' version of its methodology. Cross-bench
+results come back nested in separate groups and `limit` applies within each.
+
+`filters` and `sort` take a test's id or its name, plus `brand`, `name_contains`, `published` and
+`variant`. `variant` is the size RTINGS tested, which is how you ask for 65-inch TVs, since most
+categories have no "Size" test. A field you filter or sort on is fetched for you. When one can't be
+compared the predicate is **not applied** and the response names why: gated for this session,
+absent from the bench queried, or measured-but-empty. Otherwise an empty result reads as "no
+product qualifies" when the truth is "you can't see it". Rows with no comparable value sort last in
+both directions.
+
+**On a gated category, ask for the verdicts.** `rt_product(url, include_verdicts=true)` returns
+RTINGS' per-usage judgement in their own words, their pros and cons, and how each usage score is
+composed. Those come through even where every measurement is null.
+
+⚠️ **`rt_product` can cost you something.** On a free account it hits the endpoint RTINGS meters,
+so each new review spends one of your limited previews. It refuses by default and requires an
+explicit `consume_preview=true`, reports how many remain, and never silently re-fetches a cached
+review.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `RTINGS_SESSION_COOKIE` | unset | your session cookie (see below) |
+| `RTINGS_CACHE_DIR` | `~/.cache/rtings-mcp` | cache location |
+| `RTINGS_CACHE_MAX_MB` | `1024` | cache ceiling, LRU-evicted |
+| `RTINGS_ENABLE_GRAPH` | `true` | set `false` to disable `rt_graph` entirely |
+| `RTINGS_RATE_INTERVAL_S` | `2.0` | seconds per token refilled into the rtings.com request budget |
+| `RTINGS_MIN_REQUEST_INTERVAL_S` | — | **deprecated**; pins `RTINGS_RATE_INTERVAL_S` and forces burst 1, i.e. the old flat interval. Warns when set |
+| `RTINGS_RATE_BURST` | `5` | requests available immediately after an idle period |
+| `RTINGS_MAX_PREVIEW_SPEND` | `1` | metered previews `rt_product` may spend per run; `0` forbids it |
+| `RTINGS_CONFIG_DIR` | `~/.config/rtings-mcp` | where the credential is stored |
+| `RTINGS_CACHE_TTL_DAYS` | `30` | TTL for measurements and reviews; routing data has its own shorter clocks |
+| `RTINGS_CONCURRENCY` | `1` | in-flight requests to rtings.com |
+| `RTINGS_GRAPH_MAX_POINTS` | `200` | default curve resampling target |
+| `RTINGS_MAX_RESPONSE_CHARS` | `40000` | `rt_ratings` trims each group's page to fit this many characters on the wire and says where to page from |
+| `RTINGS_CDN_RATE_INTERVAL_S` / `RTINGS_CDN_RATE_BURST` | `0.25` / `10` | the asset CDN's own budget |
+| `RTINGS_TELEMETRY` | `true` | append header-only request records to `telemetry/requests.jsonl` |
+| `RTINGS_MEMBER_MODE` | `true` | member-tier caching. Set `0` to pin every cached file to the `anonymous` tier — a signed-in session then serves its rows but cannot cache them |
+| `RTINGS_SESSION_OVERRIDE` | unset | `member`/`free`/`anonymous` — assert your own tier if the probe reads it wrong |
+
+## Signing in (optional, and only adds anything on the 12 gated categories)
+
+You supply your own RTINGS session. **No password is ever requested and login is never automated** —
+you type it into RTINGS' own page, and the server keeps the resulting cookie.
+
+**In a conversation** (works in Claude Desktop and Claude Code):
+
+> "sign me in to RTINGS"
+
+That calls `rt_sign_in`, which opens a browser window on the sign-in page and answers straight
+away; `rt_auth_status(wait_s=45)` waits for you to finish. It needs the browser extra:
+
+```bash
+uv sync --extra browser        # or: pip install "rtings-mcp[browser]"
+```
+
+**In a terminal**, the same capture without an MCP client:
+
+```bash
+.venv/bin/rtings-mcp auth --browser
+```
+
+**Without a browser at all**, paste one instead. `_rtings_session` is **HttpOnly**, so
+`document.cookie` can't read it and "Copy as cURL" is the only way to get it by hand: open
+rtings.com logged in → DevTools → Network → right-click any request → Copy → Copy as cURL, then:
+
+```bash
+.venv/bin/rtings-mcp auth     # paste, press Ctrl-D; it validates and tells you what you have
+```
+
+Every path validates the cookie against RTINGS before storing it. A session that doesn't come back
+signed in is discarded, which matters more than it sounds: RTINGS hands anonymous visitors a
+`_rtings_session` too, so "a cookie appeared" proves nothing on its own.
+
+The cookie is stored `0600` in your config dir, sent only to `www.rtings.com`, never written to
+the cache, never logged, never returned in tool output. It grants access to your account, so treat
+the file accordingly and revoke it by logging out of RTINGS. `--status` shows the current session
+and `--clear` removes the stored copy.
+
+You shouldn't have to do this again. RTINGS re-issues the cookie on every response with a fresh
+30-day expiry, so it's a sliding idle window rather than a deadline from login. The server persists
+each re-issued value that came back with your account signed in, and discards the one an anonymous
+request mints. `RTINGS_SESSION_COOKIE` can't be refreshed this way, so prefer `rtings-mcp auth` for
+anything long-running.
+
+Running an automated client against your own account is your call and carries whatever obligations
+your account does. The server is cache-first, rate-limited, and does no bulk crawling.
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+uv pip install -e ".[browser]"             # only to run the browser sign-in itself
+.venv/bin/pytest tests/ -q                 # offline (the default; no network)
+.venv/bin/pytest -m live -q                # live, anonymous, against the real API
+.venv/bin/pytest -m "live and slow" -q -s  # + the 28-category enforcement re-scan
+.venv/bin/ruff check src/ tests/
+```
+
+## Legal
+
+MIT licensed ([LICENSE](LICENSE)). Not affiliated with or endorsed by RTINGS.com.
+
+The server calls the same keyless public JSON API that rtings.com's own front end calls, reads
+only what that API returns to the caller, and never attempts to reveal anything the server
+withholds. All test data and measurements are RTINGS' own, subject to their
+[Terms of Use](https://www.rtings.com/company/terms-of-use). Cache locally, don't redistribute it.