# IMDB MCP Server

A cloud-runnable JSON-RPC service that provides access to IMDB data. Designed to work with LLMs via the MCP (Model Context Protocol).

## How It Works

1. **LLM Configuration**: Add the MCP server URL to your LLM's configuration
2. **Discovery**: The LLM queries the server URL to understand available tools
3. **Query**: The LLM sends JSON-RPC requests to fetch IMDB data
4. **Response**: The server returns structured data that the LLM interprets and explains to users

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | HTML documentation (human-readable) |
| `/info` | GET | Service information (JSON) |
| `/jsonrpc` | POST | JSON-RPC 2.0 endpoint |
| `/mcp` | POST | MCP protocol endpoint for LLM tool calling |
| `/health` | GET | Health check for cloud deployments |

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `search_movies` | Search movies by title | `query`, `limit` |
| `get_movie_details` | Get full movie info | `movie_id` |
| `search_people` | Search actors/directors | `query`, `limit` |
| `get_person_details` | Get person info/filmography | `person_id` |
| `get_top_250_movies` | Get IMDB Top 250 | `limit` |
| `get_movie_cast` | Get cast of a movie | `movie_id`, `limit` |

## JSON-RPC Usage

Send a POST request to `/jsonrpc`:

```json
{
    "jsonrpc": "2.0",
    "method": "search_movies",
    "params": {"query": "The Matrix", "limit": 5},
    "id": 1
}
```

Response:

```json
{
    "jsonrpc": "2.0",
    "result": [
        {"id": "0133093", "title": "The Matrix", "year": 1999},
        {"id": "0234215", "title": "The Matrix Reloaded", "year": 2003}
    ],
    "id": 1
}
```

## LLM MCP Configuration

Add to your LLM's MCP server configuration:

```json
{
    "mcpServers": {
        "imdb": {
            "url": "https://your-deployed-url.com/mcp",
            "transport": "http"
        }
    }
}
```

## Local Development

### Run locally

```bash
pip install -r requirements.txt
python app.py
```

Server runs at `http://localhost:8080`

### Run with Docker

```bash
docker build -t imdb-mcp .
docker run -p 8080:8080 imdb-mcp
```

## Cloud Deployment

### Cloud Foundry

```bash
cf push
```

Uses `manifest.yaml` configuration.

### SAP BTP (Cloud Foundry)

```bash
# Build MTA archive
mbt build

# Deploy
cf deploy mta_archives/imdb-mcp-server_1.0.0.mtar
```

Uses `mta.yaml` configuration.

### Heroku

```bash
heroku create imdb-mcp-server
git push heroku main
```

Uses `Procfile` and `runtime.txt`.

### Docker (Any Cloud)

```bash
# Build
docker build -t imdb-mcp .

# Run
docker run -p 8080:8080 imdb-mcp

# Push to registry
docker tag imdb-mcp your-registry/imdb-mcp:latest
docker push your-registry/imdb-mcp:latest
```

### Google Cloud Run

```bash
gcloud run deploy imdb-mcp \
    --source . \
    --platform managed \
    --allow-unauthenticated
```

### AWS App Runner / ECS

Use the Dockerfile with your preferred AWS container service.

## Project Structure

```
imdb-mcp/
├── app.py              # FastAPI JSON-RPC server
├── imdb_backend.py     # Cinemagoer wrapper
├── server.py           # FastMCP server (for local MCP)
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project metadata
├── Dockerfile          # Container image
├── Procfile            # Heroku/PaaS process file
├── runtime.txt         # Python version
├── manifest.yaml       # Cloud Foundry manifest
├── mta.yaml            # SAP BTP MTA descriptor
├── .dockerignore       # Docker ignore patterns
└── .cfignore           # Cloud Foundry ignore patterns
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 8080 | Server port |

## Notes

- Cinemagoer queries IMDB via web scraping, responses may be slower than API-based solutions
- For non-commercial use only (per IMDB terms of service)
- No API key required