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.
- rss_mcp_server-0.1.0/.dockerignore +9 -0
- rss_mcp_server-0.1.0/.gitignore +14 -0
- rss_mcp_server-0.1.0/.qwen/tmp/pypi-token +1 -0
- rss_mcp_server-0.1.0/Dockerfile +14 -0
- rss_mcp_server-0.1.0/LICENSE +21 -0
- rss_mcp_server-0.1.0/PKG-INFO +141 -0
- rss_mcp_server-0.1.0/README.md +123 -0
- rss_mcp_server-0.1.0/docs/superpowers/plans/2026-11-18-gap-closure.md +170 -0
- rss_mcp_server-0.1.0/docs/superpowers/plans/2026-11-18-rss-mcp.md +283 -0
- rss_mcp_server-0.1.0/docs/superpowers/specs/2026-11-18-rss-mcp-design.md +160 -0
- rss_mcp_server-0.1.0/pyproject.toml +40 -0
- rss_mcp_server-0.1.0/src/rss_mcp/__init__.py +3 -0
- rss_mcp_server-0.1.0/src/rss_mcp/__main__.py +4 -0
- rss_mcp_server-0.1.0/src/rss_mcp/config.py +28 -0
- rss_mcp_server-0.1.0/src/rss_mcp/db.py +74 -0
- rss_mcp_server-0.1.0/src/rss_mcp/feed_client.py +192 -0
- rss_mcp_server-0.1.0/src/rss_mcp/models.py +44 -0
- rss_mcp_server-0.1.0/src/rss_mcp/opml.py +58 -0
- rss_mcp_server-0.1.0/src/rss_mcp/readability_fetch.py +137 -0
- rss_mcp_server-0.1.0/src/rss_mcp/server.py +361 -0
- rss_mcp_server-0.1.0/src/rss_mcp/store.py +361 -0
- rss_mcp_server-0.1.0/tests/conftest.py +15 -0
- rss_mcp_server-0.1.0/tests/fixtures/sample.opml +15 -0
- rss_mcp_server-0.1.0/tests/fixtures/sample_atom.xml +21 -0
- rss_mcp_server-0.1.0/tests/fixtures/sample_rss.xml +29 -0
- rss_mcp_server-0.1.0/tests/test_config.py +53 -0
- rss_mcp_server-0.1.0/tests/test_db.py +196 -0
- rss_mcp_server-0.1.0/tests/test_feed_client.py +530 -0
- rss_mcp_server-0.1.0/tests/test_http_transport.py +301 -0
- rss_mcp_server-0.1.0/tests/test_opml.py +62 -0
- rss_mcp_server-0.1.0/tests/test_readability_fetch.py +198 -0
- rss_mcp_server-0.1.0/tests/test_real_inoreader_opml.py +276 -0
- rss_mcp_server-0.1.0/tests/test_server_tools.py +697 -0
- rss_mcp_server-0.1.0/tests/test_store_entries.py +412 -0
- rss_mcp_server-0.1.0/tests/test_store_subscriptions.py +227 -0
- rss_mcp_server-0.1.0/uv.lock +1118 -0
|
@@ -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)
|