mcp-ivolatility-data 0.1.5__tar.gz

mcp_ivolatility_data-0.1.5/.dockerignore

@@ -0,0 +1,5 @@
+core/.venv
+**/__pycache__
+**/*.pyc
+core/tests
+*.mcpb

mcp_ivolatility_data-0.1.5/.gitignore

@@ -0,0 +1,8 @@
+# Build artifacts / local env — not in repo
+*.mcpb
+**/.venv/
+**/__pycache__/
+*.pyc
+._*
+.DS_Store
+dist/

mcp_ivolatility_data-0.1.5/.mcpbignore

@@ -0,0 +1,17 @@
+.venv
+**/__pycache__
+**/*.pyc
+tests
+docs
+k8s
+scripts
+dist
+Dockerfile
+.dockerignore
+.gitignore
+build_instructions.py
+instructions_map.yml
+instructions_seals.json
+run-data-mcp.sh
+*.mcpb
+.pytest_cache

mcp_ivolatility_data-0.1.5/Dockerfile

@@ -0,0 +1,29 @@
+# Remote iVolatility data MCP connector (streamable-http) for self-hosting (k8s).
+# Build context = mcp/ directory.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Runtime deps (same set as pyproject.toml). Pinned-light; tighten later.
+RUN pip install --no-cache-dir \
+    "mcp>=1.27.0" \
+    "certifi>=2026.2.25" \
+    "httpx>=0.28.1" \
+    "numpy>=2.4.4" \
+    "python-dotenv>=1.2.2" \
+    "pydantic>=2.12.5" \
+    "sqlglot>=30.4.0" \
+    "pyyaml>=6.0"
+
+# Source layout (engine + connector wrapper incl. bundled index/instructions).
+COPY src /app/src
+
+ENV PYTHONPATH=/app/src \
+    MCP_TRANSPORT=streamable-http \
+    MCP_HOST=0.0.0.0 \
+    MCP_PORT=8000
+# IVOL_API_KEY is provided at deploy time (k8s secret / env) — NEVER baked in.
+
+EXPOSE 8000
+
+CMD ["python", "-m", "mcp_ivolatility_data"]

mcp_ivolatility_data-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Massive.com
+
+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.

mcp_ivolatility_data-0.1.5/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: mcp-ivolatility-data
+Version: 0.1.5
+Summary: iVolatility market data in any MCP client: option chains, IV surface/IVX/skew, greeks, NBBO, earnings
+Project-URL: Homepage, https://www.ivolatility.com
+Project-URL: Documentation, https://www.ivolatility.com/api-features/
+Author-email: iVolatility <support@ivolatility.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: certifi>=2026.2.25
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlglot>=30.4.0
+Description-Content-Type: text/markdown
+
+# mcp-ivolatility-data
+
+iVolatility market data MCP server for local use by data-oriented clients
+(quants with their own Claude, Cursor, or any MCP client). One package ships
+the engine (`ivol_mcp_core`) and the bundled endpoint index, and runs the tools
+(`search_endpoints` → `call_api` → `query_data`) against the iVolatility REST API.
+
+No hosting — the client installs it locally and uses their own `IVOL_API_KEY`.
+Access control stays on the REST API (tariff/limits by key).
+
+## Install
+
+```bash
+uv tool install mcp-ivolatility-data
+claude mcp add ivolatility -e IVOL_API_KEY=<key> -- mcp-ivolatility-data
+```
+
+Or any `mcp.json`-style client (Cursor, …): `command: mcp-ivolatility-data`,
+`env: {IVOL_API_KEY: <key>}`. `uv` brings its own Python — the client does not
+install Python manually. Claude Desktop users: prefer the `.mcpb` bundle
+(double-click install, key form) or the remote connector URL.
+
+## What it covers
+
+65 endpoints: full REST (equities/futures EOD+intraday, RT REST, fixed income,
+curves) from the bundled OpenAPI spec, plus `/account/access` and WebSocket
+discovery from the prompt supplement. (RT market-wide screeners intentionally
+excluded.)
+
+## Env
+
+| Var | Required | Purpose |
+|-----|----------|---------|
+| `IVOL_API_KEY` | yes | iVolatility API key (sent as `?apiKey=`) |
+| `IVOL_API_BASE_URL` | no | defaults to `https://restapi.ivolatility.com` |
+
+Index sources (`openapi_ivolatility.yml`, `index_supplement.yml`) are bundled
+with the package; `IVOL_OPENAPI_PATH` / `IVOL_SUPPLEMENT_PATH` override them.

mcp_ivolatility_data-0.1.5/README.md

@@ -0,0 +1,72 @@
+# iVolatility Market Data — MCP Connector
+
+One MCP connector that gives any MCP client (claude.ai, Claude Code, Claude Desktop,
+Cursor…) live iVolatility data: option chains, IV/IVX/skew, greeks, equity & futures
+prices, NBBO, earnings, instrument discovery. Built on the `massive-com/mcp_massive`
+architecture (MIT) — composable tools + an in-memory store.
+
+**Docs:**
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — how it works and why it's built this way
+- [docs/USAGE.md](docs/USAGE.md) — connecting from claude.ai / Claude Code / Desktop, examples, troubleshooting
+- [docs/INSTALL.md](docs/INSTALL.md) — deploying remote, building the local `.mcpb`, env vars, tests
+
+## TL;DR
+
+- **Remote**: `https://mcp.ivolatility.com/mcp?apiKey=<user key>` — the path is `/mcp`.
+  Per-user auth; no server-side key exists.
+- **Local**: `scripts/build-mcpb.sh` → `dist/ivolatility-data-<ver>.mcpb` for
+  Claude Desktop (adds real file export, which is disabled on remote).
+- Five tools: `search_endpoints → call_api → query_data` (+ `export_data`,
+  `account_access`). Per-user in-memory tables, 1h TTL, isolated per apiKey.
+
+## Layout
+
+```
+mcp/
+  pyproject.toml     ONE PyPI distribution (mcp-ivolatility-data) shipping both packages
+  src/
+    ivol_mcp_core/           engine (mcp_massive fork): tools, store, index, assembly
+    mcp_ivolatility_data/    wrapper + CANONICAL index sources + instructions
+      openapi_ivolatility.yml    ← the only copy of the spec (63 endpoints)
+      index_supplement.yml       ← FTS enrich keys + account/WS overlay
+      instructions/*.md          ← prompt chunks (+ .stdio/.remote transport variants)
+  tests/             unit suite (integration/ is Massive-era, broken — see TODO)
+  k8s/ivol-mcp.yaml  remote deployment (ns mcp)
+  scripts/build-mcpb.sh + scripts/stamp-pypi-version.py
+  manifest.json      .mcpb passport (bundle root = mcp/)
+  build_instructions.py + instructions_map.yml + instructions_seals.json  ← prompt watchdog
+```
+
+Dedup rule: the spec and supplement live **only** inside `src/mcp_ivolatility_data/` —
+no copies at the mcp/ root (two copies silently drifted apart once already, 2026-07-01/02).
+
+## Status / TODO
+
+- [x] package the `uv tool install` local path — ONE PyPI project `mcp-ivolatility-data`
+  (both import packages in one wheel), CI `publish:pypi-mcp` on `mcp-v*` tags
+  (2026-07-09; wheel + entry point smoke-tested from a clean venv locally)
+- [ ] verify the PyPI path end-to-end after the first published `mcp-v*` tag (`uv tool install` from real PyPI; needs `PYPI_TOKEN_MCP` CI var set)
+- [ ] CI job running the unit tests (632 passing locally via `cd mcp && uv run pytest tests --ignore=tests/integration`; CI doesn't run them yet)
+- [ ] tests/integration is Massive-era and broken (`configure_credentials` API drift) — rewrite against the iVol server or drop; unit tests import its `mock_llms_txt`, so don't delete blindly
+- [ ] futures-intraday market label (minor: `Minute Historical Futures Intervals` → Futures)
+
+## History
+
+- **2026-06-26** — fork of `mcp_massive`, iVol adaptation (auth, envelope, download
+  pattern, index from OpenAPI + supplement).
+- **2026-06-29/30** — remote deploy on kvscode (mcp.ivolatility.com) + vps-s backup;
+  prompt watchdog (MR !89).
+- **2026-07-01** — security fix (shared server key removed), guidance moved into
+  tool descriptions (claude.ai ignores MCP `instructions`, #43749).
+- **2026-07-02** — per-user store isolation, transport-aware instructions, honest
+  remote export, source dedup, test-suite revival, `.mcpb` build script.
+- **Connector #2 (backtesting)** — built 2026-07-01 (`run_backtest_in_pod` via a
+  per-user Coder token), **removed 2026-07-02**: the full IVolAI ships as a Claude Code
+  Plugin (`ivolai-dist`) — remote MCP can't deliver the role/protocol to the model
+  (#43749, #56243), and inside a workspace pod the agent runs backtests natively.
+  Code remains in the git history of `feature/mcp-connector`; images
+  `ivol-mcp-backtesting:v0.1.0–v0.1.3` remain in Harbor.
+
+## Origin
+
+`core/` is a fork of `massive-com/mcp_massive` (MIT, see `core/LICENSE`).

mcp_ivolatility_data-0.1.5/README.pypi.md

@@ -0,0 +1,38 @@
+# mcp-ivolatility-data
+
+iVolatility market data MCP server for local use by data-oriented clients
+(quants with their own Claude, Cursor, or any MCP client). One package ships
+the engine (`ivol_mcp_core`) and the bundled endpoint index, and runs the tools
+(`search_endpoints` → `call_api` → `query_data`) against the iVolatility REST API.
+
+No hosting — the client installs it locally and uses their own `IVOL_API_KEY`.
+Access control stays on the REST API (tariff/limits by key).
+
+## Install
+
+```bash
+uv tool install mcp-ivolatility-data
+claude mcp add ivolatility -e IVOL_API_KEY=<key> -- mcp-ivolatility-data
+```
+
+Or any `mcp.json`-style client (Cursor, …): `command: mcp-ivolatility-data`,
+`env: {IVOL_API_KEY: <key>}`. `uv` brings its own Python — the client does not
+install Python manually. Claude Desktop users: prefer the `.mcpb` bundle
+(double-click install, key form) or the remote connector URL.
+
+## What it covers
+
+65 endpoints: full REST (equities/futures EOD+intraday, RT REST, fixed income,
+curves) from the bundled OpenAPI spec, plus `/account/access` and WebSocket
+discovery from the prompt supplement. (RT market-wide screeners intentionally
+excluded.)
+
+## Env
+
+| Var | Required | Purpose |
+|-----|----------|---------|
+| `IVOL_API_KEY` | yes | iVolatility API key (sent as `?apiKey=`) |
+| `IVOL_API_BASE_URL` | no | defaults to `https://restapi.ivolatility.com` |
+
+Index sources (`openapi_ivolatility.yml`, `index_supplement.yml`) are bundled
+with the package; `IVOL_OPENAPI_PATH` / `IVOL_SUPPLEMENT_PATH` override them.

mcp_ivolatility_data-0.1.5/build_instructions.py

@@ -0,0 +1,384 @@
+#!/usr/bin/env python3
+"""mcp prompt watchdog — резалка-сторож (the inverse-aware companion to claude/split.py).
+
+The mcp instruction chunks (``data/.../instructions/*.md``) are a MANUAL distillation
+of the master prompts (``users_data/basic/prompts/*.md``) — short, rewritten
+cheat-sheets, NOT 1:1 slices. A regex cannot reproduce a distillation, so this tool
+does NOT generate or rewrite chunks and NEVER touches the master prompts.
+
+What it does instead — it is a SENTINEL ("сторож"):
+
+  * keeps a "seal" (hash) of the master section each watched chunk was distilled from,
+  * on --check compares the live master section's hash to the seal and FAILS if the
+    master section changed but the chunk was not refreshed (catches a stale chunk
+    before it ships to prod),
+  * on --diff shows what changed in that section (sealed snapshot -> current) plus the
+    current chunk, so a human (or Claude) can update the distillation,
+  * on --reseal recomputes the seals after chunks were updated.
+
+Map (which chunk <- which master section, by heading anchor) lives in
+``instructions_map.yml`` (human-authored, commented). Seals (machine-written hashes +
+section snapshots) live in ``instructions_seals.json`` so the map keeps its comments.
+
+Usage:
+  build_instructions.py --check      # default; exit 1 on stale / missing anchor / no seal
+  build_instructions.py --diff       # show master-section change + current chunk
+  build_instructions.py --reseal     # re-stamp seals after updating chunks
+  build_instructions.py --repo PATH  # override repo root (default: parent of this file)
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+REPO_DEFAULT = Path(__file__).resolve().parent.parent  # mcp/ -> repo root
+MAP_REL = "mcp/instructions_map.yml"
+SEALS_REL = "mcp/instructions_seals.json"
+
+
+# ── section extraction ─────────────────────────────────────────────────────────
+def heading_level(line: str) -> int | None:
+    """Markdown ATX heading level (``###`` -> 3), or None if not a heading."""
+    s = line.lstrip()
+    n = len(s) - len(s.lstrip("#"))
+    if n > 0 and s[n : n + 1] == " ":
+        return n
+    return None
+
+
+def extract_section(text: str, anchor: str) -> str | None:
+    """Return the master section starting at the heading that startswith ``anchor``,
+    up to (excluding) the next heading of level <= the anchor's level (or EOF).
+    None if the anchor heading is not found."""
+    lines = text.splitlines()
+    anchor = anchor.strip()
+    start = level = None
+    for i, ln in enumerate(lines):
+        lv = heading_level(ln)
+        if lv is not None and ln.strip().startswith(anchor):
+            start, level = i, lv
+            break
+    if start is None:
+        return None
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        lv = heading_level(lines[j])
+        if lv is not None and lv <= level:
+            end = j
+            break
+    return "\n".join(lines[start:end])
+
+
+def normalize(section: str) -> str:
+    """Whitespace-stable form for hashing (ignore trailing spaces / blank edges)."""
+    return "\n".join(l.rstrip() for l in section.splitlines()).strip()
+
+
+def section_sha(section: str) -> str:
+    return hashlib.sha256(normalize(section).encode("utf-8")).hexdigest()[:12]
+
+
+# ── map / seals io ─────────────────────────────────────────────────────────────
+def load_map(repo: Path) -> dict:
+    return yaml.safe_load((repo / MAP_REL).read_text(encoding="utf-8")) or {}
+
+
+def load_seals(repo: Path) -> dict:
+    p = repo / SEALS_REL
+    if not p.exists():
+        return {}
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def save_seals(repo: Path, seals: dict) -> None:
+    (repo / SEALS_REL).write_text(
+        json.dumps(seals, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def iter_watched(cfg: dict):
+    """Yield (connector, chunk_dict) for every chunk that is bound to a master section
+    (skips ``source: own`` chunks)."""
+    for conn, c in (cfg.get("connectors") or {}).items():
+        idir = c.get("instructions_dir", "")
+        for ch in c.get("chunks") or []:
+            yield conn, idir, ch
+
+
+def seal_key(conn: str, file: str) -> str:
+    return f"{conn}/{file}"
+
+
+# ── live section read (returns (section, error)) ───────────────────────────────
+def read_section(repo: Path, ch: dict):
+    master = repo / ch["master"]
+    if not master.exists():
+        return None, f"master not found: {ch['master']}"
+    sec = extract_section(master.read_text(encoding="utf-8"), ch["anchor"])
+    if sec is None:
+        return None, f'anchor not found in master: "{ch["anchor"]}"'
+    return sec, None
+
+
+# ── tool-description watching ──────────────────────────────────────────────────
+# Guidance lives TWICE by necessity: in the instructions chunks (read by clients
+# that honour MCP `instructions`) and in the tool docstrings (the only channel
+# claude.ai actually reads — issue #43749). These helpers seal the docstrings so
+# a docstring edit forces a conscious review of the md chunks (and vice versa —
+# the chunk edits are caught by the master seals above).
+def iter_tooldesc(cfg: dict):
+    """Yield (module_rel_path, function_name) for every watched tool docstring."""
+    for entry in cfg.get("tool_descriptions") or []:
+        module = entry.get("module", "")
+        for fn in entry.get("functions") or []:
+            yield module, fn
+
+
+def read_tool_docstring(repo: Path, module_rel: str, func_name: str):
+    """Return (docstring, error) for ``func_name`` in ``module_rel``."""
+    import ast
+
+    module = repo / module_rel
+    if not module.exists():
+        return None, f"module not found: {module_rel}"
+    try:
+        tree = ast.parse(module.read_text(encoding="utf-8"))
+    except SyntaxError as e:
+        return None, f"syntax error in {module_rel}: {e}"
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == func_name:
+            doc = ast.get_docstring(node)
+            if not doc:
+                return None, f"{module_rel}:{func_name} has no docstring"
+            return doc, None
+    return None, f"function not found: {module_rel}:{func_name}"
+
+
+def tooldesc_key(func_name: str) -> str:
+    return f"tooldesc/{func_name}"
+
+
+# ── commands ───────────────────────────────────────────────────────────────────
+def cmd_check(repo: Path) -> int:
+    cfg = load_map(repo)
+    seals = load_seals(repo)
+    stale, missing, unsealed, ok = [], [], [], []
+
+    for conn, idir, ch in iter_watched(cfg):
+        f = ch["file"]
+        chunk_path = repo / idir / f
+        if not chunk_path.exists():
+            missing.append(f"{conn}/{f}: chunk file missing ({idir}/{f})")
+            continue
+        if ch.get("source") == "own":
+            ok.append(f"{conn}/{f}  (own — not watched)")
+            continue
+
+        sec, err = read_section(repo, ch)
+        if err:
+            missing.append(f"{conn}/{f}: {err}")
+            continue
+
+        key = seal_key(conn, f)
+        live = section_sha(sec)
+        sealed = (seals.get(key) or {}).get("sha")
+        if sealed is None:
+            unsealed.append(f"{conn}/{f}  (no seal yet — run --reseal)")
+        elif sealed != live:
+            stale.append(f'{conn}/{f}  master section "{ch["anchor"]}" changed '
+                         f"(sealed {sealed} -> live {live})")
+        else:
+            ok.append(f"{conn}/{f}  (seal {sealed} OK)")
+
+    for module, fn in iter_tooldesc(cfg):
+        doc, err = read_tool_docstring(repo, module, fn)
+        if err:
+            missing.append(f"tooldesc/{fn}: {err}")
+            continue
+        key = tooldesc_key(fn)
+        live = section_sha(doc)
+        sealed = (seals.get(key) or {}).get("sha")
+        if sealed is None:
+            unsealed.append(f"tooldesc/{fn}  (no seal yet — run --reseal)")
+        elif sealed != live:
+            stale.append(
+                f"tooldesc/{fn}  tool-description changed (sealed {sealed} -> live "
+                f"{live}) — sync the instructions chunks (data/*.md), then --reseal"
+            )
+        else:
+            ok.append(f"tooldesc/{fn}  (seal {sealed} OK)")
+
+    print("=== check:prompts — mcp watchdog ===")
+    for line in ok:
+        print(f"  ✅ {line}")
+    for line in unsealed:
+        print(f"  ⚠️  {line}")
+    for line in missing:
+        print(f"  ❌ {line}")
+    for line in stale:
+        print(f"  ❌ STALE  {line}")
+
+    fail = stale or missing or unsealed
+    print()
+    if fail:
+        print("FAIL — prompt chunks out of sync with master.")
+        if stale:
+            print("  → review:  python3 mcp/build_instructions.py --diff")
+            print("  → fix the chunk(s), then:  python3 mcp/build_instructions.py --reseal")
+        if unsealed:
+            print("  → first run:  python3 mcp/build_instructions.py --reseal")
+        return 1
+    print("OK — all watched chunks in sync with master.")
+    return 0
+
+
+def cmd_diff(repo: Path) -> int:
+    cfg = load_map(repo)
+    seals = load_seals(repo)
+    shown = 0
+
+    for conn, idir, ch in iter_watched(cfg):
+        if ch.get("source") == "own":
+            continue
+        f = ch["file"]
+        sec, err = read_section(repo, ch)
+        if err:
+            print(f"❌ {conn}/{f}: {err}\n")
+            shown += 1
+            continue
+        key = seal_key(conn, f)
+        live = section_sha(sec)
+        rec = seals.get(key) or {}
+        if rec.get("sha") == live:
+            continue  # in sync — nothing to show
+
+        shown += 1
+        print(f"┌─ {conn}/{f}  ← master section \"{ch['anchor']}\"")
+        sealed_text = rec.get("section", "")
+        if sealed_text:
+            print("│  MASTER SECTION CHANGED (sealed → current):")
+            d = difflib.unified_diff(
+                normalize(sealed_text).splitlines(),
+                normalize(sec).splitlines(),
+                fromfile="sealed", tofile="current", lineterm="",
+            )
+            for ln in d:
+                print(f"│    {ln}")
+        else:
+            print("│  (no sealed snapshot yet — current master section:)")
+            for ln in normalize(sec).splitlines():
+                print(f"│    {ln}")
+        chunk_path = repo / idir / f
+        print(f"│  CURRENT CHUNK ({idir}/{f}):")
+        for ln in chunk_path.read_text(encoding="utf-8").splitlines():
+            print(f"│    {ln}")
+        print("└─ update the chunk to reflect the master change, then --reseal\n")
+
+    for module, fn in iter_tooldesc(cfg):
+        doc, err = read_tool_docstring(repo, module, fn)
+        if err:
+            print(f"❌ tooldesc/{fn}: {err}\n")
+            shown += 1
+            continue
+        rec = seals.get(tooldesc_key(fn)) or {}
+        if rec.get("sha") == section_sha(doc):
+            continue
+        shown += 1
+        print(f"┌─ tooldesc/{fn}  ← docstring in {module}")
+        sealed_text = rec.get("docstring", "")
+        if sealed_text:
+            print("│  TOOL-DESCRIPTION CHANGED (sealed → current):")
+            d = difflib.unified_diff(
+                normalize(sealed_text).splitlines(),
+                normalize(doc).splitlines(),
+                fromfile="sealed", tofile="current", lineterm="",
+            )
+            for ln in d:
+                print(f"│    {ln}")
+        else:
+            print("│  (no sealed snapshot yet — current docstring:)")
+            for ln in normalize(doc).splitlines():
+                print(f"│    {ln}")
+        print("└─ sync the instructions chunks (data/*.md) if needed, then --reseal\n")
+
+    if shown == 0:
+        print("Nothing to diff — all watched chunks in sync.")
+    return 0
+
+
+def cmd_reseal(repo: Path) -> int:
+    cfg = load_map(repo)
+    seals = load_seals(repo)
+    changed = 0
+
+    for conn, idir, ch in iter_watched(cfg):
+        if ch.get("source") == "own":
+            continue
+        f = ch["file"]
+        sec, err = read_section(repo, ch)
+        if err:
+            print(f"  ❌ {conn}/{f}: {err} — NOT sealed")
+            continue
+        key = seal_key(conn, f)
+        sha = section_sha(sec)
+        prev = (seals.get(key) or {}).get("sha")
+        seals[key] = {"sha": sha, "anchor": ch["anchor"],
+                      "master": ch["master"], "section": sec}
+        if prev != sha:
+            changed += 1
+            print(f"  🔏 {conn}/{f}  {prev or '(new)'} -> {sha}")
+        else:
+            print(f"  •  {conn}/{f}  {sha} (unchanged)")
+
+    for module, fn in iter_tooldesc(cfg):
+        doc, err = read_tool_docstring(repo, module, fn)
+        if err:
+            print(f"  ❌ tooldesc/{fn}: {err} — NOT sealed")
+            continue
+        key = tooldesc_key(fn)
+        sha = section_sha(doc)
+        prev = (seals.get(key) or {}).get("sha")
+        seals[key] = {"sha": sha, "module": module, "function": fn, "docstring": doc}
+        if prev != sha:
+            changed += 1
+            print(f"  🔏 tooldesc/{fn}  {prev or '(new)'} -> {sha}")
+        else:
+            print(f"  •  tooldesc/{fn}  {sha} (unchanged)")
+
+    save_seals(repo, seals)
+    print(f"\nSealed {changed} changed chunk(s). Wrote {SEALS_REL}.")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    g = ap.add_mutually_exclusive_group()
+    g.add_argument("--check", action="store_true", help="verify seals (default)")
+    g.add_argument("--diff", action="store_true", help="show master change + chunk")
+    g.add_argument("--reseal", action="store_true", help="re-stamp seals after fixes")
+    ap.add_argument("--repo", default=str(REPO_DEFAULT), help="repo root")
+    args = ap.parse_args()
+
+    repo = Path(args.repo).resolve()
+    if not (repo / MAP_REL).exists():
+        print(f"FATAL: map not found: {repo / MAP_REL}", file=sys.stderr)
+        return 2
+
+    if args.diff:
+        return cmd_diff(repo)
+    if args.reseal:
+        return cmd_reseal(repo)
+    return cmd_check(repo)
+
+
+if __name__ == "__main__":
+    sys.exit(main())