@sebastienrousseau/cloudcdn-mcp 0.1.1

package/lib/api-client.js

@@ -0,0 +1,195 @@
+/**
+ * CloudCDN API client — a small `fetch` wrapper used by every MCP tool.
+ *
+ * Reads configuration from environment variables (the MCP host populates
+ * them via the `env` block in its config file):
+ *
+ *   CLOUDCDN_BASE_URL       — API base URL (default: https://cloudcdn.pro)
+ *   CLOUDCDN_ACCESS_KEY     — AccessKey header (storage, assets, insights)
+ *   CLOUDCDN_ACCOUNT_KEY    — AccountKey header (core, pipeline, audit, …)
+ *   CLOUDCDN_PURGE_KEY      — x-api-key header (cache purge)
+ *   CLOUDCDN_ANALYTICS_KEY  — x-api-key header (analytics endpoints)
+ *
+ * Public surface:
+ *
+ *   get(path, opts)           — GET
+ *   post(path, body, opts)    — POST  (JSON body if not a typed array)
+ *   patch(path, body, opts)   — PATCH
+ *   put(path, body, opts)     — PUT
+ *   del(path, opts)           — DELETE
+ *   head(path, opts)          — HEAD
+ *   BASE_URL                  — resolved base URL (read-only)
+ *
+ * Each helper returns `{ ok: boolean, status: number, data: unknown }`.
+ * For non-JSON responses, `data` is `{ contentType, contentLength, url }`
+ * (no body parsing — useful for binary endpoints like /api/transform).
+ *
+ * @module @sebastienrousseau/cloudcdn-mcp/api-client
+ */
+
+const BASE_URL = process.env.CLOUDCDN_BASE_URL || 'https://cloudcdn.pro';
+
+/**
+ * Resolves the auth headers for a request, based on which auth name the
+ * caller picked. Each entry is a thunk so the env vars are read at call
+ * time (not at module load) — keeps tests reliable.
+ *
+ * @type {Record<'access'|'account'|'purge'|'analytics'|'none', () => Record<string, string>>}
+ */
+const AUTH_HEADERS = {
+  access: () => {
+    const key = process.env.CLOUDCDN_ACCESS_KEY;
+    return key ? { AccessKey: key } : {};
+  },
+  account: () => {
+    const key = process.env.CLOUDCDN_ACCOUNT_KEY;
+    return key ? { AccountKey: key } : {};
+  },
+  purge: () => {
+    const key = process.env.CLOUDCDN_PURGE_KEY;
+    return key ? { 'x-api-key': key } : {};
+  },
+  analytics: () => {
+    const key = process.env.CLOUDCDN_ANALYTICS_KEY;
+    return key ? { 'x-api-key': key } : {};
+  },
+  none: () => ({}),
+};
+
+/**
+ * Builds an absolute URL with serialized query params.
+ *
+ * Undefined and null param values are silently dropped — that lets call
+ * sites pass `{ project, format }` even when one of them is unset.
+ *
+ * @param {string} path - Relative API path (e.g. `/api/assets`).
+ * @param {Record<string, unknown>} [params] - Query string parameters.
+ * @returns {string} Fully qualified URL.
+ */
+function buildUrl(path, params = {}) {
+  const url = new URL(path, BASE_URL);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null) {
+      url.searchParams.set(k, String(v));
+    }
+  }
+  return url.toString();
+}
+
+/**
+ * Issues a request and returns the structured response shape used by every
+ * MCP tool handler. Internal — call {@link get}/{@link post}/etc. instead.
+ *
+ * @param {string} method - HTTP verb.
+ * @param {string} path - Relative API path.
+ * @param {object} [opts]
+ * @param {'access'|'account'|'purge'|'analytics'|'none'} [opts.auth='none'] - Auth profile.
+ * @param {Record<string, unknown>} [opts.params] - Query string parameters.
+ * @param {unknown} [opts.body] - Request body (JSON-serialized unless ArrayBuffer/Uint8Array).
+ * @param {Record<string, string>} [opts.headers] - Extra request headers.
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+async function request(method, path, { auth = 'none', params, body, headers: extra } = {}) {
+  const url = buildUrl(path, params);
+  const authHeaders = AUTH_HEADERS[auth]?.() || {};
+
+  const headers = {
+    ...authHeaders,
+    ...extra,
+  };
+
+  const opts = { method, headers };
+
+  if (body !== undefined) {
+    if (body instanceof ArrayBuffer || body instanceof Uint8Array) {
+      opts.body = body;
+    } else {
+      headers['Content-Type'] = 'application/json';
+      opts.body = JSON.stringify(body);
+    }
+  }
+
+  const res = await fetch(url, opts);
+  const contentType = res.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    const data = await res.json();
+    return { ok: res.ok, status: res.status, data };
+  }
+
+  // Non-JSON — return metadata only (binary responses are not buffered).
+  return {
+    ok: res.ok,
+    status: res.status,
+    data: {
+      contentType,
+      contentLength: res.headers.get('content-length'),
+      url,
+    },
+  };
+}
+
+/**
+ * GET — no request body.
+ * @param {string} path
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function get(path, opts) {
+  return request('GET', path, opts);
+}
+
+/**
+ * POST — JSON-serialised body unless a typed array is given.
+ * @param {string} path
+ * @param {unknown} body
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function post(path, body, opts = {}) {
+  return request('POST', path, { ...opts, body });
+}
+
+/**
+ * PATCH — JSON-serialised body unless a typed array is given.
+ * @param {string} path
+ * @param {unknown} body
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function patch(path, body, opts = {}) {
+  return request('PATCH', path, { ...opts, body });
+}
+
+/**
+ * PUT — JSON body by default, raw bytes if `body` is an ArrayBuffer / Uint8Array.
+ * @param {string} path
+ * @param {unknown} body
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function put(path, body, opts = {}) {
+  return request('PUT', path, { ...opts, body });
+}
+
+/**
+ * DELETE — no request body.
+ * @param {string} path
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function del(path, opts) {
+  return request('DELETE', path, opts);
+}
+
+/**
+ * HEAD — no request body, no response body.
+ * @param {string} path
+ * @param {Parameters<typeof request>[2]} [opts]
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown }>}
+ */
+export function head(path, opts) {
+  return request('HEAD', path, opts);
+}
+
+export { BASE_URL };

package/lib/resources/index.js

@@ -0,0 +1,134 @@
+/**
+ * Read-only MCP resources exposed under the `cloudcdn://` scheme.
+ *
+ * Resources are passive — agents read them to populate context — and so
+ * each handler just forwards to a REST endpoint and serialises the JSON
+ * body back. All six refresh on every read.
+ *
+ * @module @sebastienrousseau/cloudcdn-mcp/lib/resources
+ */
+
+import * as api from '../api-client.js';
+
+/**
+ * Register the six MCP resources (`manifest`, `zones`, `rules`, `health`,
+ * `openapi`, `insights-today`) on the given MCP server.
+ *
+ * @param {{ resource: Function }} server - The MCP server instance.
+ * @returns {void}
+ */
+export function registerResources(server) {
+  server.resource(
+    'manifest',
+    'cloudcdn://manifest',
+    {
+      description: 'Complete JSON manifest of all CDN assets with names, paths, projects, categories, formats, and sizes.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/manifest.json');
+      return {
+        contents: [{
+          uri: 'cloudcdn://manifest',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+
+  server.resource(
+    'zones',
+    'cloudcdn://zones',
+    {
+      description: 'List of all CDN zones with file counts and storage usage.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/api/core/zones', { auth: 'account' });
+      return {
+        contents: [{
+          uri: 'cloudcdn://zones',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+
+  server.resource(
+    'rules',
+    'cloudcdn://rules',
+    {
+      description: 'Current _headers and _redirects edge configuration files.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/api/core/rules', { auth: 'account' });
+      return {
+        contents: [{
+          uri: 'cloudcdn://rules',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+
+  server.resource(
+    'health',
+    'cloudcdn://health',
+    {
+      description: 'Live service-health snapshot — binding presence (KV / AI / Vectorize / Durable Object / Queue), per-binding latency, healthy/degraded state. Refresh on every read.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/api/health', { params: { deep: 1 } });
+      return {
+        contents: [{
+          uri: 'cloudcdn://health',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+
+  server.resource(
+    'openapi',
+    'cloudcdn://openapi',
+    {
+      description: 'Full OpenAPI 3.1 specification for the CloudCDN REST API — every path, schema, tag group, security scheme, and example. Agents can read this as the source-of-truth contract when wiring direct HTTP calls.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/api-reference/openapi.json');
+      return {
+        contents: [{
+          uri: 'cloudcdn://openapi',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+
+  server.resource(
+    'insights-today',
+    'cloudcdn://insights/today',
+    {
+      description: 'Current-day insights summary — request volume, bandwidth served, cache hit ratio, top assets, error rate. Pulls from /api/insights/summary; refreshes on every read.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const res = await api.get('/api/insights/summary', { auth: 'access' });
+      return {
+        contents: [{
+          uri: 'cloudcdn://insights/today',
+          mimeType: 'application/json',
+          text: JSON.stringify(res.data, null, 2),
+        }],
+      };
+    }
+  );
+}

package/lib/tools/account.js

@@ -0,0 +1,135 @@
+/**
+ * Account-management + diagnostics MCP tools.
+ *
+ * Wraps the Phase 0 / Phase 1 / Phase 2A endpoints that don't yet have
+ * MCP coverage:
+ *
+ *   - explain_cache_miss        → GET  /api/insights/cache-explain
+ *   - account_cap_get           → GET  /api/account/cap
+ *   - account_cap_set           → PATCH /api/account/cap
+ *   - account_zone_list         → GET  /api/auth/onboarding/zone
+ *   - account_zone_provision    → POST /api/auth/onboarding/zone
+ *
+ * Auth: these endpoints are session-cookie-gated, NOT
+ * AccountKey/AccessKey. The MCP server is account-key-based today, so
+ * the LLM agent needs a session-bearer flow before these calls land
+ * end-to-end. For now the tools surface the response from the API as
+ * the agent sees it (401 unauthenticated when no cookie present) —
+ * useful for the agent to learn what flow to ask the user to run.
+ *
+ * @module @sebastienrousseau/cloudcdn-mcp/lib/tools/account
+ */
+
+import { z } from 'zod';
+import * as api from '../api-client.js';
+
+export function registerAccountTools(server) {
+  server.tool(
+    'explain_cache_miss',
+    'Diagnose why a CloudCDN URL hit or missed the edge cache. Returns the cf-cache-status + age + cache-control + cache-tag + a verdict ("hit_fresh" / "miss_origin_hit" / "bypass_no_store" / etc.) + actionable suggestions ("request again — should HIT", "purge by tag with …"). The URL MUST be on cloudcdn.pro. Session-cookie-gated.',
+    {
+      url: z.string().url().describe('Absolute https://cloudcdn.pro/... URL to inspect'),
+    },
+    async ({ url }) => {
+      const res = await api.get('/api/insights/cache-explain', { params: { url } });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'account_cap_get',
+    "Read the calling account's monthly spend cap in USD. capMode = 'degrade_only' (default — never bill overage; return 402 past zero) or 'hard_cap_with_opt_in_overage' (refuse past N until the user opts into overage billing). Session-cookie-gated.",
+    {},
+    async () => {
+      const res = await api.get('/api/account/cap');
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'account_cap_set',
+    'Set the calling account\'s monthly spend cap in USD. 0 = degrade-only (never bill overage). N > 0 = hard cap at $N/month past which requests return 402. Audit-logged via auditEvent. Session-cookie-gated.',
+    {
+      monthlyCapUsd: z.number().int().min(0).max(1_000_000).describe('Whole USD per calendar month. 0 = never bill overage.'),
+    },
+    async ({ monthlyCapUsd }) => {
+      const res = await api.patch('/api/account/cap', { monthlyCapUsd });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'account_zone_list',
+    'List the calling account\'s provisioned zones (the onboarding-wizard / multi-tenant per-account zones, distinct from the GitOps tenant zones surfaced by `zone_list`). Session-cookie-gated.',
+    {},
+    async () => {
+      const res = await api.get('/api/auth/onboarding/zone');
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'account_zone_provision',
+    'Provision a new account-scoped zone. Validates the origin via HEAD (5s timeout), slugifies the name, persists an account_zones row with an aspirational edge_hostname (<slug>.cdn.cloudcdn.pro) marked live=false until the Phase 3 routing pipeline flips it. Session-cookie-gated.',
+    {
+      name: z.string().min(1).max(64).describe('Display name (will be slugified for the edge hostname)'),
+      originUrl: z.string().url().describe('Origin URL — http:// or https://'),
+    },
+    async ({ name, originUrl }) => {
+      const res = await api.post('/api/auth/onboarding/zone', { name, originUrl });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  // ── Mutations (Phase 2C v2) ───────────────────────────────────
+
+  server.tool(
+    'purge_cache',
+    'Invalidate cached content. Pass `urls` (1-30 absolute https://cloudcdn.pro/... URLs), `tags` (Cache-Tag values), or `everything: true`. Returns the number of items invalidated. AccountKey-gated (uses CLOUDCDN_ACCOUNT_KEY env var).',
+    {
+      urls: z.array(z.string().url()).max(30).optional().describe('Specific URLs to purge (max 30)'),
+      tags: z.array(z.string().min(1).max(128)).max(30).optional().describe('Cache-Tag values to purge (max 30)'),
+      everything: z.boolean().optional().describe('Purge the entire zone — use sparingly (degrades global edge cache for ~5 min).'),
+    },
+    async ({ urls, tags, everything }) => {
+      const body = {};
+      if (urls && urls.length) body.urls = urls;
+      if (tags && tags.length) body.tags = tags;
+      if (everything === true) body.everything = true;
+      const res = await api.post('/api/purge', body);
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'deploy_function',
+    'Create or update an edge-routing rule (a "function" in the rule-engine sense). The body is the same shape as POST /api/core/rules: { name, pattern, action: "rewrite"|"redirect"|"block"|"transform"|"cache", target?, ttl?, priority? }. AccountKey-gated.',
+    {
+      name: z.string().min(1).max(64).describe('Human-friendly rule name'),
+      pattern: z.string().min(1).max(512).describe('URL pattern to match (glob or regex, see /api/core/rules docs)'),
+      action: z.enum(['rewrite', 'redirect', 'block', 'transform', 'cache']).describe('What the rule does when matched'),
+      target: z.string().max(512).optional().describe('Destination URL/path for rewrite|redirect actions'),
+      ttl: z.number().int().min(0).max(31_536_000).optional().describe('Cache TTL in seconds (for action=cache)'),
+      priority: z.number().int().min(0).max(1000).optional().describe('Lower wins. Default = 100.'),
+    },
+    async (input) => {
+      const res = await api.post('/api/core/rules', input);
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'get_analytics',
+    'Fetch account-wide statistics for a time range. Returns request counts, cache hit ratio, bytes served, AI invocations, error breakdown. Use `zone` to scope to a specific tenant zone; omit for account-wide. AccountKey-gated.',
+    {
+      zone: z.string().min(1).max(128).optional().describe('Zone slug (omit for account-wide)'),
+      range: z.enum(['1h', '24h', '7d', '30d']).default('24h').describe('Time range. 30d max on free tier.'),
+    },
+    async ({ zone, range }) => {
+      const params = { range };
+      if (zone) params.zone = zone;
+      const res = await api.get('/api/core/statistics', { params });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+}

package/lib/tools/ai.js

@@ -0,0 +1,148 @@
+/**
+ * AI / search MCP tools — semantic search, RAG concierge, vision
+ * endpoints, and placeholder generators. All are public-access.
+ *
+ * The vision and chat endpoints share a Workers AI budget guard; when the
+ * daily quota trips, responses flip to cached / fuzzy / curated mode and
+ * mark themselves with `degraded: true` so agents don't need to branch.
+ *
+ * @module @sebastienrousseau/cloudcdn-mcp/lib/tools/ai
+ */
+
+import { z } from 'zod';
+import * as api from '../api-client.js';
+
+const URL_PATH = z.string()
+  .min(1)
+  .max(2048)
+  .describe('Relative asset path (e.g. "/clients/akande/v1/logos/logo.svg"). Absolute URLs are rejected.');
+
+/**
+ * Register the AI tools (`semantic_search`, `health_check`,
+ * `generate_alt_text`, `smart_crop`, `moderate_image`, `placeholder_lqip`,
+ * `placeholder_blurhash`, `chat_ask`, `remove_background`) on the given
+ * MCP server.
+ *
+ * @param {{ tool: Function }} server - The MCP server instance.
+ * @returns {void}
+ */
+export function registerAiTools(server) {
+  server.tool(
+    'semantic_search',
+    'Search the asset catalog using natural language. Uses vector similarity (Cloudflare Vectorize) with fuzzy text fallback. Returns `mode: vector|fuzzy|cached` so agents can tell which layer responded; `degraded: true` indicates the AI path is bypassed (quota exhausted or unavailable).',
+    {
+      q: z.string().describe('Natural language search query (e.g., "dark blue banking background")'),
+      limit: z.number().int().min(1).max(50).default(20).optional(),
+    },
+    async ({ q, limit }) => {
+      const res = await api.get('/api/search', { params: { q, limit } });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'health_check',
+    'Check the health status of the CloudCDN service and the availability of its backend bindings (KV, AI, Vectorize).',
+    {},
+    async () => {
+      const res = await api.get('/api/health');
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'generate_alt_text',
+    'Generate a short, accessibility-quality alt-text description for an image using a Workers AI vision model. Caches the result for 24 h. Returns `{ alt, model, source: "ai"|"cached", degraded, dateGenerated }`. Useful at upload time to seed an `alt=` attribute, or on-demand for authoring tools.',
+    { url: URL_PATH },
+    async ({ url }) => {
+      const res = await api.post('/api/ai/alt-text', { url });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'smart_crop',
+    'Identify where the visual subject of an image sits and return a `gravity` value compatible with /api/transform. Output is one of nine compass directions plus "face" and "center", with a confidence band (`high|medium|low`). Chain with the transform tool to get a subject-aware square thumbnail.',
+    { url: URL_PATH },
+    async ({ url }) => {
+      const res = await api.post('/api/ai/smart-crop', { url });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'moderate_image',
+    'Classify an image\'s safety across five categories (nudity, violence, drugs, hate symbols, gore) using a Workers AI vision model. Returns `{ safe, verdict: "safe"|"borderline"|"unsafe", categories: { ...0-1 floats }, reasoning }`. Use as an automated gate during upload pipelines — on unparseable output the endpoint conservatively returns "borderline" so the caller still has to decide.',
+    { url: URL_PATH },
+    async ({ url }) => {
+      const res = await api.post('/api/ai/moderate', { url });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'placeholder_lqip',
+    'Generate a low-quality image placeholder (LQIP) as a base64 data URI. Useful for progressive-loading UIs that need an immediate visual placeholder while the full asset streams in. Returns `{ lqip: "data:image/webp;base64,...", bytes, width, dateGenerated }`. The result is deterministic per (url, size, blur) and cached for 24 h.',
+    {
+      url: URL_PATH,
+      size: z.number().int().min(8).max(64).default(32).optional()
+        .describe('Width of the downsampled placeholder in pixels. Clamped to [8, 64].'),
+      blur: z.number().int().min(1).max(250).default(30).optional()
+        .describe('Gaussian blur radius applied by Cloudflare Image Resizing.'),
+    },
+    async ({ url, size, blur }) => {
+      const params = { url };
+      if (size !== undefined) params.size = size;
+      if (blur !== undefined) params.blur = blur;
+      const res = await api.get('/api/lqip', { params });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'placeholder_blurhash',
+    'Generate a content-addressable placeholder hash (40-char SHA-256 prefix) plus a base64 data URI for an image. Companion to the LQIP tool — same downsampled WebP, but the hash is a stable key clients can use to dedupe placeholders or persist them by content. Cached for 24 h per (url, size) tuple.',
+    {
+      url: URL_PATH,
+      size: z.number().int().min(8).max(64).default(32).optional()
+        .describe('Width of the downsampled placeholder in pixels.'),
+    },
+    async ({ url, size }) => {
+      const params = { url };
+      if (size !== undefined) params.size = size;
+      const res = await api.get('/api/blurhash', { params });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'chat_ask',
+    'Ask the CloudCDN AI concierge a natural-language question about the platform — pricing, limits, how to use a specific endpoint, troubleshooting, etc. The concierge is a RAG agent over the `cdn/en/content/` knowledge base. Returns `{ answer, sources: string[], confidence: "high"|"medium"|"low", source: "ai"|"cached"|"curated", degraded: boolean }`. When AI quota is exhausted the curated 30-entry FAQ takes over (`source: "curated"`); the contract is identical so agents need no special branching.',
+    {
+      question: z.string().min(1).max(2000).describe('Free-form question. Be specific — "how do I purge by tag" beats "purge help".'),
+    },
+    async ({ question }) => {
+      const res = await api.post('/api/chat', { messages: [{ role: 'user', content: question }] });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'remove_background',
+    'Remove the background from an image, isolating the subject on a transparent alpha layer. **Not yet implemented** — the endpoint returns HTTP 501 because Cloudflare Workers AI does not currently include a segmentation/matting model (U^2-Net / rembg-class). The route is documented and discoverable so agents and clients can integrate ahead of the model landing; when a model becomes available the implementation will swap in without changing this contract. Use the smart_crop tool today for subject-aware framing as the nearest substitute.',
+    { url: URL_PATH },
+    async ({ url }) => {
+      // Intentionally lenient: this endpoint always returns 501, and we
+      // surface that to the agent as a structured tool result rather than
+      // a thrown error — agents should be able to read the "blocked by
+      // dependency" message and route around it.
+      try {
+        const res = await api.post('/api/ai/background-remove', { url });
+        return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+      } catch (err) {
+        const body = err?.response?.data ?? { error: { code: 'NotImplemented', message: err?.message || String(err) } };
+        return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+      }
+    }
+  );
+}

package/lib/tools/assets.js

@@ -0,0 +1,66 @@
+/**
+ * Asset-catalog MCP tools — browse, fetch metadata, and search the
+ * read-side asset index. AccessKey auth on every call.
+ *
+ * @module @sebastienrousseau/cloudcdn-mcp/lib/tools/assets
+ */
+
+import { z } from 'zod';
+import * as api from '../api-client.js';
+
+/**
+ * Register the asset tools (`assets_list`, `asset_metadata_get`,
+ * `assets_search`) on the given MCP server.
+ *
+ * @param {{ tool: Function }} server - The MCP server instance.
+ * @returns {void}
+ */
+export function registerAssetsTools(server) {
+  server.tool(
+    'assets_list',
+    'Browse and search the CDN asset catalog with filtering by project, category, and format. Supports pagination and sorting.',
+    {
+      project: z.string().optional().describe('Filter by project/zone name'),
+      category: z.string().optional().describe('Filter by category (logos, banners, icons, etc.)'),
+      format: z.string().optional().describe('Filter by file format (svg, png, webp, avif, ico)'),
+      q: z.string().optional().describe('Search query for filename or path'),
+      page: z.number().int().min(1).default(1).optional(),
+      per_page: z.number().int().min(1).max(200).default(50).optional(),
+      sort: z.enum(['name', 'size', 'project']).default('name').optional(),
+      order: z.enum(['asc', 'desc']).default('asc').optional(),
+    },
+    async (params) => {
+      const res = await api.get('/api/assets', { auth: 'access', params });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'asset_metadata_get',
+    'Get the full metadata record for a single asset by path: dimensions, format, size, project, category, ETag, content hash, and any AI-derived fields (alt text, smart-crop gravity, dominant colors) cached against it. Use this before a transform or to populate a card UI.',
+    {
+      path: z.string().min(1).max(1024).describe('Relative asset path (e.g. "/akande/v1/logos/akande.svg")'),
+    },
+    async ({ path }) => {
+      const res = await api.get('/api/assets/metadata', { auth: 'access', params: { path } });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'assets_search',
+    'Search for assets by name or path. Returns matching assets with metadata.',
+    {
+      q: z.string().describe('Search query (e.g., "logo", "banner-bankingonai")'),
+      project: z.string().optional().describe('Narrow search to a specific project'),
+      format: z.string().optional().describe('Narrow search to a specific format'),
+    },
+    async ({ q, project, format }) => {
+      const params = { q, per_page: 50 };
+      if (project) params.project = project;
+      if (format) params.format = format;
+      const res = await api.get('/api/assets', { auth: 'access', params });
+      return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+}