# Personal MCP Server

Model Context Protocol (MCP) server providing YouTube transcript fetching and extensible tools for AI assistants.

## Quick Start

```bash
# Pull and run from GitHub Container Registry (recommended)
docker compose pull
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down
```

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

## Features

- **YouTube Transcript Fetching** - Multiple formats (plain, structured, SRT, VTT), multi-language support
- **Persistent Caching** - TTL-based with configurable size and expiration
- **Rate Limiting** - Prevent abuse (100 requests/minute default)
- **Security Hardened** - Non-root user, read-only filesystem, minimal privileges

## Available Tools

### youtube_get_transcript
Fetch YouTube video transcript in various formats.

**Parameters:**
- `video_url_or_id` - YouTube URL or video ID
- `languages` - Preferred languages (default: ["en"])
- `format` - Output format: plain, structured, srt, vtt (default: plain)
- `use_cache` - Use cache if available (default: true)

### youtube_list_languages
List all available transcript languages for a video.

**Parameters:**
- `video_url_or_id` - YouTube URL or video ID

### get_server_stats
Get server statistics including cache and rate limit info.

## Configuration

Edit `docker-compose.yml` environment variables:

```yaml
MCP_SERVER_HOST: 0.0.0.0      # Bind address
MCP_SERVER_PORT: 8000         # Port number

CACHE_ENABLED: true           # Enable caching
CACHE_TTL: 3600               # Cache TTL in seconds
CACHE_MAX_SIZE: 100           # Max cached items

RATE_LIMIT_ENABLED: true      # Enable rate limiting
RATE_LIMIT_REQUESTS: 100      # Requests per window
RATE_LIMIT_WINDOW: 60         # Window in seconds

# Optional YouTube settings
# YOUTUBE_COOKIES: /app/cookies.txt
# YOUTUBE_PROXY_HTTP: http://proxy:8080
# YOUTUBE_PROXY_HTTPS: https://proxy:8080
```

## Development

Build and run locally from source:

```bash
docker compose -f docker-compose.build.yml up -d --build
```

## Available Images

From `ghcr.io/cloonix/mymcp`:
- `latest` - Latest build from main branch
- `main` - Main branch
- `v1.0.0` - Version tags (when released)

## License

MIT