substack-saved-mcp: Instructions file for Claude Code

CLAUDE.md

substack-saved-mcp CLAUDE.md is an instructions file for Claude Code from toniher/substack-saved-mcp. It costs 7,621 tokens per session, scanned A, original, MIT.

A set of instructions for Claude Code when working on the Substack Saved MCP repository. It documents development commands, tests, package building, code checks, and the repository structure.

In plain words
What is it for?
Setting up the project with uv, running tests, building or running the package, checking code style, and understanding its main components.
Why use it?
It gives the coding agent the project’s expected commands and conventions, reducing guesswork when changing the code.

Instructions file for Claude Code

Written for Claude Code: the file is CLAUDE.md. Also seen: mentions CLAUDE.md; mentions Claude Code.

This is toniher/substack-saved-mcp's own configuration. It tells Claude Code how to work on substack-saved-mcp itself, so it is not a mod to install elsewhere. Copy it as a starting point and replace the rules that are about this project. Everything substack-saved-mcp configures →

Reuse

Borrowing it

Nothing to install: this file belongs to toniher/substack-saved-mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file
curl -O https://raw.githubusercontent.com/toniher/substack-saved-mcp/main/CLAUDE.md
Clone the repo
git clone --depth 1 https://github.com/toniher/substack-saved-mcp

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for substack-saved-mcp CLAUDE.md

README.md
[![agentmods](https://agentmods.dev/badge/instructions/toniher/substack-saved-mcp/claude-md/github.svg)](https://agentmods.dev/instructions/toniher/substack-saved-mcp/claude-md)
Your own site
<a href="https://agentmods.dev/instructions/toniher/substack-saved-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/toniher/substack-saved-mcp/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for substack-saved-mcp CLAUDE.md

Your own site · 80×15
<a href="https://agentmods.dev/instructions/toniher/substack-saved-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/toniher/substack-saved-mcp/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 7,621 This file is loaded in full into every session.
When invoked 7,621 The same file — it is already loaded in full.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.07621 $0.07621
Opus 5.5 $0.03048 $0.03048
Sonnet 5.5 $0.01524 $0.01524
Haiku 4.5 $0.00762 $0.00762

Measured 17d ago against content hash d6cd01d56d19, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

substack-saved-mcp CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 17d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 52 lines

How it starts

The opening of the file, as written. The whole thing — 52 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Commands

Use uv for all development commands. Set up the environment with:

uv sync --extra dev
Task Command
Run all tests uv run python -m pytest
Run one test file uv run python -m pytest tests/test_database.py
Run one test uv run python -m pytest tests/test_database.py::test_fts5_search
Build the package uv build
Run the CLI uv run substack-saved-mcp --help
Reinstall tool globally uv tool install . --no-cache --force

ruff is configured in pyproject.toml (rules: E4, E7, E9, F, I, UP, B, RUF, line length 88, target py311). Lint with uvx ruff check . or uv run ruff check ..

After any change to dependencies or tracked files, run uv lock to keep uv.lock current, then prek run --all-files (using the repo's .pre-commit-config.yaml) before considering the work done.

Architecture

  • cli.py is the Click entry point (substack-saved-mcp). Its commands initialize the database and then delegate to the repository, sync engine, Playwright client, or MCP server.
  • mcp_server.py exposes the same application operations as FastMCP stdio tools and resources. Read tools query the local cache; sync and save/unsave operations use the authenticated browser session.
  • substack_client.py owns Playwright authentication and remote Substack interaction. login is the only intended headful workflow; normal sync and write paths use storage_state.json headlessly. Synchronous Playwright API calls are routed through _run_playwright_sync() to safely execute in a worker thread if an asyncio event loop is active (e.g. under FastMCP). The legacy reader inbox API (GET /api/v1/reader/posts?inboxType=saved, second in the source chain described below) exposes the real bookmark timestamp (saved_at) and an ISO publication date (post_date) per post. _fetch_all_saved_via_reader_api() cursor-paginates that endpoint (each page's oldest saved_at becomes the next after= cursor, until more is false), dedupes by canonical URL, and enriches each flat post with its publication object (from the response's publications array, matched by publication_id) and author_name (from publishedBylines). The full result is cached in _api_cache and sliced by offset; _fetch_saved_posts_page_impl() accepts an optional playwright_instance (same pattern as the notes fetcher and _fetch_via_dom) so this caching/slicing/fallback branch is directly testable with a Playwright double instead of only reachable through a real browser. Each page request goes through _reader_api_get(), which retries transient failures (HTTP 429 and 5xx) up to max_retries (default 5) with Retry-After-aware backoff: _retry_after_seconds() honors an integer Retry-After header (clamped to a 30s cap so a hostile value can't hang the sync) and otherwise uses capped exponential backoff (0.5s, 1s, 2s, ...); 401/403 and other 4xx are returned unretried so the existing auth/fallback handling applies. A 429 that survives all retries is deliberately treated as "unavailable" (partial list, or None → DOM fallback) rather than as a silent empty-success, so rate-limiting never masquerades as "you have no saved posts." Both _reader_api_get() and _fetch_all_saved_via_reader_api() accept an injectable sleep_func (default time.sleep) so tests exercise the backoff without real delays. If that endpoint is unavailable, it falls back to headless DOM extraction on https://substack.com/saved, which scrapes div.reader2-post-container cards, caches scrolling results in _dom_cache, and marks each dict with _dom: True; DOM cards only expose a localized relative publish string and no bookmark time, so saved_at stays unknown on that path. Every post page server-renders a window._preloads blob containing that post's own numeric ID and rich metadata (preloads.post.id, .title, .audience, .description/.subtitle, .post_date, plus preloads.pub.name); _save_post_impl reads this via page.evaluate("() => window._preloads") right after page load and, when an ID is found, calls the real POST https://substack.com/api/v1/posts/saved endpoint (body {"post_id": ...}) directly via the Playwright API request context — this also lets it populate the returned SavedPost with accurate title/publication/audience/excerpt instead of parsing page.title(). _unsave_post_impl does the mirror image: when the post's substack_post_id is already known (true for any post that has been through a normal sync, since the reader API's id field populates it), it calls DELETE https://substack.com/api/v1/posts/saved with the same body shape, no DOM interaction at all. Both treat an ok response as "confirmed" and only fall back to the best-effort DOM click (_click_bookmark_toggle()) when the numeric ID can't be obtained or the direct call doesn't confirm — never click before the API call, since the button toggles and would unsave an already-saved post. Note its selector is English-only (aria-label*='save'/'bookmark') and can silently fail on non-English Substack UIs, which is part of why the direct API path is preferred whenever possible. _click_bookmark_toggle() fingerprints the button's aria-label/aria-pressed/class before and after the click and returns "confirmed" only if that fingerprint changed, else "unconfirmed", "not_found", or "click_failed" — save_post() returns (SavedPost, confirmation) and unsave_post() returns just the confirmation string; their _save_post_impl()/_unsave_post_impl() bodies accept an optional playwright_instance for test injection (same pattern as _fetch_via_dom). fetch_post_content() reuses the same window._preloads mechanism to retrieve a saved post's full content: _fetch_post_content_impl navigates to the post's page and reads preloads.post.body_html (Substack's field name for full content — parse_remote_post() already expects this key from the reader API, though the saved-list payload never actually populates it, only individual post pages do), returning None for body_html if the page's embed format doesn't expose it (frontend change) or the account lacks paywall access; this is the case where the caller should be told to run inspect-network against an open post page to re-discover the real content source. cli.py's inspect-network command (which logs any api/v1/bookmark/saved/notes?/comment/reader/feed/restack request's method, URL, status, and JSON response body) is the tool for discovering/re-verifying these endpoints when Substack's frontend changes. It supports --authenticated/--anonymous (reuses storage_state.json via get_storage_state_path() so /saved renders the real logged-in page instead of the marketing page), --url to target any page, --filter to override the response-matching regex, --max-body to cap logged response bytes, and --out PATH to append each exchange as JSON Lines for later grepping. Response bodies are captured via context.route("**/*", handle_route) + route.fetch()/route.fulfill(), not the more obvious page.on("response", ...) + response.text(): the latter can deadlock calling response.text() inside a sync-API response event handler on the same driver thread, silently yielding null bodies — route.fetch() reads the body outside that handler and route.fulfill(response=...) re-serves the exact response so page behavior is unaffected; a body that still can't be read logs a visible yellow warning.

Read the full file on GitHub · 52 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 17d ago Changed · +1 lines · +541 tokens per session d6cd01d56d19
  2. 1mo ago Changed · -615 tokens per session 27e06e4543b6
  3. 2mo ago First seen · 51 lines · 7,695 tokens per session scan A 1a2fd0e3da11

Subscribe to this mod's changes

substack-saved-mcp CLAUDE.md is an instructions file published in the GitHub repository toniher/substack-saved-mcp (0 stars, last pushed 18d ago), licensed MIT. It adds 7,621 tokens to every session, about $0.0305 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

substack-saved-mcp CLAUDE.md compared with instructions from other repositories

substack-saved-mcp CLAUDE.md next to 6 instructions from other repositories
ModTypeStarsLast pushLicenceScanTokensWorks with
substack-saved-mcp CLAUDE.mdtoniher/substack-saved-mcpInstructions file018d agoMITA7,621Claude Code
vscode buildNext.instructions.mdmicrosoft/vscodeInstructions file196ktodayMITA9,719GitHub Copilot
next.js AGENTS.mdvercel/next.jsInstructions file144ktodayMITA8,130Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscodeInstructions file196ktodayMITA5,685GitHub Copilot
langchain AGENTS.mdlangchain-ai/langchainInstructions file150kyesterdayMITA4,680Codex, OpenCode
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harnessInstructions file283kyesterdayMITA4,342Codex, OpenCode
vscode copilot-instructions.mdmicrosoft/vscodeInstructions file196ktodayMITA3,153GitHub Copilot