camera-trng/skill.md

# Camera TRNG API Skill Documentation

This document describes how to use the Camera TRNG (True Random Number Generator) API as an MCP-compatible service.

## Overview

The Camera TRNG server provides quantum-based random number generation using thermal noise from a covered camera sensor. The API is accessible via HTTP and self-documents its capabilities through the `.well-known/mcp.json` endpoint.

## Discovery

The API can be discovered by fetching the MCP endpoint:

```bash
curl http://localhost:8787/.well-known/mcp.json
```

The response includes self-referencing URLs that use the request's hostname (from SNI/HTTP Host header), making it work correctly whether accessed via `localhost`, a domain name, or behind a reverse proxy.

## API Endpoints

### 1. Get Random Bytes (`/random`)

Generate cryptographically secure random bytes from camera sensor entropy.

**Parameters:**
- `bytes` (integer, default: 32, max: 1048576): Number of random bytes to generate
- `hex` (boolean, default: false): Return bytes as hexadecimal string instead of binary

**Examples:**
```bash
# Get 32 bytes as binary
curl "http://localhost:8787/random?bytes=32" -o random.bin

# Get 64 bytes as hex string
curl "http://localhost:8787/random?bytes=64&hex=true"

# Get 1KB of random data
curl "http://localhost:8787/random?bytes=1024" -o random.bin
```

### 2. Stream Random Bytes (`/stream`)

Stream continuous random bytes using Server-Sent Events (SSE) format. Useful for high-throughput applications.

**Parameters:**
- `bytes` (integer, optional): Total bytes to stream (omit for unlimited)
- `hex` (boolean, default: false): Stream as hexadecimal strings instead of binary

**Examples:**
```bash
# Stream unlimited random bytes (binary)
curl -N "http://localhost:8787/stream"

# Stream exactly 1MB
curl -N "http://localhost:8787/stream?bytes=1048576"

# Stream as hexadecimal strings
curl -N "http://localhost:8787/stream?hex=true"

# Stream limited bytes as hex
curl -N "http://localhost:8787/stream?bytes=1024&hex=true"
```bash
# Stream unlimited random bytes
curl -N "http://localhost:8787/stream"

# Stream exactly 1MB
curl -N "http://localhost:8787/stream?bytes=1048576"

# Stream as hex
curl -N "http://localhost:8787/stream?hex=true"
```

### 3. List Cameras (`/cameras`)

List available camera devices on the system.

**Example:**
```bash
curl "http://localhost:8787/cameras"
```

**Response:**
```json
{
  "cameras": [
    {
      "index": 0,
      "human_name": "FaceTime HD Camera",
      "description": "Built-in camera",
      "misc": ""
    }
  ]
}
```

### 4. Health Check (`/health`)

Check if the TRNG server is running.

**Example:**
```bash
curl "http://localhost:8787/health"
```

**Response:** `ok`

## MCP Integration

The API implements the Model Context Protocol (MCP) specification, allowing AI assistants and other MCP clients to discover and use the TRNG service automatically.

### MCP Tools

The following tools are exposed via MCP:

1. **get-random**: Generate random bytes (cryptographically secure)
3. **get-stream**: Stream random bytes continuously
4. **list-cameras**: Discover available cameras
5. **health-check**: Verify server status

### Self-Referencing URLs

The MCP endpoint (`/.well-known/mcp.json`) automatically detects the request's hostname from:
- HTTP `Host` header
- `X-Forwarded-Proto` header (for reverse proxy scenarios)

This ensures URLs in the MCP response always reference the correct origin, whether accessed via:
- `localhost:8787`
- `trng.example.com`
- Behind a reverse proxy with forwarded headers

## Usage Examples

### Python
```python
import requests

# Get 32 random bytes
response = requests.get("http://localhost:8787/random?bytes=32")
random_bytes = response.content

# Get hex string
response = requests.get("http://localhost:8787/random?bytes=64&hex=true")
hex_string = response.text
```

### JavaScript/Node.js
```javascript
// Get random bytes
const response = await fetch("http://localhost:8787/random?bytes=32");
const buffer = await response.arrayBuffer();
const bytes = new Uint8Array(buffer);

// Stream random data
const stream = await fetch("http://localhost:8787/stream?bytes=1024");
const reader = stream.body.getReader();
// ... read chunks
```

### curl
```bash
# Basic usage
curl "http://localhost:8787/random?bytes=32&hex=true"

# Save to file
curl "http://localhost:8787/random?bytes=1024" -o random.bin

# Stream
curl -N "http://localhost:8787/stream"
```

## Limitations

- Maximum 1MB per request (`/random`)
- Maximum 4 concurrent requests
- Requires a camera device with covered lens
- Performance depends on camera frame rate

## Security Notes

- No authentication required (intended for local/trusted networks)
- Random data is cryptographically secure when using `/random` endpoint
- Consider rate limiting in production deployments

## See Also

- `TECHNICAL.md` - Technical implementation details
- `README.md` - Project overview and setup instructions