mcp-scraper 0.66.7 → 0.67.1

package/dist/bin/mcp-scraper-install.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   renderInstallTerminal
-} from "../chunk-O7ZC5Y3Z.js";
+} from "../chunk-HUNXSVKU.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-7KB5QTHP.js";
+} from "../chunk-VES63X4Q.js";
 
 // bin/mcp-scraper-install.ts
 var noColor = process.argv.includes("--no-color") || process.env.NO_COLOR !== void 0 || process.env.FORCE_COLOR === "0" || !process.stdout.isTTY;

package/dist/bin/mcp-stdio-server.cjs

@@ -107,6 +107,12 @@ var PUBLIC_ERROR_CODES = [
   "image_redirect_limit",
   "image_base64_invalid",
   "image_source_missing",
+  "image_source_ambiguous",
+  "image_source_type_invalid",
+  "image_artifact_not_found",
+  "image_page_too_large",
+  "page_image_not_found",
+  "page_image_candidates_unusable",
   "image_format_unsupported",
   "image_storage_unconfigured",
   "featured_image_unhostable"
@@ -214,6 +220,12 @@ function publicErrorType(code) {
     case "image_redirect_limit":
     case "image_base64_invalid":
     case "image_source_missing":
+    case "image_source_ambiguous":
+    case "image_source_type_invalid":
+    case "image_artifact_not_found":
+    case "image_page_too_large":
+    case "page_image_not_found":
+    case "page_image_candidates_unusable":
     case "image_format_unsupported":
     case "image_storage_unconfigured":
     case "featured_image_unhostable":
@@ -310,7 +322,19 @@ function publicErrorMessage(code) {
     case "image_base64_invalid":
       return "The supplied inline image bytes are invalid.";
     case "image_source_missing":
-      return "Provide either a stable public image URL or inline image bytes.";
+      return "Provide exactly one of a public image or webpage URL, inline image bytes, or an owner-scoped image artifact.";
+    case "image_source_ambiguous":
+      return "Provide only one image source: sourceUrl, imageBase64, or artifactId.";
+    case "image_source_type_invalid":
+      return "Use sourceType only with inline image bytes or an owner-scoped image artifact.";
+    case "image_artifact_not_found":
+      return "The image artifact was not found, expired, or does not belong to this account.";
+    case "image_page_too_large":
+      return "The webpage is too large for bounded Commons image discovery.";
+    case "page_image_not_found":
+      return "The webpage did not expose a usable featured or content image.";
+    case "page_image_candidates_unusable":
+      return "The webpage exposed image candidates, but none returned supported public image bytes.";
     case "image_format_unsupported":
       return "Commons accepts JPEG, PNG, GIF, or WebP image bytes.";
     case "image_storage_unconfigured":
@@ -473,6 +497,18 @@ async function readResponseData(res) {
     return text;
   }
 }
+function attachJsonStructuredContent(result) {
+  if (result.isError || result.structuredContent) return result;
+  const text = result.content.find((part) => part.type === "text");
+  if (!text || text.type !== "text") return result;
+  try {
+    const parsed = JSON.parse(text.text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return result;
+    return { ...result, structuredContent: parsed };
+  } catch {
+    return result;
+  }
+}
 function httpErrorPayload(path, res, data) {
   const objectData = data && typeof data === "object" && !Array.isArray(data) ? data : null;
   const rawCode = objectData?.code ?? objectData?.errorCode ?? objectData?.error_code;
@@ -1083,8 +1119,8 @@ var HttpMcpToolExecutor = class {
   commonsGetProposal(input) {
     return this.getJson(`/commons/proposals/${encodeURIComponent(input.proposalId)}`);
   }
-  commonsHostImage(input) {
-    return this.call("/commons/images", input);
+  async commonsHostImage(input) {
+    return attachJsonStructuredContent(await this.call("/commons/images", input));
   }
   commonsUpdateEditorialArticle(input) {
     const { idempotencyKey, ...body } = input;
@@ -1286,7 +1322,7 @@ render();
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.66.7";
+var PACKAGE_VERSION = "0.67.1";
 
 // src/mcp/input-field-descriptions.ts
 var import_zod = require("zod");
@@ -8272,9 +8308,10 @@ seam is noted so you can chain them.
   guidance, recommended sections, optional sections, and heading guidance before any write occurs.
 - Host a featured image -> **commons_host_image**. The normal write sequence is **commons_prepare_entity ->
   compose the payload -> commons_host_image -> commons_validate_entity -> commons_submit_entity**. Put the
-  permanent returned URL in featuredImage.url. Use imageBase64 for available attachment bytes within the request
-  bound, or a stable direct public HTTPS image URL; never use a caller-local path, opaque chat attachment reference,
-  HTML page, private URL, or temporary/signed URL.
+  permanent returned URL in featuredImage.url. Use imageBase64 for pasted or AI-generated bytes, artifactId for an
+  owner-scoped MCP Scraper image artifact, or sourceUrl for either a public HTTPS image or a webpage containing one.
+  Webpage discovery tries Open Graph, Twitter, JSON-LD, then meaningful content images. Never pass a caller-local
+  path, opaque chat attachment reference, or private/authenticated URL.
 - Validate a composed entity without writing -> **commons_validate_entity**. Use it after image hosting and before
   submit. Validation does not fetch or store image bytes; an external/unregistered featured image is reported in
   imageDiagnostics as not publishable until commons_host_image returns its permanent Commons URL. Validation also
@@ -10181,7 +10218,7 @@ var CommonsGetEntityLinksetInputSchema = {
   idOrSlug: import_zod8.z.string().trim().min(1).max(180).describe("Transparent Commons TPW-Q entity id or /wiki/ slug whose governed RFC 9264 linkset should be read.")
 };
 var CommonsFeaturedImageInputSchema = import_zod8.z.object({
-  url: import_zod8.z.string().url().describe("For a publish-ready entity, use the permanent URL returned by commons_host_image. Submit can auto-host a stable direct public HTTPS image URL as a compatibility fallback, but validation reports any unregistered external URL as not ready. Do not use a chat attachment reference, caller-local path, temporary or signed URL, private URL, or HTML page URL."),
+  url: import_zod8.z.string().url().describe("For a publish-ready entity, use the permanent URL returned by commons_host_image. Validation reports any unregistered external URL as not ready. Do not use a chat attachment reference, caller-local path, private URL, or HTML page URL here; pass the original image or webpage source to commons_host_image first."),
   alt: import_zod8.z.string().trim().max(500).optional(),
   caption: import_zod8.z.string().trim().max(1e3).optional(),
   sourceUrl: import_zod8.z.string().url().optional(),
@@ -10280,7 +10317,7 @@ var CommonsSubmitEntityInputSchema = {
   entityId: import_zod8.z.string().trim().max(80).optional().describe("Existing Transparent Public Wiki entity id when proposing an edit. New entities normally omit this and receive a TPW-Q id."),
   entityType: import_zod8.z.string().trim().max(120).default("PublicArticle").describe("Backend Wikidata-style type. Prefer precise entity classes such as SoftwareApplication, Organization, Person, Event, Place, Taxon, ScienceConcept, MathConcept, TechArticle, or PublicArticle; the public article structure should match the selected type."),
   disambiguationName: import_zod8.z.string().trim().max(240).optional().describe("Clarifying name used when the concept could be confused with another entity."),
-  featuredImage: CommonsFeaturedImageInputSchema.optional().describe("Required for auto-published public entities. First call commons_host_image and place its returned permanent URL here; validation does not fetch external images and reports unregistered URLs as not publishable. Submit retains a compatibility fallback that auto-hosts a stable direct public HTTPS image URL. The image is also added to the media manifest if absent."),
+  featuredImage: CommonsFeaturedImageInputSchema.optional().describe("Required for auto-published public entities. First call commons_host_image with attachment bytes, an image artifact, a direct image URL, or a webpage URL, then place its returned permanent URL here. Validation does not fetch external images and reports unregistered URLs as not publishable. Submit retains a compatibility fallback for public URLs. The image is also added to the media manifest if absent."),
   source: CommonsSourceInputSchema.optional().describe("Source provenance. Store original URL, source byline, and origin canonical here; canonical does not replace rights review."),
   tags: import_zod8.z.array(import_zod8.z.string().trim().min(1).max(80)).max(24).optional().describe("Standardized topic tags. Use existing/searchable concepts when possible."),
   keywords: import_zod8.z.array(import_zod8.z.string().trim().min(1).max(120)).max(50).optional().describe("SEO and retrieval keywords."),
@@ -10342,12 +10379,31 @@ var CommonsGetEntityLedgerInputSchema = {
   idOrSlug: import_zod8.z.string().trim().min(1).max(180).describe("Published entity id or /wiki/ slug whose contribution ledger should be read.")
 };
 var CommonsHostImageInputSchema = {
-  sourceUrl: import_zod8.z.string().url().optional().describe("Stable direct public HTTPS URL whose response is the image bytes to host. Do not pass an HTML webpage, chat attachment reference, caller-local path, temporary or signed URL, or private/authenticated URL."),
-  imageBase64: import_zod8.z.string().min(16).optional().describe("Base64 image bytes for an image you already hold, including forwarded chat attachment bytes. Prefer this over a temporary attachment URL when the serialized request remains under about 3 MB; larger files require a stable direct public HTTPS source URL."),
+  sourceUrl: import_zod8.z.string().url().optional().describe("Public HTTPS direct image URL or webpage URL. A direct image is hosted as-is; an HTML page is inspected for Open Graph, Twitter, JSON-LD, and meaningful content images, then the first usable candidate is hosted. Temporary signed URLs are consumed immediately and query credentials are not retained as provenance."),
+  imageBase64: import_zod8.z.string().min(16).optional().describe("Base64 image bytes for an image already available to the caller, including a pasted attachment or AI-generated image. Use sourceType to preserve whether it was uploaded or generated. Keep the complete serialized request within the client transport limit."),
+  artifactId: import_zod8.z.string().trim().min(1).max(500).optional().describe("Owner-scoped image artifact returned by an MCP Scraper media or screenshot workflow. The server reauthorizes ownership and reads the bytes directly; do not construct an artifact ID."),
+  sourceType: import_zod8.z.enum(["uploaded", "ai_generated"]).optional().describe("Provenance for imageBase64 or artifactId. Use ai_generated only when an image model created the supplied bytes; otherwise use uploaded or omit it."),
   alt: import_zod8.z.string().trim().max(500).optional().describe("Alt text describing the image for readers who cannot see it."),
   license: import_zod8.z.string().trim().max(240).optional().describe("License or usage terms of the original image, preserved with the hosted copy."),
   attribution: import_zod8.z.string().trim().max(500).optional().describe("Credit line for the original photographer, publication, or archive.")
 };
+var CommonsHostImageOutputSchema = {
+  ok: import_zod8.z.boolean(),
+  data: import_zod8.z.object({
+    id: import_zod8.z.string().describe("Stable Commons image ID."),
+    url: import_zod8.z.string().url().describe("Permanent Commons URL to use as featuredImage.url."),
+    contentType: import_zod8.z.enum(["image/jpeg", "image/png", "image/gif", "image/webp"]),
+    bytes: import_zod8.z.number().int().positive(),
+    digest: import_zod8.z.string(),
+    sourceUrl: import_zod8.z.string().url().nullable().describe("Sanitized direct asset URL that supplied the hosted bytes, when applicable."),
+    sourcePageUrl: import_zod8.z.string().url().nullable().describe("Sanitized webpage URL from which the image was discovered, when applicable."),
+    sourceKind: import_zod8.z.enum(["uploaded", "ai_generated", "artifact", "direct_url", "webpage", "registered"]),
+    selectionSource: import_zod8.z.enum(["provided_bytes", "artifact", "direct_url", "og:image", "twitter:image", "json-ld", "content-image", "registered"]),
+    reused: import_zod8.z.boolean().describe("True when identical image bytes were already stored.")
+  }).optional(),
+  error: import_zod8.z.string().optional(),
+  message: import_zod8.z.string().optional()
+};
 var CommonsGetProposalInputSchema = {
   proposalId: import_zod8.z.string().trim().min(1).max(120).describe("Proposal id returned by commons_submit_entity, in the form commons-proposal-<uuid>.")
 };
@@ -14144,9 +14200,9 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.commonsGetEntityLedger(input));
   server.registerTool("commons_host_image", {
     title: "Host a Transparent Commons Image",
-    description: "Normal prerequisite for any featured image whose URL was not already returned by commons_host_image. Host image bytes from imageBase64 when you already have an attachment and the serialized request stays under about 3 MB, or from a stable direct public HTTPS image URL; do not pass a webpage, caller-local path, private URL, or temporary/signed attachment URL. Returns the permanent Commons URL to place in featuredImage.url before commons_validate_entity and commons_submit_entity. Submit can still auto-host a stable public source as a compatibility fallback. JPEG, PNG, GIF, and WebP are accepted up to 10 MB; SVG is rejected. Identical bytes are stored once.",
+    description: "Turn one supplied image source into a permanent Transparent Commons image before validation and submission. Provide exactly one of imageBase64 for a pasted or AI-generated image, artifactId for an owner-scoped MCP Scraper image artifact, or sourceUrl for either a direct public HTTPS image or a webpage containing the desired image. Webpages are inspected in deterministic order for Open Graph, Twitter, JSON-LD, and meaningful content images; unusable candidates fall through to the next candidate. Returns the permanent URL for featuredImage.url plus source and selection provenance. JPEG, PNG, GIF, and WebP are accepted up to 10 MB; SVG is rejected. Identical bytes are stored once. Never pass a caller-local path or private/authenticated URL.",
     inputSchema: CommonsHostImageInputSchema,
-    outputSchema: recordOutputSchema("commons_host_image", CommonsGenericOutputSchema),
+    outputSchema: recordOutputSchema("commons_host_image", CommonsHostImageOutputSchema),
     annotations: {
       title: "Host a Transparent Commons Image",
       readOnlyHint: false,
@@ -18752,7 +18808,7 @@ var HostedMemoryMcpToolExecutor = class {
 
 // release-message.json
 var release_message_default = {
-  message: "Transparent Commons now verifies featured-image readiness before publishing, and replacement integration connections keep their paid period."
+  message: "Transparent Commons image hosting now accepts the source a user has and returns the same permanent-image result in both readable and typed MCP channels."
 };
 
 // src/install-terminal.ts

package/dist/bin/mcp-stdio-server.js

@@ -13,21 +13,21 @@ import {
   registerScheduledResultsMcpTools,
   registerSerpIntelligenceCaptureTools,
   resolveDeploymentProfile
-} from "../chunk-Z5QQEWXA.js";
+} from "../chunk-STQQOEHC.js";
 import "../chunk-PGJQDMC2.js";
-import "../chunk-F434YJPV.js";
-import "../chunk-U2UHJWFW.js";
+import "../chunk-2L4C4DAZ.js";
+import "../chunk-ES25GP6C.js";
 import {
   renderInstallTerminal
-} from "../chunk-O7ZC5Y3Z.js";
+} from "../chunk-HUNXSVKU.js";
 import "../chunk-VXLU74YZ.js";
 import "../chunk-GGZEC22A.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-7KB5QTHP.js";
+} from "../chunk-VES63X4Q.js";
 import "../chunk-DNM65UCK.js";
 import "../chunk-AYJHI2FK.js";
-import "../chunk-HZDJ5UZ4.js";
+import "../chunk-65FTMB7G.js";
 
 // bin/mcp-stdio-server.ts
 import { readFileSync } from "fs";

package/dist/bin/paa-harvest.cjs

@@ -311,6 +311,12 @@ var PUBLIC_ERROR_CODES = [
   "image_redirect_limit",
   "image_base64_invalid",
   "image_source_missing",
+  "image_source_ambiguous",
+  "image_source_type_invalid",
+  "image_artifact_not_found",
+  "image_page_too_large",
+  "page_image_not_found",
+  "page_image_candidates_unusable",
   "image_format_unsupported",
   "image_storage_unconfigured",
   "featured_image_unhostable"

package/dist/bin/paa-harvest.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   harvest
-} from "../chunk-CGOMGGOF.js";
+} from "../chunk-62LEXS5O.js";
 import {
   browserServiceApiKey
-} from "../chunk-U2UHJWFW.js";
+} from "../chunk-ES25GP6C.js";
 import "../chunk-77LQV73B.js";
-import "../chunk-HZDJ5UZ4.js";
+import "../chunk-65FTMB7G.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/{chunk-F434YJPV.js → chunk-2L4C4DAZ.js}

@@ -1,7 +1,7 @@
 import {
   publicErrorMessage,
   sanitizeVendorName
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/outbound-sanitize.ts
 var KEY_RENAMES = {

package/dist/{chunk-LVXRWJJJ.js → chunk-2LXTOAKS.js}

@@ -10,7 +10,7 @@ import {
   finishHarvestAttempt,
   publicErrorMessage,
   startHarvestAttempt
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/harvest-problems.ts
 function errorMessage(err) {

package/dist/{chunk-CGOMGGOF.js → chunk-62LEXS5O.js}

@@ -6,7 +6,7 @@ import {
   currentCostContext,
   recordKernelSession,
   runWithCostContext
-} from "./chunk-U2UHJWFW.js";
+} from "./chunk-ES25GP6C.js";
 import {
   DEFAULT_PROXY_MODE,
   HarvestOptionsSchema,
@@ -21,7 +21,7 @@ import {
   RECAPTCHA_INSTRUCTIONS,
   RequestAbortedError,
   sanitizeVendorName
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/driver/BrowserDriver.ts
 import { chromium } from "playwright-extra";

package/dist/{chunk-HZDJ5UZ4.js → chunk-65FTMB7G.js}

@@ -53,6 +53,12 @@ var PUBLIC_ERROR_CODES = [
   "image_redirect_limit",
   "image_base64_invalid",
   "image_source_missing",
+  "image_source_ambiguous",
+  "image_source_type_invalid",
+  "image_artifact_not_found",
+  "image_page_too_large",
+  "page_image_not_found",
+  "page_image_candidates_unusable",
   "image_format_unsupported",
   "image_storage_unconfigured",
   "featured_image_unhostable"
@@ -187,6 +193,12 @@ function publicErrorType(code) {
     case "image_redirect_limit":
     case "image_base64_invalid":
     case "image_source_missing":
+    case "image_source_ambiguous":
+    case "image_source_type_invalid":
+    case "image_artifact_not_found":
+    case "image_page_too_large":
+    case "page_image_not_found":
+    case "page_image_candidates_unusable":
     case "image_format_unsupported":
     case "image_storage_unconfigured":
     case "featured_image_unhostable":
@@ -283,7 +295,19 @@ function publicErrorMessage(code) {
     case "image_base64_invalid":
       return "The supplied inline image bytes are invalid.";
     case "image_source_missing":
-      return "Provide either a stable public image URL or inline image bytes.";
+      return "Provide exactly one of a public image or webpage URL, inline image bytes, or an owner-scoped image artifact.";
+    case "image_source_ambiguous":
+      return "Provide only one image source: sourceUrl, imageBase64, or artifactId.";
+    case "image_source_type_invalid":
+      return "Use sourceType only with inline image bytes or an owner-scoped image artifact.";
+    case "image_artifact_not_found":
+      return "The image artifact was not found, expired, or does not belong to this account.";
+    case "image_page_too_large":
+      return "The webpage is too large for bounded Commons image discovery.";
+    case "page_image_not_found":
+      return "The webpage did not expose a usable featured or content image.";
+    case "page_image_candidates_unusable":
+      return "The webpage exposed image candidates, but none returned supported public image bytes.";
     case "image_format_unsupported":
       return "Commons accepts JPEG, PNG, GIF, or WebP image bytes.";
     case "image_storage_unconfigured":

package/dist/{chunk-U2UHJWFW.js → chunk-ES25GP6C.js}

@@ -1,6 +1,6 @@
 import {
   getDb
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/lib/browser-service-env.ts
 function browserServiceApiKey() {

package/dist/{chunk-O7ZC5Y3Z.js → chunk-HUNXSVKU.js}

@@ -1,6 +1,6 @@
 // release-message.json
 var release_message_default = {
-  message: "Transparent Commons now verifies featured-image readiness before publishing, and replacement integration connections keep their paid period."
+  message: "Transparent Commons image hosting now accepts the source a user has and returns the same permanent-image result in both readable and typed MCP channels."
 };
 
 // src/install-terminal.ts

package/dist/{chunk-HWGQVP3Q.js → chunk-LCGTNWOT.js}

@@ -15,7 +15,7 @@ import {
   sanitizeVendorName,
   serializePublicErrorEnvelope,
   settleDebitMcIdempotent
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/site-extract-content-store.ts
 import { createHash } from "crypto";

package/dist/{chunk-EVOBJYBE.js → chunk-LN6N3YLK.js}

@@ -8,7 +8,7 @@ import {
 import {
   buildPublicErrorEnvelope,
   getDb
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/lib/media-extractor.ts
 import { createWriteStream, mkdirSync, rmSync } from "fs";

package/dist/{chunk-Z5QQEWXA.js → chunk-STQQOEHC.js}

@@ -8,13 +8,13 @@ import {
 } from "./chunk-PGJQDMC2.js";
 import {
   sanitizeOutboundDiagnostics
-} from "./chunk-F434YJPV.js";
+} from "./chunk-2L4C4DAZ.js";
 import {
   browserServiceProfileName,
   browserServiceProfileSaveChanges,
   recordVendorUsage,
   vendorCostUsd
-} from "./chunk-U2UHJWFW.js";
+} from "./chunk-ES25GP6C.js";
 import {
   buildSerpEmailQuery,
   classifyEmailScope,
@@ -25,7 +25,7 @@ import {
 } from "./chunk-VXLU74YZ.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-7KB5QTHP.js";
+} from "./chunk-VES63X4Q.js";
 import {
   createPrivateArtifact,
   privateArtifactOwnerId,
@@ -45,7 +45,7 @@ import {
   normalizePublicErrorCode,
   publicErrorMessage,
   sanitizeVendorName
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/harvest-timeout.ts
 var SCRAPE_FUNCTION_MAX_MS = 8e5;
@@ -390,9 +390,10 @@ seam is noted so you can chain them.
   guidance, recommended sections, optional sections, and heading guidance before any write occurs.
 - Host a featured image -> **commons_host_image**. The normal write sequence is **commons_prepare_entity ->
   compose the payload -> commons_host_image -> commons_validate_entity -> commons_submit_entity**. Put the
-  permanent returned URL in featuredImage.url. Use imageBase64 for available attachment bytes within the request
-  bound, or a stable direct public HTTPS image URL; never use a caller-local path, opaque chat attachment reference,
-  HTML page, private URL, or temporary/signed URL.
+  permanent returned URL in featuredImage.url. Use imageBase64 for pasted or AI-generated bytes, artifactId for an
+  owner-scoped MCP Scraper image artifact, or sourceUrl for either a public HTTPS image or a webpage containing one.
+  Webpage discovery tries Open Graph, Twitter, JSON-LD, then meaningful content images. Never pass a caller-local
+  path, opaque chat attachment reference, or private/authenticated URL.
 - Validate a composed entity without writing -> **commons_validate_entity**. Use it after image hosting and before
   submit. Validation does not fetch or store image bytes; an external/unregistered featured image is reported in
   imageDiagnostics as not publishable until commons_host_image returns its permanent Commons URL. Validation also
@@ -7505,7 +7506,7 @@ var CommonsGetEntityLinksetInputSchema = {
   idOrSlug: z6.string().trim().min(1).max(180).describe("Transparent Commons TPW-Q entity id or /wiki/ slug whose governed RFC 9264 linkset should be read.")
 };
 var CommonsFeaturedImageInputSchema = z6.object({
-  url: z6.string().url().describe("For a publish-ready entity, use the permanent URL returned by commons_host_image. Submit can auto-host a stable direct public HTTPS image URL as a compatibility fallback, but validation reports any unregistered external URL as not ready. Do not use a chat attachment reference, caller-local path, temporary or signed URL, private URL, or HTML page URL."),
+  url: z6.string().url().describe("For a publish-ready entity, use the permanent URL returned by commons_host_image. Validation reports any unregistered external URL as not ready. Do not use a chat attachment reference, caller-local path, private URL, or HTML page URL here; pass the original image or webpage source to commons_host_image first."),
   alt: z6.string().trim().max(500).optional(),
   caption: z6.string().trim().max(1e3).optional(),
   sourceUrl: z6.string().url().optional(),
@@ -7604,7 +7605,7 @@ var CommonsSubmitEntityInputSchema = {
   entityId: z6.string().trim().max(80).optional().describe("Existing Transparent Public Wiki entity id when proposing an edit. New entities normally omit this and receive a TPW-Q id."),
   entityType: z6.string().trim().max(120).default("PublicArticle").describe("Backend Wikidata-style type. Prefer precise entity classes such as SoftwareApplication, Organization, Person, Event, Place, Taxon, ScienceConcept, MathConcept, TechArticle, or PublicArticle; the public article structure should match the selected type."),
   disambiguationName: z6.string().trim().max(240).optional().describe("Clarifying name used when the concept could be confused with another entity."),
-  featuredImage: CommonsFeaturedImageInputSchema.optional().describe("Required for auto-published public entities. First call commons_host_image and place its returned permanent URL here; validation does not fetch external images and reports unregistered URLs as not publishable. Submit retains a compatibility fallback that auto-hosts a stable direct public HTTPS image URL. The image is also added to the media manifest if absent."),
+  featuredImage: CommonsFeaturedImageInputSchema.optional().describe("Required for auto-published public entities. First call commons_host_image with attachment bytes, an image artifact, a direct image URL, or a webpage URL, then place its returned permanent URL here. Validation does not fetch external images and reports unregistered URLs as not publishable. Submit retains a compatibility fallback for public URLs. The image is also added to the media manifest if absent."),
   source: CommonsSourceInputSchema.optional().describe("Source provenance. Store original URL, source byline, and origin canonical here; canonical does not replace rights review."),
   tags: z6.array(z6.string().trim().min(1).max(80)).max(24).optional().describe("Standardized topic tags. Use existing/searchable concepts when possible."),
   keywords: z6.array(z6.string().trim().min(1).max(120)).max(50).optional().describe("SEO and retrieval keywords."),
@@ -7666,12 +7667,31 @@ var CommonsGetEntityLedgerInputSchema = {
   idOrSlug: z6.string().trim().min(1).max(180).describe("Published entity id or /wiki/ slug whose contribution ledger should be read.")
 };
 var CommonsHostImageInputSchema = {
-  sourceUrl: z6.string().url().optional().describe("Stable direct public HTTPS URL whose response is the image bytes to host. Do not pass an HTML webpage, chat attachment reference, caller-local path, temporary or signed URL, or private/authenticated URL."),
-  imageBase64: z6.string().min(16).optional().describe("Base64 image bytes for an image you already hold, including forwarded chat attachment bytes. Prefer this over a temporary attachment URL when the serialized request remains under about 3 MB; larger files require a stable direct public HTTPS source URL."),
+  sourceUrl: z6.string().url().optional().describe("Public HTTPS direct image URL or webpage URL. A direct image is hosted as-is; an HTML page is inspected for Open Graph, Twitter, JSON-LD, and meaningful content images, then the first usable candidate is hosted. Temporary signed URLs are consumed immediately and query credentials are not retained as provenance."),
+  imageBase64: z6.string().min(16).optional().describe("Base64 image bytes for an image already available to the caller, including a pasted attachment or AI-generated image. Use sourceType to preserve whether it was uploaded or generated. Keep the complete serialized request within the client transport limit."),
+  artifactId: z6.string().trim().min(1).max(500).optional().describe("Owner-scoped image artifact returned by an MCP Scraper media or screenshot workflow. The server reauthorizes ownership and reads the bytes directly; do not construct an artifact ID."),
+  sourceType: z6.enum(["uploaded", "ai_generated"]).optional().describe("Provenance for imageBase64 or artifactId. Use ai_generated only when an image model created the supplied bytes; otherwise use uploaded or omit it."),
   alt: z6.string().trim().max(500).optional().describe("Alt text describing the image for readers who cannot see it."),
   license: z6.string().trim().max(240).optional().describe("License or usage terms of the original image, preserved with the hosted copy."),
   attribution: z6.string().trim().max(500).optional().describe("Credit line for the original photographer, publication, or archive.")
 };
+var CommonsHostImageOutputSchema = {
+  ok: z6.boolean(),
+  data: z6.object({
+    id: z6.string().describe("Stable Commons image ID."),
+    url: z6.string().url().describe("Permanent Commons URL to use as featuredImage.url."),
+    contentType: z6.enum(["image/jpeg", "image/png", "image/gif", "image/webp"]),
+    bytes: z6.number().int().positive(),
+    digest: z6.string(),
+    sourceUrl: z6.string().url().nullable().describe("Sanitized direct asset URL that supplied the hosted bytes, when applicable."),
+    sourcePageUrl: z6.string().url().nullable().describe("Sanitized webpage URL from which the image was discovered, when applicable."),
+    sourceKind: z6.enum(["uploaded", "ai_generated", "artifact", "direct_url", "webpage", "registered"]),
+    selectionSource: z6.enum(["provided_bytes", "artifact", "direct_url", "og:image", "twitter:image", "json-ld", "content-image", "registered"]),
+    reused: z6.boolean().describe("True when identical image bytes were already stored.")
+  }).optional(),
+  error: z6.string().optional(),
+  message: z6.string().optional()
+};
 var CommonsGetProposalInputSchema = {
   proposalId: z6.string().trim().min(1).max(120).describe("Proposal id returned by commons_submit_entity, in the form commons-proposal-<uuid>.")
 };
@@ -11599,9 +11619,9 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.commonsGetEntityLedger(input));
   server.registerTool("commons_host_image", {
     title: "Host a Transparent Commons Image",
-    description: "Normal prerequisite for any featured image whose URL was not already returned by commons_host_image. Host image bytes from imageBase64 when you already have an attachment and the serialized request stays under about 3 MB, or from a stable direct public HTTPS image URL; do not pass a webpage, caller-local path, private URL, or temporary/signed attachment URL. Returns the permanent Commons URL to place in featuredImage.url before commons_validate_entity and commons_submit_entity. Submit can still auto-host a stable public source as a compatibility fallback. JPEG, PNG, GIF, and WebP are accepted up to 10 MB; SVG is rejected. Identical bytes are stored once.",
+    description: "Turn one supplied image source into a permanent Transparent Commons image before validation and submission. Provide exactly one of imageBase64 for a pasted or AI-generated image, artifactId for an owner-scoped MCP Scraper image artifact, or sourceUrl for either a direct public HTTPS image or a webpage containing the desired image. Webpages are inspected in deterministic order for Open Graph, Twitter, JSON-LD, and meaningful content images; unusable candidates fall through to the next candidate. Returns the permanent URL for featuredImage.url plus source and selection provenance. JPEG, PNG, GIF, and WebP are accepted up to 10 MB; SVG is rejected. Identical bytes are stored once. Never pass a caller-local path or private/authenticated URL.",
     inputSchema: CommonsHostImageInputSchema,
-    outputSchema: recordOutputSchema("commons_host_image", CommonsGenericOutputSchema),
+    outputSchema: recordOutputSchema("commons_host_image", CommonsHostImageOutputSchema),
     annotations: {
       title: "Host a Transparent Commons Image",
       readOnlyHint: false,
@@ -12116,6 +12136,18 @@ async function readResponseData(res) {
     return text;
   }
 }
+function attachJsonStructuredContent(result) {
+  if (result.isError || result.structuredContent) return result;
+  const text = result.content.find((part) => part.type === "text");
+  if (!text || text.type !== "text") return result;
+  try {
+    const parsed = JSON.parse(text.text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return result;
+    return { ...result, structuredContent: parsed };
+  } catch {
+    return result;
+  }
+}
 function httpErrorPayload(path, res, data) {
   const objectData = data && typeof data === "object" && !Array.isArray(data) ? data : null;
   const rawCode = objectData?.code ?? objectData?.errorCode ?? objectData?.error_code;
@@ -12726,8 +12758,8 @@ var HttpMcpToolExecutor = class {
   commonsGetProposal(input) {
     return this.getJson(`/commons/proposals/${encodeURIComponent(input.proposalId)}`);
   }
-  commonsHostImage(input) {
-    return this.call("/commons/images", input);
+  async commonsHostImage(input) {
+    return attachJsonStructuredContent(await this.call("/commons/images", input));
   }
   commonsUpdateEditorialArticle(input) {
     const { idempotencyKey, ...body } = input;

package/dist/{chunk-JZPSG4NR.js → chunk-UL4ZKAWZ.js}

@@ -1,6 +1,6 @@
 import {
   getDb
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/lead-list-enrichment-repository.ts
 import { createHash, randomUUID } from "crypto";

package/dist/{chunk-7KB5QTHP.js → chunk-VES63X4Q.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var PACKAGE_VERSION = "0.66.7";
+var PACKAGE_VERSION = "0.67.1";
 
 export {
   PACKAGE_VERSION

package/dist/{chunk-HBZENASD.js → chunk-Y46YNQMM.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-RJ7JVYKU.js";
 import {
   getDb
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/location-data-repository.ts
 import { createHash, randomUUID } from "crypto";

package/dist/{db-MNNNIWVS.js → db-ZGZAKYBW.js}

@@ -126,7 +126,7 @@ import {
   updateKpoJobState,
   upsertPageSnapshot,
   verifyPassword
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 export {
   CORE_SCHEMA_VERSION,
   CREDIT_LOTS_EPOCH,

package/dist/{extract-bundle-RW7CVIRF.js → extract-bundle-QQIYJSBW.js}

@@ -4,7 +4,7 @@ import {
   downloadAsset,
   embedCommonsTexts,
   publicizeExtractionFailure
-} from "./chunk-EVOBJYBE.js";
+} from "./chunk-LN6N3YLK.js";
 import "./chunk-OZJMVCDK.js";
 import {
   computeIssues,
@@ -18,12 +18,12 @@ import {
   createSiteExtractContentReader,
   createSiteExtractImageArtifact,
   extractJobLimitInfo
-} from "./chunk-HWGQVP3Q.js";
+} from "./chunk-LCGTNWOT.js";
 import "./chunk-DNM65UCK.js";
 import "./chunk-AYJHI2FK.js";
 import {
   getDb
-} from "./chunk-HZDJ5UZ4.js";
+} from "./chunk-65FTMB7G.js";
 
 // src/api/extract-bundle.ts
 import { createWriteStream, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";

package/dist/index.cjs

@@ -321,6 +321,12 @@ var PUBLIC_ERROR_CODES = [
   "image_redirect_limit",
   "image_base64_invalid",
   "image_source_missing",
+  "image_source_ambiguous",
+  "image_source_type_invalid",
+  "image_artifact_not_found",
+  "image_page_too_large",
+  "page_image_not_found",
+  "page_image_candidates_unusable",
   "image_format_unsupported",
   "image_storage_unconfigured",
   "featured_image_unhostable"

package/dist/index.js

@@ -1,11 +1,11 @@
 import {
   harvest
-} from "./chunk-CGOMGGOF.js";
+} from "./chunk-62LEXS5O.js";
 import {
   recordVendorUsage
-} from "./chunk-U2UHJWFW.js";
+} from "./chunk-ES25GP6C.js";
 import "./chunk-77LQV73B.js";
-import "./chunk-HZDJ5UZ4.js";
+import "./chunk-65FTMB7G.js";
 
 // src/video/VideoGenerator.ts
 import { execSync as execSync2 } from "child_process";