Skip to content

feat(feeds): private RSS and podcast feeds with API and MCP - #534

Merged
adeelahmad merged 5 commits into
mainfrom
claude/project-thread-rovv80
Oct 18, 2026
Merged

adeelahmad merged 5 commits into
mainfrom
claude/project-thread-rovv80

Conversation

@adeelahmad

Copy link
Copy Markdown
Owner

Description

Before: nothing in Lens could be followed from a feed reader or a podcast app; a podcast episode was listened to in the web app only, and the timeline was read there too.

After: an editor makes a feed for a namespace, as RSS or as a podcast feed with Apple Podcasts' tags, and adds resources, podcast episodes, timeline activities and text to it. The feed has a private address (/api/v1/feeds/public/lfd_…) that any feed reader or podcast app follows; an episode's audio is its enclosure, served with byte ranges and HEAD. A feed lists only what the readers of its namespace could already read, never a vault's, and its address can be rotated; readers get 304 Not Modified when nothing changed, and the feed asks directories and crawlers to keep out.

This is the first of three pull requests for the ask: next come graph workflow output nodes (pick assets or timeline activities, publish them to a feed, make an episode about them) that routines run, then the Feeds page and the canvas nodes in the web app. docs/feeds.md says so (status: in progress).

How: domain/syndication.py holds feeds and their items (tables feed and feed_item; the token is hashed for lookup and sealed so the namespace's readers see the address again) and renders RSS 2.0 with the iTunes and podcastindex namespaces; routes/feeds.py is the API (ETag/304, X-Robots-Tag, Referrer-Policy: no-referrer); the MCP tools are list_feeds, create_feed and publish_to_feed. The threat model gains the public entry point, the output row and P-FEEDS.

Motivation and Context

Adeel's ask in the project: RSS and iTunes podcast endpoints from routines, so a routine can pick part of the graph or all of it and publish a podcast, or timeline events, through a feed. This PR is the feeds themselves; the routine nodes build on it.

Screenshots (if appropriate):

n/a (API only; the web page comes in the third PR)

Steps to reproduce (if appropriate):

POST /api/v1/feeds {"namespace": "...", "title": "...", "kind": "podcast"}, then POST /api/v1/feeds/{id}/items {"recordings": [...]} and open the feed's url in a podcast app.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests (tests/api/test_feeds.py, 5 tests; test_mcp.py write-tool list).
  • My change requires documentation updates, and I have updated docs/ accordingly (docs/feeds.md, docs/mcp.md, docs/requirements.md, README).
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: the feed endpoints and private feeds are here; the routine nodes and the web page are the next two PRs of the same thread. Merged on green CI (local CI green: backend, frontend, pre-commit, title).
  • Agents: /api/v1/feeds and the MCP tools list_feeds, create_feed, publish_to_feed.
  • Zero setup: no new prerequisite, .env or step; the tables come with the schema.
  • Fewest clicks: every setting has a default (rss, en, 50 items, author Lens); the web page is the third PR.
  • Configurable: a feed's settings are per feed through the API (and the web page next); no new server setting, nothing in the wizard.
  • Light: XML built from database rows with the standard library; no new dependency, nothing heavy.
  • Private and secure: the token is 256 random bits, hashed for lookup and sealed with the server key; items are bounded by who reads the namespace and never a vault's; itunes:block, podcast:locked, X-Robots-Tag, Referrer-Policy: no-referrer; text double-escaped. Threat model: entry point, output row, P-FEEDS.
  • Cost: no model calls; items store ids and render from live rows.
  • User decides: nothing is published until an editor makes a feed and adds to it; existing defaults unchanged.
  • Upgrades: new tables only (DEFINE ... IF NOT EXISTS); no change to stored data.
  • Honest: docs label it in progress; an episode item lists the sources it cites, each with a link.
  • Tests, docs and generated files updated (make openapi).
  • Open standards: RSS 2.0, Atom link rel=self, the iTunes and podcastindex namespaces; stdlib only, MIT kept.
  • Result reported in the thread with the PR; "refine later" items in docs/feeds.md.
  • Reuse: podcasts._readers/_vault/target's rule for where things may go, events.get_many/visible, recording_routes.serve_audio, settings.seal, deps.web_origin.

Generated by Claude Code

A namespace publishes what's in it as an RSS or iTunes podcast feed at a
tokenized address that feed readers and podcast apps follow: resources,
podcast episodes (their audio as enclosures, with byte ranges), timeline
activities and text. Editors make feeds and add to them through the API
(/api/v1/feeds) and the MCP tools list_feeds, create_feed and
publish_to_feed. What a feed lists is bounded by who reads its namespace
and never a vault; the token is found by its hash, rotated on demand, and
the feed asks directories and crawlers to keep out. Threat model: P-FEEDS.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CDEiKGoyQX8Vmnv9bi5JpD
@adeelahmad adeelahmad self-assigned this Oct 18, 2026
Keeps both changelog entries and both MCP docs changes, the threat model's
same-commit prose_version, and the OpenAPI client regenerated with make openapi.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CDEiKGoyQX8Vmnv9bi5JpD
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CDEiKGoyQX8Vmnv9bi5JpD
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CDEiKGoyQX8Vmnv9bi5JpD
The changelog entry moves to the end of Unreleased, so pull requests adding
at the top no longer conflict with it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CDEiKGoyQX8Vmnv9bi5JpD
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants