drupal-mcp-connector 2.16.0 → 2.17.0

package/.agents/commands/drupal-create-translation.md

@@ -1,11 +1,11 @@
 ---
-description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
+description: "Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers."
 argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; continue a paragraph with drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
+Create a translation as an unpublished non-default draft (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. When an English working draft already exists, both live and working revision IDs are sent (If-Match) so Sentinel will add the language on that draft (#282). English live title, body, status, alias, default revision, and paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. The response includes `_revisions.live` / `_revisions.working` when known. Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. Continue a node draft with drupal_update_node and langcode; a paragraph with drupal_update_paragraph and langcode; media with drupal_update_media and langcode. Image alt is a relationship (same file UUID, meta.alt) — on media that is field_media_image, not a node image field. For paragraphs pass revisionId as the host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied for content-tier callers.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,7 +16,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
-- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values, 'media' for media (name, caption, image alt).
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
 - `relationships` (object (pass as JSON)): JSON:API relationships. Use for image alt (same file UUID, meta.alt).
 - `revisionId` (string): Paragraph revision id the host already pins. Required for Home-shaped non-default pins.

package/.agents/commands/drupal-get-media.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single media entity by UUID and media type."
-argument-hint: "<type> <id> [site]"
+description: "Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel."
+argument-hint: "<type> <id> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_media`.
 
-Fetch a single media entity by UUID and media type.
+Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language (e.g. 'es') to read the unpublished working translation instead of the default language.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-list-translations.md

@@ -1,11 +1,11 @@
 ---
-description: "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node."
+description: "List live and working translation langcodes for a Drupal node, paragraph, or media entity. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node."
 argument-hint: "<type> <id> [site] [entityType]"
 ---
 
 Call the MCP tool `drupal_list_translations`.
 
-List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node.
+List live and working translation langcodes for a Drupal node, paragraph, or media entity. Uses Sentinel's translation inventory when available (live default revision vs unpublished working draft), including core content_translation_outdated and source when the server sends them. Core JSON:API alone serves one language and cannot prove others are absent. Defaults to node.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,6 +15,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
-- `entityType` (string): Entity type machine name. Default: 'node'.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' or 'media' when listing those.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-update-media.md

@@ -1,11 +1,11 @@
 ---
-description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched."
-argument-hint: "<type> <id> [site] [name] [status] [fields]"
+description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first."
+argument-hint: "<type> <id> [site] [name] [status] [fields] [langcode]"
 ---
 
 Call the MCP tool `drupal_update_media`.
 
-Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.
+Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -17,6 +17,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `name` (string)
 - `status` (boolean (true/false)): Published flag. Only sent when provided; requires allowPublish when true.
-- `fields` (object (pass as JSON)): Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically.
+- `fields` (object (pass as JSON)): Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically. Image alt is meta.alt on field_media_image with the existing file UUID.
+- `langcode` (string): Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.17.0] - 2026-09-11
+
+### Added
+- **Governed media draft translation (#296).** `drupal_create_translation` and
+  `drupal_list_translations` accept `entityType: "media"`. Continue with
+  `drupal_update_media` + `langcode`; read with `drupal_get_media` + `langcode`.
+  Same Sentinel `/mcp-draft` live/working pair as nodes (d.o #3622412). Image
+  alt/title are kept on the file relationship (`meta.alt` / `meta.title`) so a
+  translator can read the source. Canonical media writes without `langcode` are
+  unchanged. Requires MCP Sentinel with media draft routes.
+
+### Security
+- Bump transitive `hono` 4.13.1 → 4.13.7 (via `@modelcontextprotocol/node`)
+  and override it to `^4.13.5`, clearing three moderate advisories:
+  GHSA-gqvv-2mrq-wpjv (`toSSG()` path traversal), GHSA-g6gw-c38x-mqfc
+  (`parseBody()` unbounded nesting), and GHSA-crvj-82cr-hjcx (query parser
+  after URL fragment). `npm audit` reports 0 vulnerabilities (#299).
+
 ## [2.16.0] - 2026-09-11
 
 ### Added
@@ -1620,6 +1638,7 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.17.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.17.0
 [2.16.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.16.0
 [2.15.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.2
 [2.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",
@@ -83,6 +83,7 @@
   },
   "overrides": {
     "@hono/node-server": "^2.0.5",
+    "hono": "^4.13.5",
     "postcss": "^8.5.18"
   }
 }

package/src/lib/canonical.js

@@ -65,14 +65,19 @@ export function normalizeRelationship(ref) {
   // JSON:API encodes type as "entityType--bundle"; split into the two parts.
   const [entityType = null, bundle = null] = (ref.type || "").split("--");
   const out = { id: ref.id, entityType, bundle };
-  // ERR identifiers carry the revision id in JSON:API `meta` (#192). Dropping
-  // it made every canonical re-read look like a plain {id, type} even when the
-  // write sent target_revision_id.
+  // ERR identifiers carry the revision id in JSON:API `meta` (#192). Image
+  // fields carry alt/title the same way (#296). Dropping either made a
+  // canonical re-read look like a plain {id, type}.
   if (ref.meta && typeof ref.meta === "object") {
-    const vid = new Map(Object.entries(ref.meta)).get("target_revision_id");
+    const entries = new Map(Object.entries(ref.meta));
+    const meta = {};
+    const vid = entries.get("target_revision_id");
     if (vid !== undefined && vid !== null && vid !== "") {
-      out.meta = { target_revision_id: vid };
+      meta.target_revision_id = vid;
     }
+    if (typeof entries.get("alt") === "string") meta.alt = entries.get("alt");
+    if (typeof entries.get("title") === "string") meta.title = entries.get("title");
+    if (Object.keys(meta).length > 0) out.meta = meta;
   }
   return out;
 }

package/src/lib/draft-write.js

@@ -46,7 +46,7 @@ function requireWorkingPair(draftRevision) {
   const live = String(draftRevision?.liveVid ?? "");
   const working = String(draftRevision?.workingVid ?? "");
   if (!/^[1-9]\d*$/.test(live) || !/^[1-9]\d*$/.test(working) || live === working) {
-    throw new Error("Draft continuation requires distinct, verified live and working node revision IDs.");
+    throw new Error("Draft continuation requires distinct, verified live and working revision IDs.");
   }
   return { live, working };
 }
@@ -59,8 +59,8 @@ function requireWorkingPair(draftRevision) {
  * @returns {string}
  */
 function draftResource(backend, entityType, bundle, id) {
-  if (entityType !== "node" && entityType !== "paragraph") {
-    throw new Error("Governed draft translation is implemented for nodes and paragraphs.");
+  if (entityType !== "node" && entityType !== "paragraph" && entityType !== "media") {
+    throw new Error("Governed draft translation is implemented for nodes, paragraphs, and media.");
   }
   if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
     throw new Error("This backend does not support governed draft continuation.");
@@ -150,8 +150,8 @@ export async function createTranslationDraft(backend, input, preflight = false)
   const working = workingRaw === undefined || workingRaw === null || workingRaw === ""
     ? ""
     : String(workingRaw);
-  if (entityType !== "node" || !/^[1-9]\d*$/.test(live)) {
-    throw new Error("Translation create requires a verified live node revision ID.");
+  if ((entityType !== "node" && entityType !== "media") || !/^[1-9]\d*$/.test(live)) {
+    throw new Error("Translation create requires a verified live revision ID.");
   }
   if (working && (!/^[1-9]\d*$/.test(working) || working === live)) {
     throw new Error("Translation create requires distinct live and working revision IDs when a working copy exists.");

package/src/lib/node-draft-inventory.js

@@ -9,7 +9,8 @@ import { readTranslationInventory } from "./draft-write.js";
  * @returns {Promise<object|null>}
  */
 export async function readNodeDraftInventory(backend, ref) {
-  if (ref.entityType !== "node" || typeof backend.rawQuery !== "function"
+  if ((ref.entityType !== "node" && ref.entityType !== "media")
+    || typeof backend.rawQuery !== "function"
     || typeof backend.resourcePath !== "function") return null;
   let inventory;
   try {
@@ -24,7 +25,7 @@ export async function readNodeDraftInventory(backend, ref) {
       || !Array.isArray(inventory.working.translations)
       || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
         || typeof row.status !== "boolean")))) {
-    throw new Error("Sentinel returned an invalid node revision inventory. Re-read before updating.");
+    throw new Error("Sentinel returned an invalid revision inventory. Re-read before updating.");
   }
   return inventory;
 }

package/src/tools/media.js

@@ -14,6 +14,11 @@ import {
   resolveSecurityConfig, redactCanonicalEntity,
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
+import {
+  assertDraftLangcode, readDraftTranslation, readTranslationInventory, writeDraft,
+} from "../lib/draft-write.js";
+import { assertInventoryDraftLanguage } from "../lib/node-draft-inventory.js";
+import { entityRevisionId } from "../lib/write-revision.js";
 
 /**
  * List all media types (bundles of the media entity type).
@@ -51,14 +56,39 @@ async function listMedia({ site: siteName, type, status, name, limit = 20, offse
 
 /**
  * Fetch a single media entity by UUID, redacted per policy.
- * @param {object} args - { site?, type, id }.
+ * Pass langcode to read an unpublished working translation via Sentinel.
+ * @param {object} args - { site?, type, id, langcode? }.
  * @returns {Promise<object|null>} The redacted media entity, or null.
  */
-async function getMedia({ site: siteName, type, id }) {
+async function getMedia({ site: siteName, type, id, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "media", type);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "media", bundle: type, id });
+    const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
+    if (workingRow && workingRow.status === false && inventory.live?.vid && inventory.working?.vid) {
+      const entity = await readDraftTranslation(backend, {
+        entityType: "media", bundle: type, id, langcode: targetLang,
+        draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
+      });
+      return redactCanonicalEntity(entity, sec, "media");
+    }
+    const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
+    if (!liveHas) return null;
+    if (targetLang !== inventory.defaultLangcode) {
+      const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
+      return {
+        id, entityType: "media", bundle: type, langcode: targetLang,
+        status: liveRow?.status ?? null,
+        fields: { name: liveRow?.name ?? null },
+        _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
+        note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
+      };
+    }
+  }
   const entity = await backend.getEntity({ entityType: "media", bundle: type, id });
   return entity ? redactCanonicalEntity(entity, sec, "media") : null;
 }
@@ -91,12 +121,13 @@ async function createMedia({ site: siteName, type, name, status = false, fields
 /**
  * Update a media entity (partial — omitted fields are left untouched; `status`
  * is strictly opt-in, #171). Reference-shaped `fields` values are routed to
- * relationships — see splitReferenceFields.
+ * relationships — see splitReferenceFields. Pass langcode to continue an
+ * unpublished working translation via Sentinel (not a canonical live PATCH).
  *
- * @param {object} args - { site?, type, id, name?, status?, fields? }.
+ * @param {object} args - { site?, type, id, name?, status?, fields?, langcode? }.
  * @returns {Promise<object>} The updated media descriptor.
  */
-async function updateMedia({ site: siteName, type, id, name, status, fields = {} }) {
+async function updateMedia({ site: siteName, type, id, name, status, fields = {}, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "media", type);
@@ -105,6 +136,30 @@ async function updateMedia({ site: siteName, type, id, name, status, fields = {}
   if (status !== undefined) attributes.status = status;
   assertPublishAllowed(sec, attributes);
   const backend = await resolveBackend(site);
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "media", bundle: type, id });
+    assertInventoryDraftLanguage(inventory, targetLang);
+    const liveVid = inventory.live?.vid;
+    const workingVid = inventory.working?.vid;
+    if (!liveVid || !workingVid || String(workingVid) === String(liveVid)) {
+      throw new Error(
+        "No unpublished working translation for this language. " +
+        "Create it with drupal_create_translation first; a canonical langcode PATCH is not attempted.",
+      );
+    }
+    const result = await writeDraft(backend, {
+      entityType: "media", bundle: type, id, attributes, langcode: targetLang,
+      ...(relationships ? { relationships } : {}),
+      draftRevision: { liveVid, workingVid },
+    });
+    const redacted = redactCanonicalEntity(result, sec, "media");
+    const working = entityRevisionId(result) ?? workingVid;
+    return {
+      ...redacted,
+      _revisions: { live: liveVid, working },
+    };
+  }
   // #171: pre-read so an unrequested published-state flip is reported, not silent.
   let existing = null;
   if (status === undefined) {
@@ -241,13 +296,14 @@ export const definitions = [
   },
   {
     name: "drupal_get_media",
-    description: "Fetch a single media entity by UUID and media type.",
+    description: "Fetch a single media entity by UUID and media type. Image alt/title are on the file relationship (meta.alt / meta.title). Pass langcode to read an unpublished working translation via Sentinel.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
         site: { type: "string" },
         type: { type: "string" },
         id:   { type: "string", description: "Media entity UUID" },
+        langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
       },
     },
   },
@@ -267,7 +323,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_media",
-    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched.",
+    description: "Update a media entity's name, status, or field values. Partial: omitted fields (status included) are left untouched. Pass langcode to continue an unpublished working translation via Sentinel; this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -276,7 +332,8 @@ export const definitions = [
         id:     { type: "string" },
         name:   { type: "string" },
         status: { type: "boolean", description: "Published flag. Only sent when provided; requires allowPublish when true." },
-        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically." },
+        fields: { type: "object", description: "Field values. Entity-reference values in JSON:API linkage shape ({ data: { type, id } }) are sent as relationships automatically. Image alt is meta.alt on field_media_image with the existing file UUID." },
+        langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
       },
     },
   },

package/src/tools/translations.js

@@ -9,12 +9,15 @@
  *   - drupal_create_translation — add a language as an unpublished forward draft
  *
  * Continuation of an existing unpublished translation is drupal_update_node
- * with `langcode`. Reads of that draft are drupal_get_node / drupal_get_revision
+ * with `langcode` (media: drupal_update_media; paragraph: drupal_update_paragraph).
+ * Reads of that draft are drupal_get_node / drupal_get_media / drupal_get_paragraph
  * with `langcode`.
  *
  * Paragraph field-value translation uses the same surface with
- * entityType "paragraph" and the pinned paragraph revision. Image alt is a
- * node relationship (`meta.alt`) with the shared file target unchanged.
+ * entityType "paragraph" and the pinned paragraph revision. Media uses the
+ * node live/working pair (`entityType: "media"`). Image alt on a media entity
+ * is the file relationship (`field_media_image` + `meta.alt`) with the shared
+ * file target unchanged.
  */
 
 import { getSiteConfig } from "../lib/config.js";
@@ -62,7 +65,8 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
   assertReadAllowed(sec, entityType, type);
 
   const backend = await resolveBackend(site);
-  if ((entityType === "node" || entityType === "paragraph") && typeof backend.rawQuery === "function") {
+  if ((entityType === "node" || entityType === "paragraph" || entityType === "media")
+    && typeof backend.rawQuery === "function") {
     try {
       const meta = await readTranslationInventory(backend, { entityType, bundle: type, id });
       const liveLangs = (meta.live?.translations ?? []).map((row) => row.langcode);
@@ -127,8 +131,8 @@ async function createTranslation({
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, type);
 
-  if (entityType !== "node" && entityType !== "paragraph") {
-    throw new Error("Governed translation create is implemented for nodes and paragraphs.");
+  if (entityType !== "node" && entityType !== "paragraph" && entityType !== "media") {
+    throw new Error("Governed translation create is implemented for nodes, paragraphs, and media.");
   }
 
   const backend = await resolveBackend(site);
@@ -151,12 +155,14 @@ async function createTranslation({
     draftRevision = await resolveNodeTranslationPair(backend, {
       entityType, bundle: type, id, existing,
     });
-    if (drafted.status === undefined && drafted.moderation_state === undefined) {
-      drafted.moderation_state = "draft";
+    if (entityType === "node") {
+      if (drafted.status === undefined && drafted.moderation_state === undefined) {
+        drafted.moderation_state = "draft";
+      }
+      drafted = await applySafeDraftDefault({
+        backend, entityType, bundle: type, id, attributes: drafted, existingEntity: existing,
+      });
     }
-    drafted = await applySafeDraftDefault({
-      backend, entityType, bundle: type, id, attributes: drafted, existingEntity: existing,
-    });
     assertPublishAllowed(sec, drafted);
   }
 
@@ -174,7 +180,7 @@ async function createTranslation({
     entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
   });
   const redacted = omitLiveComputedMetatag(redactCanonicalEntity(created, sec, entityType));
-  if (entityType !== "node") return redacted;
+  if (entityType === "paragraph") return redacted;
   const workingVid = entityRevisionId(created) ?? draftRevision.workingVid;
   const liveVid = draftRevision.liveVid;
   if (liveVid === undefined || liveVid === null) {
@@ -193,7 +199,7 @@ export const definitions = [
   {
     name: "drupal_list_translations",
     description:
-      "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's " +
+      "List live and working translation langcodes for a Drupal node, paragraph, or media entity. Uses Sentinel's " +
       "translation inventory when available (live default revision vs unpublished working " +
       "draft), including core content_translation_outdated and source when the server sends them. " +
       "Core JSON:API alone serves one language and cannot prove others are absent. " +
@@ -202,7 +208,7 @@ export const definitions = [
       type: "object", required: ["type", "id"],
       properties: {
         site:       { type: "string", description: "Named site (omit for default)" },
-        entityType: { type: "string", description: "Entity type machine name. Default: 'node'." },
+        entityType: { type: "string", description: "Entity type machine name. Default: 'node'. Use 'paragraph' or 'media' when listing those." },
         type:       { type: "string", description: "Bundle machine name, e.g. 'basic_page'" },
         id:         { type: "string", description: "Entity UUID" },
       },
@@ -219,15 +225,17 @@ export const definitions = [
       "paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. " +
       "The response includes `_revisions.live` / `_revisions.working` when known. " +
       "Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. " +
-      "Continue a node draft with drupal_update_node and langcode; continue a paragraph with " +
-      "drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, " +
-      "meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's " +
-      "draft-translation endpoint. Publication stays denied for content-tier callers.",
+      "Continue a node draft with drupal_update_node and langcode; a paragraph with " +
+      "drupal_update_paragraph and langcode; media with drupal_update_media and langcode. " +
+      "Image alt is a relationship (same file UUID, meta.alt) — on media that is " +
+      "field_media_image, not a node image field. For paragraphs pass revisionId as the " +
+      "host pin. Requires Sentinel's draft-translation endpoint. Publication stays denied " +
+      "for content-tier callers.",
     inputSchema: {
       type: "object", required: ["type", "id", "langcode"],
       properties: {
         site:          { type: "string" },
-        entityType:    { type: "string", description: "Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values." },
+        entityType:    { type: "string", description: "Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values, 'media' for media (name, caption, image alt)." },
         type:          { type: "string", description: "Bundle machine name, e.g. 'basic_page' or 'p_hero'" },
         id:            { type: "string", description: "Entity UUID" },
         langcode:      { type: "string", description: "Target language code, e.g. 'es', 'de', 'pt-br'" },