mastodon-scout

# Mastodon Scout ## Purpose Read-only Mastodon CLI that fetches data from the Mastodon API. Returns human-readable summaries by default, or raw JSON with `--json` flag. --- ## Invocation Rules (MANDATORY) ### Binary Selection - **macOS / Darwin** → `dist/mastodon-scout` - **Linux** → `dist/mastodon-scout-linux` ### Commands #### Home Timeline ``` {baseDir}/bin/mastodon-scout home ``` Fetches the authenticated user's home timeline. #### User Tweets ``` {baseDir}/bin/mastodon-scout user-tweets ``` Fetches the authenticated user's own posts. #### Mentions ``` {baseDir}/bin/mastodon-scout mentions ``` Fetches mentions of the authenticated user. #### Search ``` {baseDir}/bin/mastodon-scout search <query> ``` Searches for posts matching the query. ### Flags (Optional) ``` --instance <url> # Mastodon instance URL (default: https://mastodon.social) --limit <int> # Number of items to return (default: 20) --timeout <int> # Timeout in seconds (default: 30) --json # Output raw JSON instead of human-readable text ``` ### Environment Variables (REQUIRED) ``` MASTODON_TOKEN # OAuth bearer token for authentication ``` --- ## Output Modes ### Text Mode (Default) ```bash mastodon-scout home ``` Returns human-readable summary of timeline data. The agent MAY summarize and explain the timeline results to make them more accessible to the user. ### JSON Mode ```bash mastodon-scout --json home ``` Returns raw JSON data from the Mastodon API. When JSON mode is used, return the output verbatim without interpretation. --- ## Error Handling - If the binary exits non-zero: - In JSON mode: return error output verbatim - In text mode: the agent MAY explain the error to the user - Do not retry - If MASTODON_TOKEN is not set: - The binary will exit with an error message - Agent should guide the user to the authentication setup section --- ## Examples That Trigger This Skill - `mastodon-scout home` - `show my mastodon timeline` - `check mastodon mentions` - `search mastodon for "golang"` - `get my mastodon posts` --- ## Performance Requirements - Execute binary directly - No web searches - No secondary tools beyond the binary - Minimize latency --- ## Notes - In text mode: agent MAY summarize and explain results - In JSON mode: output verbatim, no interpretation - This skill is **read-only** (no posting, following, or other mutations) --- ## 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. The tool requires a Mastodon OAuth bearer token set in the `MASTODON_TOKEN` environment variable. ### How to Obtain a Token (Guide the User): **Step 1: Access Development Settings** - User should log into their Mastodon instance (e.g., mastodon.social, fosstodon.org) - Navigate to: **Settings → Development** (or Preferences → Development) - Direct URL format: `https://[instance-domain]/settings/applications` **Step 2: Create Application** - Click "New Application" - Fill in details: - **Application name**: `mastodon-scout` (or any name) - **Application website**: Can leave blank or use any URL - **Redirect URI**: `urn:ietf:wg:oauth:2.0:oob` (for CLI apps) - **Scopes**: **CRITICAL - Only select `read`** (uncheck write, follow, push) **Step 3: Get Access Token** - Click "Submit" - Click on the created application to view details - Copy the **"Your access token"** field value **Step 4: Set Environment Variable** ```bash export MASTODON_TOKEN="paste_token_here" ``` **Step 5: Verify Token Works** ```bash ./dist/mastodon-scout home ``` ### Common Mastodon Instances: - `mastodon.social` - General purpose (default) - `fosstodon.org` - FOSS/tech community - `mas.to` - Tech focused - `hachyderm.io` - Tech/infosec community Use `--instance https://your-instance.com` flag for non-default instances. ### Security Notes to Communicate: - 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 --- ## Output Format ### Text Mode (Default) Human-readable summary of posts, formatted for readability. The agent decides how to present the information. ### JSON Mode (`--json` flag) All commands return JSON in the following format: ```json { "success": true, "data": [ /* Mastodon API response */ ] } ``` Or on error: ```json { "success": false, "error": "error message" } ``` The `data` field contains the raw Mastodon API response without any modifications.