Usage Guide
Comprehensive guide to using the ActivityPub MCP Server effectively. Learn advanced workflows, best practices, and power-user techniques for exploring the fediverse.
🎯 Understanding the Fediverse
Decentralized Network
The fediverse consists of thousands of independent servers (instances) that communicate using open protocols like ActivityPub.
Actors and Objects
Users are "actors" who create and share "objects" (posts, images, etc.) across the network using standardized formats.
Federation
Instances can federate (connect) with each other, allowing users to follow and interact across different servers.
🔧 Tool Categories
🔍 Discovery Tools
discover-actor- Find and analyze fediverse usersdiscover-instances- Search for instances by topicsearch-content- Find posts and content
Use for: Finding new communities, researching topics, identifying key actors
📊 Information Tools
get-instance-info- Instance metadata and statisticsfetch-timeline- Actor's recent postsget-post-details- Detailed post information
Use for: Understanding communities, analyzing content, tracking activity
🔧 Utility Tools
health-check- Server status and performanceclear-cache- Reset cached datavalidate-actor- Check actor accessibility
Use for: Troubleshooting, maintenance, optimization
📈 Advanced Workflows
Community Research Workflow
- Topic Discovery: Use
discover-instancesto find relevant communities - Instance Analysis: Use
get-instance-infoto understand each community - Key Actor Identification: Use
discover-actorto find influential users - Content Analysis: Use
fetch-timelineto analyze recent discussions - Trend Identification: Look for common themes and popular topics
Example Query:
"Research the open source software community in the fediverse. Find the most active instances, identify key contributors, and summarize current discussions."
Content Monitoring Workflow
- Actor Selection: Identify actors to monitor
- Baseline Establishment: Get current activity levels
- Regular Monitoring: Check timelines periodically
- Change Detection: Identify significant changes or trends
- Analysis and Reporting: Summarize findings
Example Query:
"Monitor @mozilla@mozilla.social for new product announcements and summarize any significant updates from the past week."
Network Analysis Workflow
- Seed Selection: Choose starting actors or instances
- Connection Mapping: Discover followers and following relationships
- Influence Analysis: Identify highly connected actors
- Community Detection: Find clusters and subgroups
- Visualization: Create network maps and diagrams
Example Query:
"Map the network of climate science researchers in the fediverse. Show how they're connected and identify the most influential voices."
💡 Best Practices
🎯 Efficient Discovery
- Start Broad, Then Narrow: Begin with general searches, then focus on specific actors or instances
- Use Multiple Formats: Try different actor identifier formats (@user@domain, URLs)
- Cross-Reference: Verify information across multiple sources
- Cache Awareness: Understand that data may be cached for performance
⚡ Performance Optimization
- Batch Requests: Group related queries together
- Limit Results: Use appropriate limits for large datasets
- Monitor Rate Limits: Respect instance rate limiting
- Clear Cache Strategically: Only clear cache when fresh data is needed
🔒 Privacy and Ethics
- Respect Privacy: Only access public information
- Follow Instance Rules: Respect each instance's terms of service
- Be Mindful of Load: Don't overwhelm small instances
- Attribute Sources: Credit instances and actors when sharing findings
📊 Data Quality
- Verify Timestamps: Check when data was last updated
- Handle Errors Gracefully: Account for unavailable instances or actors
- Cross-Validate: Confirm important findings through multiple sources
- Document Methodology: Keep track of your research process
🔍 Advanced Query Techniques
Chained Discovery
Use results from one tool as input for another:
# 1. Find instances
discover-instances "journalism"
# 2. Get details for each
get-instance-info journa.host
# 3. Find key actors
discover-actor @admin@journa.host
# 4. Analyze their content
fetch-timeline https://journa.host/users/adminComparative Analysis
Compare multiple instances or actors side by side:
"Compare the posting frequency, engagement levels, and topic focus between @user1@instance1.com and @user2@instance2.com"
Temporal Analysis
Track changes over time:
"Track how the discussion about renewable energy has evolved on climate-focused instances over the past month"
Cross-Instance Research
Research topics across multiple instances:
"Find all instances discussing artificial intelligence and compare their perspectives and community attitudes"
🚨 Common Pitfalls
❌ Over-Reliance on Single Sources
Problem: Drawing conclusions from one instance or actor
Solution: Always cross-reference with multiple sources
❌ Ignoring Instance Differences
Problem: Treating all instances as equivalent
Solution: Understand each instance's culture, rules, and focus
❌ Cache Confusion
Problem: Not understanding when data is cached vs. fresh
Solution: Check timestamps and clear cache when needed
❌ Rate Limit Violations
Problem: Making too many requests too quickly
Solution: Pace requests and respect instance limits
📚 Learning Resources
ActivityPub Specification
Official W3C specification for the ActivityPub protocol
Read Specification