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 → {baseDir}/bin/mastodon-scout
• Linux → {baseDir}/bin/mastodon-scout

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)

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

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

export MASTODON_TOKEN="paste_token_here"

Step 5: Verify Token Works

{baseDir}/bin/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:

{
  "success": true,
  "data": [ /* Mastodon API response */ ]
}

Or on error:

{
  "success": false,
  "error": "error message"
}

The data field contains the raw Mastodon API response without any modifications.