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.
- freshrss_agent-0.1.0/LICENSE +21 -0
- freshrss_agent-0.1.0/MANIFEST.in +4 -0
- freshrss_agent-0.1.0/PKG-INFO +227 -0
- freshrss_agent-0.1.0/README.md +198 -0
- freshrss_agent-0.1.0/freshrss_agent/__init__.py +54 -0
- freshrss_agent-0.1.0/freshrss_agent/__main__.py +5 -0
- freshrss_agent-0.1.0/freshrss_agent/agent_data/IDENTITY.md +15 -0
- freshrss_agent-0.1.0/freshrss_agent/agent_server.py +73 -0
- freshrss_agent-0.1.0/freshrss_agent/api/__init__.py +19 -0
- freshrss_agent-0.1.0/freshrss_agent/api/api_client_base.py +137 -0
- freshrss_agent-0.1.0/freshrss_agent/api/api_client_reader.py +70 -0
- freshrss_agent-0.1.0/freshrss_agent/api/api_client_subscriptions.py +78 -0
- freshrss_agent-0.1.0/freshrss_agent/api_client.py +7 -0
- freshrss_agent-0.1.0/freshrss_agent/auth.py +100 -0
- freshrss_agent-0.1.0/freshrss_agent/freshrss_input_models.py +70 -0
- freshrss_agent-0.1.0/freshrss_agent/freshrss_response_models.py +70 -0
- freshrss_agent-0.1.0/freshrss_agent/main_agent.json +14 -0
- freshrss_agent-0.1.0/freshrss_agent/mcp/__init__.py +4 -0
- freshrss_agent-0.1.0/freshrss_agent/mcp/mcp_reader.py +65 -0
- freshrss_agent-0.1.0/freshrss_agent/mcp/mcp_subscriptions.py +81 -0
- freshrss_agent-0.1.0/freshrss_agent/mcp_config.json +3 -0
- freshrss_agent-0.1.0/freshrss_agent/mcp_server.py +63 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/PKG-INFO +227 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/SOURCES.txt +41 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/dependency_links.txt +1 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/entry_points.txt +3 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/requires.txt +17 -0
- freshrss_agent-0.1.0/freshrss_agent.egg-info/top_level.txt +6 -0
- freshrss_agent-0.1.0/pyproject.toml +59 -0
- freshrss_agent-0.1.0/requirements.txt +2 -0
- freshrss_agent-0.1.0/scripts/security_sanitizer.py +160 -0
- freshrss_agent-0.1.0/scripts/validate_a2a_agent.py +139 -0
- freshrss_agent-0.1.0/scripts/validate_agent.py +15 -0
- freshrss_agent-0.1.0/scripts/verify_api_integration.py +280 -0
- freshrss_agent-0.1.0/setup.cfg +4 -0
- freshrss_agent-0.1.0/tests/__init__.py +0 -0
- freshrss_agent-0.1.0/tests/conftest.py +10 -0
- freshrss_agent-0.1.0/tests/test_api_wrapper.py +82 -0
- freshrss_agent-0.1.0/tests/test_auth.py +17 -0
- freshrss_agent-0.1.0/tests/test_concept_parity.py +23 -0
- freshrss_agent-0.1.0/tests/test_freshrss_mcp_validation.py +19 -0
- freshrss_agent-0.1.0/tests/test_init_dynamics.py +10 -0
- 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,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
|
+

|
|
34
|
+

|
|
35
|
+

|
|
36
|
+

|
|
37
|
+

|
|
38
|
+

|
|
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
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+

|
|
9
|
+

|
|
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,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
|
+
]
|