Perform full-text FTS5 search across cached saved posts.

Searches title, excerpt, publication name, author, and content text. Allows filtering by publication name, audience tier (see list_audiences for cached values, e.g. "everyone", "only_paid"), original post date (published_at), and saved date (saved_at).

List cached saved posts with pagination and optional publication/audience filters.

sort_by can be 'saved_at' (when post was bookmarked) or 'published_at' (when post was published). audience filters by tier (see list_audiences for cached values, e.g. "everyone", "only_paid").

Retrieve full cached post details, timestamps (published_at and saved_at), and content by URL or local ID.

Bookmark a Substack post remotely on Substack and save it to the local cache.

Requires an active authenticated Substack session (run 'substack-saved-mcp login' if expired). Remote confirmation is best-effort: Substack's bookmark button markup isn't officially documented, so this detects whether the button's rendered state provably changed after clicking. remote_confirmed=False means the post is still cached locally, but the tool could not verify the bookmark was actually created on Substack's side — a subsequent 'sync --force' will correct the local cache if the remote save didn't actually happen.

Unbookmark a Substack post remotely and soft-delete it in local cache.

Soft-deletion preserves post history while removing it from active search/list outputs. When the post's Substack ID is known (normally true after a sync), this calls Substack's real unsave endpoint directly and is reliably confirmed; otherwise it falls back to a best-effort DOM click (see save_post). remote_confirmed=False means the post was still soft-deleted locally, but the tool could not verify the unbookmark on Substack's side.

Fetch a saved post's full content, cleaned and formatted for LLM consumption.

Returns the cached content_text if a previous fetch already stored it, unless force_refetch is set. Otherwise fetches the post's page directly, extracts its body_html from Substack's server-rendered window._preloads blob, converts it to plain text (headings, list items, and links kept readable), and caches the result. Requires an active authenticated Substack session. If the content can't be located on the page (e.g. Substack changed how it embeds it, or the post is paywalled beyond this account's access), returns success=False with a message suggesting the caller run 'substack-saved-mcp inspect-network' while opening the post so the real content source can be captured.

List all publications in local cache with post counts.

List distinct audience tiers present in local cache with post counts.

Discovers actual values in use (e.g. "everyone", "only_paid") rather than a hardcoded enum, since Substack's audience values aren't officially documented and may vary or grow over time.

Return cache statistics, database path, and last sync run status.

Trigger incremental or full resync of saved posts from Substack account into local SQLite cache.

Requires an active authenticated Substack session.