# Reddit MCP Server

Enterprise-grade Model Context Protocol (MCP) server for seamless Reddit data access. Enables AI agents and developers to search, monitor, and analyze Reddit's 73M daily active users and 100K+ communities.

## Features (MVP v0.1.0)

- **search_reddit** - Search all of Reddit or specific subreddits with filters
- **get_subreddit_posts** - Monitor subreddits for hot, new, top, or rising posts
- **get_post_comments** - Retrieve nested comment threads with full context
- **get_trending_topics** - Discover trending keywords and topics in real-time

All tools include intelligent Redis caching (75%+ hit rate) and automatic rate limiting.

## Prerequisites

- Python 3.11 or higher
- Redis server (local or cloud)
- Reddit API credentials (client ID and secret)

### Getting Reddit API Credentials

1. Go to https://www.reddit.com/prefs/apps
2. Click "Create App" or "Create Another App"
3. Select "script" as the app type
4. Fill in the required fields:
   - Name: "Reddit MCP Server"
   - Redirect URI: http://localhost:8080
5. Save your **client ID** (under the app name) and **client secret**

## Local Development Setup

### 1. Clone and Install

```bash
# Clone the repository
cd /Users/padak/github/apify-actors

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure Environment Variables

Create a `.env` file in the project root:

```bash
# Reddit API Credentials
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here

# Redis Connection
REDIS_URL=redis://localhost:6379

# Logging (optional)
LOG_LEVEL=INFO
```

### 3. Start Redis (Local)

```bash
# Using Docker
docker run -d -p 6379:6379 redis:7-alpine

# Or install Redis locally (macOS)
brew install redis
brew services start redis
```

### 4. Run the Server

```bash
python -m src.main
```

The MCP server will start in standby mode on the configured port (default: `/mcp` endpoint).

## Testing

```bash
# Run all tests
pytest tests/

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

# Run only unit tests
pytest tests/unit/

# Run only integration tests (requires Redis + Reddit API)
pytest tests/integration/
```

## Apify Deployment

### Deploy to Apify Platform

1. **Install Apify CLI**

```bash
npm install -g apify-cli
apify login
```

2. **Configure Secrets**

In the Apify Console, add these secrets to your Actor:
- `REDDIT_CLIENT_ID`
- `REDDIT_CLIENT_SECRET`
- `REDIS_URL`

3. **Deploy**

```bash
apify push
```

The Actor will be deployed in standby mode and accessible via the MCP endpoint.

### Environment Variables (Apify)

| Variable | Type | Required | Description |
|----------|------|----------|-------------|
| `REDDIT_CLIENT_ID` | Secret | Yes | Reddit API client ID |
| `REDDIT_CLIENT_SECRET` | Secret | Yes | Reddit API client secret |
| `REDIS_URL` | String | Yes | Redis connection URL |
| `LOG_LEVEL` | String | No | Logging level (default: INFO) |

## Project Structure

```
/Users/padak/github/apify-actors/
├── src/
│   ├── main.py              # Entry point
│   ├── tools/               # MCP tool implementations
│   ├── reddit/              # Reddit API integration
│   ├── cache/               # Redis caching layer
│   ├── models/              # Pydantic data models
│   └── utils/               # Shared utilities
├── tests/                   # Test suite
├── docs/                    # Documentation
├── actor.json               # Apify Actor configuration
├── Dockerfile               # Container definition
├── requirements.txt         # Python dependencies
└── README.md                # This file
```

## Development Workflow

### Code Quality

```bash
# Format code with Black
black src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type check with mypy
mypy src/ --strict
```

### Running Individual Tools (Development)

TODO: Add examples once tools are implemented (MVP-006 through MVP-009)

## Architecture

- **MCP Server**: FastMCP framework for JSON-RPC protocol handling
- **Reddit API**: PRAW (Python Reddit API Wrapper) for authenticated access
- **Caching**: Redis with intelligent TTL policies (2min - 1hr)
- **Rate Limiting**: Token bucket algorithm (100 requests/min)
- **Data Validation**: Pydantic models for type-safe inputs/outputs

See `/Users/padak/github/apify-actors/docs/architecture/` for detailed technical documentation.

## Troubleshooting

### Redis Connection Errors

```bash
# Check if Redis is running
redis-cli ping
# Should return: PONG

# Test connection with URL
redis-cli -u redis://localhost:6379 ping
```

### Reddit API Authentication Errors

- Verify your client ID and secret are correct
- Check that your Reddit app type is "script"
- Ensure the redirect URI matches: http://localhost:8080

### Import Errors

```bash
# Ensure you're in the virtual environment
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt
```

## Contributing

This is an MVP project. Contributions should align with the roadmap:

- **MVP (Week 1-2)**: Core 4 tools + caching + rate limiting
- **v1.0 (Week 3-4)**: Monetization, sentiment analysis, user auth
- **v2.0 (Month 2+)**: Write operations, real-time monitoring, analytics

## Documentation

- [Product Requirements (PRD)](/Users/padak/github/apify-actors/docs/prd/prd.md)
- [Architecture Overview](/Users/padak/github/apify-actors/docs/architecture/)
- [Epic Stories](/Users/padak/github/apify-actors/docs/stories/)

## License

[Add license information]

## Support

For issues or questions, please refer to the documentation in `/docs/` or create an issue in the repository.

---

**Status**: MVP v0.1.0 (Week 1-2 Development)
**Target**: 5,000 MAU by Month 6 (Apify $1M Challenge)