This server follows the layered abstraction pattern for scalability and self-documentation:

Layer 1: Discovery

discover_operations()

Purpose: See what operations are available and get workflow recommendations.

Returns: List of all operations (Reddit research + feed management) with descriptions and recommended workflows.

Layer 2: Schema Inspection

get_operation_schema("discover_subreddits", include_examples=True)

Purpose: Understand parameter requirements, validation rules, and see examples before executing.

Returns: Complete schema with parameter types, descriptions, ranges, and usage examples.

Layer 3: Execution

execute_operation("discover_subreddits", {
    "query": "machine learning",
    "limit": 15,
    "min_confidence": 0.6
})

Purpose: Perform the actual operation with validated parameters.

Returns: Operation results wrapped in {"success": bool, "data": ...} format.

Why This Pattern?

• Self-documenting: Operations describe their own requirements
• Version-safe: Schema changes don't break existing clients
• Extensible: Add new operations without changing core tools
• Type-safe: Full validation before execution

Example Workflow

# Step 1: Discover available operations
result = discover_operations()
# Shows: discover_subreddits, search_subreddit, fetch_posts, fetch_multiple,
#        fetch_comments, create_feed, list_feeds, get_feed, update_feed, delete_feed

# Step 2: Get schema for the operation you want to use
schema = get_operation_schema("discover_subreddits", include_examples=True)
# Returns parameter types, validation rules, and examples

# Step 3: Execute with validated parameters
communities = execute_operation("discover_subreddits", {
    "query": "artificial intelligence ethics",
    "limit": 20,
    "min_confidence": 0.7,
    "include_nsfw": False
})

discover_subreddits

Find relevant communities using semantic vector search across 20,000+ indexed subreddits.

execute_operation("discover_subreddits", {
    "query": "machine learning frameworks",
    "limit": 15,
    "min_confidence": 0.6,
    "include_nsfw": False
})

Returns: Communities with confidence scores (0-1), match tiers, subscribers, and descriptions.

Use for: Starting any research project, finding niche communities, validating topic coverage.

search_subreddit

Search for posts within a specific subreddit.

execute_operation("search_subreddit", {
    "subreddit_name": "MachineLearning",
    "query": "transformer architectures",
    "sort": "relevance",
    "time_filter": "month",
    "limit": 25
})

Returns: Posts matching the search query with scores, comments, and timestamps.

Use for: Deep-diving into specific communities, finding historical discussions.

fetch_posts

Get posts from a single subreddit by listing type (hot, new, top, rising).

execute_operation("fetch_posts", {
    "subreddit_name": "technology",
    "listing_type": "top",
    "time_filter": "week",
    "limit": 20
})

Returns: Recent posts from the subreddit with scores, comments, and authors.

Use for: Monitoring specific communities, trend analysis, content curation.

fetch_multiple

70% more efficient - Batch fetch posts from multiple subreddits concurrently.

execute_operation("fetch_multiple", {
    "subreddit_names": ["Python", "django", "flask"],
    "listing_type": "hot",
    "limit_per_subreddit": 10,
    "time_filter": "day"
})

Returns: Posts from all specified subreddits, organized by community.

Use for: Comparative analysis, multi-community research, feed monitoring.

fetch_comments

Get complete comment tree for deep analysis of discussions.

execute_operation("fetch_comments", {
    "submission_id": "abc123",
    "comment_limit": 100,
    "comment_sort": "best"
})

Returns: Post details + nested comment tree with scores, authors, and timestamps.

Use for: Understanding community sentiment, identifying expert opinions, analyzing debates.

Feeds let you save research configurations for ongoing monitoring. Perfect for long-term projects, competitive analysis, and market research campaigns.

create_feed

Save discovered subreddits with analysis and metadata.

execute_operation("create_feed", {
    "name": "AI Research Communities",
    "website_url": "https://example.com",
    "analysis": {
        "description": "AI/ML communities for technical discussions",
        "audience_personas": ["ML engineers", "researchers", "data scientists"],
        "keywords": ["machine learning", "deep learning", "neural networks"]
    },
    "selected_subreddits": [
        {
            "name": "MachineLearning",
            "description": "ML community",
            "subscribers": 2500000,
            "confidence_score": 0.85
        },
        {
            "name": "deeplearning",
            "description": "Deep learning discussions",
            "subscribers": 150000,
            "confidence_score": 0.92
        }
    ]
})

Returns: Created feed with UUID, timestamps, and metadata.

Use for: Starting long-term research projects, saving competitive analysis configurations.

list_feeds

View all your saved feeds with pagination.

execute_operation("list_feeds", {
    "limit": 10,
    "offset": 0
})

Returns: Array of feeds with metadata, sorted by recently viewed.

Use for: Managing multiple research projects, reviewing saved configurations.

get_feed

Retrieve a specific feed by ID.

execute_operation("get_feed", {
    "feed_id": "550e8400-e29b-41d4-a716-446655440000"
})

Returns: Complete feed details including subreddits, analysis, and metadata.

Use for: Resuming research projects, reviewing feed configurations.

update_feed

Modify feed name, subreddits, or analysis (partial updates supported).

execute_operation("update_feed", {
    "feed_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Feed Name",
    "selected_subreddits": [
        # Add or replace subreddits
    ]
})

Returns: Updated feed with new timestamps.

Use for: Refining research scope, adding newly discovered communities.

delete_feed

Remove a feed permanently.

execute_operation("delete_feed", {
    "feed_id": "550e8400-e29b-41d4-a716-446655440000"
})

Returns: Confirmation of deletion.

Use for: Cleaning up completed projects, removing outdated configurations.

Feed Workflow Example

# 1. Discover relevant subreddits
communities = execute_operation("discover_subreddits", {
    "query": "sustainable energy technology",
    "limit": 20
})

# 2. Create a feed with selected communities
feed = execute_operation("create_feed", {
    "name": "Clean Energy Research",
    "analysis": {
        "description": "Communities discussing renewable energy and sustainability",
        "audience_personas": ["engineers", "researchers", "policy makers"],
        "keywords": ["solar", "wind", "battery", "sustainable"]
    },
    "selected_subreddits": communities["data"]["subreddits"][:10]
})

# 3. Later: Resume research from saved feed
saved_feed = execute_operation("get_feed", {
    "feed_id": feed["data"]["id"]
})

# 4. Fetch posts from feed subreddits
posts = execute_operation("fetch_multiple", {
    "subreddit_names": [sub["name"] for sub in saved_feed["data"]["selected_subreddits"]],
    "listing_type": "hot",
    "limit_per_subreddit": 5
})

This server uses Descope OAuth2 for secure authentication:

• Type: OAuth2 with Descope provider
• Scope: Read-only access to public Reddit content
• Setup: No Reddit credentials needed - server handles authentication
• Token: Automatically managed by your MCP client
• Privacy: Only accesses public Reddit data, no personal information collected

Your AI assistant will prompt for authentication on first use. The process takes ~30 seconds and only needs to be done once.

The server provides intelligent recovery suggestions for common errors:

404 Not Found

Cause: Subreddit doesn't exist or name is misspelled Recovery: Verify the subreddit name or use discover_subreddits to find communities

429 Rate Limited

Cause: Too many requests to Reddit API (60 requests/minute limit) Recovery: Reduce the limit parameter or wait 30 seconds before retrying

403 Private/Forbidden

Cause: Subreddit is private, quarantined, or banned Recovery: Try other communities from your discovery results

422 Validation Error

Cause: Parameters don't match schema requirements Recovery: Use get_operation_schema() to check parameter types and validation rules

401 Authentication Required

Cause: Descope token expired or invalid Recovery: Re-authenticate when prompted by your AI assistant

reddit-research-mcp/
├── src/
│   ├── server.py          # FastMCP server with 3-layer architecture
│   ├── config.py          # Reddit API configuration
│   ├── chroma_client.py   # Vector database proxy
│   ├── resources.py       # MCP resources
│   ├── models.py          # Data models
│   └── tools/
│       ├── search.py      # Search operations
│       ├── posts.py       # Post fetching
│       ├── comments.py    # Comment retrieval
│       ├── discover.py    # Subreddit discovery
│       └── feed.py        # Feed CRUD operations
├── tests/                 # Test suite
├── reports/               # Example reports
└── specs/                 # Architecture docs

This project uses:

• Python 3.11+ with type hints
• FastMCP for the server framework
• Vector search via authenticated proxy (Render.com)
• ChromaDB for semantic search
• PRAW for Reddit API interaction
• httpx for HTTP client requests (feed operations)