mcrentcast/README.md

# mcrentcast - Rentcast MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to the Rentcast API with advanced caching, rate limiting, and cost management features.

## 🌟 Features

- **🏠 Complete Rentcast API Integration**: Access all Rentcast endpoints for property data, valuations, listings, and market statistics
- **💾 Intelligent Caching**: Automatic response caching with hit/miss tracking and configurable TTL
- **🛡️ Rate Limiting**: Configurable daily/monthly/per-minute limits with exponential backoff
- **💰 Cost Management**: Track API usage, estimate costs, and get confirmations before expensive operations
- **🧪 Mock API for Testing**: Full mock implementation for development without consuming credits
- **✨ MCP Integration**: Seamless integration with Claude and other MCP-compatible clients
- **🐳 Docker Ready**: Complete Docker Compose setup for easy deployment
- **📊 Usage Analytics**: Track API usage patterns, cache performance, and costs

## 📋 Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [MCP Tools](#mcp-tools)
- [Mock API](#mock-api)
- [Development](#development)
- [Testing](#testing)
- [API Documentation](#api-documentation)
- [Troubleshooting](#troubleshooting)

## 🚀 Quick Start

### Prerequisites

- Python 3.13+
- [uv](https://github.com/astral-sh/uv) package manager
- Rentcast API key (or use mock mode for testing)

### Installation

```bash
# Clone the repository
git clone https://git.supported.systems/MCP/mcrentcast.git
cd mcrentcast

# Run the installation script
./install.sh

# IMPORTANT: Set your API key in the .env file
nano .env  # Set RENTCAST_API_KEY=your_actual_api_key

# For development (from cloned repo)
claude mcp add mcrentcast -- uvx --from . mcrentcast

# For production (install from git)
claude mcp add mcrentcast -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast
```

## 📦 Installation

### Method 1: Automated Installation

```bash
./install.sh
```

This script will:
- Install Python dependencies with uv
- Create necessary directories
- Initialize the database
- Set up configuration files

### Method 2: Manual Installation

```bash
# Install dependencies
uv sync

# Create data directory
mkdir -p data

# Initialize database
uv run python -c "from mcrentcast.database import db_manager; db_manager.create_tables()"

# Copy environment configuration
cp .env.example .env

# Edit .env with your API key
nano .env
```

### Using the Installed Scripts

After installation, you can use the provided command-line scripts:

```bash
# Run the MCP server (for Claude integration)
uv run mcrentcast

# Run the mock API server (for testing)
uv run mcrentcast-mock-api
```

### Method 3: Docker

```bash
# Start with Docker Compose
make dev  # Development mode
make prod # Production mode
```

## ⚙️ Configuration

### Environment Variables

Create a `.env` file with your configuration:

```env
# Rentcast API Configuration
RENTCAST_API_KEY=your_api_key_here
RENTCAST_BASE_URL=https://api.rentcast.io/v1

# Mock API Settings (for testing)
USE_MOCK_API=false  # Set to true for testing without credits
MOCK_API_URL=http://localhost:8001/v1

# Rate Limiting
DAILY_API_LIMIT=100
MONTHLY_API_LIMIT=1000
REQUESTS_PER_MINUTE=3

# Cache Settings
CACHE_TTL_HOURS=24
MAX_CACHE_SIZE_MB=100

# Database
DATABASE_URL=sqlite:///./data/mcrentcast.db
```

### Claude Desktop Configuration

#### Option 1: Using `claude mcp add` with uvx (Recommended)

```bash
# Navigate to the project directory
cd /path/to/mcrentcast

# Make sure your API key is set in .env file
# Edit .env and set RENTCAST_API_KEY=your_actual_key

# For production (install directly from git)
claude mcp add mcrentcast -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast

# For development (from cloned repository)
claude mcp add mcrentcast -- uvx --from . mcrentcast

# Alternative: use the mcp.json configuration (development only)
claude mcp add mcrentcast .

# For testing with mock API (no real API key needed)
claude mcp add mcrentcast-test -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast \
  -e USE_MOCK_API=true \
  -e RENTCAST_API_KEY=test_key_basic

# To use different scopes
claude mcp add --scope user mcrentcast -- uvx --from . mcrentcast  # Available to all projects
claude mcp add --scope local mcrentcast .  # Only for current project (default)
```

#### Option 2: Manual Configuration

Add to your Claude MCP configuration file (usually `~/.config/claude/mcp.json` or similar):

```json
{
  "servers": {
    "mcrentcast": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcrentcast.server"],
      "cwd": "/path/to/mcrentcast",
      "env": {
        "PYTHONPATH": "/path/to/mcrentcast/src:${PYTHONPATH}",
        "RENTCAST_API_KEY": "your_api_key_here",
        "USE_MOCK_API": "false"
      }
    }
  }
}
```

Note: The server uses the `mcp.json` file in the project root for configuration when using `claude mcp add`.

## 🔧 Usage

### With Claude

Once added to Claude, you can use natural language:

```
User: Search for properties in Austin, Texas

Claude: I'll search for properties in Austin, Texas.
[Uses search_properties tool]
Found 10 properties in Austin, TX...
```

### Direct Python Usage

```python
from mcrentcast.rentcast_client import RentcastClient

async def example():
    client = RentcastClient(api_key="your_key")
    
    # Search properties
    properties, cached, age = await client.get_property_records(
        city="Austin", 
        state="TX", 
        limit=10
    )
    
    # Get value estimate
    estimate, cached, age = await client.get_value_estimate(
        address="123 Main St, Austin, TX"
    )
    
    await client.close()
```

## 🛠️ MCP Tools

The server provides 13 MCP tools:

### Property Data Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `search_properties` | Search for property records | `city`, `state`, `zipCode`, `limit`, `offset` |
| `get_property` | Get specific property details | `property_id` |
| `get_value_estimate` | Get property value estimate | `address` |
| `get_rent_estimate` | Get rental price estimate | `address`, `bedrooms`, `bathrooms`, `squareFootage` |

### Listing Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `search_sale_listings` | Find properties for sale | `city`, `state`, `zipCode`, `limit` |
| `search_rental_listings` | Find rental properties | `city`, `state`, `zipCode`, `limit` |
| `get_market_statistics` | Get market analysis data | `city`, `state`, `zipCode` |

### Management Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `set_api_key` | Configure Rentcast API key | `api_key` |
| `expire_cache` | Expire cache entries | `cache_key`, `all` |
| `get_cache_stats` | View cache performance | - |
| `get_usage_stats` | Track API usage and costs | `days` |
| `set_api_limits` | Configure rate limits | `daily_limit`, `monthly_limit`, `requests_per_minute` |
| `get_api_limits` | View current limits | - |

## 🧪 Mock API

The project includes a complete mock of the Rentcast API for testing without consuming API credits:

### Starting Mock API

#### Using the Script Command

```bash
# Start mock API server (runs on port 8001)
uv run mcrentcast-mock-api
```

#### Using Make Commands

```bash
# Start mock API only
make mock-api

# Start full stack with mock API
make test-mock
```

### Test API Keys

The mock API includes predefined test keys with different rate limits:

| Key | Daily Limit | Use Case |
|-----|-------------|----------|
| `test_key_free_tier` | 50 | Testing free tier |
| `test_key_basic` | 100 | Standard testing |
| `test_key_pro` | 1,000 | High-volume testing |
| `test_key_enterprise` | 10,000 | Unlimited testing |
| `test_key_rate_limited` | 1 | Rate limit testing |

### Using Mock Mode

To use the mock API instead of the real Rentcast API, set in `.env`:

```env
USE_MOCK_API=true
RENTCAST_API_KEY=test_key_basic
MOCK_API_URL=http://localhost:8001/v1
```

Then run the MCP server normally:

```bash
uv run mcrentcast
```

## 🔬 Development

### Project Structure

```
mcrentcast/
├── src/mcrentcast/       # Core MCP server code
│   ├── server.py         # FastMCP server implementation
│   ├── rentcast_client.py # Rentcast API client
│   ├── database.py       # Database management
│   ├── models.py         # Data models
│   ├── config.py         # Configuration
│   └── mock_api.py       # Mock API server
├── tests/                # Test suite
├── docs/                 # Documentation
├── scripts/              # Utility scripts
├── docker-compose.yml    # Docker configuration
├── Makefile             # Build automation
└── pyproject.toml       # Python dependencies
```

### Running Locally

```bash
# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run with mock API
USE_MOCK_API=true uv run python -m mcrentcast.server

# Run linting
uv run ruff check src/

# Format code
uv run black src/ tests/
```

### Docker Development

```bash
# Build images
make build

# Start development environment
make dev

# View logs
make logs

# Run tests in container
make test

# Access shell
make shell
```

## 🧪 Testing

### Unit Tests

```bash
uv run pytest tests/ -v
```

### Integration Tests

```bash
# Start mock API
make mock-api

# Run integration tests
uv run pytest tests/test_integration.py -v
```

### Test Coverage

```bash
uv run pytest --cov=src --cov-report=html
# View report at htmlcov/index.html
```

## 📚 API Documentation

### Rentcast API Endpoints

The server integrates with all major Rentcast endpoints:

- **Property Records**: Search and retrieve property information
- **Value Estimates**: Get property valuations
- **Rent Estimates**: Calculate rental prices
- **Sale Listings**: Find properties for sale
- **Rental Listings**: Find rental properties
- **Market Statistics**: Access market trends and analytics

### Response Caching

All API responses are automatically cached:
- Default TTL: 24 hours (configurable)
- Cache hit/miss tracking
- Manual cache expiration available
- Cache size management

### Rate Limiting

Configurable rate limits:
- Daily request limits
- Monthly request limits
- Per-minute rate limiting
- Exponential backoff on failures

## 🔍 Troubleshooting

### Common Issues

#### Server won't start
```bash
# Check Python version
python --version  # Should be 3.13+

# Reinstall dependencies
uv sync --reinstall

# Check database
rm -f data/mcrentcast.db
uv run python -c "from mcrentcast.database import db_manager; db_manager.create_tables()"
```

#### API Key Issues
```bash
# Test with mock API
USE_MOCK_API=true uv run python scripts/test_mock_api.py

# Verify API key
curl -H "X-Api-Key: your_key" https://api.rentcast.io/v1/properties
```

#### Cache Issues
```bash
# Clear cache
rm -f data/mcrentcast.db

# Expire specific cache
uv run python -c "
from mcrentcast.database import db_manager
import asyncio
asyncio.run(db_manager.expire_cache_entry('cache_key_here'))
"
```

### Debug Mode

Enable debug logging:
```env
DEBUG=true
LOG_LEVEL=DEBUG
```

### Getting Help

- Check `docs/` directory for detailed guides
- Review `docs/mock-api.md` for testing documentation
- Check `docs/claude-setup.md` for MCP integration help

## 📄 License

MIT License - See LICENSE file for details

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

## 🙏 Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP support
- Uses [Rentcast API](https://developers.rentcast.io/) for property data
- Powered by [uv](https://github.com/astral-sh/uv) for Python management

## 📞 Support

- Documentation: See `/docs` directory
- Issues: Create an issue on GitHub
- Mock API Guide: See `docs/mock-api.md`
- Claude Setup: See `docs/claude-setup.md`

---

**Note**: This is an unofficial integration with the Rentcast API. Please ensure you comply with Rentcast's terms of service and API usage guidelines.