mrrss-assistant

# MrRSS Assistant ## Overview Use the MrRSS HTTP API as the source of truth for user data. Prefer read-only inspection first, ask before destructive operations, and keep outputs concise enough for a user to act on. ## Connection Workflow 1. Determine the base URL. Default to `http://localhost:1234` for server mode unless the user provides another host or port. Desktop development builds may use a different local port; ask the user or inspect their running command if the API is unreachable. 2. Set the API root to `{base_url}/api`. 3. Verify connectivity with `GET {api_root}/version`, then `GET {api_root}/feeds`. 4. If both fail, explain that MrRSS or `mrrss-server` must be running and stop before attempting data operations. 5. Use `references/api.md` for supported endpoints and request shapes. If the repo is available and API details may have changed, regenerate it with `scripts/generate_api_reference.py`. ## Safety - Treat `GET` requests as safe. - Ask for explicit confirmation before deleting feeds, clearing caches, resetting statistics, clearing summaries/translations, or bulk-marking articles. - For settings changes, first read `GET /settings`, show the exact keys that will change, then submit only after confirmation. - Never expose API keys, passwords, custom headers, IMAP credentials, or FreshRSS credentials in final answers. Redact sensitive settings when reporting configuration. - Avoid direct SQLite access unless the API is unavailable and the user explicitly asks for offline inspection. ## Common Tasks ### Inspect Feeds Use `GET /feeds` to list feeds. Report feed titles, categories, unread counts, last error fields when present, and stale feeds. For health checks, follow with targeted refresh only after user approval if many feeds are involved. ### Find Articles Use `GET /articles` with `filter`, `feed_id`, `category`, `page`, and `limit`. For user-facing summaries, fetch only the pages required and cite article titles, feeds, and dates. Use `GET /articles/content?id={id}` when the list response lacks enough text. ### Summarize Or Translate Prefer MrRSS endpoints so user settings and cached results are respected: - `POST /summarize` for article summaries. - `POST /translate/text` for ad hoc text translation. - `POST /translate/article` for article translation. If an AI endpoint fails, check `GET /ai/test/info` and available profiles before asking the user to reconfigure credentials. ### Manage Article State Use the dedicated article endpoints for read, favorite, hidden, and read-later state. Confirm before bulk operations such as mark-all-read or clearing read-later. ### Analyze Reading Activity Use `GET /api/statistics`, `/api/statistics/all-time`, and `/api/statistics/available-months`. Present trends as plain language, not only raw counts. ## API Reference Read `references/api.md` when you need endpoint details. It is generated from `docs/SERVER_MODE/swagger.json` in the MrRSS repository. To regenerate: ```bash python skills/mrrss-assistant/scripts/generate_api_reference.py docs/SERVER_MODE/swagger.json skills/mrrss-assistant/references/api.md ```