rss-mcp-server 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of rss-mcp-server might be problematic. Click here for more details.

Files changed (36) hide show
  1. rss_mcp_server-0.1.0/.dockerignore +9 -0
  2. rss_mcp_server-0.1.0/.gitignore +14 -0
  3. rss_mcp_server-0.1.0/.qwen/tmp/pypi-token +1 -0
  4. rss_mcp_server-0.1.0/Dockerfile +14 -0
  5. rss_mcp_server-0.1.0/LICENSE +21 -0
  6. rss_mcp_server-0.1.0/PKG-INFO +141 -0
  7. rss_mcp_server-0.1.0/README.md +123 -0
  8. rss_mcp_server-0.1.0/docs/superpowers/plans/2026-11-18-gap-closure.md +170 -0
  9. rss_mcp_server-0.1.0/docs/superpowers/plans/2026-11-18-rss-mcp.md +283 -0
  10. rss_mcp_server-0.1.0/docs/superpowers/specs/2026-11-18-rss-mcp-design.md +160 -0
  11. rss_mcp_server-0.1.0/pyproject.toml +40 -0
  12. rss_mcp_server-0.1.0/src/rss_mcp/__init__.py +3 -0
  13. rss_mcp_server-0.1.0/src/rss_mcp/__main__.py +4 -0
  14. rss_mcp_server-0.1.0/src/rss_mcp/config.py +28 -0
  15. rss_mcp_server-0.1.0/src/rss_mcp/db.py +74 -0
  16. rss_mcp_server-0.1.0/src/rss_mcp/feed_client.py +192 -0
  17. rss_mcp_server-0.1.0/src/rss_mcp/models.py +44 -0
  18. rss_mcp_server-0.1.0/src/rss_mcp/opml.py +58 -0
  19. rss_mcp_server-0.1.0/src/rss_mcp/readability_fetch.py +137 -0
  20. rss_mcp_server-0.1.0/src/rss_mcp/server.py +361 -0
  21. rss_mcp_server-0.1.0/src/rss_mcp/store.py +361 -0
  22. rss_mcp_server-0.1.0/tests/conftest.py +15 -0
  23. rss_mcp_server-0.1.0/tests/fixtures/sample.opml +15 -0
  24. rss_mcp_server-0.1.0/tests/fixtures/sample_atom.xml +21 -0
  25. rss_mcp_server-0.1.0/tests/fixtures/sample_rss.xml +29 -0
  26. rss_mcp_server-0.1.0/tests/test_config.py +53 -0
  27. rss_mcp_server-0.1.0/tests/test_db.py +196 -0
  28. rss_mcp_server-0.1.0/tests/test_feed_client.py +530 -0
  29. rss_mcp_server-0.1.0/tests/test_http_transport.py +301 -0
  30. rss_mcp_server-0.1.0/tests/test_opml.py +62 -0
  31. rss_mcp_server-0.1.0/tests/test_readability_fetch.py +198 -0
  32. rss_mcp_server-0.1.0/tests/test_real_inoreader_opml.py +276 -0
  33. rss_mcp_server-0.1.0/tests/test_server_tools.py +697 -0
  34. rss_mcp_server-0.1.0/tests/test_store_entries.py +412 -0
  35. rss_mcp_server-0.1.0/tests/test_store_subscriptions.py +227 -0
  36. rss_mcp_server-0.1.0/uv.lock +1118 -0
@@ -0,0 +1,9 @@
1
+ .git
2
+ .venv
3
+ .pytest_cache
4
+ .qwen
5
+ .superpowers
6
+ dist
7
+ docs
8
+ tests
9
+ uv.lock
@@ -0,0 +1,14 @@
1
+ .superpowers/
2
+ .worktrees/
3
+ __pycache__/
4
+ *.py[cod]
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+ .venv/
9
+ dist/
10
+ *.egg-info/
11
+ .coverage
12
+ htmlcov/
13
+ *.db
14
+ .DS_Store
@@ -0,0 +1 @@
1
+ pypi-AgEIcHlwaS5vcmcCJDYyYTVhOTAyLWFlMDMtNDQxNC05OWFjLTA1YTI4YzVhM2MxYQACKlszLCJlZDJhNDBkZC1lNWI1LTRhMGQtYmFmYy03ODFhYWVhYTNhMWIiXQAABiCmUvIJGaJq-1mZsIF1-d_E9WPBJtVxzn_GNZrcJ6Preg
@@ -0,0 +1,14 @@
1
+ FROM python:3.13-slim
2
+
3
+ WORKDIR /app
4
+ COPY pyproject.toml README.md LICENSE ./
5
+ COPY src ./src
6
+ RUN pip install --no-cache-dir . \
7
+ && useradd --create-home --uid 10001 rss \
8
+ && mkdir -p /data && chown rss:rss /data
9
+
10
+ USER rss
11
+ ENV RSS_MCP_DB=/data/rss.db
12
+ VOLUME /data
13
+ EXPOSE 8000
14
+ ENTRYPOINT ["rss-mcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HUANG Cheng
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.5
2
+ Name: rss-mcp-server
3
+ Version: 0.1.0
4
+ Summary: Agent-only MCP server for RSS subscriptions, fetch, and unread tracking.
5
+ Project-URL: Homepage, https://github.com/huangcheng/rss-mcp
6
+ Project-URL: Repository, https://github.com/huangcheng/rss-mcp
7
+ Project-URL: Issues, https://github.com/huangcheng/rss-mcp/issues
8
+ Author: HUANG Cheng
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Requires-Python: >=3.11
12
+ Requires-Dist: feedparser
13
+ Requires-Dist: httpx
14
+ Requires-Dist: lxml
15
+ Requires-Dist: mcp<3,>=2.3
16
+ Requires-Dist: readability-lxml
17
+ Description-Content-Type: text/markdown
18
+
19
+ # rss-mcp
20
+
21
+ Agent-only MCP server for RSS and Atom. A host drives it over stdio (default) or Streamable HTTP. There is no GUI, TUI, or interactive CLI. Subscriptions, cached entries, unread state, and full-text search live in one local SQLite file. v1 is tools only: no resources, prompts, or MCP Apps.
22
+
23
+ Protocol: [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) (stdio or Streamable HTTP, tools) via the official Python SDK v2 (`mcp` ≥ 2.3). Design: [docs/superpowers/specs/2026-11-18-rss-mcp-design.md](docs/superpowers/specs/2026-11-18-rss-mcp-design.md).
24
+
25
+ Requires Python 3.11+.
26
+
27
+ ## Host config
28
+
29
+ In stdio mode, the process reads JSON-RPC from stdin and writes MCP messages only to stdout. It exits when stdin closes.
30
+
31
+ Cursor `mcp.json` (any stdio host can use the same command):
32
+
33
+ ```json
34
+ {
35
+ "mcpServers": {
36
+ "rss-mcp": {
37
+ "command": "uvx",
38
+ "args": ["rss-mcp-server"],
39
+ "env": {
40
+ "RSS_MCP_DB": "/absolute/path/rss.db"
41
+ }
42
+ }
43
+ }
44
+ }
45
+ ```
46
+
47
+ The PyPI distribution is `rss-mcp-server` (`rss-mcp` is blocked by a similar existing project); it installs both the `rss-mcp-server` and `rss-mcp` commands. From this checkout: `uv run rss-mcp`, or `uvx --from /absolute/path/to/rss-mcp rss-mcp`.
48
+
49
+ ## HTTP transport
50
+
51
+ Run the same server over Streamable HTTP instead of stdio:
52
+
53
+ ```bash
54
+ uv run rss-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
55
+ ```
56
+
57
+ | Flag | Default |
58
+ | --- | --- |
59
+ | `--transport` | `stdio` (choices: `stdio`, `streamable-http`) |
60
+ | `--host` | `127.0.0.1` |
61
+ | `--port` | `8000` |
62
+ | `--path` | `/mcp` |
63
+
64
+ The MCP endpoint is then `http://127.0.0.1:8000/mcp`. Hosts that support remote servers can point at it directly:
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "rss-mcp": {
70
+ "url": "http://127.0.0.1:8000/mcp"
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ All sessions share one SQLite database (same `RSS_MCP_DB` setting). The endpoint serves both protocol eras: 2026-07-28 stateless per-request POSTs (with the `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` headers and `_meta` envelope) and the legacy `initialize` handshake (up to 2025-11-25, with sessions) for older hosts.
77
+
78
+ Set `RSS_MCP_AUTH_TOKEN` to require `Authorization: Bearer <token>` on every HTTP request (both eras; stdio is unaffected). Hosts that support custom headers:
79
+
80
+ ```json
81
+ {
82
+ "mcpServers": {
83
+ "rss-mcp": {
84
+ "url": "http://127.0.0.1:8000/mcp",
85
+ "headers": { "Authorization": "Bearer <token>" }
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ Without a token the endpoint is unauthenticated: keep the default loopback bind, or put it behind a reverse proxy with auth before exposing it beyond localhost.
92
+
93
+ ## Docker
94
+
95
+ The image runs the HTTP transport, stores the database in a `/data` volume, and runs as a non-root user:
96
+
97
+ ```bash
98
+ docker build -t rss-mcp .
99
+ docker run -d --name rss-mcp -p 127.0.0.1:8000:8000 \
100
+ -e RSS_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
101
+ -v rss-mcp-data:/data rss-mcp
102
+ ```
103
+
104
+ The container binds `0.0.0.0` internally (required for port mapping), so set `RSS_MCP_AUTH_TOKEN` whenever the published port is reachable beyond your machine. Publishing to `127.0.0.1` as above keeps it local. Run exactly one container per database volume.
105
+
106
+ ## Environment
107
+
108
+ | Variable | Default |
109
+ | --- | --- |
110
+ | `RSS_MCP_DB` | `~/.local/share/rss-mcp/rss.db` |
111
+ | `RSS_MCP_USER_AGENT` | `rss-mcp/0.1 (+https://github.com/huangcheng/rss-mcp)` |
112
+ | `RSS_MCP_AUTH_TOKEN` | unset (HTTP bearer auth disabled) |
113
+
114
+ `list_entries` and `search_entries` use `limit` 20 when omitted and clamp to 0–100. Each fetch upserts at most 50 entries and sends stored `ETag` / `Last-Modified` when the feed has them.
115
+
116
+ ## Tools
117
+
118
+ - `add_subscription` — Add a feed by URL. Repeating a URL returns the existing subscription.
119
+ - `remove_subscription` — Delete a subscription and its cached entries.
120
+ - `list_subscriptions` — List subscriptions with unread counts.
121
+ - `fetch_feed` — Fetch one subscription, or every subscription when the id is omitted.
122
+ - `list_entries` — List cached entries (article bodies omitted). Limit falls back to the server default and is clamped.
123
+ - `read_entry` — Return one entry with full content. `fetch_full` replaces content only when article text is returned. `mark_read` marks it read.
124
+ - `search_entries` — Full-text search over cached title, summary, and content (bodies omitted; use `read_entry` for full text).
125
+ - `mark_entry` — Mark entries read or unread. Unknown ids are skipped.
126
+ - `import_opml` — Add each OPML feed. Existing URLs are skipped.
127
+ - `export_opml` — Export subscriptions as an OPML document.
128
+
129
+ ## Live tests
130
+
131
+ Optional network tests against a real Inoreader OPML export:
132
+
133
+ ```bash
134
+ uv run pytest tests/test_real_inoreader_opml.py -v -s
135
+ ```
136
+
137
+ They skip when `/Users/huangcheng/Downloads/Cheng-Inoreader-feeds-final-20261016.opml` is missing. Unit tests do not require that file.
138
+
139
+ ## License
140
+
141
+ [MIT](LICENSE) © 2026 HUANG Cheng
@@ -0,0 +1,123 @@
1
+ # rss-mcp
2
+
3
+ Agent-only MCP server for RSS and Atom. A host drives it over stdio (default) or Streamable HTTP. There is no GUI, TUI, or interactive CLI. Subscriptions, cached entries, unread state, and full-text search live in one local SQLite file. v1 is tools only: no resources, prompts, or MCP Apps.
4
+
5
+ Protocol: [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) (stdio or Streamable HTTP, tools) via the official Python SDK v2 (`mcp` ≥ 2.3). Design: [docs/superpowers/specs/2026-11-18-rss-mcp-design.md](docs/superpowers/specs/2026-11-18-rss-mcp-design.md).
6
+
7
+ Requires Python 3.11+.
8
+
9
+ ## Host config
10
+
11
+ In stdio mode, the process reads JSON-RPC from stdin and writes MCP messages only to stdout. It exits when stdin closes.
12
+
13
+ Cursor `mcp.json` (any stdio host can use the same command):
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "rss-mcp": {
19
+ "command": "uvx",
20
+ "args": ["rss-mcp-server"],
21
+ "env": {
22
+ "RSS_MCP_DB": "/absolute/path/rss.db"
23
+ }
24
+ }
25
+ }
26
+ }
27
+ ```
28
+
29
+ The PyPI distribution is `rss-mcp-server` (`rss-mcp` is blocked by a similar existing project); it installs both the `rss-mcp-server` and `rss-mcp` commands. From this checkout: `uv run rss-mcp`, or `uvx --from /absolute/path/to/rss-mcp rss-mcp`.
30
+
31
+ ## HTTP transport
32
+
33
+ Run the same server over Streamable HTTP instead of stdio:
34
+
35
+ ```bash
36
+ uv run rss-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
37
+ ```
38
+
39
+ | Flag | Default |
40
+ | --- | --- |
41
+ | `--transport` | `stdio` (choices: `stdio`, `streamable-http`) |
42
+ | `--host` | `127.0.0.1` |
43
+ | `--port` | `8000` |
44
+ | `--path` | `/mcp` |
45
+
46
+ The MCP endpoint is then `http://127.0.0.1:8000/mcp`. Hosts that support remote servers can point at it directly:
47
+
48
+ ```json
49
+ {
50
+ "mcpServers": {
51
+ "rss-mcp": {
52
+ "url": "http://127.0.0.1:8000/mcp"
53
+ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ All sessions share one SQLite database (same `RSS_MCP_DB` setting). The endpoint serves both protocol eras: 2026-07-28 stateless per-request POSTs (with the `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` headers and `_meta` envelope) and the legacy `initialize` handshake (up to 2025-11-25, with sessions) for older hosts.
59
+
60
+ Set `RSS_MCP_AUTH_TOKEN` to require `Authorization: Bearer <token>` on every HTTP request (both eras; stdio is unaffected). Hosts that support custom headers:
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "rss-mcp": {
66
+ "url": "http://127.0.0.1:8000/mcp",
67
+ "headers": { "Authorization": "Bearer <token>" }
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ Without a token the endpoint is unauthenticated: keep the default loopback bind, or put it behind a reverse proxy with auth before exposing it beyond localhost.
74
+
75
+ ## Docker
76
+
77
+ The image runs the HTTP transport, stores the database in a `/data` volume, and runs as a non-root user:
78
+
79
+ ```bash
80
+ docker build -t rss-mcp .
81
+ docker run -d --name rss-mcp -p 127.0.0.1:8000:8000 \
82
+ -e RSS_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
83
+ -v rss-mcp-data:/data rss-mcp
84
+ ```
85
+
86
+ The container binds `0.0.0.0` internally (required for port mapping), so set `RSS_MCP_AUTH_TOKEN` whenever the published port is reachable beyond your machine. Publishing to `127.0.0.1` as above keeps it local. Run exactly one container per database volume.
87
+
88
+ ## Environment
89
+
90
+ | Variable | Default |
91
+ | --- | --- |
92
+ | `RSS_MCP_DB` | `~/.local/share/rss-mcp/rss.db` |
93
+ | `RSS_MCP_USER_AGENT` | `rss-mcp/0.1 (+https://github.com/huangcheng/rss-mcp)` |
94
+ | `RSS_MCP_AUTH_TOKEN` | unset (HTTP bearer auth disabled) |
95
+
96
+ `list_entries` and `search_entries` use `limit` 20 when omitted and clamp to 0–100. Each fetch upserts at most 50 entries and sends stored `ETag` / `Last-Modified` when the feed has them.
97
+
98
+ ## Tools
99
+
100
+ - `add_subscription` — Add a feed by URL. Repeating a URL returns the existing subscription.
101
+ - `remove_subscription` — Delete a subscription and its cached entries.
102
+ - `list_subscriptions` — List subscriptions with unread counts.
103
+ - `fetch_feed` — Fetch one subscription, or every subscription when the id is omitted.
104
+ - `list_entries` — List cached entries (article bodies omitted). Limit falls back to the server default and is clamped.
105
+ - `read_entry` — Return one entry with full content. `fetch_full` replaces content only when article text is returned. `mark_read` marks it read.
106
+ - `search_entries` — Full-text search over cached title, summary, and content (bodies omitted; use `read_entry` for full text).
107
+ - `mark_entry` — Mark entries read or unread. Unknown ids are skipped.
108
+ - `import_opml` — Add each OPML feed. Existing URLs are skipped.
109
+ - `export_opml` — Export subscriptions as an OPML document.
110
+
111
+ ## Live tests
112
+
113
+ Optional network tests against a real Inoreader OPML export:
114
+
115
+ ```bash
116
+ uv run pytest tests/test_real_inoreader_opml.py -v -s
117
+ ```
118
+
119
+ They skip when `/Users/huangcheng/Downloads/Cheng-Inoreader-feeds-final-20261016.opml` is missing. Unit tests do not require that file.
120
+
121
+ ## License
122
+
123
+ [MIT](LICENSE) © 2026 HUANG Cheng
@@ -0,0 +1,170 @@
1
+ # rss-mcp Gap Closure Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Close the post-v1 gaps that hurt agent UX and release hygiene: agent-sized list/search payloads, optional mark-read on read, SDK/config robustness, PyPI metadata, and tracked live OPML tests.
6
+
7
+ **Architecture:** Keep the existing Store/server split. Prefer shaping MCP tool responses in `server.py` (omit/truncate fields for list/search) rather than changing Store row shapes. Harden config + feed_client at the edges. No new transports or UI.
8
+
9
+ **Tech Stack:** Existing (`mcp` SDK v2, httpx, feedparser, pytest). Manual PyPI publish only — no GitHub Actions release workflow.
10
+
11
+ **Spec:** `docs/superpowers/specs/2026-11-18-rss-mcp-design.md` (agent-sized results, agent-only, MCP 2026-07-28)
12
+
13
+ ## Global Constraints
14
+
15
+ - Product `rss-mcp` / import `rss_mcp`; stdio tools-only; no GUI/TUI
16
+ - MCP 2026-07-28 via official SDK; pin `mcp` to a compatible minor range (e.g. `>=2.3,<3`)
17
+ - Default DB `~/.local/share/rss-mcp/rss.db`; override `RSS_MCP_DB`
18
+ - Agent-sized defaults remain: list/search default limit 20, max 100
19
+ - `read_entry` remains the only tool that returns full article bodies by default
20
+ - No auto-release CI in this plan (manual `uv publish`)
21
+ - Commits only when the human asks (plan may say “commit”; skip unless requested)
22
+
23
+ ## Review Focus
24
+
25
+ - `list_entries` / `search_entries` after a feed with large HTML `content` → response omits or truncates body; `read_entry` still returns full content
26
+ - `read_entry(..., mark_read=True)` → `read_at` set; default `mark_read=False` leaves unread unchanged
27
+ - `RSS_MCP_DB=" "` → treated as unset (falls back to default path), not a relative `" "` path
28
+ - Non-ASCII `RSS_MCP_USER_AGENT` on `fetch_feed` → `FetchResult(status="error")`, never raises
29
+ - `server/discover` → `serverInfo.version` is `0.1.0` (or package `__version__`); tools capability without list_changed listen expectation if `subscriptions=False`
30
+
31
+ ## File structure (touched)
32
+
33
+ ```
34
+ pyproject.toml # metadata + mcp pin
35
+ LICENSE # MIT (or SPDX already chosen)
36
+ README.md # note list/search omit content; mark_read
37
+ src/rss_mcp/__init__.py # version stays in sync with pyproject
38
+ src/rss_mcp/config.py # strip RSS_MCP_DB
39
+ src/rss_mcp/feed_client.py # UnicodeEncodeError; optional to_thread parse
40
+ src/rss_mcp/server.py # entry payloads; mark_read; MCPServer kwargs
41
+ tests/test_config.py
42
+ tests/test_feed_client.py
43
+ tests/test_server_tools.py
44
+ tests/test_real_inoreader_opml.py # already present untracked → keep skipif
45
+ ```
46
+
47
+ ---
48
+
49
+ ### Task 1: PyPI / package metadata
50
+
51
+ **Files:**
52
+ - Modify: `pyproject.toml`
53
+ - Create: `LICENSE` (MIT)
54
+ - Modify: `README.md` (only if metadata links need a one-line “License” mention — optional)
55
+ - Test: none required beyond `uv build` succeeding
56
+
57
+ **Interfaces:**
58
+ - Produces: `readme = "README.md"`; `license = "MIT"`; `authors`; `[project.urls]` Homepage/Repository (use `https://github.com/huangcheng/rss-mcp` unless human provides another URL — Ruling recorded in PR/commit message if wrong)
59
+ - Produces: `dependencies` pin `mcp>=2.3,<3`
60
+ - Keeps `version = "0.1.0"` aligned with `rss_mcp.__version__`
61
+
62
+ - [ ] **Step 1: Add metadata + license file + mcp pin**
63
+ - [ ] **Step 2: Run `uv build` — expect wheel/sdist in `dist/`**
64
+ - [ ] **Step 3: Run `uv run pytest -q` — expect existing suite still green**
65
+
66
+ ---
67
+
68
+ ### Task 2: Config + fetch edge hardening
69
+
70
+ **Files:**
71
+ - Modify: `src/rss_mcp/config.py`
72
+ - Modify: `src/rss_mcp/feed_client.py`
73
+ - Modify: `tests/test_config.py`
74
+ - Modify: `tests/test_feed_client.py`
75
+
76
+ **Interfaces:**
77
+ - `load_settings`: `raw_db = os.environ.get("RSS_MCP_DB");` if missing or `not raw_db.strip()` → default path; else `Path(raw_db.strip()).expanduser()`
78
+ - `fetch_feed` except tuple includes `UnicodeEncodeError` → `_error(...)`
79
+ - Optional in same task: wrap `feedparser.parse(io.BytesIO(body))` in `await asyncio.to_thread(...)` so cancellation can land between HTTP and parse (keep path-injection BytesIO behavior)
80
+
81
+ - [ ] **Step 1: Failing tests** `test_load_settings_whitespace_rss_mcp_db_uses_default`, `test_fetch_feed_returns_error_for_non_ascii_user_agent`
82
+ - [ ] **Step 2: Run — expect FAIL**
83
+ - [ ] **Step 3: Implement**
84
+ - [ ] **Step 4: Run focused + full suite — expect PASS**
85
+
86
+ ---
87
+
88
+ ### Task 3: Agent-sized list/search + mark_read on read
89
+
90
+ **Files:**
91
+ - Modify: `src/rss_mcp/server.py`
92
+ - Modify: `tests/test_server_tools.py`
93
+ - Modify: `README.md` (tool one-liners)
94
+
95
+ **Interfaces:**
96
+ - Add helper `_entry_payload(entry: Entry, *, full: bool) -> dict`:
97
+ - `full=True` → `asdict(entry)` (read path)
98
+ - `full=False` → `asdict(entry)` but set `content` to `None` (omit body; keep `summary`)
99
+ - `list_entries` / `search_entries` return `{"entries": [_entry_payload(e, full=False) for e in rows]}`
100
+ - `read_entry(entry_id, fetch_full: bool = False, mark_read: bool = False)`:
101
+ - existing fetch_full behavior
102
+ - if `mark_read`: `store.mark_entries([entry_id], True)` then re-get entry before return
103
+ - return `_entry_payload(entry, full=True)`
104
+ - Do **not** change Store `list_entries`/`search_entries` return types
105
+
106
+ - [ ] **Step 1: Failing tests**
107
+ - `test_list_entries_omits_content_bodies`
108
+ - `test_search_entries_omits_content_bodies`
109
+ - `test_read_entry_returns_full_content`
110
+ - `test_read_entry_mark_read_default_false`
111
+ - `test_read_entry_mark_read_true_sets_read_at`
112
+ - [ ] **Step 2: Run — expect FAIL**
113
+ - [ ] **Step 3: Implement helper + tool arg + README one-liner updates**
114
+ - [ ] **Step 4: Full suite PASS**
115
+
116
+ ---
117
+
118
+ ### Task 4: MCPServer identity + subscriptions off
119
+
120
+ **Files:**
121
+ - Modify: `src/rss_mcp/server.py`
122
+ - Modify: `tests/test_server_tools.py`
123
+
124
+ **Interfaces:**
125
+ - `MCPServer("rss-mcp", version=__version__, subscriptions=False, lifespan=...)`
126
+ - Keep existing private handler pop for resources/prompts until SDK offers a public API
127
+ - Assert discover/handshake: `server_info.version == "0.1.0"` (or whatever `__version__` is)
128
+ - Assert tools capability still present; if SDK exposes `list_changed`, prefer false / no listen when subscriptions=False — pin whatever the installed SDK actually reports and document in test name
129
+
130
+ - [ ] **Step 1: Failing test** for version + subscriptions behavior
131
+ - [ ] **Step 2: Implement MCPServer kwargs**
132
+ - [ ] **Step 3: Suite PASS**
133
+
134
+ ---
135
+
136
+ ### Task 5: Land live Inoreader OPML tests
137
+
138
+ **Files:**
139
+ - Add (if not already): `tests/test_real_inoreader_opml.py` (currently untracked)
140
+ - Modify: `README.md` — short “Live tests” note: path + `pytest tests/test_real_inoreader_opml.py -v -s`, skips if file missing
141
+
142
+ **Interfaces:** none new — keep `skipif(not OPML_PATH.is_file())`; do not require network in default CI mental model (document as optional)
143
+
144
+ - [ ] **Step 1: Ensure file is in repo tree with skipif**
145
+ - [ ] **Step 2: Offline: `uv run pytest -q` still passes (live tests skipped without file OR file present but mark network tests clearly)**
146
+ - Ruling: keep tests collectable; they need network when not skipped — default local path skip is enough for machines without the OPML
147
+ - [ ] **Step 3: With OPML present + network, optional sanity: run the module once**
148
+
149
+ ---
150
+
151
+ ## Spec coverage
152
+
153
+ | Gap | Task |
154
+ |-----|------|
155
+ | Agent-sized list/search | 3 |
156
+ | read → optional mark_read | 3 |
157
+ | Pin mcp / PyPI metadata | 1 |
158
+ | version + subscriptions=False | 4 |
159
+ | RSS_MCP_DB strip / non-ASCII UA | 2 |
160
+ | Live OPML tests tracked | 5 |
161
+ | to_thread parse (optional) | 2 |
162
+ | GitHub auto-release | Out of scope (declined) |
163
+
164
+ ## Out of scope
165
+
166
+ - GitHub Actions publish workflow
167
+ - HTTP/SSE transport, Resources/Prompts/Apps
168
+ - OPML folder→tags, URL canonicalization beyond strip
169
+ - Changing default DB layout / XDG_DATA_HOME
170
+ - Publishing to PyPI in this plan (human runs `uv publish` after)