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)

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

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

export MASTODON_TOKEN="paste_token_here"

Step 5: Verify

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