Skip to content

README.md

Latest commit

 

History

History
231 lines (178 loc) · 6.83 KB

README.md

File metadata and controls

231 lines (178 loc) · 6.83 KB

Reddit API Integration

Reddit platform integration module with OAuth2 authentication and complete Reddit API access functionality.

🔧 Authentication Setup

1. Get Reddit API Credentials

  1. Visit Reddit Apps
  2. Click "Create App" or "Create Another App"
  3. Fill in application information:
    • Name: Application name (e.g., PersonalizationMCP)
    • App type: Select "web app"
    • Description: Application description (optional)
    • About URL: About page URL (optional)
    • Redirect URI: http://localhost:8888/callback
  4. After creation, record the following information:
    • Client ID: Application ID (below the app name)
    • Client Secret: Client secret key

2. Configure Authentication

Add Reddit configuration to the config file in the project root directory:

# Reddit API Configuration
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here
REDDIT_REDIRECT_URI=http://localhost:8888/callback

3. OAuth2 Authentication Flow

Method 1: Using MCP Functions for Authentication

# 1. Setup OAuth2 authentication
setup_result = mcp_personalhub_setup_reddit_oauth(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# 2. Visit the returned authentication URL for authorization
# User needs to visit the auth URL in browser and authorize

# 3. Complete authentication (after getting authorization code)
complete_result = mcp_personalhub_complete_reddit_oauth(
    client_id="your_client_id",
    client_secret="your_client_secret",
    authorization_code="authorization_code_from_callback"
)

Method 2: Manual Configuration

If you already have valid access tokens, you can configure directly:

REDDIT_ACCESS_TOKEN=your_access_token
REDDIT_REFRESH_TOKEN=your_refresh_token

🚀 Features

📊 Account Information

  • User Overview: Get mixed timeline of posts and comments
  • Karma Breakdown: View karma distribution across subreddits
  • User Preferences: Get account settings and preferences
  • Trophies & Achievements: View Reddit trophies and achievements

📝 Content Management

  • Submitted Posts: Get all user-submitted posts
  • Comment History: View user's comment records
  • Saved Content: Get saved posts and comments
  • Hidden Posts: View hidden content
  • Voting Records: Get upvoted/downvoted content

👥 Community Interaction

  • Subscribed Subreddits: View followed communities
  • Moderated Communities: Get subreddits where user is moderator
  • Contributor Permissions: View subreddits with contributor access

💬 Messaging System

  • Inbox: Get all messages
  • Unread Messages: View unread messages
  • Sent Messages: View sent message history

🛠️ API Function List

Authentication Management

# Configuration status check
get_reddit_config()
test_reddit_credentials()

# OAuth2 authentication flow
setup_reddit_oauth(client_id, client_secret, redirect_uri?)
complete_reddit_oauth(client_id, client_secret, authorization_code, redirect_uri?)

# Token management
get_reddit_token_status()
refresh_reddit_token()
auto_refresh_reddit_token_if_needed()

User Information

# Basic information
get_user_subreddits(access_token?, limit=100)
get_user_trophies(access_token?)
get_user_preferences(access_token?)
get_user_karma_breakdown(access_token?)

# Community permissions
get_moderated_subreddits(access_token?, limit=100)
get_contributor_subreddits(access_token?, limit=100)

Content Retrieval

# Posts and comments
get_user_submitted_posts(username?, access_token?, limit=100, sort="new")
get_user_comments(username?, access_token?, limit=100, sort="new")
get_user_overview(username?, access_token?, limit=100, sort="new")

# Saved and interactions
get_saved_content(username?, access_token?, limit=100)
get_hidden_posts(username?, access_token?, limit=100)
get_upvoted_content(username?, access_token?, limit=100)
get_downvoted_content(username?, access_token?, limit=100)

Messaging System

# Message management (requires privatemessages scope)
get_inbox_messages(access_token?, limit=100)
get_unread_messages(access_token?, limit=100)
get_sent_messages(access_token?, limit=100)

📋 Usage Examples

Get User Activity Overview

# Get recent posts and comments
overview = get_user_overview(limit=20, sort="new")

# Get subscribed communities
subreddits = get_user_subreddits(limit=50)

# Get karma distribution
karma = get_user_karma_breakdown()

View Content History

# Get submitted posts
posts = get_user_submitted_posts(limit=10, sort="top")

# Get comment history
comments = get_user_comments(limit=10, sort="new")

# Get saved content
saved = get_saved_content(limit=20)

Check Messages

# Get inbox messages
inbox = get_inbox_messages(limit=10)

# Get unread messages
unread = get_unread_messages(limit=5)

🔒 Permission Scopes

Reddit API uses the following OAuth2 permission scopes:

  • identity: Access user basic information
  • read: Read user content and subscriptions
  • history: Access voting and hidden content history
  • privatemessages: Access private messages (optional, requires special permission)

⚠️ Important Notes

API Limitations

  • Request Rate: Reddit API has strict rate limiting
  • Permission Requirements: Some features require specific OAuth permissions
  • Data Access: Can only access data for the currently authenticated user

Privacy Settings

  • User privacy settings may affect data retrieval
  • Some content may be inaccessible due to user settings
  • Private messaging functionality requires additional permission requests

Token Management

  • Access tokens are valid for 1 hour
  • Refresh tokens can be used to automatically update access tokens
  • Recommended to use auto_refresh_reddit_token_if_needed() for automatic token management

🔍 Troubleshooting

Common Issues

  1. 403 Forbidden Error

    • Check OAuth permission scopes
    • Verify token validity
    • Confirm user privacy settings

  2. Authentication Failure

    • Ensure Client ID and Secret are correct
    • Check redirect URI matches
    • Verify authorization code hasn't expired

  3. Empty Data Returns

    • May be due to user privacy setting restrictions
    • Check query parameters (username, limits, etc.)
    • Confirm user has relevant content

Debugging Tips

  • Use get_reddit_config() to check configuration status
  • Use test_reddit_credentials() to verify credentials
  • Check get_reddit_token_status() to understand token status

📚 Related Resources
⚡