Cloudcdn Pro

CloudCDN

The multi-tenant, AI-native CDN you can read end-to-end and deploy yourself. Sub-100ms TTFB across 300+ Cloudflare PoPs, agent-controllable over MCP, WCAG-AA accessible, light/dark themed, 100% tested.

---

Why CloudCDN

Most CDNs are a deploy target. CloudCDN is also a product — multi-tenant zones, isolated cache tags, per-asset analytics, AI vision and search, a passkey-protected dashboard, and an [MCP server](mcp/README.md) so AI agents can drive zones, transforms, and cache autonomously. Open source, MIT, runs on free-tier Cloudflare with no SaaS dependency.

| What you usually get | What CloudCDN ships | | :--- | :--- | | A single zone serving a single site | Multi-tenant — 65 isolated tenant zones, per-tenant Cache-Tags, per-asset analytics | | Image resizing | Resize plus AI alt-text, smart-crop (subject-aware gravity), background-remove, content moderation | | A purge button | URL purge, tag purge, full purge — plus a 90-day immutable audit log of every control-plane mutation | | Search-by-filename | Semantic search (Vectorize) with day-bucketed edge cache and fuzzy fallback when AI quota is dry | | Static docs | Interactive OpenAPI explorer (Scalar) with Try-It console + four pre-built client libs | | A dashboard you log into with a password | Dashboard with WebAuthn passkeys + HMAC-session fallback | | Whatever theme the vendor picks | Light/dark Skeletonic Stylus theme, per-user preference, zero-FOUC boot, every page WCAG-AA clean in both modes | | "We have an SDK" | An MCP server — Claude Code, Claude Desktop, Cursor, Windsurf, and Cline can manage your CDN without code |

Overview

CloudCDN is a multi-tenant CDN platform built entirely on Cloudflare Workers, Pages, KV, Vectorize, and Workers AI. A single SVG upload scaffolds a complete project directory. Every image is optimized, cached at the edge, and served in under 100ms globally.

• 65 tenant zones with isolated v1/ directory structures (plus shared cmn/ and common/ asset libraries)
• 1,824 optimized assets in the live manifest — single source per image, derivatives on demand
• 36 edge API endpoints across 8 planes (Storage, Core, Assets, Insights, Delivery, AI, Auth, Webhooks)
• 3,190 tests with 100% statement / branch / function / line coverage on 41 gated production files
• WCAG-AA accessible — zero serious/critical axe-core violations on every page we own, both themes, blocking gate on every PR
• Light + dark theme site-wide via [data-theme] + CSS native light-dark(), pre-paint boot to prevent FOUC
• Quota-resilient AI — response cache, neuron budget, circuit breaker, and curated FAQ fallback keep /api/search and /api/chat answering when Workers AI is exhausted; vision endpoints share the same guard
• Agent-controllable — [@cloudcdn/mcp-server](mcp/README.md) exposes 42 tools + 6 resources for Claude Code, Cursor, Windsurf, Cline, Claude Desktop, and VS Code Copilot
• Signed commits enforced end-to-end — from developer machine to edge deployment via the verify-signatures gate

Architecture

graph TD
    A[Developer] -->|signed commit| B{GitHub}
    B -->|CI/CD| C[Cloudflare Pages]
    C --> D[Edge Middleware]
    D --> E[clients/]
    D --> F[stocks/]
    D --> G[cdn/]
    D --> H[Edge Functions]
    H --> I[Storage API]
    H --> J[Core API]
    H --> K[Assets API]
    H --> L[Insights API]
    H --> M[Delivery API]
    H --> N[AI Services]

/
├── clients/          65 tenant asset directories + 2 shared libraries (cmn, common)
├── stocks/           Global stock media (images, diagrams, videos)
├── cdn/              Application layer (localized pages, dashboard, docs)
│   ├── en/           English homepage (canonical)
│   ├── fr/, de/...   27 more localized homepages
│   ├── dashboard/    Asset dashboard UI
│   ├── api-reference/ OpenAPI docs
│   ├── content/      Markdown knowledge base
│   └── shared/       theme.css, theme-boot.js, theme-toggle.js,
│                     skeletonic vendor CSS, scalar-theme bridge
├── scripts/          Build scripts, i18n, tests (not deployed as content)
├── functions/        Cloudflare edge functions (middleware + 38 APIs)
├── mcp/              Model Context Protocol server — agents drive the CDN
├── manifest.json     Auto-generated asset registry
└── wrangler.toml     Cloudflare bindings (AI, Vectorize, KV)

Routing model

Three physical pillars, mapped to clean public URLs by the edge middleware:

| Public URL | Physical pillar | Notes | | :--- | :--- | :--- | | //v1/... | clients//v1/... | Per-tenant zones | | /stocks/ | stocks/ | Shared stock media (direct) | | /, //, /api-reference, /dist/, /dashboard/ | cdn//... and cdn/shared/... | The application layer |

Leaked physical paths (/cdn//..., including old bookmarks and preview-deploy URLs) 301 to the canonical clean URL with Cache-Control: no-store so browsers don't pin stale targets. The whole rule set has zero-redirect-loop tests covering both authenticated and unauthenticated paths.

Features

| | | | :--- | :--- | | Edge Delivery | Static assets served from 300+ Cloudflare data centers with immutable 1-year cache headers and automatic CORS. | | Image Transforms | On-the-fly resize, format conversion, blur, and sharpen via /api/transform. Supports WebP, AVIF, PNG, JPEG. Auto-degrades quality + format on slow networks when Save-Data or Sec-CH-Effective-Connection-Type indicate a constrained client. | | Format Negotiation | /api/auto reads the browser Accept header and serves the optimal format (AVIF > WebP > PNG) automatically. Skips heavier decoders (JPEG XL / AVIF) on Save-Data or slow ECT clients. | | AI Vision Endpoints | /api/ai/alt-text generates accessibility descriptions, /api/ai/smart-crop returns a subject-aware gravity directive, /api/ai/moderate classifies images across five safety categories. All three use the shared Workers AI budget guard so a quota dip degrades to the cache, not to an error. | | Progressive Placeholders | /api/lqip returns a base64 data URI for an inline progressive placeholder; /api/blurhash returns a 40-char content hash + data URI pair for hash-deduped caching. Both via Cloudflare Image Resizing. | | Per-Asset Analytics | /api/insights/asset?path=... returns daily request counts and error roll-ups per individual asset — answers "how is this image performing" with no extra instrumentation. | | Signed URLs | HMAC-SHA256 time-limited URLs for protected assets with constant-time signature verification. | | HLS Streaming | Adaptive bitrate video delivery via HTTP Live Streaming playlists and byte-range segmentation. | | Semantic Search | Natural language asset search powered by Workers AI embeddings and Vectorize vector similarity. Day-bucketed edge cache, neuron budget, and fuzzy fallback keep results flowing when AI quota is exhausted — responses are annotated with mode: vector \| fuzzy \| cached. | | AI Concierge | RAG-powered chat assistant with SSE streaming, confidence scoring, and follow-up suggestions. Layered fallback: edge response cache → 30-entry curated FAQ → templated default. Failures never surface as HTTP errors; metadata.source is ai \| cached \| curated. | | MCP Server | [@cloudcdn/mcp-server](mcp/README.md) exposes 42 tools + 6 resources (storage, zones, assets, insights, audit, transform, purge, signed URLs, HLS playlists, AI vision, placeholders, semantic search, scoped tokens, webhooks, operational logs) for AI agents. Drop-in compatible with Claude Code, Claude Desktop, Cursor, Windsurf, and Cline. | | Audit Trail | Every control-plane mutation (token create/revoke, webhook register/delete, zone create, purge) writes to an immutable 90-day audit log accessible via /api/core/audit-logs. Records carry IP, user-agent, trace ID, and action-specific metadata. | | Asset Pipeline | Upload a single SVG → automatic directory scaffold with PWA icons, banners, and favicon. | | Zone Management | Create, delete, and configure tenant zones via GitOps commits through the Core API. | | Edge Analytics | Real-time request tracking, bandwidth monitoring, cache ratio, geo distribution, and error tracking. | | Cache Purge | Instant invalidation by URL, surrogate tag (Cache-Tag), or full purge via the Cloudflare API. | | Dashboard | Protected asset browser with faceted search, transform builder, insights charts, and upload pipeline. | | Passkey Auth | WebAuthn / FIDO2 passkeys on the dashboard with HMAC-session fallback. Stateless signed challenges, 7-day rolling sessions, full audit trail. | | Light + Dark Theme | Site-wide [data-theme] system on every public page, locale page, dashboard view, login page, and the API explorer. Pre-paint synchronous boot prevents FOUC; toggle persists in localStorage; respects prefers-color-scheme on first visit. Powered by Skeletonic Stylus + a thin theme.css layer. | | Accessibility | Zero serious/critical axe-core violations on every page we own, in both themes. WCAG 2.2 AA contrast, full keyboard support, :focus-visible rings on every interactive, prefers-reduced-motion respect, screen-reader-only skip links. The a11y audit is a blocking CI gate on every PR. | | OpenAPI explorer | /api-reference ships the Scalar interactive console with Try-It requests, four pre-built client libraries (JS / TS / Python / cURL), and an OpenAPI 3.1 spec download. The widget's darkMode is bridged to the site-wide theme toggle. | | Edge canonicalisation | /cdn//... paths (deploy-internal) 301 to the clean URL with Cache-Control: no-store. Same fix for /api-reference (no slash) and the homepage /. Stops Pages' index.html → directory 308 from looping with the canonicalisation rule. |

API

Eight planes with strict authentication separation:

| Plane | Prefix | Auth | Description | | :--- | :--- | :--- | :--- | | Storage | /api/storage/ | AccessKey | Upload, download, delete, batch operations | | Core | /api/core/ | AccountKey | Zones, domains, edge rules, statistics, audit log | | Assets | /api/assets | AccessKey | Paginated catalog, per-asset metadata | | Insights | /api/insights/ | Any key | Summary, top assets, geography, errors, per-asset | | Delivery | /api/transform /api/auto /api/signed /api/stream /api/purge /api/lqip /api/blurhash /api/pipeline | Public + PurgeKey + AccountKey | Edge transforms, format negotiation, signed URLs, HLS, cache, placeholders, pipeline ingest | | AI | /api/search /api/chat /api/ai/alt-text /api/ai/smart-crop /api/ai/moderate /api/ai/background-remove | Public + ai:read scope | Semantic search, RAG concierge, vision endpoints | | Auth | /api/passkeys/* /api/tokens | Session / AccountKey | WebAuthn registration + authentication, scoped API token management | | Webhooks | /api/webhooks /api/logs | AccountKey | Webhook registration + dispatch log inspection |

Interactive reference with Try-It console (interactive Scalar): cloudcdn.pro/api-reference

Install

git clone https://github.com/sebastienrousseau/cloudcdn.pro.git
cd cloudcdn.pro
npm ci

Stratos CLI

The companion command-line client is Stratos, maintained in its own MIT-licensed repository and distributed as a single Node ≥ 18 script. One-liner install:

# macOS / Linux
curl -sL https://cloudcdn.pro/dist/stratos/install.sh | bash

# Windows (PowerShell)
irm https://cloudcdn.pro/dist/stratos/install.ps1 | iex

Each installer verifies a pinned SHA-256 before placing a stratos shim on $PATH. Then:

stratos version
stratos health --deep
stratos purge https://cloudcdn.pro/akande/v1/logos/logo.svg
stratos signed /clients/akande/private.pdf --expires 1700000000
stratos assets --project=akande --format=svg

Configure via environment variables: CLOUDCDN_URL, CLOUDCDN_ACCOUNT_KEY, CLOUDCDN_ACCESS_KEY, SIGNED_URL_SECRET. See [SECRETS.md](./SECRETS.md) for the full reference and the stratos repo for the complete command and exit-code documentation.

First 5 Minutes

# Start local development server
npx wrangler pages dev . --port 8788

# Run the full test suite (2,994 tests at 100% coverage)
npm test
npm run test:coverage

# Generate the asset manifest
npm run build:manifest

# Build the dashboard CSS + Skeletonic vendor bundle
npm run build:all

Upload your first asset

# Upload via the Storage API
curl -X PUT -H "AccessKey: YOUR_KEY" \
  -H "Content-Type: image/svg+xml" \
  -T ./logo.svg \
  https://cloudcdn.pro/api/storage/clients/myproject/v1/logos/logo.svg

# Or use the Asset Pipeline to scaffold a full directory
curl -X POST -H "AccountKey: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "client", "name": "myproject", "svg": "" }' \
  https://cloudcdn.pro/api/pipeline

Transform an image on the fly

# Resize to 400px WebP
curl 'https://cloudcdn.pro/api/transform?url=/myproject/v1/logos/logo.svg&w=400&format=webp'

# Generate a blur placeholder
curl 'https://cloudcdn.pro/api/transform?url=/myproject/v1/logos/logo.svg&w=32&q=1&blur=20'

# Auto-negotiate format (no auth needed)
curl 'https://cloudcdn.pro/api/auto?path=/myproject/v1/logos/logo'

Environment Variables

A short list of the most common variables is below. The full reference — every env var, secret, and binding the runtime consumes, with the wrangler command to set each — lives in [SECRETS.md](./SECRETS.md).

| Variable | Description | | :--- | :--- | | ACCOUNT_KEY | Core API authentication (admin) | | ACCESS_KEY | Public-read AccessKey for /api/assets, /api/insights/*, /api/transform, /api/ai/* | | STORAGE_KEY | Storage API authentication (files) | | DASHBOARD_PASSWORD | Dashboard login (password fallback) | | PASSKEY_STRICT_VERIFY | Set to 1 to reject WebAuthn assertions that fail cryptographic verification. Default: loose mode (logs but accepts), used during rollout. | | GITHUB_TOKEN | GitOps mutations (upload/delete) | | GITHUB_REPO | Repository for Git-based storage | | CLOUDFLARE_API_TOKEN | Cache purge, domains | | CLOUDFLARE_ZONE_ID | Cache invalidation | | SIGNED_URL_SECRET | HMAC signed URL generation | | AI_DAILY_BUDGET | Workers AI neuron soft cap per UTC day (default 9000). When tripped, /api/search and /api/chat switch to cached + fuzzy / curated answers. | | AI_CB_TTL_SEC | Circuit-breaker open duration in seconds after a quota error (default 60). |

Operator health check

GET /api/health returns the binding-presence summary cheaply. Pass ?deep=1 to actually exercise each binding (ASSETS manifest fetch, KV probe, AI/Vectorize/Durable-Object/WAE/Queue shape checks) and get per-binding latency + healthy/unhealthy state. Status is 200 ok when required bindings are reachable; 503 degraded otherwise.

Testing

npm test                # 3,190 tests across 72 suites
npm run test:coverage   # 100% on statements / branches / functions / lines
npm run test:visual     # Playwright visual regression
npm run test:load       # k6 smoke against production
npm run test:audit      # npm dependency security audit

The vitest config gates 41 production files at 100% — every Cloudflare Function endpoint, every API handler, the middleware, the build scripts, the Stratos CLI, the theme system (theme-boot.js, theme-toggle.js, scalar-theme.js), and the Skeletonic vendor script. CI fails fast on any cov

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sebastienrousseau
• Source: sebastienrousseau/cloudcdn.pro
• License: MIT
• Homepage: https://cloudcdn.pro

Install and usage instructions live in the source repository linked above.