mastodon-scout

# Mastodon Scout ## Purpose Read-only Mastodon skill. Fetches data from the Mastodon API via a bundled Python script (`scripts/mastodon_scout.py`). Returns human-readable summaries by default, or raw JSON with `--json`. --- ## Invocation Rules (MANDATORY) ```bash python3 ./scripts/mastodon_scout.py <command> [options] ``` ### Commands | Command | What it fetches | |---------|----------------| | `home` | Authenticated user's home timeline | | `user-tweets` | Authenticated user's own posts | | `mentions` | Mentions of the authenticated user | | `search <query>` | Posts matching the query | ### Options ``` --instance <url> Mastodon instance base URL (default: $MASTODON_INSTANCE or https://mastodon.social) --limit <int> Number of items to return (default: $LIMIT or 20) --json Output raw JSON instead of human-readable text ``` ### Environment Variables ``` MASTODON_TOKEN Required. OAuth bearer token. MASTODON_INSTANCE Optional. Instance base URL (default: https://mastodon.social). ``` ### Examples ```bash python3 ./scripts/mastodon_scout.py home python3 ./scripts/mastodon_scout.py mentions --limit 10 python3 ./scripts/mastodon_scout.py search "golang" python3 ./scripts/mastodon_scout.py home --json python3 ./scripts/mastodon_scout.py home --instance https://fosstodon.org ``` --- ## Output Modes ### Text Mode (Default) The script formats each post as: ``` [N] Display Name (@user@instance) · <timestamp> <content> ↩ <replies> 🔁 <reblogs> ⭐ <favourites> <url> ``` The agent MAY add a brief summary after the list. ### JSON Mode (`--json`) Returns raw Mastodon API JSON. Return it verbatim — no interpretation. --- ## Error Handling The script prints a human-readable error to stderr and exits non-zero: | Condition | Message | |-----------|---------| | Token missing | `Error: MASTODON_TOKEN is not set` | | 401 | `Mastodon API error: 401 Unauthorized — check MASTODON_TOKEN` | | 403 | `Mastodon API error: 403 Forbidden` | | 422 | `Mastodon API error: 422 Unprocessable Entity` | | 429 | `Mastodon API error: 429 Rate Limited — try again later` | Do not retry on error. Guide the user to Authentication Setup if the token is missing or invalid. --- ## Examples That Trigger This Skill - `mastodon-scout home` - `show my mastodon timeline` - `check mastodon mentions` - `search mastodon for "golang"` - `get my mastodon posts` --- ## Notes - This skill is **read-only** (no posting, following, or other mutations) - `scripts/mastodon_scout.py` uses stdlib only — no pip install required - In JSON mode: output verbatim, no interpretation --- ## Authentication Setup (Agent MAY Help) **EXCEPTION TO STRICT MODE**: If the user needs help obtaining a token, the agent **may** provide guidance before executing the skill. ### How to Obtain a Token: **Step 1: Access Development Settings** - Log into your Mastodon instance (e.g., mastodon.social, fosstodon.org) - Navigate to: **Settings → Development** (or Preferences → Development) - Direct URL: `https://[instance-domain]/settings/applications` **Step 2: Create Application** - Click "New Application" - **Application name**: `mastodon-scout` (or any name) - **Redirect URI**: `urn:ietf:wg:oauth:2.0:oob` - **Scopes**: **CRITICAL — only select `read`** (uncheck write, follow, push) **Step 3: Get Access Token** - Click Submit, then open the created application - Copy the **"Your access token"** value **Step 4: Set Environment Variable** ```bash export MASTODON_TOKEN="paste_token_here" ``` **Step 5: Verify** ```bash python3 ./scripts/mastodon_scout.py home --limit 5 ``` ### Common Mastodon Instances: - `mastodon.social` — General purpose (default) - `fosstodon.org` — FOSS/tech community - `mas.to` — Tech focused - `hachyderm.io` — Tech/infosec community ### Security Notes: - Token is **read-only** (cannot post, follow, or delete) - Keep token secret (don't commit to git) - Can be revoked anytime in Development settings - Each Mastodon instance requires its own token