feat(mcp): media facet — the 1.10.0 media tools over MCP Cloud (#146)

Implements RepoProvider.media on the loopback provider so
contentrain_media_list/get/ingest/update/delete work on both MCP Cloud
surfaces, with policy at the proxy and mechanism at the loopback.

- server/utils/mcp-media-facet.ts: the contract MediaProvider as a
  deterministic passthrough over Studio's ee media stack — cursor
  pagination, tenant isolation (get→null / update+delete→404 on foreign
  assets), and the ingest quota dance (fetchRemoteMedia SSRF/MIME/size →
  reserveStorageIfAllowed → upload source:'agent' → reconcile/release).
  Returns null when useMediaProvider() is null (CE / no R2) so the
  tools stay hidden.
- proxy: STUDIO_HEADERS + x-cr-{project-id,workspace-id,media-owner,plan},
  injected ONLY when mediaEligible (media stack + plan media.upload +
  cdn_enabled + owner). Media tools are excluded from the empty-allowlist
  "unrestricted" rule — a key needs media_enabled or an explicit listing,
  so existing keys never silently gain URL ingest / destructive delete.
- loopback: resolveProvider builds the facet from the four proxy headers;
  git.ts carries RepoProvider.media; the tenant fingerprint gains the
  project id so an eligibility flip re-inits the session within a request.
- key surface: mcp_cloud_keys.media_enabled (migration 018, default false)
  + create route + panel "Allow media tools" toggle + Media badge.
- OAuth: advertisedScopes() adds media:read/media:write only where the
  media stack is configured; the 4 well-known routes inject availability;
  scope→tool mapping + step-up already routed media (from #145).
- deps already at 1.10.0 (#145). openWorldHint present on all 24 tools.
- tests: facet unit suite (18), fingerprint + scope/metadata units,
  proxy eligibility matrix + key media gate + oauth media path, contract
  media_enabled column case. lint/typecheck clean; unit+integration+nuxt
  1048, contract 105, managed e2e 12/12 (media absent without R2).

Co-authored-by: Contentrain <mcp@contentrain.io>

Author: ABB65

.contentrain/content/system/error-messages/en.json

@@ -140,9 +140,11 @@
   "media.file_not_found_storage": "The file was not found in storage. It may have been removed.",
   "media.file_too_large": "File exceeds {limit}MB limit.",
   "media.file_type_not_allowed": "File type not allowed: {type}",
+  "media.invalid_cursor": "Invalid pagination cursor. Start a new listing without a cursor.",
   "media.library_upgrade": "Asset Manager is available on all plans. {plan} includes {mediaStorage} storage. Upgrade to {toPlan} for {toMediaStorage} storage and custom variants.",
   "media.list_failed": "Failed to list media assets: {detail}",
   "media.no_file_provided": "No file was provided for upload.",
+  "media.rename_not_supported": "Renaming media assets is not supported over MCP. Update alt text or tags instead.",
   "media.storage_not_configured": "Media storage is not configured. Contact your administrator to set up R2 storage credentials.",
   "media.update_failed": "Failed to update media asset: {detail}",
   "media.upload_upgrade": "Media upload is available on all plans. {plan} includes {mediaStorage} storage and {maxFileSize} file size limit. Upgrade to {toPlan} for {toMediaStorage} storage and {toMaxFileSize} file limit.",

.contentrain/content/system/ui-strings/en.json

@@ -471,6 +471,9 @@
   "mcp_cloud.key_created_title": "API key created",
   "mcp_cloud.key_created_warning": "Copy your key now — it won't be shown again.",
   "mcp_cloud.last_used": "Last used {when}",
+  "mcp_cloud.media_badge": "Media",
+  "mcp_cloud.media_enabled_hint": "Lets this key list, ingest (from a URL), update and delete media assets. Requires the media add-on and CDN delivery on the project.",
+  "mcp_cloud.media_enabled_label": "Allow media tools",
   "mcp_cloud.name_label": "Key name",
   "mcp_cloud.name_placeholder": "My MCP agent",
   "mcp_cloud.never_used": "Never used",

CLAUDE.md

@@ -293,6 +293,22 @@ rate-limited but free. Keys live in `mcp_cloud_keys` (SHA-256 hashed); UI is
 (15 min TTL). Multiple instances need sticky sessions for `mcp-session-id`
 affinity; rate limit (Redis) and quota (DB) are already instance-safe.
 
+**Media facet (MCP 1.10.0's 5 media tools).** The facet is
+`RepoProvider.media` — absent = the tools are hidden from `tools/list`.
+Policy lives at the **proxy** (`runMcpCloudProxy` computes `mediaEligible`
+= media stack + plan `media.upload` + project `cdn_enabled` + workspace
+owner), which injects `x-cr-project-id`/`x-cr-workspace-id`/`x-cr-media-owner`/`x-cr-plan`
+ONLY when eligible; the loopback (`mcp-cloud-server.ts`) turns those into
+`buildMcpMediaFacet` (`server/utils/mcp-media-facet.ts`), a passthrough
+over the ee media stack (`useMediaProvider`) that owns SSRF/MIME/size (via
+`fetchRemoteMedia`) + storage-quota + tenant isolation. Key-surface
+exception: media tools are **never** covered by the empty-`allowed_tools`
+"unrestricted" rule — a key needs `media_enabled=true` or an explicit
+listing (else existing keys would silently gain URL ingest + destructive
+delete). OAuth advertises `media:read`/`media:write` only where the media
+stack is configured (`advertisedScopes`). The tenant fingerprint includes
+project id, so an eligibility flip re-inits the session within one request.
+
 **Two deliberate boundaries — keep them in mind when changing this path:**
 
 - **Reduced tool surface.** The loopback server runs against Studio's

app/components/organisms/WorkspaceMcpCloudPanel.vue

@@ -14,6 +14,7 @@ interface McpCloudKey {
   key_prefix: string
   project_id: string
   allowed_tools: string[]
+  media_enabled: boolean
   rate_limit_per_minute: number
   monthly_call_limit: number | null
   last_used_at: string | null
@@ -33,6 +34,7 @@ const loading = ref(true)
 
 const newKeyName = ref('')
 const newKeyProjectId = ref<string>('')
+const newKeyMediaEnabled = ref(false)
 const creating = ref(false)
 
 const revealedKey = ref<string | null>(null)
@@ -118,13 +120,15 @@ async function handleCreate() {
         body: {
           name: newKeyName.value.trim(),
           projectId: newKeyProjectId.value,
+          mediaEnabled: newKeyMediaEnabled.value,
         },
       },
     )
     revealedKey.value = created.key
     revealedProjectId.value = created.project_id ?? newKeyProjectId.value
     revealDialogOpen.value = true
     newKeyName.value = ''
+    newKeyMediaEnabled.value = false
     toast.success(t('mcp_cloud.create_success'))
     await refresh()
   }
@@ -198,8 +202,13 @@ function formatRelative(iso: string | null): string {
         <li v-for="key in keys" :key="key.id" class="flex items-center gap-3 px-4 py-3">
           <span class="icon-[annon--key] size-4 text-muted" aria-hidden="true" />
           <div class="min-w-0 flex-1">
-            <div class="truncate text-sm font-medium text-heading dark:text-secondary-100">
-              {{ key.name }}
+            <div class="flex items-center gap-2">
+              <span class="truncate text-sm font-medium text-heading dark:text-secondary-100">
+                {{ key.name }}
+              </span>
+              <AtomsBadge v-if="key.media_enabled" variant="info" size="sm">
+                {{ t('mcp_cloud.media_badge') }}
+              </AtomsBadge>
             </div>
             <div class="text-xs text-muted">
               <span class="font-mono">{{ key.key_prefix }}…</span>
@@ -250,6 +259,16 @@ function formatRelative(iso: string | null): string {
             class="mt-1.5"
           />
         </div>
+        <div>
+          <AtomsFormSwitch
+            :model-value="newKeyMediaEnabled"
+            :label="t('mcp_cloud.media_enabled_label')"
+            @update:model-value="newKeyMediaEnabled = $event"
+          />
+          <p class="mt-1 text-xs text-muted">
+            {{ t('mcp_cloud.media_enabled_hint') }}
+          </p>
+        </div>
         <AtomsBaseButton type="submit" variant="primary" size="md" :disabled="!newKeyName.trim() || !newKeyProjectId || creating">
           {{ creating ? t('mcp_cloud.creating') : t('mcp_cloud.create') }}
         </AtomsBaseButton>

docs/REMOTE_MCP.md

@@ -36,12 +36,24 @@ different project (the old connection stays until you disconnect it).
 | `project:metadata` | Project structure reads: `status`, `describe`, `describe_format` |
 | `content:read` | Content reads: `content_list`, `validate`, … |
 | `content:write` | Content/model writes: `content_save`, `content_delete`, `model_save`, `model_delete` |
+| `media:read` | Media reads: `media_list`, `media_get` |
+| `media:write` | Media writes: `media_ingest` (from a URL), `media_update`, `media_delete` |
 | `offline_access` | A refresh token (stay connected without re-approving) |
 
-`media:read` / `media:write` are reserved for the media stack and grant no
-tools yet. Studio's merge/review lifecycle tools are never exposed over
-remote MCP — writes land as `cr/*` branches and follow the project's
-workflow (auto-merge or review), exactly like the API-key surface.
+The `media:*` scopes are **advertised only on deployments where the media
+stack is configured** (Enterprise + object storage). The media tools
+additionally require the workspace plan's `media.upload` feature and the
+project's CDN delivery being enabled — where any of those is missing, the
+tools don't appear at all. Ingest is **URL-only** (MCP has no binary
+channel) and the fetch is SSRF-guarded, MIME-whitelisted and size-capped
+server-side. Studio's merge/review lifecycle tools are never exposed over
+remote MCP — content writes land as `cr/*` branches and follow the
+project's workflow (auto-merge or review), exactly like the API-key
+surface; media writes go through the media service, not git.
+
+API keys never gain media tools implicitly: an "unrestricted" key (empty
+tool list) still cannot call them — media access must be explicitly
+enabled per key (the "Allow media tools" toggle, or by listing the tools).
 
 Calls from remote MCP connections and API keys draw on the **same**
 `api.mcp_calls_per_month` workspace quota.

server/api/mcp/remote/[...slug].ts

@@ -53,15 +53,15 @@ export default defineEventHandler(async (event) => {
 
   const project = await db.getProjectById(
     grant.projectId,
-    'id, repo_full_name, content_root, workspace_id',
+    'id, repo_full_name, content_root, workspace_id, cdn_enabled',
   )
   if (!project || project.workspace_id !== grant.workspaceId) {
     throw createError({ statusCode: 404, message: errorMessage('project.not_found') })
   }
 
   const workspace = await db.getWorkspaceById(
     grant.workspaceId,
-    'id, github_installation_id, plan, overage_settings',
+    'id, github_installation_id, plan, overage_settings, owner_id',
   )
   if (!workspace?.github_installation_id) {
     throw createError({ statusCode: 400, message: errorMessage('github.installation_missing') })
@@ -87,6 +87,8 @@ export default defineEventHandler(async (event) => {
     installationId: workspace.github_installation_id as number,
     repoFullName: project.repo_full_name as string,
     contentRoot: (project.content_root as string | null) ?? '',
+    cdnEnabled: project.cdn_enabled === true,
+    mediaOwnerId: (workspace.owner_id as string | null) ?? null,
     allowedTools: toolsForScope(grant.scope),
     rateLimitPerMinute: OAUTH_RATE_LIMIT_PER_MINUTE,
     rateLimitKey: `mcp-oauth:${grant.grantId}`,

server/api/mcp/v1/[projectId]/[...slug].ts

@@ -42,15 +42,15 @@ export default defineEventHandler(async (event) => {
 
   const project = await db.getProjectById(
     keyData.projectId,
-    'id, repo_full_name, content_root, workspace_id',
+    'id, repo_full_name, content_root, workspace_id, cdn_enabled',
   )
   if (!project || project.workspace_id !== keyData.workspaceId) {
     throw createError({ statusCode: 404, message: errorMessage('project.not_found') })
   }
 
   const workspace = await db.getWorkspaceById(
     keyData.workspaceId,
-    'id, github_installation_id, plan, overage_settings',
+    'id, github_installation_id, plan, overage_settings, owner_id',
   )
   if (!workspace?.github_installation_id) {
     throw createError({ statusCode: 400, message: errorMessage('github.installation_missing') })
@@ -69,6 +69,9 @@ export default defineEventHandler(async (event) => {
     installationId: workspace.github_installation_id as number,
     repoFullName: project.repo_full_name as string,
     contentRoot: (project.content_root as string | null) ?? '',
+    cdnEnabled: project.cdn_enabled === true,
+    mediaOwnerId: (workspace.owner_id as string | null) ?? null,
+    mediaToolsOptIn: keyData.mediaEnabled,
     allowedTools: keyData.allowedTools,
     rateLimitPerMinute: keyData.rateLimitPerMinute,
     rateLimitKey: `mcp-cloud:${keyData.keyId}`,

server/api/workspaces/[workspaceId]/mcp-cloud-keys/index.post.ts

@@ -20,6 +20,7 @@ interface CreateKeyInput {
   projectId: string
   name: string
   allowedTools?: string[]
+  mediaEnabled?: boolean
   rateLimitPerMinute?: number
   monthlyCallLimit?: number | null
 }
@@ -93,6 +94,7 @@ export default defineEventHandler(async (event) => {
     keyHash,
     keyPrefix,
     allowedTools,
+    mediaEnabled: body.mediaEnabled === true,
     rateLimitPerMinute: body.rateLimitPerMinute,
     monthlyCallLimit: body.monthlyCallLimit ?? null,
     createdBy: session.user.id,
@@ -105,6 +107,7 @@ export default defineEventHandler(async (event) => {
     name: row.name,
     projectId: row.project_id,
     allowedTools: row.allowed_tools ?? [],
+    mediaEnabled: row.media_enabled === true,
     rateLimitPerMinute: row.rate_limit_per_minute,
     monthlyCallLimit: row.monthly_call_limit,
     createdAt: row.created_at,

server/plugins/mcp-cloud-server.ts

@@ -27,13 +27,27 @@
 
 import { startHttpMcpServerWith } from '@contentrain/mcp/server/http'
 import { createStudioGitProvider } from '../providers/git'
+import { buildMcpMediaFacet } from '../utils/mcp-media-facet'
 import { closeInternalMcp, mcpTenantFingerprint, setInternalMcp } from '../utils/mcp-cloud-runtime'
+import type { Plan } from '../utils/license'
 
 const HEADER_INSTALLATION_ID = 'x-cr-installation-id'
 const HEADER_REPO_OWNER = 'x-cr-repo-owner'
 const HEADER_REPO_NAME = 'x-cr-repo-name'
 const HEADER_CONTENT_ROOT = 'x-cr-content-root'
 const HEADER_MEDIA_BASE = 'x-cr-media-base'
+// Media facet identity — injected by the proxy only for media-eligible
+// requests (plan + cdn_enabled + media stack checked proxy-side). All
+// four must be present or the facet is not built and the media tools
+// stay hidden from tools/list.
+const HEADER_PROJECT_ID = 'x-cr-project-id'
+const HEADER_WORKSPACE_ID = 'x-cr-workspace-id'
+const HEADER_MEDIA_OWNER = 'x-cr-media-owner'
+const HEADER_PLAN = 'x-cr-plan'
+
+function headerString(value: string | string[] | undefined): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
 
 export default defineNitroPlugin((nitroApp) => {
   // Fire-and-forget: we do not want to block Nitro's startup on an
@@ -83,6 +97,18 @@ async function bootInternalMcpServer(): Promise<void> {
       // same absolute URLs Studio's own write path produces.
       const mediaBase = headers[HEADER_MEDIA_BASE]
 
+      // Media facet — built only when the proxy attested eligibility by
+      // injecting ALL four identity headers (client values are stripped
+      // proxy-side, so these are trusted). Absent set → no facet → the 5
+      // media tools stay out of this session's tools/list.
+      const projectId = headerString(headers[HEADER_PROJECT_ID])
+      const workspaceId = headerString(headers[HEADER_WORKSPACE_ID])
+      const mediaOwner = headerString(headers[HEADER_MEDIA_OWNER])
+      const plan = headerString(headers[HEADER_PLAN])
+      const media = (projectId && workspaceId && mediaOwner && plan)
+        ? buildMcpMediaFacet({ projectId, workspaceId, uploadedBy: mediaOwner, plan: plan as Plan }) ?? undefined
+        : undefined
+
       return createStudioGitProvider({
         installationId,
         owner,
@@ -93,6 +119,7 @@ async function bootInternalMcpServer(): Promise<void> {
         mediaBaseUrl: typeof mediaBase === 'string' && mediaBase.length > 0
           ? mediaBase
           : undefined,
+        media,
       })
     },
   })

server/providers/database.ts

@@ -630,6 +630,7 @@ export interface DatabaseProvider {
     keyHash: string
     keyPrefix: string
     allowedTools: string[]
+    mediaEnabled?: boolean
     rateLimitPerMinute?: number
     monthlyCallLimit?: number | null
     createdBy?: string | null