freshrss-agent 0.1.0__py3-none-any.whl

freshrss_agent/__init__.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+import warnings
+
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "freshrss_agent.api",
+]
+
+OPTIONAL_MODULES = {
+    "freshrss_agent.agent_server": "agent",
+    "freshrss_agent.mcp_server": "mcp",
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    try:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+    except ImportError:
+        pass
+
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+__all__.extend(["_MCP_AVAILABLE", "_AGENT_AVAILABLE"])

freshrss_agent/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/python
+from freshrss_agent.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

freshrss_agent/agent_data/IDENTITY.md

@@ -0,0 +1,15 @@
+# IDENTITY.md - FreshRSS Agent Identity
+
+## [default]
+ * **Name:** FreshRSS Agent
+ * **Role:** FreshRSS API + MCP Server + A2A Server
+ * **Emoji:** 🤖
+
+ ### System Prompt
+ You are the FreshRSS Agent.
+ Use the `mcp-client` universal skill and check the reference documentation for
+ `freshrss-agent.md` to discover the exact tags and tools available for your capabilities.
+
+ ### Capabilities
+ - **MCP Operations**: Leverage the `mcp-client` skill to interact with the target MCP server.
+ - **Custom Agent**: Handle custom tasks or general tasks.

freshrss_agent/agent_server.py

@@ -0,0 +1,73 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.1.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    initialize_workspace()
+    meta = load_identity()
+    agent_name = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "FreshRSS"))
+
+    print(f"{agent_name} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        agent_description=os.getenv(
+            "AGENT_DESCRIPTION",
+            meta.get("description", "FreshRSS API + MCP Server + A2A Server"),
+        ),
+        system_prompt=os.getenv(
+            "AGENT_SYSTEM_PROMPT",
+            meta.get("content") or build_system_prompt_from_workspace(),
+        ),
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

freshrss_agent/api/__init__.py

@@ -0,0 +1,19 @@
+from .api_client_base import FreshRSSClientBase
+from .api_client_reader import ReaderMixin
+from .api_client_subscriptions import SubscriptionsMixin
+
+
+class FreshRSSApi(ReaderMixin, SubscriptionsMixin, FreshRSSClientBase):
+    """FreshRSS GReader API client (reader + subscriptions)."""
+
+
+# Backward-compat alias for the scaffold (auth.py imports ApiClientSystem).
+ApiClientSystem = FreshRSSApi
+
+__all__ = [
+    "FreshRSSApi",
+    "FreshRSSClientBase",
+    "ReaderMixin",
+    "SubscriptionsMixin",
+    "ApiClientSystem",
+]

freshrss_agent/api/api_client_base.py

@@ -0,0 +1,137 @@
+#!/usr/bin/python
+"""GReader (Google Reader compatible) HTTP base client for FreshRSS."""
+
+import logging
+from typing import Any
+
+import requests
+import urllib3
+from agent_utilities.base_utilities import get_logger
+from agent_utilities.core.exceptions import AuthError, UnauthorizedError
+
+logger = get_logger(__name__)
+
+
+class FreshRSSClientBase:
+    """Base client for the FreshRSS Google Reader compatible API (GReader).
+
+    Implements the GReader auth flow:
+      1. ``ClientLogin`` exchanges ``Email``/``Passwd`` for an ``Auth`` token.
+      2. Authenticated requests send ``Authorization: GoogleLogin auth=<token>``.
+      3. Write actions require a short-lived POST token (``T`` form field) fetched
+         from the ``token`` endpoint.
+      4. On HTTP 401 the client re-runs ClientLogin once and retries.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None,
+        username: str | None,
+        api_password: str | None,
+        verify: bool = True,
+    ):
+        self.base_url = (base_url or "").rstrip("/")
+        self.username = username or ""
+        self.api_password = api_password or ""
+        self.verify = verify
+        self.session = requests.Session()
+        self._auth_token: str | None = None
+
+        if self.verify is False:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    # -- internals -----------------------------------------------------------
+
+    def _greader_url(self, path: str) -> str:
+        return f"{self.base_url}/api/greader.php/{path.lstrip('/')}"
+
+    def _login(self) -> str:
+        """Run ClientLogin and cache the ``Auth`` token."""
+        url = self._greader_url("accounts/ClientLogin")
+        response = self.session.post(
+            url,
+            data={"Email": self.username, "Passwd": self.api_password},
+            verify=self.verify,
+            timeout=30,
+        )
+        if response.status_code in (401, 403):
+            logger.error("FreshRSS ClientLogin failed: %s", response.status_code)
+            raise AuthError if response.status_code == 401 else UnauthorizedError
+        response.raise_for_status()
+        token: str | None = None
+        for line in response.text.splitlines():
+            if line.startswith("Auth="):
+                token = line[len("Auth=") :].strip()
+                break
+        if not token:
+            raise AuthError
+        self._auth_token = token
+        return token
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self._auth_token:
+            self._login()
+        return {"Authorization": f"GoogleLogin auth={self._auth_token}"}
+
+    def _get_write_token(self) -> str:
+        """Fetch a short-lived POST token required by write actions."""
+        response = self.session.get(
+            self._greader_url("reader/api/0/token"),
+            headers=self._auth_headers(),
+            verify=self.verify,
+            timeout=30,
+        )
+        if response.status_code == 401:
+            self._login()
+            response = self.session.get(
+                self._greader_url("reader/api/0/token"),
+                headers=self._auth_headers(),
+                verify=self.verify,
+                timeout=30,
+            )
+        response.raise_for_status()
+        return response.text.strip()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        data: Any | None = None,
+    ) -> Any:
+        """Issue an authenticated GReader request, retrying once on 401.
+
+        ``output=json`` is always injected so JSON responses are returned. The
+        JSON body is decoded when possible; otherwise the raw text is returned.
+        """
+        params = dict(params or {})
+        params.setdefault("output", "json")
+        url = self._greader_url(path)
+
+        def _send() -> requests.Response:
+            return self.session.request(
+                method,
+                url,
+                params=params,
+                data=data,
+                headers=self._auth_headers(),
+                verify=self.verify,
+                timeout=60,
+            )
+
+        response = _send()
+        if response.status_code == 401:
+            # Token expired — re-login once and retry.
+            self._auth_token = None
+            response = _send()
+        if response.status_code == 401:
+            logger.error("FreshRSS request unauthorized after re-login: %s", url)
+            raise AuthError
+        response.raise_for_status()
+        try:
+            return response.json()
+        except ValueError:
+            return {"status": response.status_code, "text": response.text}
+
+    def set_debug(self, debug: bool = False) -> None:
+        logger.setLevel(logging.DEBUG if debug else logging.ERROR)

freshrss_agent/api/api_client_reader.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python
+"""Reader operations for the FreshRSS GReader API (stream contents, item bodies)."""
+
+from typing import Any
+
+
+class ReaderMixin:
+    """Read-side GReader operations: stream contents, item bodies, unread counts."""
+
+    request: Any
+
+    def stream_contents(
+        self,
+        stream_id: str = "user/-/state/com.google/reading-list",
+        count: int = 100,
+        order: str = "o",
+        newer_than: int | None = None,
+        continuation: str | None = None,
+    ) -> dict[str, Any]:
+        """Fetch items for a stream.
+
+        ``stream_id`` is a GReader stream id (e.g.
+        ``user/-/state/com.google/reading-list`` for all items, ``feed/<feedUrl>``
+        for one feed, or ``user/-/label/<category>``). ``order`` is ``o`` (oldest
+        first) or ``n`` (newest first). ``newer_than`` is a unix-seconds watermark
+        mapped to the GReader ``ot`` parameter (exclude items older than this).
+        ``continuation`` resumes a previous page. Returns the raw
+        ``{"items": [...], "continuation": "..."}`` payload.
+        """
+        params: dict[str, Any] = {"n": count, "r": order}
+        if newer_than is not None:
+            params["ot"] = int(newer_than)
+        if continuation:
+            params["c"] = continuation
+        result = self.request(
+            "GET",
+            f"reader/api/0/stream/contents/{stream_id}",
+            params=params,
+        )
+        # Normalize each item to flat, transport-safe top-level fields so a KG
+        # connector reads ``text`` directly (a nested ``summary.content`` field-map
+        # does not survive the MCP structured-output round-trip reliably). The raw
+        # GReader fields (origin/categories/canonical) are preserved alongside.
+        if isinstance(result, dict) and isinstance(result.get("items"), list):
+            for item in result["items"]:
+                if not isinstance(item, dict):
+                    continue
+                body = (item.get("summary") or {}).get("content") or (
+                    item.get("content") or {}
+                ).get("content") or ""
+                item["text"] = body
+                canonical = item.get("canonical") or []
+                if isinstance(canonical, list) and canonical:
+                    item["url"] = canonical[0].get("href", "")
+        return result
+
+    def item_contents(self, item_ids: list[str] | str) -> dict[str, Any]:
+        """Fetch full contents for specific item ids (GReader ``i`` parameters)."""
+        if isinstance(item_ids, str):
+            item_ids = [item_ids]
+        data = [("i", item_id) for item_id in item_ids]
+        return self.request(
+            "POST",
+            "reader/api/0/stream/items/contents",
+            data=data,
+        )
+
+    def unread_count(self) -> dict[str, Any]:
+        """Return unread counts per stream."""
+        return self.request("GET", "reader/api/0/unread-count")

freshrss_agent/api/api_client_subscriptions.py

@@ -0,0 +1,78 @@
+#!/usr/bin/python
+"""Subscription, category and tagging operations for the FreshRSS GReader API."""
+
+from typing import Any
+
+
+class SubscriptionsMixin:
+    """Manage feeds, categories and item tags (read/star) via the GReader API."""
+
+    request: Any
+    _get_write_token: Any
+
+    def subscription_list(self) -> dict[str, Any]:
+        """List all feed subscriptions."""
+        return self.request("GET", "reader/api/0/subscription/list")
+
+    def categories(self) -> dict[str, Any]:
+        """List categories / tags (``tag/list``)."""
+        return self.request("GET", "reader/api/0/tag/list")
+
+    def _stream_for_feed(self, feed_url: str) -> str:
+        return feed_url if feed_url.startswith("feed/") else f"feed/{feed_url}"
+
+    def subscribe(
+        self,
+        feed_url: str,
+        title: str | None = None,
+        category: str | None = None,
+    ) -> dict[str, Any]:
+        """Subscribe to a feed, optionally setting its title and category."""
+        data: list[tuple[str, str]] = [
+            ("ac", "subscribe"),
+            ("s", self._stream_for_feed(feed_url)),
+            ("T", self._get_write_token()),
+        ]
+        if title:
+            data.append(("t", title))
+        if category:
+            data.append(("a", f"user/-/label/{category}"))
+        return self.request("POST", "reader/api/0/subscription/edit", data=data)
+
+    def unsubscribe(self, feed_url: str) -> dict[str, Any]:
+        """Unsubscribe from a feed."""
+        data = [
+            ("ac", "unsubscribe"),
+            ("s", self._stream_for_feed(feed_url)),
+            ("T", self._get_write_token()),
+        ]
+        return self.request("POST", "reader/api/0/subscription/edit", data=data)
+
+    def label(self, feed_url: str, category: str) -> dict[str, Any]:
+        """Add a category label to an existing feed subscription."""
+        data = [
+            ("ac", "edit"),
+            ("s", self._stream_for_feed(feed_url)),
+            ("a", f"user/-/label/{category}"),
+            ("T", self._get_write_token()),
+        ]
+        return self.request("POST", "reader/api/0/subscription/edit", data=data)
+
+    def mark_read(self, item_ids: list[str] | str) -> dict[str, Any]:
+        """Mark one or more items as read."""
+        if isinstance(item_ids, str):
+            item_ids = [item_ids]
+        data: list[tuple[str, str]] = [("T", self._get_write_token())]
+        data.append(("a", "user/-/state/com.google/read"))
+        data.extend(("i", item_id) for item_id in item_ids)
+        return self.request("POST", "reader/api/0/edit-tag", data=data)
+
+    def star(self, item_id: str, starred: bool = True) -> dict[str, Any]:
+        """Star or unstar an item."""
+        key = "a" if starred else "r"
+        data = [
+            ("T", self._get_write_token()),
+            (key, "user/-/state/com.google/starred"),
+            ("i", item_id),
+        ]
+        return self.request("POST", "reader/api/0/edit-tag", data=data)

freshrss_agent/api_client.py

@@ -0,0 +1,7 @@
+#!/usr/bin/python
+"""Facade re-export of the modular api/ sub-package (backward compatibility)."""
+
+from .api import *  # noqa: F401,F403
+from .api import __all__ as _api_all
+
+__all__ = list(_api_all)

freshrss_agent/auth.py

@@ -0,0 +1,100 @@
+#!/usr/bin/python
+
+"""Authentication.
+
+Priority:
+1. **OIDC Delegation** (RFC 8693 Token Exchange) — when ``ENABLE_DELEGATION`` is
+   active, exchanges the IdP-issued user token for a downstream access token via the
+   shared ``agent_utilities.mcp.delegated_auth`` helper.
+2. **Fixed credentials** — falls back to the ``FRESHRSS_API_PASSWORD`` env var.
+
+For a multi-tenant service, add an ``instances.py`` that resolves a configured
+instance NAME (from ``<service>_instances`` in ``~/.config/agent-utilities/config.json``)
+to ``(url, token, verify)`` and call it here before the delegation/fixed paths — see
+``gitlab_api.instances`` (CONCEPT:KG-2.9g) for the golden pattern.
+"""
+
+import os
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+from agent_utilities.core.exceptions import AuthError, UnauthorizedError
+
+from .api import ApiClientSystem
+
+logger = get_logger(__name__)
+_client = None
+
+
+def get_client(
+    url: str | None = None,
+    token: str | None = None,
+    verify: bool | None = None,
+    config: dict | None = None,
+) -> ApiClientSystem:
+    """Get or create a singleton API client (OIDC delegation or fixed credentials)."""
+    global _client
+    if _client is not None:
+        return _client
+
+    base_url = url or os.getenv("FRESHRSS_URL", "http://localhost:8080")
+    api_password = token or os.getenv("FRESHRSS_API_PASSWORD", "")
+    username = os.getenv("FRESHRSS_USER", "")
+    if verify is None:
+        verify = to_boolean(string=os.getenv("FRESHRSS_SSL_VERIFY", "True"))
+
+    from agent_utilities.mcp.delegated_auth import (
+        get_delegated_token,
+        get_user_identity,
+        is_delegation_enabled,
+    )
+
+    # --- Path 1: OIDC Delegation (RFC 8693 Token Exchange) ---
+    if is_delegation_enabled(config):
+        try:
+            delegated_token = get_delegated_token(
+                config=config,
+                audience=(config or {}).get("audience", base_url),
+                scopes=(config or {}).get("delegated_scopes", "api"),
+                verify=verify,
+            )
+            identity = get_user_identity()
+            logger.info(
+                "Using OIDC delegated token",
+                extra={"user_email": identity.get("email"), "url": base_url},
+            )
+            _client = ApiClientSystem(
+                base_url=base_url,
+                username=username,
+                api_password=delegated_token,
+                verify=verify,
+            )
+            return _client
+        except Exception as e:
+            logger.error(
+                "OIDC delegation failed",
+                extra={"error_type": type(e).__name__, "error_message": str(e)},
+            )
+            raise RuntimeError(f"Token exchange failed: {str(e)}") from e
+
+    # --- Path 2: Fixed Credentials (FRESHRSS_API_PASSWORD) ---
+    logger.info("Using fixed credentials")
+    try:
+        _client = ApiClientSystem(
+            base_url=base_url,
+            username=username,
+            api_password=api_password,
+            verify=verify,
+        )
+    except (AuthError, UnauthorizedError) as e:
+        raise RuntimeError(
+            f"AUTHENTICATION ERROR: The credentials provided are not valid for '{base_url}'. "
+            f"Please check your FRESHRSS_API_PASSWORD and FRESHRSS_URL environment variables. "
+            f"Error details: {str(e)}"
+        ) from e
+    except Exception as e:
+        raise RuntimeError(
+            f"AUTHENTICATION ERROR: Failed to instantiate client. "
+            f"Error details: {str(e)}"
+        ) from e
+
+    return _client

freshrss_agent/freshrss_input_models.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python
+"""Pydantic input models for FreshRSS GReader API request parameters."""
+
+from pydantic import BaseModel, Field
+
+
+class StreamContentsParams(BaseModel):
+    """Parameters for fetching stream contents."""
+
+    stream_id: str = Field(
+        default="user/-/state/com.google/reading-list",
+        description="GReader stream id (reading-list, feed/<url>, user/-/label/<cat>).",
+    )
+    count: int = Field(
+        default=100, description="Maximum number of items (GReader 'n')."
+    )
+    order: str = Field(
+        default="o", description="'o' oldest-first or 'n' newest-first (GReader 'r')."
+    )
+    newer_than: int | None = Field(
+        default=None,
+        description="Unix-seconds watermark; exclude items older than this (GReader 'ot').",
+    )
+    continuation: str | None = Field(
+        default=None, description="Continuation token for pagination (GReader 'c')."
+    )
+
+
+class ItemContentsParams(BaseModel):
+    """Parameters for fetching specific item bodies."""
+
+    item_ids: list[str] | str = Field(
+        description="One or more GReader long-form item ids."
+    )
+
+
+class SubscribeParams(BaseModel):
+    """Parameters for subscribing to a feed."""
+
+    feed_url: str = Field(description="Feed URL (or 'feed/<url>' stream id).")
+    title: str | None = Field(default=None, description="Optional feed title.")
+    category: str | None = Field(
+        default=None, description="Optional category label to assign."
+    )
+
+
+class UnsubscribeParams(BaseModel):
+    """Parameters for unsubscribing from a feed."""
+
+    feed_url: str = Field(description="Feed URL (or 'feed/<url>' stream id).")
+
+
+class LabelParams(BaseModel):
+    """Parameters for adding a category label to a feed."""
+
+    feed_url: str = Field(description="Feed URL (or 'feed/<url>' stream id).")
+    category: str = Field(description="Category label to add.")
+
+
+class MarkReadParams(BaseModel):
+    """Parameters for marking items as read."""
+
+    item_ids: list[str] | str = Field(description="One or more item ids.")
+
+
+class StarParams(BaseModel):
+    """Parameters for starring/unstarring an item."""
+
+    item_id: str = Field(description="The item id to star or unstar.")
+    starred: bool = Field(default=True, description="True to star, False to unstar.")