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:

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:

# 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:

# 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:

curl "http://localhost:8787/cameras"

Response:

{
  "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:

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)
2. get-stream: Stream random bytes continuously
3. list-cameras: Discover available cameras
4. 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

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

// 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

# 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