apify-actor-reddit-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Reddit MCP Server - an enterprise-grade Model Context Protocol server that provides Reddit data access through 4 production MCP tools. Built as an Apify Actor for the $1M Challenge.

Status: MVP complete (9/10 stories done, ~40h development time) Target: 5,000 MAU by Month 6

Essential Commands

Development Setup

# Install dependencies
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDIS_URL

# Start Redis (required)
docker run -d -p 6379:6379 redis:7-alpine

Running the Server

# Run MCP server
python -m src.main

# Verify Redis connection
redis-cli ping  # Should return PONG

Testing

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest --cov=src --cov-report=html tests/

# Run specific test category
pytest tests/test_tools/  # Tool tests only
pytest tests/test_cache/  # Cache tests only
pytest tests/test_reddit/ # Reddit API tests only

# Run single test file
pytest tests/test_tools/test_search_reddit.py -v

Code Quality

# Format code (required before commit)
black src/ tests/

# Lint (must pass)
ruff check src/ tests/

# Type check (strict mode)
mypy src/ --strict

# Run all quality checks
black src/ tests/ && ruff check src/ tests/ && mypy src/ --strict

Apify Deployment

# Deploy to Apify platform
apify login
apify push

# Test Actor locally
apify run

Architecture Overview

High-Level Data Flow

MCP Client → FastMCP Server → Tool Implementation
                ↓
            Cache Check (Redis)
                ↓
         Cache Hit? → Return cached data
                ↓ No
         Rate Limiter (100 QPM)
                ↓
         Reddit API (PRAW)
                ↓
         Response Normalizer
                ↓
         Store in Cache → Return to Client