@meterapp/car-image-sdk 1.1.0 → 1.3.0

package/dist/mcp/index.js

@@ -10,7 +10,7 @@
  * entry point of the SDK has no runtime dependencies.
  */
 import * as z from "zod";
-import { CATALOG, COLORS, CREDITS_PER_DOLLAR, CREDITS_PER_IMAGE, DEFAULT_BASE_URL, FORMATS, FREE_CREDITS, MAX_DIMENSION, MIN_YEAR, REFERRAL_SOURCES, REQUEST_KINDS, REQUEST_SORTS, REQUEST_STATUSES, SIZES, VIEWS, } from "../types.js";
+import { CATALOG, COLORS, CREDITS_PER_DOLLAR, CREDITS_PER_IMAGE, DEFAULT_BASE_URL, FITS, FORMATS, FREE_CREDITS, MAX_DIMENSION, MAX_PADDING_PERCENT, MIN_YEAR, REFERRAL_SOURCES, REQUEST_KINDS, REQUEST_SORTS, REQUEST_STATUSES, SIZES, VIEWS, } from "../types.js";
 import { SDK_VERSION } from "../version.js";
 /**
  * Catalog size as agents read it in the instructions and tool descriptions.
@@ -26,7 +26,49 @@ export const MCP_SERVER_INFO = {
     version: SDK_VERSION,
     websiteUrl: DEFAULT_BASE_URL,
 };
-export const MCP_INSTRUCTIONS = `Car Image API by Meter: studio-quality, transparent-background renders of any vehicle in the open @meterapp/vehicle-db catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, model years ${CATALOG_YEARS}). Six camera views, fifteen preset colors, PNG/WebP/JPG up to 1024 px.
+/**
+ * Which tools a server exposes. `core` is what an agent needs to find, render
+ * and embed a car; the request board and the two "about you" tools live in
+ * `all`, for hosts that opt in (`?toolset=all` on the remote URL,
+ * `car-image mcp --toolset all` locally). Fewer, sharper tools cost less
+ * context and make the right one easier to pick.
+ */
+export const MCP_TOOLSETS = {
+    core: [
+        "get_car_image",
+        "create_car_image_urls",
+        "search_vehicles",
+        "resolve_vehicle",
+        "list_image_options",
+        "get_account",
+        "rate_image",
+        "describe_api",
+    ],
+    all: [
+        "get_car_image",
+        "create_car_image_urls",
+        "search_vehicles",
+        "resolve_vehicle",
+        "list_image_options",
+        "get_account",
+        "rate_image",
+        "describe_api",
+        "list_requests",
+        "request_vehicle",
+        "request_feature",
+        "get_request",
+        "upvote_request",
+        "comment_on_request",
+        "share_building",
+        "share_referral",
+    ],
+};
+export const DEFAULT_MCP_TOOLSET = "core";
+export const MCP_TOOLSET_NAMES = Object.keys(MCP_TOOLSETS);
+export function isMcpToolset(value) {
+    return typeof value === "string" && MCP_TOOLSET_NAMES.includes(value);
+}
+const INSTRUCTIONS_COMMON = `Car Image API by Meter: studio-quality, transparent-background renders of any vehicle in the open @meterapp/vehicle-db catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, model years ${CATALOG_YEARS}). Six camera views, fifteen preset colors, PNG/WebP/JPG up to 1024 px, any width and height (fit contain|cover|inside), transparent or a solid background color.
 
 Costs: every delivered image costs exactly ${CREDITS_PER_IMAGE} credit ($1 = ${CREDITS_PER_DOLLAR.toLocaleString("en-US")} credits; ${FREE_CREDITS} free credits per account), cold or CDN hit. create_car_image_urls charges 1 credit per URL when the URL is created; redemptions are free. search_vehicles, resolve_vehicle, list_image_options, get_account, rate_image and describe_api are free.
 
@@ -36,9 +78,15 @@ Security: never place the API key in URLs, HTML, logs, screenshots or client-sid
 
 Money: on an insufficient-credits error (HTTP 402) stop and ask the human to buy credits at ${DEFAULT_BASE_URL}/billing or with \`car-image billing\`; never purchase credits autonomously. On a rate limit (HTTP 429) wait the number of seconds in retry_after before trying again.
 
-Quality: after a human judges a render, call rate_image (good/bad or 1-5) so future renders improve.
-
-Requests: when search_vehicles or resolve_vehicle finds no match for a vehicle the human needs, offer request_vehicle so it gets added (an existing open request for the same car is upvoted instead of duplicated); ideas for the API go through request_feature, and list_requests shows what others have asked for.`;
+Quality: after a human judges a render, call rate_image (good/bad or 1-5) so future renders improve.`;
+const INSTRUCTIONS_REQUESTS = `Requests: when search_vehicles or resolve_vehicle finds no match for a vehicle the human needs, offer request_vehicle so it gets added (an existing open request for the same car is upvoted instead of duplicated); ideas for the API go through request_feature, and list_requests shows what others have asked for.`;
+const INSTRUCTIONS_CORE_ONLY = `Missing vehicles: when search_vehicles or resolve_vehicle finds no match for a vehicle the human needs, do not substitute another car; point the human to ${DEFAULT_BASE_URL}/requests to ask for it (or connect with toolset=all for the request board tools).`;
+/** The server instructions for a toolset; `all` includes the request board paragraph. */
+export function mcpInstructions(toolset = DEFAULT_MCP_TOOLSET) {
+    return `${INSTRUCTIONS_COMMON}\n\n${toolset === "all" ? INSTRUCTIONS_REQUESTS : INSTRUCTIONS_CORE_ONLY}`;
+}
+/** Instructions for the full toolset; kept for callers that predate toolsets. */
+export const MCP_INSTRUCTIONS = mcpInstructions("all");
 const yearSchema = z.coerce
     .number()
     .int()
@@ -58,8 +106,25 @@ export const imageInputSchema = z.object({
         .enum(["thumb", "small", "medium", "large"])
         .optional()
         .describe(`Square size preset: thumb=${SIZES.thumb}, small=${SIZES.small}, medium=${SIZES.medium}, large=${SIZES.large} px. Omit for ${MAX_DIMENSION} px.`),
-    width: z.number().int().min(1).max(MAX_DIMENSION).optional().describe(`Explicit width in px (1-${MAX_DIMENSION}); overrides size.`),
+    width: z.number().int().min(1).max(MAX_DIMENSION).optional().describe(`Explicit width in px (1-${MAX_DIMENSION}); overrides size. With height too, the output is exactly width x height.`),
     height: z.number().int().min(1).max(MAX_DIMENSION).optional().describe(`Explicit height in px (1-${MAX_DIMENSION}).`),
+    fit: z
+        .enum(FITS)
+        .optional()
+        .describe("With width and height: contain (default) keeps the whole car and pads the rest; cover fills the box and crops; inside may return a smaller image."),
+    background: z
+        .string()
+        .max(20)
+        .optional()
+        .describe('Solid background: a hex color such as "#f4f4f4", "white" or "black". Omit for transparent (jpg is white).'),
+    trim: z.boolean().optional().describe("Crop to the car's own bounds before sizing, so it fills the box instead of floating in the square source frame."),
+    padding: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_PADDING_PERCENT)
+        .optional()
+        .describe(`Margin around a trimmed car, percent of its longer side (0-${MAX_PADDING_PERCENT}). Only with trim.`),
     format: z
         .enum(FORMATS)
         .default("png")
@@ -87,6 +152,17 @@ export const MCP_TOOL_SCHEMAS = {
             .max(1_000_000)
             .optional()
             .describe("Maximum redemptions per URL; 0 (default) means unlimited until expiry."),
+        renew: z
+            .boolean()
+            .optional()
+            .describe("Auto-renew past the TTL: the first load in each further window of ttl_seconds bills one more credit and renews the URL, until renew_days. Use for email, CMS pages and documents that outlive a TTL; pair with ttl_seconds 604800 so the cost ceiling is 1 credit per image per opened week. Requires max_uses 0."),
+        renew_days: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .optional()
+            .describe("How long a renewable URL keeps renewing, 1 to 365 days from creation (default 365). Only with renew: true."),
     }),
     search_vehicles: z.object({
         query: z
@@ -167,19 +243,287 @@ export const MCP_TOOL_SCHEMAS = {
         detail: z.string().max(500).optional().describe('Optional specifics, e.g. the article, the person, or the search query.'),
     }),
 };
+/* --------------------------------------------------------------- outputs ---
+ *
+ * A tool may advertise an `outputSchema` (MCP 2025-06-18 and later). Hosts show
+ * it next to the input schema, validate `structuredContent` against it, and can
+ * hand the model typed data instead of re-parsing the text block. The server SDK
+ * enforces the promise from the other side: a tool that declares an output
+ * schema and then returns no structured content, or content that does not match,
+ * fails the call. Two rules follow from that, and both are load-bearing:
+ *
+ *   - Every object here is a `looseObject`. These payloads are the REST API's,
+ *     which gains fields as the product does (`usage_30d`, `year_ranges`,
+ *     `limits`). A strict object advertises `additionalProperties: false`, which
+ *     would make a validating client reject a response for being newer than it.
+ *   - Only what BOTH servers guarantee is required. Where the remote server and
+ *     the stdio one disagreed, they were made to agree (`toVehicleMatch`,
+ *     `toImageOptions`, `etag` and `credits_usd` in the stdio handlers) rather
+ *     than the schema being weakened to cover both.
+ *
+ * `describe_api` deliberately has none: its result *is* the reference prose, and
+ * restating it as structured content would double the tokens of every call.
+ */
+/** The vehicle echoed back with an image: exactly what would render it again. */
+const vehicleDescriptorSchema = z.looseObject({
+    make: z.string(),
+    model: z.string(),
+    year: z.number().int(),
+    view: z.enum(VIEWS),
+    color: z.enum(COLORS),
+    width: z.number().int().optional(),
+    height: z.number().int().optional(),
+    fit: z.enum(FITS).optional(),
+    background: z.string().optional(),
+    trim: z.boolean().optional(),
+    padding: z.number().int().optional(),
+    format: z.enum([...FORMATS, "auto"]),
+});
+/** `free_credits` is absent from the account endpoint's copy; the packs are not. */
+const pricingSchema = z.looseObject({
+    credits_per_image: z.number(),
+    credits_per_dollar: z.number(),
+    free_credits: z.number().optional(),
+    packs: z
+        .array(z.looseObject({ credits: z.number().int(), cents: z.number().int(), label: z.string().optional() }))
+        .optional(),
+});
+/** One catalog hit, in the single spelling both servers emit (see {@link toVehicleMatch}). */
+const vehicleMatchSchema = z.looseObject({
+    kind: z.enum(["make", "model"]),
+    make: z.string(),
+    make_slug: z.string(),
+    model: z.string().nullable(),
+    model_slug: z.string().nullable(),
+    vehicle_type: z.string().nullable(),
+    years: z.array(z.number().int()),
+    match_kind: z.string().nullable(),
+});
+/** Shared by the list/create/vote results and, minus the count, by the detail. */
+const requestFields = {
+    id: z.string(),
+    kind: z.enum(REQUEST_KINDS),
+    title: z.string(),
+    body: z.string().nullable(),
+    vehicle: z.looseObject({ make: z.string(), model: z.string(), year: z.number().int().nullable() }).nullable(),
+    status: z.enum(REQUEST_STATUSES),
+    votes: z.number().int(),
+    author: z.string(),
+    url: z.string(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    viewer: z.looseObject({ voted: z.boolean() }).optional(),
+};
+const requestCommentSchema = z.looseObject({
+    id: z.string(),
+    request_id: z.string(),
+    body: z.string(),
+    author: z.string(),
+    created_at: z.string(),
+});
+const requestRecordSchema = z.looseObject({ ...requestFields, comments: z.number().int() });
+/** On the detail the thread takes the `comments` name, so the count moves aside. */
+const requestDetailSchema = z.looseObject({
+    ...requestFields,
+    comment_count: z.number().int(),
+    comments: z.array(requestCommentSchema),
+});
+const requestListResult = z.looseObject({
+    data: z.array(requestRecordSchema),
+    next_cursor: z.string().nullable(),
+    request_id: z.string(),
+});
+const requestResult = z.looseObject({ data: requestRecordSchema, request_id: z.string() });
+const createdRequestResult = z.looseObject({
+    data: requestRecordSchema,
+    /** True when an open vehicle request already existed and took the vote instead. */
+    deduplicated: z.boolean(),
+    request_id: z.string(),
+});
+export const MCP_TOOL_OUTPUT_SCHEMAS = {
+    get_car_image: z.looseObject({
+        credits_charged: z.number().nullable(),
+        credits_remaining: z.number().nullable(),
+        source: z.enum(["cache", "generated"]).nullable(),
+        width: z.number().int().nullable(),
+        height: z.number().int().nullable(),
+        content_type: z.string(),
+        etag: z.string().nullable(),
+        request_id: z.string().nullable(),
+        vehicle: vehicleDescriptorSchema,
+    }),
+    create_car_image_urls: z.looseObject({
+        data: z.array(z.looseObject({
+            id: z.string(),
+            /** Signed delivery URL; needs no key and is safe to put in HTML. */
+            url: z.string(),
+            expires_at: z.string(),
+            /** 0 means unlimited redemptions until it expires. */
+            max_uses: z.number().int(),
+            /** Auto-renewing URLs keep serving, one credit per opened window, until this instant. */
+            renews_until: z.string().nullable().optional(),
+            vehicle: vehicleDescriptorSchema,
+        })),
+        billing: z.looseObject({
+            charged_on: z.literal("creation"),
+            credits_charged: z.number(),
+            credits_remaining: z.number(),
+            renewal: z.looseObject({ window_seconds: z.number(), credits_per_window: z.number(), until: z.string() }).nullable().optional(),
+        }),
+        request_id: z.string(),
+    }),
+    search_vehicles: z.looseObject({
+        data: z.looseObject({ query: z.string(), results: z.array(vehicleMatchSchema) }),
+    }),
+    resolve_vehicle: z.looseObject({
+        data: z.looseObject({
+            /** Ready to pass straight to get_car_image. */
+            params: z.looseObject({
+                make: z.string(),
+                model: z.string(),
+                year: z.number().int(),
+                view: z.enum(VIEWS),
+                color: z.enum(COLORS),
+            }),
+            display: z.looseObject({ make_name: z.string(), model_name: z.string() }).optional(),
+            /** Other catalog vehicles that fit the phrase; ask when confidence is low. */
+            candidates: z.array(z.looseObject({
+                make_name: z.string().optional(),
+                make_slug: z.string().optional(),
+                model_name: z.string().optional(),
+                model_slug: z.string().optional(),
+                years: z.array(z.number().int()).optional(),
+                match_kind: z.string().optional(),
+            })),
+            /** high | medium | low; confirm with the human before spending on low. */
+            confidence: z.enum(["high", "medium", "low"]),
+            image_path: z.string().optional(),
+            /** The attributes read out of the phrase; nulls are what it did not say. */
+            extracted: z.looseObject({}).optional(),
+        }),
+        /** The equivalent CLI invocation, for a human who wants to repeat it. */
+        cli: z.string(),
+    }),
+    list_image_options: z.looseObject({
+        data: z.looseObject({
+            views: z.array(z.looseObject({
+                id: z.enum(VIEWS),
+                label: z.string(),
+                yaw_degrees: z.number(),
+                description: z.string(),
+                aliases: z.array(z.string()),
+            })),
+            colors: z.array(z.looseObject({ name: z.enum(COLORS), hex: z.string() })),
+            sizes: z.looseObject({ presets: z.record(z.string(), z.number().int()), max: z.number().int() }),
+            formats: z.array(z.enum(FORMATS)),
+            pricing: pricingSchema,
+            catalog: z.looseObject({
+                makes: z.number().int(),
+                models: z.number().int(),
+                /** [first, last] model year in the catalog. */
+                years: z.tuple([z.number().int(), z.number().int()]),
+                sources: z.array(z.string()),
+            }),
+        }),
+    }),
+    get_account: z.looseObject({
+        data: z.looseObject({
+            credits: z.number(),
+            credits_usd: z.number(),
+            auto_reload: z.boolean(),
+            has_payment_method: z.boolean(),
+            pricing: pricingSchema,
+            key: z.looseObject({ id: z.string().optional(), scopes: z.array(z.string()) }).optional(),
+        }),
+        links: z.record(z.string(), z.string()).optional(),
+        request_id: z.string().optional(),
+    }),
+    rate_image: z.looseObject({
+        data: z.looseObject({
+            asset_id: z.string().nullable().optional(),
+            /** True when the render was marked for re-rendering. */
+            flagged: z.boolean(),
+            rating: z.number().int().optional(),
+            verdict: z.enum(["good", "bad"]).optional(),
+        }),
+        request_id: z.string(),
+    }),
+    list_requests: requestListResult,
+    request_vehicle: createdRequestResult,
+    request_feature: createdRequestResult,
+    get_request: z.looseObject({ data: requestDetailSchema, request_id: z.string() }),
+    upvote_request: requestResult,
+    comment_on_request: z.looseObject({ data: requestCommentSchema, request_id: z.string() }),
+    share_building: z.looseObject({
+        data: z.looseObject({ building: z.string(), updated_at: z.string() }),
+        request_id: z.string(),
+    }),
+    share_referral: z.looseObject({
+        data: z.looseObject({ source: z.enum(REFERRAL_SOURCES), detail: z.string().nullable(), updated_at: z.string() }),
+        request_id: z.string(),
+    }),
+};
+/**
+ * Normalizes a catalog hit into the one shape `search_vehicles` promises.
+ *
+ * The remote server reads the catalog library (camelCase) and the stdio one
+ * reads `GET /api/v1/vehicles?q=` (snake_case, and it omits `model_name`
+ * entirely on a make hit rather than sending null). Agents pass these straight
+ * to get_car_image, so both are mapped onto `make`/`model` with explicit nulls.
+ */
+export function toVehicleMatch(source) {
+    return {
+        kind: source.kind,
+        make: source.makeName ?? source.make_name ?? "",
+        make_slug: source.makeSlug ?? source.make_slug ?? "",
+        model: source.modelName ?? source.model_name ?? null,
+        model_slug: source.modelSlug ?? source.model_slug ?? null,
+        vehicle_type: source.vehicleType ?? source.vehicle_type ?? null,
+        years: source.years ?? [],
+        match_kind: source.matchKind ?? source.match_kind ?? null,
+    };
+}
+function idsOf(values) {
+    if (!Array.isArray(values))
+        return [];
+    return values.map((value) => (typeof value === "string" ? value : String(value?.id ?? ""))).filter(Boolean);
+}
+/**
+ * Normalizes the options payload into the one shape `list_image_options`
+ * promises. `GET /api/v1/images/options` describes formats and catalog sources
+ * as objects and the year span as `{from, to}`; agents want bare ids and a
+ * `[from, to]` pair, so both that shape and an already-flat one are accepted.
+ * Anything else in the payload (`limits`, `sizes.source`) rides along untouched.
+ */
+export function toImageOptions(data) {
+    const source = (data ?? {});
+    const catalog = (source.catalog ?? {});
+    const years = catalog.years;
+    return {
+        ...source,
+        formats: idsOf(source.formats),
+        catalog: {
+            ...catalog,
+            years: Array.isArray(years) ? [years[0], years[1]] : [years?.from ?? MIN_YEAR, years?.to ?? MIN_YEAR],
+            sources: idsOf(catalog.sources),
+        },
+    };
+}
 export const MCP_TOOLS = {
     get_car_image: {
         name: "get_car_image",
         title: "Get car image",
-        description: `Render or fetch a studio-quality, transparent-background image of a specific vehicle (make, model, year) from one of six camera angles in one of fifteen preset colors. Returns the image inline (PNG/WebP/JPG, up to ${MAX_DIMENSION} px) plus usage metadata (credits_charged, credits_remaining, source cache|generated, request_id). COSTS ${CREDITS_PER_IMAGE} CREDIT per call, cached or generated. Use resolve_vehicle first when the request is free text; use create_car_image_urls instead when the image must be embedded in a web page or document.`,
+        description: `Render or fetch a studio-quality, transparent-background image of a specific vehicle (make, model, year) from one of six camera angles in one of fifteen preset colors, at any width and height up to ${MAX_DIMENSION} px (fit contain|cover|inside), transparent or on a solid background, optionally trimmed to the car. Returns the image inline (PNG/WebP/JPG) plus usage metadata (credits_charged, credits_remaining, source cache|generated, request_id). COSTS ${CREDITS_PER_IMAGE} CREDIT per call, cached or generated. Use resolve_vehicle first when the request is free text; use create_car_image_urls instead when the image must be embedded in a web page or document.`,
         inputSchema: MCP_TOOL_SCHEMAS.get_car_image,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_car_image,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
     create_car_image_urls: {
         name: "create_car_image_urls",
         title: "Create signed car image URLs",
-        description: "Create 1-50 signed, key-free delivery URLs that browsers, emails or documents can load directly (<img src>). Each URL costs 1 credit at creation; redemptions within the TTL are free and publicly cacheable. Returns id, url, expires_at, max_uses and the normalized vehicle for each image. Prefer this over get_car_image whenever the output is HTML, Markdown, a document or a website.",
+        description: "Create 1-50 signed, key-free delivery URLs that browsers, emails or documents can load directly (<img src>). Each URL costs 1 credit at creation; redemptions within the TTL are free and publicly cacheable. Each image takes the same sizing options as get_car_image (width, height, fit, background, trim). For email, CMS pages or documents that outlive a TTL, set renew: true with ttl_seconds 604800: the URL keeps serving past expiry at one more credit per opened week, for up to renew_days. Returns id, url, expires_at, max_uses, renews_until and the normalized vehicle for each image. Prefer this over get_car_image whenever the output is HTML, Markdown, a document or a website.",
         inputSchema: MCP_TOOL_SCHEMAS.create_car_image_urls,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.create_car_image_urls,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
     search_vehicles: {
@@ -187,13 +531,15 @@ export const MCP_TOOLS = {
         title: "Search the vehicle catalog",
         description: `Free. Fuzzy-search the open vehicle catalog (${CATALOG_MAKES} makes, ${CATALOG_MODELS} models, ${CATALOG_YEARS}) by make and/or model with typo tolerance. Returns canonical make/model names, available years and match kind, ready to pass to get_car_image. Use it to confirm a vehicle exists or to list a make's models before rendering.`,
         inputSchema: MCP_TOOL_SCHEMAS.search_vehicles,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.search_vehicles,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     resolve_vehicle: {
         name: "resolve_vehicle",
         title: "Resolve free text to image parameters",
-        description: 'Free. Turn a natural-language request such as "red 2024 porsche 911 side view" into exact get_car_image parameters (make, model, year, view, color) plus alternative candidates and a 0-1 confidence. Call this before rendering when the user did not spell out the parameters; ask the user to choose when confidence is low or several candidates fit.',
+        description: 'Free. Turn a natural-language request such as "red 2024 porsche 911 side view" into exact get_car_image parameters (make, model, year, view, color) plus alternative candidates and a confidence of high, medium or low. Call this before rendering when the user did not spell out the parameters; ask the user to choose when confidence is low or several candidates fit.',
         inputSchema: MCP_TOOL_SCHEMAS.resolve_vehicle,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.resolve_vehicle,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     list_image_options: {
@@ -201,6 +547,7 @@ export const MCP_TOOLS = {
         title: "List image options",
         description: "Free. List the supported camera views (with yaw angles and aliases), the fifteen preset colors with hex swatches, size presets, output formats, current pricing and catalog coverage. Use it when you need to validate or explain what can be requested.",
         inputSchema: MCP_TOOL_SCHEMAS.list_image_options,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_image_options,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
     get_account: {
@@ -208,6 +555,7 @@ export const MCP_TOOLS = {
         title: "Get account and credits",
         description: "Free. Show the caller's remaining credits (and the dollar equivalent), auto-reload status, whether a payment method is on file, recent usage and the key's scopes. Check this before large batches; if credits are insufficient, ask a human to top up rather than buying credits yourself.",
         inputSchema: MCP_TOOL_SCHEMAS.get_account,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_account,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     rate_image: {
@@ -215,6 +563,7 @@ export const MCP_TOOLS = {
         title: "Rate a delivered image",
         description: "Free. Record quality feedback on a delivered image, either by the request_id returned with it or by vehicle (make, model, year, view, color). Provide verdict good|bad or rating 1-5 and an optional reason. Feedback drives re-renders and prompt improvements.",
         inputSchema: MCP_TOOL_SCHEMAS.rate_image,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.rate_image,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
     describe_api: {
@@ -229,6 +578,7 @@ export const MCP_TOOLS = {
         title: "List vehicle and feature requests",
         description: "Free, public. List what people have asked for: vehicles missing from the catalog and feature ideas, with vote and comment counts, status (open, planned, in_progress, done, declined) and a public page URL. Sort by votes or recency, filter by kind or status. Use it before request_vehicle or request_feature to find an existing request to upvote.",
         inputSchema: MCP_TOOL_SCHEMAS.list_requests,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_requests,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     request_vehicle: {
@@ -236,6 +586,7 @@ export const MCP_TOOLS = {
         title: "Request a missing vehicle",
         description: "Free. Ask for a vehicle that search_vehicles/resolve_vehicle cannot find. If an open request for the same make, model and year already exists it is upvoted instead and returned with deduplicated: true, so calling this is always safe. The requester's vote counts, and the human gets a short thank-you email with the request page.",
         inputSchema: MCP_TOOL_SCHEMAS.request_vehicle,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.request_vehicle,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     request_feature: {
@@ -243,6 +594,7 @@ export const MCP_TOOLS = {
         title: "Request a feature",
         description: "Free. File a feature request for the API (new views, formats, endpoints, anything). Not deduplicated: check list_requests first and upvote an existing one when it matches. Returns the request with its public page URL; the human gets a short thank-you email.",
         inputSchema: MCP_TOOL_SCHEMAS.request_feature,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.request_feature,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
     get_request: {
@@ -250,6 +602,7 @@ export const MCP_TOOLS = {
         title: "Get a request",
         description: "Free, public. One request with its full comment thread, vote count and status.",
         inputSchema: MCP_TOOL_SCHEMAS.get_request,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_request,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     upvote_request: {
@@ -257,6 +610,7 @@ export const MCP_TOOLS = {
         title: "Upvote a request",
         description: "Free. Add the caller's vote to a request (idempotent; voting twice changes nothing). Returns the updated request.",
         inputSchema: MCP_TOOL_SCHEMAS.upvote_request,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.upvote_request,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     comment_on_request: {
@@ -264,6 +618,7 @@ export const MCP_TOOLS = {
         title: "Comment on a request",
         description: "Free. Add a public comment to a request, e.g. the body style or use case that matters. Comments show the author's first name only.",
         inputSchema: MCP_TOOL_SCHEMAS.comment_on_request,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.comment_on_request,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
     share_building: {
@@ -271,6 +626,7 @@ export const MCP_TOOLS = {
         title: "Tell us what you are building",
         description: "Free. Record what the human is building with the API. Private to the Car Image team (never shown publicly); re-sharing overwrites the previous answer. Only call it with the human's own words and consent.",
         inputSchema: MCP_TOOL_SCHEMAS.share_building,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.share_building,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
     share_referral: {
@@ -278,6 +634,7 @@ export const MCP_TOOLS = {
         title: "Tell us how you found us",
         description: "Free. Record where the human first heard about Car Image API (one of a fixed list of sources, plus optional detail). Private to the Car Image team; re-sharing overwrites. Only call it with the human's consent.",
         inputSchema: MCP_TOOL_SCHEMAS.share_referral,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.share_referral,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     },
 };
@@ -297,10 +654,13 @@ export const API_REFERENCE = [
             `view (${VIEWS.join("|")}; default front-3-4)`,
             `color (${COLORS.join("|")}; default silver)`,
             "size (thumb=256|small=512|medium=768|large=1024)",
-            `w, h (1-${MAX_DIMENSION} px)`,
-            `format (${FORMATS.join("|")}; default png)`,
+            `w, h (1-${MAX_DIMENSION} px; both -> the output is exactly w x h)`,
+            `fit (${FITS.join("|")}; default contain; only matters with both w and h)`,
+            "background (transparent default; white|black|hex such as f4f4f4; jpg defaults to white)",
+            `trim (1 crops to the car's alpha bounds before sizing), padding (0-${MAX_PADDING_PERCENT} percent, only with trim)`,
+            `format (${FORMATS.join("|")}|auto; default png; auto negotiates webp/png from Accept)`,
         ],
-        returns: "image bytes; headers X-Credits-Charged, X-Credits-Remaining, X-Image-Source (cache|generated), X-Image-Width, X-Image-Height, ETag, X-Request-Id. With Accept: application/json: {data:{url,expires_at,vehicle,width,height,format}, billing:{credits_charged,credits_remaining}, request_id}",
+        returns: "image bytes; headers X-Credits-Charged, X-Credits-Remaining, X-Image-Source (cache|generated), X-Image-Width, X-Image-Height, ETag, X-Request-Id (Vary: Accept with format=auto). With Accept: application/json: {data:{url,expires_at,vehicle,width,height,format}, billing:{credits_charged,credits_remaining}, request_id}",
         errors: ["400 invalid params", "401 missing/invalid key", "402 insufficient credits (balance, required_credits)", "404 vehicle not in catalog", "429 rate limited (Retry-After)", "502 render failed (refunded)"],
         notes: "Do not purchase credits automatically on 402; ask the human. Respect Retry-After on 429.",
         sdk: "client.getImage({ make, model, year, view, color, size, format }) / client.getImageUrl(...)",
@@ -312,20 +672,20 @@ export const API_REFERENCE = [
         summary: "Create 1-50 signed delivery URLs for browsers (no key needed to load them).",
         auth: "bearer",
         credits: "1 per URL, charged at creation; redemptions are free",
-        params: ["images: [{make, model, year, view?, color?, width?, height?, format?}] (or a single image object)", "ttl_seconds (60-604800; default 3600)", "max_uses (0 = unlimited; default 0)"],
-        returns: "201 {data:[{id,url,expires_at,max_uses,vehicle}], billing:{charged_on:'creation',credits_charged,credits_remaining}, request_id}",
-        errors: ["400 invalid body or batch > 50", "401", "402", "404 vehicle not in catalog", "429"],
-        sdk: "client.createImageUrls([{ make, model, year }], { ttlSeconds, maxUses })",
-        cli: "car-image url --make BMW --model M3 --year 2022 --ttl 86400",
+        params: ["images: [{make, model, year, view?, color?, size?, width?, height?, fit?, background?, trim?, padding?, format?}] (or a single image object)", "ttl_seconds (60-604800; default 3600)", "max_uses (0 = unlimited; default 0)", "renew (auto-renew past the TTL at 1 credit per opened window; requires max_uses 0)", "renew_days (1-365; default 365)", "header Idempotency-Key (optional; a retry with the same key and body replays the first response instead of billing again)"],
+        returns: "201 {data:[{id,url,expires_at,max_uses,renews_until,vehicle}], billing:{charged_on:'creation',credits_charged,credits_remaining,credits_per_url,renewal?}, request_id}; a replay carries Idempotent-Replayed: true",
+        errors: ["400 invalid body or batch > 50", "401", "402", "404 vehicle not in catalog", "409 same Idempotency-Key still in flight", "422 same Idempotency-Key with a different body", "429"],
+        sdk: "client.createImageUrls([{ make, model, year }], { ttlSeconds, maxUses, renew, renewDays })",
+        cli: "car-image url --make BMW --model M3 --year 2022 --ttl 86400 [--renew] [--idempotency-key <key>]",
     },
     {
         method: "GET",
         path: "/api/v1/delivery/{token}",
-        summary: "Redeem a signed URL; public within its TTL and max_uses.",
+        summary: "Redeem a signed URL; public within its TTL and max_uses. An auto-renewing URL loaded after its TTL bills 1 credit for the new window on first load.",
         auth: "public",
-        credits: "free",
-        returns: "image bytes with public Cache-Control for the remaining lifetime",
-        errors: ["404/410 expired, exhausted or invalid token"],
+        credits: "free within a paid window; 1 per new window of a renewable URL",
+        returns: "image bytes with public Cache-Control for the remaining window",
+        errors: ["403 expired, revoked or invalid token", "402 renewal unpaid (resumes once credits land)", "410 exhausted"],
     },
     {
         method: "GET",
@@ -333,7 +693,7 @@ export const API_REFERENCE = [
         summary: "Views, colors, sizes, formats, pricing and catalog coverage.",
         auth: "public",
         credits: "free",
-        returns: "{data:{views:[{id,label,yaw_degrees,description,aliases}], colors:[{name,hex}], sizes:{presets,max}, formats, pricing:{credits_per_image,credits_per_dollar,free_credits}, catalog:{makes,models,years,sources}}}",
+        returns: "{data:{views:[{id,label,yaw_degrees,description,aliases}], colors:[{name,hex}], sizes:{presets,max,source}, fits, default_fit, backgrounds, trim, formats, pricing:{credits_per_image,credits_per_dollar,free_credits}, catalog:{makes,models,years,sources}}}",
         sdk: "client.options()",
         cli: "car-image options",
     },
@@ -344,7 +704,7 @@ export const API_REFERENCE = [
         auth: "bearer",
         credits: "free",
         params: ['query: "red 2024 porsche 911 side view"'],
-        returns: "{data:{params:{make,model,year,view,color}, candidates:[...], confidence:0-1}}",
+        returns: "{data:{params:{make,model,year,view,color}, display:{make_name,model_name}, candidates:[...], confidence:high|medium|low, image_path}}",
         sdk: "client.resolve(query)",
         cli: "car-image resolve red 2024 porsche 911 side view",
     },