convez.ai
MCP ServerDevOps & InfraestruturaAvançado
sebastienrousseau

CloudCDN — MCP Server para CDN Multi-tenant

sebastienrousseau/cloudcdn.pro

CDN self-hosted controlável por agents IA com 42 MCP tools

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que expõe um CDN auto-hospedável multi-tenant construído sobre Cloudflare Workers, com 42 ferramentas de controle para agentes IA gerenciarem zonas, transformações e cache autonomamente. Inclui DAM (Digital Asset Management), busca semântica, limitação de taxa atômica via Durable Objects, e dashboard com autenticação WebAuthn.

Instalação

$npx convez-ai sebastienrousseau/cloudcdn.pro

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
1
Acompanhando
2
Saúde
85%
Último commit
há 3 dias
Versão
v0.0.9
Issues abertas
4
Contribuidores
3

Casos de uso

  • Automatizar gerenciamento de zonas multi-tenant e cache via agents
  • Integrar controle de CDN em pipelines de IA sem dependência SaaS
  • Consultar analytics por asset e controlar purges via MCP

Veredito

Implementação robusta (100% cobertura de testes, WCAG-AA) e rara: CDN como produto com agência para agents, não apenas como alvo de deploy. Exige operacional Cloudflare maduro; ideal para quem precisa de automação cross-layer CDN + IA em arquitetura já serverless.

README

A tradução para o português deste README ainda está na fila.


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 so AI agents can drive zones, transforms, and cache autonomously. It is self-hosted, has no SaaS dependency, and is available under your choice of Apache-2.0 or MIT.

What you usually getWhat CloudCDN ships
A single zone serving a single siteMulti-tenant — isolated tenant zones, per-tenant Cache-Tags, per-asset analytics
Basic file storageDigital asset management (DAM) — versioned directory structures, auto-generated TypeScript manifests, and global stock libraries
Image resizingResize plus AI alt-text, smart-crop (subject-aware gravity), background-remove, content moderation
A purge buttonURL purge, tag purge, full purge — plus 90-day audit records for control-plane mutations
Search-by-filenameSemantic search (Vectorize) with day-bucketed edge cache and fuzzy fallback when AI quota is dry
Static docsInteractive OpenAPI explorer (Scalar) with Try-It console + four pre-built client libs
A dashboard you log into with a passwordDashboard with WebAuthn passkeys + HMAC-session fallback
Whatever theme the vendor picksLight/dark Skeletonic Stylus theme, per-user preference, zero-FOUC boot, and blocking axe checks for the homepage and dashboard
"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 self-hosted, multi-tenant CDN and digital asset management (DAM) platform built entirely on Cloudflare Workers, Pages, KV, Vectorize, and Workers AI. A single SVG upload scaffolds a complete project directory, and static assets are cached at the edge.

  • Tenant-isolated zones with versioned directory structures and shared asset libraries
  • Generated asset manifest with matching TypeScript path definitions
  • OpenAPI 3.1 contract across Storage, Core, Assets, Insights, Delivery, AI, Auth, and Webhooks
  • Root and MCP test suites with blocking coverage thresholds defined in version control
  • Accessibility-gated — the homepage and dashboard have blocking axe-core checks for serious and critical violations
  • 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 — @sebastienrousseau/cloudcdn-mcp exposes tools and 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/          Tenant asset directories and shared libraries
├── 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 URLPhysical pillarNotes
/<project>/v1/...clients/<project>/v1/...Per-tenant zones
/stocks/<path>stocks/<path>Shared stock media (direct)
/, /<locale>/, /api-reference, /dist/, /dashboard/cdn/<locale>/... and cdn/shared/...The application layer

Leaked physical paths (/cdn/<locale>/..., 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 DeliveryStatic assets served through Cloudflare's global network with immutable 1-year cache headers and automatic CORS.
Image TransformsOn-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 URLsHMAC-SHA256 time-limited URLs for protected assets with constant-time signature verification.
HLS StreamingAdaptive bitrate video delivery via HTTP Live Streaming playlists and byte-range segmentation.
Semantic SearchNatural 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 ConciergeRAG-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@sebastienrousseau/cloudcdn-mcp exposes storage, zones, assets, insights, audit, transform, purge, signed URLs, HLS playlists, AI vision, placeholders, semantic search, scoped tokens, webhooks, and operational logs to AI agents. Drop-in compatible with Claude Code, Claude Desktop, Cursor, Windsurf, and Cline.
Audit TrailControl-plane mutations (token create/revoke, webhook register/delete, zone create, purge) emit 90-day audit records accessible via /api/core/audit-logs. Records carry IP, user-agent, trace ID, and action-specific metadata.
Asset PipelineUpload a single SVG → automatic directory scaffold with PWA icons, banners, and favicon.
Zone ManagementCreate, delete, and configure tenant zones via GitOps commits through the Core API.
Edge AnalyticsReal-time request tracking, bandwidth monitoring, cache ratio, geo distribution, and error tracking.
Cache PurgeInstant invalidation by URL, surrogate tag (Cache-Tag), or full purge via the Cloudflare API.
DashboardProtected asset browser with faceted search, transform builder, insights charts, and upload pipeline.
Passkey AuthWebAuthn / FIDO2 passkeys on the dashboard with HMAC-session fallback. Stateless signed challenges, 7-day rolling sessions, full audit trail.
Light + Dark ThemeSite-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.
AccessibilityThe homepage and dashboard have blocking axe-core checks for serious and critical violations. The interface includes keyboard navigation, :focus-visible rings, reduced-motion handling, and skip links.
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/<locale>/... 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. The Pages default host cloudcdn-pro.pages.dev redirects to https://cloudcdn.pro (301 for GET/HEAD, 308 otherwise); preview hosts and custom domains are untouched.

API

Eight planes with strict authentication separation:

PlanePrefixAuthDescription
Storage/api/storage/AccessKeyUpload, download, delete, batch operations
Core/api/core/AccountKeyZones, domains, edge rules, statistics, audit log
Assets/api/assetsAccessKeyPaginated catalog, per-asset metadata
Insights/api/insights/Any keySummary, top assets, geography, errors, per-asset
Delivery/api/transform /api/auto /api/signed /api/stream /api/purge /api/lqip /api/blurhash /api/pipelinePublic + PurgeKey + AccountKeyEdge 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-removePublic + ai:read scopeSemantic search, RAG concierge, vision endpoints
Auth/api/passkeys/* /api/tokensSession / AccountKeyWebAuthn registration + authentication, scoped API token management
Webhooks/api/webhooks /api/logsAccountKeyWebhook 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 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 root test suite with enforced coverage thresholds
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 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": "<base64>" }' \
  https://cloudcdn.pro/api/pipeline
# 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.

VariableDescription
ACCOUNT_KEYCore API authentication (admin)
ACCESS_KEYPublic-read AccessKey for /api/assets, /api/insights/*, /api/transform, /api/ai/*
STORAGE_KEYStorage API authentication (files)
DASHBOARD_PASSWORDDashboard login (password fallback)
WEBHOOK_SECRET_KEYEncrypts webhook signing secrets in Pages and the optional queue consumer
GITHUB_TOKENGitOps mutations (upload/delete)
GITHUB_REPORepository for Git-based storage
CLOUDFLARE_API_TOKENCache purge, domains
CLOUDFLARE_ZONE_IDCache invalidation
SIGNED_URL_SECRETHMAC signed URL generation
AI_DAILY_BUDGETWorkers 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_SECCircuit-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,806 tests across 91 suites
npm run test:coverage   # Enforces the repository coverage thresholds
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 configuration gates the Cloudflare endpoints, middleware, build scripts, Stratos CLI, theme system, and Skeletonic integration. Its current thresholds are 99% statements, 95% branches, 99% functions, and 100% lines. CI fails on any threshold drop or test error; the accessibility audit on the homepage and dashboard is a blocking gate on every pull request.

The MCP package (mcp/) carries its own vitest suite with the same 100% gate — see mcp/README.md#testing.

CategorySuitesApprox. tests
Endpoint unit tests (36 API endpoints)241,500+
Domain regression (Data / Control / Edge)13320+
Cross-cutting (auth, CORS, pagination, streaming, signed URLs, passkeys)14370+
OpenAPI spec validation2500+
Infrastructure (manifest, client libs, Skeletonic vendor)9420+
AI fallback (cache, budget, breaker, curated, vector)540+
Theme system (theme-boot, theme-toggle, scalar-theme via happy-dom)324
Stratos CLI230+
Total913,806

Accessibility

The homepage and dashboard are audited for serious and critical axe-core violations. Concrete interface commitments:

  • WCAG 2.2 AA contrast on every interactive (headings use --accent-text for AA-passing tinting; the primary CTA uses #4f46e5 because the brand --accent #6366f1 lands at 4.46:1 against white, just below the 4.5 threshold)
  • Keyboard-first — every focusable element has a :focus-visible ring; the skip-link is screen-reader-visible only when focused
  • Reduced motion — prefers-reduced-motion: reduce disables every transition and animation site-wide
  • Form labels — every input/select carries an associated <label for> or aria-label
  • Blocking CI gate — .github/workflows/test.yml runs axe-core/playwright against the homepage and dashboard on every PR; the build fails on a serious/critical regression

Third-party widgets (Scalar API explorer on /api-reference) carry their own a11y issues we can't fix without forking; those are surfaced in the audit output but don't gate the build.

Security

  • Timing-safe HMAC — XOR-based constant-time comparison on all signature verifications (sessions, signed URLs, passkey challenges, webhook signing)
  • Fail-closed auth — production endpoints deny access when secrets are not configured (no default-allow)
  • Path traversal hardened — URL decoding, null byte rejection, .git blocking, SSRF guards on /api/auto and /api/transform
  • Per-route CSP — public pages serve script-src 'self' (no inline, no third-party). Dashboard, dist, and /api-reference get tighter overrides where needed. CSP is asserted by middleware unit tests.
  • Passkey + session — WebAuthn for the dashboard with HMAC-signed 7-day sessions, stateless signed challenges (no KV round-trip), constant-time signature verification, audit trail on every register/auth/revoke
  • Scoped API tokens — /api/tokens lets account admins mint per-scope tokens (storage:read, assets:read, purge:write, …). SHA-256 hashed at rest, 8-char prefix only in list output, last-used timestamps for staleness audit
  • Cache hardening on redirects — every /cdn/<locale>/... 301 ships Cache-Control: no-store so future rule iterations can't poison browser caches
  • HSTS preload — Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
  • SHA-pinned Actions — every GitHub Action pinned by full commit hash; verify-signatures job blocks deploy on any unsigned commit
  • Signed commits enforced end-to-end — developer machine → GitHub → edge deploy. The deploy workflow fails closed if any commit on the push is unverified.

Full responsible-disclosure policy in SECURITY.md. Coordinated disclosure: 90-day window, no bounty programme but security researchers get public credit on request.

Resilience — AI quota fallback

/api/search and /api/chat depend on Cloudflare Workers AI and Vectorize, both of which have daily quotas. To keep users error-free when those exhaust, both endpoints run three layered fallbacks (see functions/api/_shared.js):

  1. Edge response cache — Workers Cache API, day-bucketed key path. Hot queries replay instantly with zero AI cost. Search TTL 1h, chat TTL 24h.
  2. Neuron budget + circuit breaker — per-day usage counter in KV (ai:neurons:YYYY-MM-DD) against AI_DAILY_BUDGET. Quota-shaped errors (429, codes 3040/7006/9001, or quota|capacity|too many|rate limit|exceeded substrings) flip ai:cb:open for AI_CB_TTL_SEC, short-circuiting subsequent AI calls.
  3. Curated fallback for chat — 30-entry FAQ at functions/api/chat-fallback.json (seeded from cdn/en/content/{faq,pricing,limits}.md). Token-Jaccard match against question variants; replay through the same SSE event sequence (metadata/token/done) so the client only needs metadata.source (ai | cached | curated) and metadata.degraded to render.

Search annotates its mode (vector | fuzzy | cached) on every response. AI failures never surface as 5xx — chat falls back to the curated answer, search falls back to fuzzy.

Scripts

CommandDescription
npm run build:manifestRebuild manifest.json + TypeScript definitions
npm run build:cssRebuild dashboard Tailwind CSS
node scripts/prune-icons.mjsRemove legacy icon variants
node scripts/prune-formats.mjsKeep single source per image
node scripts/generate-client-libs.mjsGenerate API client libraries (JS, TS, Python, cURL)
node scripts/index-assets.mjsBuild Vectorize embeddings for semantic search
node scripts/patch-openapi.mjsPatch OpenAPI spec with missing response codes

Deployment

Pushes to main trigger automatic deployment via Cloudflare Pages:

  1. Verify signatures — every commit must be cryptographically signed
  2. Deploy to edge — wrangler pages deploy to Cloudflare's global network
  3. Compress images — auto-generate WebP/AVIF from new PNGs (signed commit)
  4. Regenerate manifest — update asset registry via GitHub API (signed commit)

Versioning and deprecation

The HTTP API is versioned by date. The current version is surfaced on every response as X-API-Version (currently 2026-04-01). When a new version ships, the previous version is supported for at least 12 months. Sunset dates are announced via the Deprecation and Sunset response headers (RFC 8594) at least 90 days in advance.

The npm package (@sebastienrousseau/cloudcdn-mcp) follows semantic versioning. Breaking changes ship in major versions only.

Contributing and security

  • CONTRIBUTING.md — how to set up the project, send a PR, and meet the commit-signing requirement.
  • SECURITY.md — responsible disclosure + the full security architecture (CSP profiles, signed URLs, HMAC sessions, passkeys, rate limiting, supply chain).
  • CODE_OF_CONDUCT.md — Contributor Covenant 2.1.
  • ARCHITECTURE.md — system layout, request flow, and the AI fallback design.

Deep docs

  • docs/theming.md — the light/dark token system, how to add a new page, why explicit [data-theme] overrides instead of relying on color-scheme inheritance, and the full token table.
  • docs/accessibility.md — WCAG 2.2 AA commitments, the axe-core CI gate, past contrast regressions, and how to audit locally.
  • docs/mcp.md — the MCP tools and resources, what each plane covers, example agent prompts, and how to add a new tool.
  • docs/cli.md — Stratos CLI install, configuration, command reference, and exit codes.
  • docs/STATUS.md — operator transparency: the live /api/health endpoints, internal SLO targets, and how to read an incident.
  • docs/seo.md — sitemap registration and the branded and category search measurement cadence.

License

The project is dual-licensed under your choice of the Apache License 2.0 or MIT license.

Acknowledgements

Built by Sebastien Rousseau on Cloudflare Workers, Pages, KV, Vectorize, and Workers AI.

Ver o original no GitHub

Bom para

Relacionados