freshrss-agent 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.
Files changed (43) hide show
  1. freshrss_agent-0.1.0/LICENSE +21 -0
  2. freshrss_agent-0.1.0/MANIFEST.in +4 -0
  3. freshrss_agent-0.1.0/PKG-INFO +227 -0
  4. freshrss_agent-0.1.0/README.md +198 -0
  5. freshrss_agent-0.1.0/freshrss_agent/__init__.py +54 -0
  6. freshrss_agent-0.1.0/freshrss_agent/__main__.py +5 -0
  7. freshrss_agent-0.1.0/freshrss_agent/agent_data/IDENTITY.md +15 -0
  8. freshrss_agent-0.1.0/freshrss_agent/agent_server.py +73 -0
  9. freshrss_agent-0.1.0/freshrss_agent/api/__init__.py +19 -0
  10. freshrss_agent-0.1.0/freshrss_agent/api/api_client_base.py +137 -0
  11. freshrss_agent-0.1.0/freshrss_agent/api/api_client_reader.py +70 -0
  12. freshrss_agent-0.1.0/freshrss_agent/api/api_client_subscriptions.py +78 -0
  13. freshrss_agent-0.1.0/freshrss_agent/api_client.py +7 -0
  14. freshrss_agent-0.1.0/freshrss_agent/auth.py +100 -0
  15. freshrss_agent-0.1.0/freshrss_agent/freshrss_input_models.py +70 -0
  16. freshrss_agent-0.1.0/freshrss_agent/freshrss_response_models.py +70 -0
  17. freshrss_agent-0.1.0/freshrss_agent/main_agent.json +14 -0
  18. freshrss_agent-0.1.0/freshrss_agent/mcp/__init__.py +4 -0
  19. freshrss_agent-0.1.0/freshrss_agent/mcp/mcp_reader.py +65 -0
  20. freshrss_agent-0.1.0/freshrss_agent/mcp/mcp_subscriptions.py +81 -0
  21. freshrss_agent-0.1.0/freshrss_agent/mcp_config.json +3 -0
  22. freshrss_agent-0.1.0/freshrss_agent/mcp_server.py +63 -0
  23. freshrss_agent-0.1.0/freshrss_agent.egg-info/PKG-INFO +227 -0
  24. freshrss_agent-0.1.0/freshrss_agent.egg-info/SOURCES.txt +41 -0
  25. freshrss_agent-0.1.0/freshrss_agent.egg-info/dependency_links.txt +1 -0
  26. freshrss_agent-0.1.0/freshrss_agent.egg-info/entry_points.txt +3 -0
  27. freshrss_agent-0.1.0/freshrss_agent.egg-info/requires.txt +17 -0
  28. freshrss_agent-0.1.0/freshrss_agent.egg-info/top_level.txt +6 -0
  29. freshrss_agent-0.1.0/pyproject.toml +59 -0
  30. freshrss_agent-0.1.0/requirements.txt +2 -0
  31. freshrss_agent-0.1.0/scripts/security_sanitizer.py +160 -0
  32. freshrss_agent-0.1.0/scripts/validate_a2a_agent.py +139 -0
  33. freshrss_agent-0.1.0/scripts/validate_agent.py +15 -0
  34. freshrss_agent-0.1.0/scripts/verify_api_integration.py +280 -0
  35. freshrss_agent-0.1.0/setup.cfg +4 -0
  36. freshrss_agent-0.1.0/tests/__init__.py +0 -0
  37. freshrss_agent-0.1.0/tests/conftest.py +10 -0
  38. freshrss_agent-0.1.0/tests/test_api_wrapper.py +82 -0
  39. freshrss_agent-0.1.0/tests/test_auth.py +17 -0
  40. freshrss_agent-0.1.0/tests/test_concept_parity.py +23 -0
  41. freshrss_agent-0.1.0/tests/test_freshrss_mcp_validation.py +19 -0
  42. freshrss_agent-0.1.0/tests/test_init_dynamics.py +10 -0
  43. freshrss_agent-0.1.0/tests/test_startup.py +9 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Audel Rouhi
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,4 @@
1
+ include LICENSE
2
+ include README.md
3
+ include requirements.txt
4
+ recursive-include freshrss_agent *.py *.json
@@ -0,0 +1,227 @@
1
+ Metadata-Version: 2.4
2
+ Name: freshrss-agent
3
+ Version: 0.1.0
4
+ Summary: FreshRSS API + MCP Server + A2A Server
5
+ Author-email: Audel Rouhi <knucklessg1@gmail.com>
6
+ License: MIT
7
+ Classifier: Development Status :: 4 - Beta
8
+ Classifier: License :: OSI Approved :: MIT License
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: <3.15,>=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: agent-utilities>=0.51.0
16
+ Requires-Dist: python-dotenv>=1.0.0
17
+ Provides-Extra: mcp
18
+ Requires-Dist: agent-utilities[mcp]>=0.51.0; extra == "mcp"
19
+ Provides-Extra: agent
20
+ Requires-Dist: agent-utilities[agent,logfire]>=0.51.0; extra == "agent"
21
+ Provides-Extra: all
22
+ Requires-Dist: freshrss-agent[agent,logfire,mcp]>=0.1.0; extra == "all"
23
+ Provides-Extra: test
24
+ Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
25
+ Requires-Dist: pytest; extra == "test"
26
+ Requires-Dist: pytest-asyncio; extra == "test"
27
+ Requires-Dist: pytest-cov; extra == "test"
28
+ Dynamic: license-file
29
+
30
+ # FreshRSS
31
+ ## CLI or API | MCP | Agent
32
+
33
+ ![PyPI - Version](https://img.shields.io/pypi/v/freshrss-agent)
34
+ ![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
35
+ ![PyPI - Downloads](https://img.shields.io/pypi/dd/freshrss-agent)
36
+ ![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/freshrss-agent)
37
+ ![PyPI - License](https://img.shields.io/pypi/l/freshrss-agent)
38
+ ![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/freshrss-agent)
39
+
40
+ *Version: 0.1.0*
41
+
42
+ > **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
43
+ > interfaces, the integrated A2A agent server, and guidance for provisioning the
44
+ > backing platform are maintained in the
45
+ > [official documentation](https://knuckles-team.github.io/freshrss-agent/).
46
+
47
+ ---
48
+
49
+ ## Table of Contents
50
+
51
+ - [Overview](#overview)
52
+ - [Key Features](#key-features)
53
+ - [MCP](#mcp)
54
+ - [Available MCP Tools](#available-mcp-tools)
55
+ - [Environment Variables](#environment-variables)
56
+ - [Transport Configuration Examples](#stdio-transport-local-ides--cursor-claude-desktop-vs-code)
57
+ - [Additional Deployment Options](#additional-deployment-options)
58
+ - [Usage](#usage)
59
+ - [Installation](#installation)
60
+ - [Documentation](#documentation)
61
+
62
+ ---
63
+
64
+ ## Overview
65
+
66
+ **FreshRSS MCP Server + A2A Agent**
67
+
68
+ A connector for the self-hosted [FreshRSS](https://freshrss.org/) RSS reader,
69
+ wrapping its **Google Reader compatible API** (GReader). It exposes two
70
+ action-routed MCP tool domains:
71
+
72
+ - **`freshrss_reader`** — `stream_contents` (feed items + continuation), `item_contents`, `unread_count`.
73
+ - **`freshrss_subscriptions`** — `list`, `subscribe`, `unsubscribe`, `label`, `categories`, `mark_read`, `star`.
74
+
75
+ This repository is actively maintained - Contributions are welcome!
76
+
77
+ ---
78
+
79
+ ## Key Features
80
+
81
+ - **Consolidated Action-Routed MCP Tools:** Two togglable tool domains group every
82
+ GReader operation, minimizing token overhead and tool bloat in LLM contexts.
83
+ - **Google Reader Compatible:** Wraps the FreshRSS GReader API — `ClientLogin` auth,
84
+ transparent re-authentication on `401`, and automatic write-token handling.
85
+ - **Enterprise-Grade Security:** OIDC token delegation (RFC 8693), Eunomia policy
86
+ enforcement, and per-instance credential resolution.
87
+ - **Integrated A2A Agent:** Built-in Pydantic AI agent server alongside the MCP server.
88
+ - **Native Telemetry & Tracing:** Out-of-the-box OpenTelemetry exports and Langfuse tracing.
89
+
90
+ ---
91
+
92
+ ## MCP
93
+
94
+ ### Available MCP Tools
95
+
96
+ This server uses dynamic Action-Routed tools to optimize token overhead and maximize
97
+ IDE compatibility. Each tool takes an `action` plus a `params_json` payload.
98
+
99
+ | Tool Module | Toggle Env Var | Enabled by Default | Description & Action-Routed Methods |
100
+ |-------------|----------------|--------------------|-------------------------------------|
101
+ | **Reader** | `READERTOOL` | `True` | Read FreshRSS streams via the GReader API. Action-routed methods: `stream_contents`, `item_contents`, `unread_count`. |
102
+ | **Subscriptions** | `SUBSCRIPTIONSTOOL` | `True` | Curate feeds, categories, and item tags. Action-routed methods: `list`, `subscribe`, `unsubscribe`, `label`, `categories`, `mark_read`, `star`. |
103
+
104
+ Detailed tool schemas, parameter shapes, and validation constraints are preserved in
105
+ [docs/usage.md](docs/usage.md).
106
+
107
+ ### Environment Variables
108
+
109
+ The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
110
+ `sse` mode.
111
+
112
+ * `FRESHRSS_URL`: The base URL of the FreshRSS instance (e.g. `http://freshrss.arpa`).
113
+ * `FRESHRSS_USER`: The FreshRSS username (GReader `Email` field).
114
+ * `FRESHRSS_API_PASSWORD`: The FreshRSS **API password** (Settings → Authentication).
115
+ * `FRESHRSS_SSL_VERIFY`: Whether to verify TLS certificates (default `True`).
116
+
117
+ #### stdio Transport (local IDEs - Cursor, Claude Desktop, VS Code)
118
+
119
+ ```json
120
+ {
121
+ "mcpServers": {
122
+ "freshrss-mcp": {
123
+ "command": "uvx",
124
+ "args": ["--from", "freshrss-agent", "freshrss-mcp"],
125
+ "env": {
126
+ "FRESHRSS_URL": "https://service.example.com",
127
+ "FRESHRSS_USER": "admin",
128
+ "FRESHRSS_API_PASSWORD": "your_api_password"
129
+ }
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ #### Streamable-HTTP Transport (networked / production)
136
+
137
+ ```json
138
+ {
139
+ "mcpServers": {
140
+ "freshrss-mcp": {
141
+ "command": "uvx",
142
+ "args": ["--from", "freshrss-agent", "freshrss-mcp", "--transport", "streamable-http", "--port", "8000"],
143
+ "env": {
144
+ "TRANSPORT": "streamable-http",
145
+ "HOST": "0.0.0.0",
146
+ "PORT": "8000",
147
+ "FRESHRSS_URL": "https://service.example.com",
148
+ "FRESHRSS_USER": "admin",
149
+ "FRESHRSS_API_PASSWORD": "your_api_password"
150
+ }
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ <!-- BEGIN GENERATED: additional-deployment-options -->
157
+ ### Additional Deployment Options
158
+
159
+ `freshrss-agent` can also run as a **local container** (Docker / Podman / `uv`) or be
160
+ consumed from a **remote deployment**. The
161
+ [Deployment guide](https://knuckles-team.github.io/freshrss-agent/deployment/) has full,
162
+ copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
163
+ **local container / uv**, and **remote URL**:
164
+
165
+ - **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
166
+ `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
167
+ - **Remote URL** — connect to a server deployed behind Caddy at
168
+ `http://freshrss-mcp.arpa/mcp` using the `"url"` key.
169
+ <!-- END GENERATED: additional-deployment-options -->
170
+
171
+ ## Usage
172
+
173
+ Once configured, an LLM (or a direct caller) invokes a tool domain with an `action`
174
+ and a JSON `params_json` payload. Examples:
175
+
176
+ ```jsonc
177
+ // Fetch the 50 most recent unread items, newest first
178
+ {
179
+ "tool": "freshrss_reader",
180
+ "action": "stream_contents",
181
+ "params_json": "{\"count\": 50, \"order\": \"n\"}"
182
+ }
183
+
184
+ // Subscribe to a feed and file it under a category
185
+ {
186
+ "tool": "freshrss_subscriptions",
187
+ "action": "subscribe",
188
+ "params_json": "{\"feed_url\": \"http://example.com/rss\", \"category\": \"News\"}"
189
+ }
190
+
191
+ // Mark items as read
192
+ {
193
+ "tool": "freshrss_subscriptions",
194
+ "action": "mark_read",
195
+ "params_json": "{\"item_ids\": [\"tag:google.com,2005:reader/item/0001\"]}"
196
+ }
197
+ ```
198
+
199
+ Invoking a tool with an unknown or omitted `action` returns the discovery payload
200
+ listing every valid action for that domain.
201
+
202
+ ## Installation
203
+
204
+ ```bash
205
+ # Using uv (recommended)
206
+ uv pip install freshrss-agent
207
+
208
+ # Using standard pip
209
+ python -m pip install freshrss-agent
210
+ ```
211
+
212
+ After installation two console scripts are available:
213
+
214
+ ```bash
215
+ freshrss-mcp # run the MCP server
216
+ freshrss-agent # run the A2A agent server
217
+ ```
218
+
219
+ ## Documentation
220
+
221
+ Full installation, deployment, usage, and platform-provisioning guides live in the
222
+ [`docs/`](docs/) directory and are published via mkdocs + GitHub Pages at the
223
+ [official documentation site](https://knuckles-team.github.io/freshrss-agent/):
224
+
225
+ - [Overview](docs/overview.md) · [Installation](docs/installation.md) ·
226
+ [Usage](docs/usage.md) · [Deployment](docs/deployment.md) ·
227
+ [Platform](docs/platform.md) · [Concepts](docs/concepts.md)
@@ -0,0 +1,198 @@
1
+ # FreshRSS
2
+ ## CLI or API | MCP | Agent
3
+
4
+ ![PyPI - Version](https://img.shields.io/pypi/v/freshrss-agent)
5
+ ![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
6
+ ![PyPI - Downloads](https://img.shields.io/pypi/dd/freshrss-agent)
7
+ ![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/freshrss-agent)
8
+ ![PyPI - License](https://img.shields.io/pypi/l/freshrss-agent)
9
+ ![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/freshrss-agent)
10
+
11
+ *Version: 0.1.0*
12
+
13
+ > **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
14
+ > interfaces, the integrated A2A agent server, and guidance for provisioning the
15
+ > backing platform are maintained in the
16
+ > [official documentation](https://knuckles-team.github.io/freshrss-agent/).
17
+
18
+ ---
19
+
20
+ ## Table of Contents
21
+
22
+ - [Overview](#overview)
23
+ - [Key Features](#key-features)
24
+ - [MCP](#mcp)
25
+ - [Available MCP Tools](#available-mcp-tools)
26
+ - [Environment Variables](#environment-variables)
27
+ - [Transport Configuration Examples](#stdio-transport-local-ides--cursor-claude-desktop-vs-code)
28
+ - [Additional Deployment Options](#additional-deployment-options)
29
+ - [Usage](#usage)
30
+ - [Installation](#installation)
31
+ - [Documentation](#documentation)
32
+
33
+ ---
34
+
35
+ ## Overview
36
+
37
+ **FreshRSS MCP Server + A2A Agent**
38
+
39
+ A connector for the self-hosted [FreshRSS](https://freshrss.org/) RSS reader,
40
+ wrapping its **Google Reader compatible API** (GReader). It exposes two
41
+ action-routed MCP tool domains:
42
+
43
+ - **`freshrss_reader`** — `stream_contents` (feed items + continuation), `item_contents`, `unread_count`.
44
+ - **`freshrss_subscriptions`** — `list`, `subscribe`, `unsubscribe`, `label`, `categories`, `mark_read`, `star`.
45
+
46
+ This repository is actively maintained - Contributions are welcome!
47
+
48
+ ---
49
+
50
+ ## Key Features
51
+
52
+ - **Consolidated Action-Routed MCP Tools:** Two togglable tool domains group every
53
+ GReader operation, minimizing token overhead and tool bloat in LLM contexts.
54
+ - **Google Reader Compatible:** Wraps the FreshRSS GReader API — `ClientLogin` auth,
55
+ transparent re-authentication on `401`, and automatic write-token handling.
56
+ - **Enterprise-Grade Security:** OIDC token delegation (RFC 8693), Eunomia policy
57
+ enforcement, and per-instance credential resolution.
58
+ - **Integrated A2A Agent:** Built-in Pydantic AI agent server alongside the MCP server.
59
+ - **Native Telemetry & Tracing:** Out-of-the-box OpenTelemetry exports and Langfuse tracing.
60
+
61
+ ---
62
+
63
+ ## MCP
64
+
65
+ ### Available MCP Tools
66
+
67
+ This server uses dynamic Action-Routed tools to optimize token overhead and maximize
68
+ IDE compatibility. Each tool takes an `action` plus a `params_json` payload.
69
+
70
+ | Tool Module | Toggle Env Var | Enabled by Default | Description & Action-Routed Methods |
71
+ |-------------|----------------|--------------------|-------------------------------------|
72
+ | **Reader** | `READERTOOL` | `True` | Read FreshRSS streams via the GReader API. Action-routed methods: `stream_contents`, `item_contents`, `unread_count`. |
73
+ | **Subscriptions** | `SUBSCRIPTIONSTOOL` | `True` | Curate feeds, categories, and item tags. Action-routed methods: `list`, `subscribe`, `unsubscribe`, `label`, `categories`, `mark_read`, `star`. |
74
+
75
+ Detailed tool schemas, parameter shapes, and validation constraints are preserved in
76
+ [docs/usage.md](docs/usage.md).
77
+
78
+ ### Environment Variables
79
+
80
+ The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
81
+ `sse` mode.
82
+
83
+ * `FRESHRSS_URL`: The base URL of the FreshRSS instance (e.g. `http://freshrss.arpa`).
84
+ * `FRESHRSS_USER`: The FreshRSS username (GReader `Email` field).
85
+ * `FRESHRSS_API_PASSWORD`: The FreshRSS **API password** (Settings → Authentication).
86
+ * `FRESHRSS_SSL_VERIFY`: Whether to verify TLS certificates (default `True`).
87
+
88
+ #### stdio Transport (local IDEs - Cursor, Claude Desktop, VS Code)
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "freshrss-mcp": {
94
+ "command": "uvx",
95
+ "args": ["--from", "freshrss-agent", "freshrss-mcp"],
96
+ "env": {
97
+ "FRESHRSS_URL": "https://service.example.com",
98
+ "FRESHRSS_USER": "admin",
99
+ "FRESHRSS_API_PASSWORD": "your_api_password"
100
+ }
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ #### Streamable-HTTP Transport (networked / production)
107
+
108
+ ```json
109
+ {
110
+ "mcpServers": {
111
+ "freshrss-mcp": {
112
+ "command": "uvx",
113
+ "args": ["--from", "freshrss-agent", "freshrss-mcp", "--transport", "streamable-http", "--port", "8000"],
114
+ "env": {
115
+ "TRANSPORT": "streamable-http",
116
+ "HOST": "0.0.0.0",
117
+ "PORT": "8000",
118
+ "FRESHRSS_URL": "https://service.example.com",
119
+ "FRESHRSS_USER": "admin",
120
+ "FRESHRSS_API_PASSWORD": "your_api_password"
121
+ }
122
+ }
123
+ }
124
+ }
125
+ ```
126
+
127
+ <!-- BEGIN GENERATED: additional-deployment-options -->
128
+ ### Additional Deployment Options
129
+
130
+ `freshrss-agent` can also run as a **local container** (Docker / Podman / `uv`) or be
131
+ consumed from a **remote deployment**. The
132
+ [Deployment guide](https://knuckles-team.github.io/freshrss-agent/deployment/) has full,
133
+ copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
134
+ **local container / uv**, and **remote URL**:
135
+
136
+ - **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
137
+ `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
138
+ - **Remote URL** — connect to a server deployed behind Caddy at
139
+ `http://freshrss-mcp.arpa/mcp` using the `"url"` key.
140
+ <!-- END GENERATED: additional-deployment-options -->
141
+
142
+ ## Usage
143
+
144
+ Once configured, an LLM (or a direct caller) invokes a tool domain with an `action`
145
+ and a JSON `params_json` payload. Examples:
146
+
147
+ ```jsonc
148
+ // Fetch the 50 most recent unread items, newest first
149
+ {
150
+ "tool": "freshrss_reader",
151
+ "action": "stream_contents",
152
+ "params_json": "{\"count\": 50, \"order\": \"n\"}"
153
+ }
154
+
155
+ // Subscribe to a feed and file it under a category
156
+ {
157
+ "tool": "freshrss_subscriptions",
158
+ "action": "subscribe",
159
+ "params_json": "{\"feed_url\": \"http://example.com/rss\", \"category\": \"News\"}"
160
+ }
161
+
162
+ // Mark items as read
163
+ {
164
+ "tool": "freshrss_subscriptions",
165
+ "action": "mark_read",
166
+ "params_json": "{\"item_ids\": [\"tag:google.com,2005:reader/item/0001\"]}"
167
+ }
168
+ ```
169
+
170
+ Invoking a tool with an unknown or omitted `action` returns the discovery payload
171
+ listing every valid action for that domain.
172
+
173
+ ## Installation
174
+
175
+ ```bash
176
+ # Using uv (recommended)
177
+ uv pip install freshrss-agent
178
+
179
+ # Using standard pip
180
+ python -m pip install freshrss-agent
181
+ ```
182
+
183
+ After installation two console scripts are available:
184
+
185
+ ```bash
186
+ freshrss-mcp # run the MCP server
187
+ freshrss-agent # run the A2A agent server
188
+ ```
189
+
190
+ ## Documentation
191
+
192
+ Full installation, deployment, usage, and platform-provisioning guides live in the
193
+ [`docs/`](docs/) directory and are published via mkdocs + GitHub Pages at the
194
+ [official documentation site](https://knuckles-team.github.io/freshrss-agent/):
195
+
196
+ - [Overview](docs/overview.md) · [Installation](docs/installation.md) ·
197
+ [Usage](docs/usage.md) · [Deployment](docs/deployment.md) ·
198
+ [Platform](docs/platform.md) · [Concepts](docs/concepts.md)
@@ -0,0 +1,54 @@
1
+ #!/usr/bin/env python
2
+
3
+ import importlib
4
+ import inspect
5
+ import warnings
6
+
7
+ warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
8
+
9
+ __all__: list[str] = []
10
+
11
+ CORE_MODULES = [
12
+ "freshrss_agent.api",
13
+ ]
14
+
15
+ OPTIONAL_MODULES = {
16
+ "freshrss_agent.agent_server": "agent",
17
+ "freshrss_agent.mcp_server": "mcp",
18
+ }
19
+
20
+
21
+ def _import_module_safely(module_name: str):
22
+ """Try to import a module and return it, or None if not available."""
23
+ try:
24
+ return importlib.import_module(module_name)
25
+ except ImportError:
26
+ return None
27
+
28
+
29
+ def _expose_members(module):
30
+ """Expose public classes and functions from a module into globals and __all__."""
31
+ for name, obj in inspect.getmembers(module):
32
+ if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
33
+ "_"
34
+ ):
35
+ globals()[name] = obj
36
+ __all__.append(name)
37
+
38
+
39
+ for module_name in CORE_MODULES:
40
+ try:
41
+ module = importlib.import_module(module_name)
42
+ _expose_members(module)
43
+ except ImportError:
44
+ pass
45
+
46
+ for module_name, extra_name in OPTIONAL_MODULES.items():
47
+ module = _import_module_safely(module_name)
48
+ if module is not None:
49
+ _expose_members(module)
50
+ globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
51
+ else:
52
+ globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
53
+
54
+ __all__.extend(["_MCP_AVAILABLE", "_AGENT_AVAILABLE"])
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/python
2
+ from freshrss_agent.agent_server import agent_server
3
+
4
+ if __name__ == "__main__":
5
+ agent_server()
@@ -0,0 +1,15 @@
1
+ # IDENTITY.md - FreshRSS Agent Identity
2
+
3
+ ## [default]
4
+ * **Name:** FreshRSS Agent
5
+ * **Role:** FreshRSS API + MCP Server + A2A Server
6
+ * **Emoji:** 🤖
7
+
8
+ ### System Prompt
9
+ You are the FreshRSS Agent.
10
+ Use the `mcp-client` universal skill and check the reference documentation for
11
+ `freshrss-agent.md` to discover the exact tags and tools available for your capabilities.
12
+
13
+ ### Capabilities
14
+ - **MCP Operations**: Leverage the `mcp-client` skill to interact with the target MCP server.
15
+ - **Custom Agent**: Handle custom tasks or general tasks.
@@ -0,0 +1,73 @@
1
+ #!/usr/bin/python
2
+ import logging
3
+ import os
4
+ import sys
5
+ import warnings
6
+
7
+ __version__ = "0.1.0"
8
+
9
+ logging.basicConfig(
10
+ level=logging.INFO,
11
+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
12
+ handlers=[logging.StreamHandler()],
13
+ )
14
+ logger = logging.getLogger(__name__)
15
+
16
+
17
+ def agent_server():
18
+ from agent_utilities import (
19
+ build_system_prompt_from_workspace,
20
+ create_agent_parser,
21
+ create_agent_server,
22
+ initialize_workspace,
23
+ load_identity,
24
+ )
25
+
26
+ warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
27
+ warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
28
+
29
+ initialize_workspace()
30
+ meta = load_identity()
31
+ agent_name = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "FreshRSS"))
32
+
33
+ print(f"{agent_name} v{__version__}", file=sys.stderr)
34
+ parser = create_agent_parser()
35
+ args = parser.parse_args()
36
+
37
+ if args.debug:
38
+ logging.getLogger().setLevel(logging.DEBUG)
39
+ logger.debug("Debug mode enabled")
40
+
41
+ create_agent_server(
42
+ mcp_url=args.mcp_url,
43
+ mcp_config=args.mcp_config or "mcp_config.json",
44
+ host=args.host,
45
+ port=args.port,
46
+ provider=args.provider,
47
+ model_id=args.model_id,
48
+ router_model=args.model_id,
49
+ agent_model=args.model_id,
50
+ base_url=args.base_url,
51
+ api_key=args.api_key,
52
+ agent_description=os.getenv(
53
+ "AGENT_DESCRIPTION",
54
+ meta.get("description", "FreshRSS API + MCP Server + A2A Server"),
55
+ ),
56
+ system_prompt=os.getenv(
57
+ "AGENT_SYSTEM_PROMPT",
58
+ meta.get("content") or build_system_prompt_from_workspace(),
59
+ ),
60
+ custom_skills_directory=args.custom_skills_directory,
61
+ enable_web_ui=args.web,
62
+ enable_otel=args.otel,
63
+ otel_endpoint=args.otel_endpoint,
64
+ otel_headers=args.otel_headers,
65
+ otel_public_key=args.otel_public_key,
66
+ otel_secret_key=args.otel_secret_key,
67
+ otel_protocol=args.otel_protocol,
68
+ debug=args.debug,
69
+ )
70
+
71
+
72
+ if __name__ == "__main__":
73
+ agent_server()
@@ -0,0 +1,19 @@
1
+ from .api_client_base import FreshRSSClientBase
2
+ from .api_client_reader import ReaderMixin
3
+ from .api_client_subscriptions import SubscriptionsMixin
4
+
5
+
6
+ class FreshRSSApi(ReaderMixin, SubscriptionsMixin, FreshRSSClientBase):
7
+ """FreshRSS GReader API client (reader + subscriptions)."""
8
+
9
+
10
+ # Backward-compat alias for the scaffold (auth.py imports ApiClientSystem).
11
+ ApiClientSystem = FreshRSSApi
12
+
13
+ __all__ = [
14
+ "FreshRSSApi",
15
+ "FreshRSSClientBase",
16
+ "ReaderMixin",
17
+ "SubscriptionsMixin",
18
+ "ApiClientSystem",
19
+ ]