reddit-mcp-buddy

Exposes five specialized Reddit tools through the Model Context Protocol using dual transport layers: StdioServerTransport for Claude Desktop integration and StreamableHTTPServerTransport on port 3000 for testing/debugging. The MCP server core (src/mcp-server.ts) handles protocol negotiation, schema validation, and tool routing with full TypeScript type safety. Supports both synchronous and streaming responses through MCP's standardized message format.

Implements AuthManager class with three authentication modes: anonymous (10 req/min via public endpoints), OAuth2 user credentials (60 req/min), and app credentials (100 req/min). Uses sliding window algorithm for rate limit enforcement with in-memory promise tracking to prevent duplicate in-flight API calls. Credentials are validated at request time and cached to avoid repeated authentication overhead.

Provides Dockerfile and docker-compose configuration for containerized deployment. Supports environment variable injection for Reddit credentials, cache size, rate limits, and port configuration. Enables easy deployment to Docker registries, Kubernetes clusters, or cloud platforms without manual setup. Includes health check endpoints for container orchestration.

Entire codebase written in TypeScript 5.5+ with strict mode enabled, providing compile-time type checking for all Reddit API interactions, tool parameters, and response handling. Eliminates entire classes of runtime errors (null reference exceptions, type mismatches) common in JavaScript. Includes comprehensive type definitions for Reddit API responses, MCP protocol messages, and internal data structures.

CacheManager implements an LRU (Least Recently Used) cache with 50MB capacity and adaptive time-to-live (2-30 minutes) based on content type and request patterns. Tracks cache hit/miss rates to optimize TTL values dynamically. Uses in-memory storage with automatic eviction when capacity is exceeded, reducing Reddit API calls by caching frequently accessed posts, comments, and user profiles.

Implements search_posts tool that queries Reddit's full-text search API with support for advanced filters (subreddit, time range, sort order, score thresholds). Returns LLM-optimized structured results with post metadata, comment counts, and engagement metrics. Uses ContentProcessor to clean and format results, removing fake metrics and normalizing data for consistent LLM consumption.

Implements get_comments tool that retrieves full comment threads for a given post ID, including nested replies up to configurable depth. Uses Reddit's API to fetch comments in 'best' sort order (default) or alternative sorts (hot, new, top, controversial). Preserves comment context (parent relationships, author info, scores) and flattens nested structures into LLM-friendly format with depth indicators.

Implements get_subreddit_info tool that retrieves subreddit metadata (description, subscriber count, creation date, rules) and get_subreddit_posts tool that lists posts from a subreddit with configurable sorting (hot/new/top/rising/controversial) and time filtering (day/week/month/year/all). Uses Reddit's API to fetch up to 100 posts per request with pagination support via 'after' tokens.

Implements get_user_info tool that retrieves user profile data (username, link karma, comment karma, account age, profile description) and get_user_posts tool that fetches user's post/comment history with sorting and filtering. Uses Reddit's API to access public user data with caching to reduce repeated lookups. Breaks down karma by subreddit to identify user's primary communities.

ContentProcessor pipeline cleans Reddit API responses by removing fake engagement metrics (Reddit's vote fuzzing), normalizing timestamps to ISO 8601 format, stripping HTML entities, and formatting text for LLM consumption. Removes redundant fields, collapses nested structures, and adds metadata hints (post age, engagement rate) to help LLMs understand context. Ensures consistent output format across all tools.

Implements request deduplication by tracking in-flight API calls using a promise cache keyed by request parameters. When duplicate requests arrive before the first completes, subsequent calls await the same promise instead of making new API calls. Reduces thundering herd problems and API quota waste in high-concurrency scenarios. Automatically clears completed promises to prevent memory leaks.

Provides command-line interface (src/cli.ts) for testing individual tools without MCP client. Supports commands like 'search-posts', 'get-comments', 'get-subreddit-posts' with argument parsing and formatted output. Useful for debugging tool implementations, testing authentication, and verifying API responses before integration with Claude Desktop.