reddit-rss-mcp 1.1.0__tar.gz

reddit_rss_mcp-1.1.0/.gitignore

@@ -0,0 +1,10 @@
+*.pyc
+.DS_Store
+.env
+.venv/
+__pycache__/
+uv.lock
+dist/
+build/
+*.egg-info/
+.pytest_cache/

reddit_rss_mcp-1.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-06-15
+
+### Added
+
+- Transparent retry with backoff on Reddit HTTP 429 rate limits. The `Retry-After`
+  header is honored when present; otherwise the request uses exponential backoff
+  with jitter (up to 7 retries). A global minimum interval between outbound
+  requests reduces 429s at the source. Shared across all tools (`browse_subreddit`,
+  `get_post`, `search_reddit`, `fetch_json`). Closes #1.
+- Unit tests for the retry/backoff and throttle layer.
+
+### Fixed
+
+- `browse_subreddit` params dict type annotation (`str` was not assignable to the
+  inferred `int`-only dict).
+
+## [1.0.0] - 2026-06-01
+
+### Added
+
+- Initial stdio MCP server fetching and refining Reddit content via public
+  RSS/Atom feeds: `browse_subreddit`, `get_post`, `search_reddit`, and a generic
+  `fetch_json`. No authentication required.

reddit_rss_mcp-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jörgen Karlsson
+
+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.

reddit_rss_mcp-1.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: reddit-rss-mcp
+Version: 1.1.0
+Summary: Local MCP server that fetches and refines Reddit (and other JSON) content for Claude, via Reddit's public RSS feeds (no auth).
+Project-URL: Homepage, https://github.com/jorgen-k/reddit-mcp
+Project-URL: Repository, https://github.com/jorgen-k/reddit-mcp
+Project-URL: Changelog, https://github.com/jorgen-k/reddit-mcp/blob/main/CHANGELOG.md
+Author: Jörgen Karlsson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,mcp,model-context-protocol,reddit,rss
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# reddit-mcp
+
+<!-- mcp-name: io.github.jorgen-k/reddit-mcp -->
+
+A small **local MCP server** that lets Claude read Reddit (and other JSON
+endpoints), refining the responses down to the fields that matter.
+
+> **How it reaches Reddit:** Reddit gates its Data API (new apps require a
+> moderation use case + approval) and blocks anonymous `.json` access, but it
+> still publishes public **Atom/RSS feeds** for reading content. This server
+> uses those — so it needs **no account, no app, no API key, no login**.
+>
+> Trade-off: RSS carries title, author, link, timestamp, and full post/comment
+> text, but **not** scores, upvote ratios, or comment counts (those only live in
+> the gated API).
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `browse_subreddit(subreddit, sort="hot", time_filter="day", limit=25)` | Posts from a subreddit (`hot`/`new`/`top`/`rising`/`controversial`). |
+| `get_post(url, comment_limit=50)` | A post plus its comments (flat list — RSS doesn't expose the reply tree). |
+| `search_reddit(query, subreddit=None, sort="relevance", time_filter="all", limit=25)` | Search Reddit, optionally scoped to one subreddit. |
+| `fetch_json(url)` | Reddit URLs → the `.rss` feed (refined); other URLs → fetched as-is, falling back to the `.json` convention. |
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/) — handles Python + deps. `uv run server.py`
+  provisions an isolated env from `pyproject.toml` on first run. No other setup.
+
+## Install
+
+The published package is [`reddit-rss-mcp`](https://pypi.org/project/reddit-rss-mcp/)
+on PyPI (the plain `reddit-mcp` name belongs to an unrelated project). `uvx`
+fetches and runs it for you, no clone needed.
+
+**Claude Code:**
+
+```sh
+claude mcp add reddit -s user -- uvx reddit-rss-mcp
+```
+
+**Claude Desktop & Cowork** (add to `claude_desktop_config.json`; use the absolute
+path from `which uvx`, then follow the quit/relaunch steps below):
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "/absolute/path/to/uvx",
+      "args": ["reddit-rss-mcp"]
+    }
+  }
+}
+```
+
+### From GitHub (latest `main`, no clone)
+
+To run unreleased changes, point `uvx` at the repo and the `reddit-rss-mcp` entry
+point. Append `@v1.1.0` (or any tag) to pin a release instead of tracking `main`:
+
+```sh
+claude mcp add reddit -s user -- uvx --from git+https://github.com/jorgen-k/reddit-mcp reddit-rss-mcp
+```
+
+### From a local clone
+
+Prefer this if you want to edit the code. Clone it somewhere first:
+
+```sh
+git clone https://github.com/jorgen-k/reddit-mcp.git
+cd reddit-mcp
+```
+
+#### Claude Code
+
+```sh
+claude mcp add reddit -s user -- uv --directory "$(pwd)" run server.py
+```
+
+Verify with `claude mcp list` (should show `reddit: ✓ Connected`). If Claude
+can't find `uv`, use its absolute path (`which uv`) instead of bare `uv`.
+
+#### Claude Desktop & Cowork
+
+Both use the same config file:
+`~/Library/Application Support/Claude/claude_desktop_config.json`. Add a
+`mcpServers` entry using **absolute paths** — the app doesn't inherit your shell
+`PATH`. Get the values with `which uv` and `pwd`:
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "/absolute/path/to/uv",
+      "args": ["--directory", "/absolute/path/to/reddit-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+If the file already has other top-level keys, add `mcpServers` alongside them —
+don't overwrite the file.
+
+Then:
+
+1. **Fully quit the app** — `Cmd+Q`, not just closing the window. The running
+   app rewrites this file, so an edit made while it's open can be discarded.
+2. **Relaunch.** It may take a couple of restarts before the server registers.
+3. **Grant permission** when the app prompts to run the server.
+
+The Reddit tools then appear in the app.
+
+> **Don't use a Custom Connector** (the "add server by URL" option) for a local
+> server — those are dialed from Anthropic's cloud and can't reach `localhost`,
+> no matter the cert or tunnel. The config-file method above spawns the server
+> locally on your machine, which is what works.
+
+### Updating after a code change
+
+The server runs as a long-lived process that's spawned once when the client
+connects. Editing `server.py` does **not** hot-reload it — the running process
+keeps the old code until it's restarted. After any change, restart the server so
+the new code takes effect:
+
+- **Claude Code:** run `/mcp`, select `reddit`, and reconnect it (or restart
+  Claude Code).
+- **Claude Desktop & Cowork:** fully quit the app (`Cmd+Q`) and relaunch.
+
+## Notes
+
+- Read-only, public content only.
+- No scores/vote counts/comment counts (RSS limitation). For those you'd need
+  Reddit's Data API, which now requires a moderation use case + approval.
+- Be considerate with request volume — these are public feeds.
+
+### Rate limiting
+
+Reddit throttles its unauthenticated RSS feeds aggressively. On an HTTP 429 the
+server transparently retries with backoff (honoring the `Retry-After` header
+when present, otherwise exponential backoff with jitter) and only surfaces an
+error after retries are exhausted. It also keeps a small minimum gap between
+outbound requests to avoid tripping the limit in the first place. All tools
+share this behavior. A 429 is retried up to 7 times, sleeping roughly
+2, 4, 8, 16, 32, 64, 128 seconds (plus jitter) between attempts.
+
+### Search is only as good as Reddit's search
+
+`search_reddit` uses Reddit's own search engine — RSS is just the output format,
+so results are identical to the website/API search, not a separate (weaker)
+index. That engine has real limits:
+
+- **It doesn't search comment text** — only post titles and bodies (and
+  community names). A term that only appears in a comment won't be found.
+- **Very new posts lag** — search indexing isn't instant. To catch brand-new
+  posts reliably, use `browse_subreddit(sort="new")` instead of search.
+- **It isn't exhaustive** — low-relevance results get dropped or buried.
+
+So a "no results" means *"Reddit's search didn't surface it,"* not a guarantee
+it was never posted anywhere on the site.

reddit_rss_mcp-1.1.0/README.md

@@ -0,0 +1,160 @@
+# reddit-mcp
+
+<!-- mcp-name: io.github.jorgen-k/reddit-mcp -->
+
+A small **local MCP server** that lets Claude read Reddit (and other JSON
+endpoints), refining the responses down to the fields that matter.
+
+> **How it reaches Reddit:** Reddit gates its Data API (new apps require a
+> moderation use case + approval) and blocks anonymous `.json` access, but it
+> still publishes public **Atom/RSS feeds** for reading content. This server
+> uses those — so it needs **no account, no app, no API key, no login**.
+>
+> Trade-off: RSS carries title, author, link, timestamp, and full post/comment
+> text, but **not** scores, upvote ratios, or comment counts (those only live in
+> the gated API).
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `browse_subreddit(subreddit, sort="hot", time_filter="day", limit=25)` | Posts from a subreddit (`hot`/`new`/`top`/`rising`/`controversial`). |
+| `get_post(url, comment_limit=50)` | A post plus its comments (flat list — RSS doesn't expose the reply tree). |
+| `search_reddit(query, subreddit=None, sort="relevance", time_filter="all", limit=25)` | Search Reddit, optionally scoped to one subreddit. |
+| `fetch_json(url)` | Reddit URLs → the `.rss` feed (refined); other URLs → fetched as-is, falling back to the `.json` convention. |
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/) — handles Python + deps. `uv run server.py`
+  provisions an isolated env from `pyproject.toml` on first run. No other setup.
+
+## Install
+
+The published package is [`reddit-rss-mcp`](https://pypi.org/project/reddit-rss-mcp/)
+on PyPI (the plain `reddit-mcp` name belongs to an unrelated project). `uvx`
+fetches and runs it for you, no clone needed.
+
+**Claude Code:**
+
+```sh
+claude mcp add reddit -s user -- uvx reddit-rss-mcp
+```
+
+**Claude Desktop & Cowork** (add to `claude_desktop_config.json`; use the absolute
+path from `which uvx`, then follow the quit/relaunch steps below):
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "/absolute/path/to/uvx",
+      "args": ["reddit-rss-mcp"]
+    }
+  }
+}
+```
+
+### From GitHub (latest `main`, no clone)
+
+To run unreleased changes, point `uvx` at the repo and the `reddit-rss-mcp` entry
+point. Append `@v1.1.0` (or any tag) to pin a release instead of tracking `main`:
+
+```sh
+claude mcp add reddit -s user -- uvx --from git+https://github.com/jorgen-k/reddit-mcp reddit-rss-mcp
+```
+
+### From a local clone
+
+Prefer this if you want to edit the code. Clone it somewhere first:
+
+```sh
+git clone https://github.com/jorgen-k/reddit-mcp.git
+cd reddit-mcp
+```
+
+#### Claude Code
+
+```sh
+claude mcp add reddit -s user -- uv --directory "$(pwd)" run server.py
+```
+
+Verify with `claude mcp list` (should show `reddit: ✓ Connected`). If Claude
+can't find `uv`, use its absolute path (`which uv`) instead of bare `uv`.
+
+#### Claude Desktop & Cowork
+
+Both use the same config file:
+`~/Library/Application Support/Claude/claude_desktop_config.json`. Add a
+`mcpServers` entry using **absolute paths** — the app doesn't inherit your shell
+`PATH`. Get the values with `which uv` and `pwd`:
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "/absolute/path/to/uv",
+      "args": ["--directory", "/absolute/path/to/reddit-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+If the file already has other top-level keys, add `mcpServers` alongside them —
+don't overwrite the file.
+
+Then:
+
+1. **Fully quit the app** — `Cmd+Q`, not just closing the window. The running
+   app rewrites this file, so an edit made while it's open can be discarded.
+2. **Relaunch.** It may take a couple of restarts before the server registers.
+3. **Grant permission** when the app prompts to run the server.
+
+The Reddit tools then appear in the app.
+
+> **Don't use a Custom Connector** (the "add server by URL" option) for a local
+> server — those are dialed from Anthropic's cloud and can't reach `localhost`,
+> no matter the cert or tunnel. The config-file method above spawns the server
+> locally on your machine, which is what works.
+
+### Updating after a code change
+
+The server runs as a long-lived process that's spawned once when the client
+connects. Editing `server.py` does **not** hot-reload it — the running process
+keeps the old code until it's restarted. After any change, restart the server so
+the new code takes effect:
+
+- **Claude Code:** run `/mcp`, select `reddit`, and reconnect it (or restart
+  Claude Code).
+- **Claude Desktop & Cowork:** fully quit the app (`Cmd+Q`) and relaunch.
+
+## Notes
+
+- Read-only, public content only.
+- No scores/vote counts/comment counts (RSS limitation). For those you'd need
+  Reddit's Data API, which now requires a moderation use case + approval.
+- Be considerate with request volume — these are public feeds.
+
+### Rate limiting
+
+Reddit throttles its unauthenticated RSS feeds aggressively. On an HTTP 429 the
+server transparently retries with backoff (honoring the `Retry-After` header
+when present, otherwise exponential backoff with jitter) and only surfaces an
+error after retries are exhausted. It also keeps a small minimum gap between
+outbound requests to avoid tripping the limit in the first place. All tools
+share this behavior. A 429 is retried up to 7 times, sleeping roughly
+2, 4, 8, 16, 32, 64, 128 seconds (plus jitter) between attempts.
+
+### Search is only as good as Reddit's search
+
+`search_reddit` uses Reddit's own search engine — RSS is just the output format,
+so results are identical to the website/API search, not a separate (weaker)
+index. That engine has real limits:
+
+- **It doesn't search comment text** — only post titles and bodies (and
+  community names). A term that only appears in a comment won't be found.
+- **Very new posts lag** — search indexing isn't instant. To catch brand-new
+  posts reliably, use `browse_subreddit(sort="new")` instead of search.
+- **It isn't exhaustive** — low-relevance results get dropped or buried.
+
+So a "no results" means *"Reddit's search didn't surface it,"* not a guarantee
+it was never posted anywhere on the site.

reddit_rss_mcp-1.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "reddit-rss-mcp"
+version = "1.1.0"
+description = "Local MCP server that fetches and refines Reddit (and other JSON) content for Claude, via Reddit's public RSS feeds (no auth)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Jörgen Karlsson" }]
+keywords = ["mcp", "reddit", "rss", "claude", "model-context-protocol"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/jorgen-k/reddit-mcp"
+Repository = "https://github.com/jorgen-k/reddit-mcp"
+Changelog = "https://github.com/jorgen-k/reddit-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+reddit-rss-mcp = "server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+include = ["server.py"]
+
+[tool.hatch.build.targets.sdist]
+include = ["server.py", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

reddit_rss_mcp-1.1.0/server.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+"""Local MCP server that fetches and refines Reddit (and other JSON) content.
+
+Reddit gates its Data API (new apps require a moderation use case + approval)
+and blocks anonymous ``.json`` access, but it still publishes public **Atom/RSS
+feeds** for reading content. These tools fetch those feeds and trim them to the
+useful fields. No authentication, account, or app registration required.
+
+Feeds carry title, author, link, timestamp, and full post/comment text — but
+NOT scores, upvote ratios, or comment counts (those only exist in the gated API).
+
+The generic ``fetch_json`` tool also works for non-Reddit services that expose
+JSON via the ``.json`` convention.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html
+import os
+import random
+import re
+import time
+import xml.etree.ElementTree as ET
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# Feed readers send their own User-Agent; Reddit serves RSS to them normally.
+USER_AGENT = os.environ.get("REDDIT_USER_AGENT", "reddit-mcp/1.0 (personal RSS reader)")
+REDDIT_BASE = "https://www.reddit.com"
+ATOM = {"a": "http://www.w3.org/2005/Atom"}
+TIMEOUT = 30.0
+TEXT_MAX = 2000
+
+# Reddit throttles its unauthenticated RSS feeds aggressively. Retry 429s with
+# backoff (honoring Retry-After) and keep a global minimum gap between requests
+# rather than failing fast.
+MAX_RETRIES = 7  # retries after the first attempt: ~2,4,8,16,32,64,128s backoff
+BACKOFF_BASE = 2.0  # seconds; per-retry sleep is BACKOFF_BASE * 2**attempt + jitter
+MIN_INTERVAL = 1.0  # minimum seconds between outbound requests
+
+mcp = FastMCP("reddit")
+
+# Serialize the throttle so concurrent tool calls still respect MIN_INTERVAL.
+_throttle_lock = asyncio.Lock()
+_last_request_at = 0.0
+
+
+async def _throttle() -> None:
+    """Sleep so successive outbound requests are at least MIN_INTERVAL apart."""
+    global _last_request_at
+    if MIN_INTERVAL <= 0:
+        return
+    async with _throttle_lock:
+        wait = MIN_INTERVAL - (time.monotonic() - _last_request_at)
+        if wait > 0:
+            await asyncio.sleep(wait)
+        _last_request_at = time.monotonic()
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Reddit sends Retry-After as integer seconds; ignore the HTTP-date form."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+async def _get_with_retry(
+    client: httpx.AsyncClient, url: str, params: dict | None = None
+) -> httpx.Response:
+    """GET with throttling and 429 retry/backoff.
+
+    On a 429 we wait for the Retry-After header (if present) or an exponential
+    backoff with jitter, retrying up to MAX_RETRIES times. Only after exhausting
+    retries do we raise the rate-limited error, noting attempts and the last
+    Retry-After seen.
+    """
+    last_retry_after: float | None = None
+    for attempt in range(MAX_RETRIES + 1):
+        await _throttle()
+        resp = await client.get(url, params=params)
+        if resp.status_code != 429:
+            return resp
+        last_retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+        if attempt == MAX_RETRIES:
+            break
+        if last_retry_after is not None:
+            delay = last_retry_after
+        else:
+            delay = BACKOFF_BASE * (2**attempt) + random.random()
+        await asyncio.sleep(delay)
+
+    attempts = MAX_RETRIES + 1
+    suffix = (
+        f"; last Retry-After was {last_retry_after:g}s"
+        if last_retry_after is not None
+        else ""
+    )
+    raise RuntimeError(
+        f"Reddit rate-limited this request (HTTP 429) after {attempts} "
+        f"attempt(s){suffix}. Wait a bit and retry."
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Fetch + parse
+# --------------------------------------------------------------------------- #
+async def _fetch_feed(url: str, params: dict | None = None) -> tuple[str | None, list[dict]]:
+    """GET an Atom feed and return (feed_title, [refined entries])."""
+    headers = {"User-Agent": USER_AGENT}
+    async with httpx.AsyncClient(
+        timeout=TIMEOUT, follow_redirects=True, headers=headers
+    ) as client:
+        resp = await _get_with_retry(client, url, params)
+    resp.raise_for_status()
+    try:
+        root = ET.fromstring(resp.content)
+    except ET.ParseError as e:
+        raise RuntimeError(f"Could not parse feed (not valid Atom XML): {e}")
+    feed_title = root.findtext("a:title", namespaces=ATOM)
+    entries = [_refine_entry(e) for e in root.findall("a:entry", ATOM)]
+    return feed_title, entries
+
+
+# --------------------------------------------------------------------------- #
+# Refinement helpers
+# --------------------------------------------------------------------------- #
+def _truncate(text: str | None, limit: int = TEXT_MAX) -> str | None:
+    if not text:
+        return text
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"… [truncated, {len(text)} chars total]"
+
+
+def _html_to_text(raw: str | None, limit: int = TEXT_MAX) -> str | None:
+    """Convert the HTML in a feed <content> to readable plain text."""
+    if not raw:
+        return raw
+    s = re.sub(r"(?is)<(script|style).*?</\1>", "", raw)
+    s = re.sub(r"(?i)<br\s*/?>", "\n", s)
+    s = re.sub(r"(?i)</p>", "\n\n", s)
+    s = re.sub(r"(?s)<[^>]+>", "", s)
+    s = html.unescape(s)
+    s = re.sub(r"\n{3,}", "\n\n", s).strip()
+    return _truncate(s, limit)
+
+
+def _refine_entry(entry: ET.Element) -> dict:
+    """Reduce an Atom entry (post or comment) to the useful fields."""
+    full_id = entry.findtext("a:id", default="", namespaces=ATOM)
+    kind, _, short_id = full_id.partition("_")  # e.g. "t3_abc123"
+    link_el = entry.find("a:link", ATOM)
+    category = entry.find("a:category", ATOM)
+    return {
+        "id": short_id or full_id,
+        "type": {"t3": "post", "t1": "comment"}.get(kind, kind or None),
+        "title": entry.findtext("a:title", namespaces=ATOM),
+        "author": entry.findtext("a:author/a:name", namespaces=ATOM),
+        "subreddit": category.get("term") if category is not None else None,
+        "published": entry.findtext("a:published", namespaces=ATOM),
+        "updated": entry.findtext("a:updated", namespaces=ATOM),
+        "link": link_el.get("href") if link_el is not None else None,
+        "text": _html_to_text(entry.findtext("a:content", namespaces=ATOM)),
+    }
+
+
+def _is_reddit_host(netloc: str) -> bool:
+    host = netloc.lower().split(":")[0]
+    return host == "reddit.com" or host.endswith(".reddit.com")
+
+
+# --------------------------------------------------------------------------- #
+# Tools
+# --------------------------------------------------------------------------- #
+@mcp.tool()
+async def browse_subreddit(
+    subreddit: str,
+    sort: str = "hot",
+    time_filter: str = "day",
+    limit: int = 25,
+) -> dict:
+    """List posts from a subreddit (via its public RSS feed).
+
+    Note: RSS does not include scores, upvote ratios, or comment counts.
+
+    Args:
+        subreddit: Subreddit name, with or without the "r/" prefix.
+        sort: One of hot, new, top, rising, controversial.
+        time_filter: For top/controversial — hour, day, week, month, year, all.
+        limit: Number of posts (1-100).
+    """
+    sub = subreddit.strip().removeprefix("r/").strip("/")
+    sort = sort.strip().lower()
+    limit = max(1, min(int(limit), 100))
+    params: dict[str, str | int] = {"limit": limit}
+    if sort in ("top", "controversial"):
+        params["t"] = time_filter
+    title, entries = await _fetch_feed(f"{REDDIT_BASE}/r/{sub}/{sort}/.rss", params)
+    return {
+        "subreddit": sub,
+        "sort": sort,
+        "feed_title": title,
+        "count": len(entries),
+        "posts": entries,
+    }
+
+
+@mcp.tool()
+async def get_post(url: str, comment_limit: int = 50) -> dict:
+    """Fetch a single post and its comments (via the post's RSS feed).
+
+    Comments come back as a flat list (RSS doesn't expose the reply tree), and
+    scores/vote counts are not available.
+
+    Args:
+        url: A Reddit post URL or permalink (e.g.
+            https://www.reddit.com/r/python/comments/abc123/title/ or
+            /r/python/comments/abc123/title/).
+        comment_limit: Max comments to return.
+    """
+    u = url.strip()
+    path = u if u.startswith("/") else urlsplit(u).path
+    path = path.rstrip("/")
+    if path.endswith("/.rss"):
+        path = path[: -len("/.rss")]
+    feed_url = f"{REDDIT_BASE}{path}/.rss"
+
+    _, entries = await _fetch_feed(feed_url, {"limit": comment_limit})
+    posts = [e for e in entries if e["type"] == "post"]
+    comments = [e for e in entries if e["type"] == "comment"][:comment_limit]
+    if not posts and not comments:
+        raise RuntimeError("No content found — is this a valid post URL?")
+
+    return {
+        "post": posts[0] if posts else None,
+        "comment_count": len(comments),
+        "comments": comments,
+    }
+
+
+@mcp.tool()
+async def search_reddit(
+    query: str,
+    subreddit: str | None = None,
+    sort: str = "relevance",
+    time_filter: str = "all",
+    limit: int = 25,
+) -> dict:
+    """Search Reddit, optionally scoped to a subreddit (via the search RSS feed).
+
+    Note: RSS results do not include scores or comment counts.
+
+    Args:
+        query: Search terms.
+        subreddit: Restrict to this subreddit (with or without "r/").
+        sort: relevance, hot, top, new, comments.
+        time_filter: hour, day, week, month, year, all.
+        limit: Number of results (1-100).
+    """
+    limit = max(1, min(int(limit), 100))
+    params = {"q": query, "sort": sort, "t": time_filter, "limit": limit}
+    if subreddit:
+        sub = subreddit.strip().removeprefix("r/").strip("/")
+        params["restrict_sr"] = "1"
+        url = f"{REDDIT_BASE}/r/{sub}/search.rss"
+    else:
+        url = f"{REDDIT_BASE}/search.rss"
+    title, entries = await _fetch_feed(url, params)
+    return {"query": query, "count": len(entries), "results": entries}
+
+
+@mcp.tool()
+async def fetch_json(url: str) -> dict:
+    """Fetch a URL as structured data.
+
+    For Reddit URLs (any feed type — user, domain, multireddit, etc.) this
+    fetches the ``.rss`` feed and returns refined entries. For other services it
+    tries the URL as-is, falling back to the ``.json`` convention if the plain
+    response isn't JSON.
+
+    Args:
+        url: The URL to fetch.
+    """
+    parts = urlsplit(url.strip())
+
+    if _is_reddit_host(parts.netloc):
+        path = parts.path.rstrip("/")
+        if not path.endswith(".rss"):
+            path += "/.rss"
+        target = urlunsplit((parts.scheme, parts.netloc, path, parts.query, ""))
+        title, entries = await _fetch_feed(target)
+        return {"url": target, "feed_title": title, "count": len(entries), "entries": entries}
+
+    # Non-Reddit: try the URL as given, then fall back to the .json convention.
+    async with httpx.AsyncClient(
+        timeout=TIMEOUT, follow_redirects=True, headers={"User-Agent": USER_AGENT}
+    ) as client:
+        resp = await _get_with_retry(client, url.strip())
+        if resp.is_success:
+            try:
+                return {"url": str(resp.url), "data": resp.json()}
+            except ValueError:
+                pass  # not JSON — try the .json fallback below
+
+        path = parts.path.rstrip("/")
+        if not path.endswith(".json"):
+            fallback = urlunsplit(
+                (parts.scheme, parts.netloc, path + ".json", parts.query, "")
+            )
+            resp = await _get_with_retry(client, fallback)
+
+    resp.raise_for_status()
+    try:
+        return {"url": str(resp.url), "data": resp.json()}
+    except ValueError:
+        return {
+            "url": str(resp.url),
+            "note": f"Response was not JSON (content-type: "
+            f"{resp.headers.get('content-type', '')}).",
+            "text": _truncate(resp.text, 5000),
+        }
+
+
+def main() -> None:
+    """Run the server over stdio (for Claude Code and Cowork plugins)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()