@meterapp/car-image-sdk 1.0.2 → 1.2.0

package/dist/mcp/index.js

@@ -10,17 +10,25 @@
  * entry point of the SDK has no runtime dependencies.
  */
 import * as z from "zod";
-import { COLORS, CREDITS_PER_DOLLAR, CREDITS_PER_IMAGE, DEFAULT_BASE_URL, FORMATS, FREE_CREDITS, MAX_DIMENSION, MIN_YEAR, SIZES, VIEWS, } from "../types.js";
+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 { SDK_VERSION } from "../version.js";
+/**
+ * Catalog size as agents read it in the instructions and tool descriptions.
+ * Derived from CATALOG so the figures cannot drift from the database; agents
+ * pick tools off these numbers, so understating them costs real calls.
+ */
+const CATALOG_MAKES = CATALOG.makes.toLocaleString("en-US");
+const CATALOG_MODELS = CATALOG.models.toLocaleString("en-US");
+const CATALOG_YEARS = `${CATALOG.yearFrom}-${CATALOG.yearTo}`;
 export const MCP_SERVER_INFO = {
     name: "car-image-api",
     title: "Car Image API",
     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 (1,145 makes, 14,841 models, model years 1990-2026). Six camera views, fifteen preset colors, PNG/WebP/JPG up to 1024 px.
+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.
 
-Costs: every delivered image costs exactly ${CREDITS_PER_IMAGE} credit ($1 = ${CREDITS_PER_DOLLAR.toLocaleString("en-US")} credits; ${FREE_CREDITS} free credits per account), whether it is served from cache or generated on demand. 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.
+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.
 
 Workflow: (1) resolve_vehicle turns free text such as "red 2024 porsche 911 side view" into exact parameters; search_vehicles browses the catalog. (2) Call get_car_image when the image itself is needed in the conversation. (3) For web pages, emails, documents or anything a browser will load, call create_car_image_urls and embed the signed URLs; they need no key.
 
@@ -28,7 +36,9 @@ 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.`;
+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.`;
 const yearSchema = z.coerce
     .number()
     .int()
@@ -77,6 +87,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
@@ -119,27 +140,328 @@ export const MCP_TOOL_SCHEMAS = {
             .optional()
             .describe('Filter by path fragment or keyword, e.g. "images/car", "image-urls", "feedback". Omit for the full compact reference.'),
     }),
+    list_requests: z.object({
+        kind: z.enum(REQUEST_KINDS).optional().describe("Only vehicle requests or only feature requests. Omit for both."),
+        status: z
+            .enum(REQUEST_STATUSES)
+            .optional()
+            .describe("Filter by status. Omit for everything that is not declined."),
+        sort: z.enum(REQUEST_SORTS).default("top").describe("top = most upvotes first (default); new = most recent first."),
+        limit: z.number().int().min(1).max(100).default(25).describe("Maximum number of requests (1-100)."),
+        cursor: z.string().max(200).optional().describe("next_cursor from a previous page, to read the next one."),
+    }),
+    request_vehicle: z.object({
+        make: z.string().min(1).max(80).describe('Manufacturer, e.g. "Rivian". Case does not matter.'),
+        model: z.string().min(1).max(80).describe('Model, e.g. "R1T".'),
+        year: z.coerce.number().int().min(1900).max(2035).optional().describe("Model year, if it matters. Omit to ask for the model in general."),
+        note: z.string().max(2000).optional().describe("Why it is needed, body style, trim; anything that helps prioritise."),
+    }),
+    request_feature: z.object({
+        title: z.string().min(1).max(120).describe('Short summary, e.g. "Interior views".'),
+        body: z.string().max(2000).optional().describe("Details: the use case, what the output should look like."),
+    }),
+    get_request: z.object({
+        id: z.string().uuid().describe("The request id from list_requests, request_vehicle or request_feature."),
+    }),
+    upvote_request: z.object({
+        id: z.string().uuid().describe("The request id to upvote. Idempotent."),
+    }),
+    comment_on_request: z.object({
+        id: z.string().uuid().describe("The request id to comment on."),
+        body: z.string().min(1).max(1000).describe("The comment (1-1000 characters)."),
+    }),
+    share_building: z.object({
+        building: z.string().min(1).max(2000).describe("What the human is building with the API, in their words (1-2000 characters)."),
+    }),
+    share_referral: z.object({
+        source: z.enum(REFERRAL_SOURCES).describe("Where the human first heard about Car Image API."),
+        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(),
+    format: z.enum(FORMATS),
+});
+/** `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(),
+            })),
+            confidence: z.union([z.enum(["high", "medium", "low"]), z.number()]),
+            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.`,
         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. 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: {
         name: "search_vehicles",
         title: "Search the vehicle catalog",
-        description: "Free. Fuzzy-search the open vehicle catalog (1,145 makes, 14,841 models, 1990-2026) 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.",
+        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: {
@@ -147,6 +469,7 @@ export const MCP_TOOLS = {
         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.',
         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: {
@@ -154,6 +477,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: {
@@ -161,6 +485,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: {
@@ -168,6 +493,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: {
@@ -177,6 +503,70 @@ export const MCP_TOOLS = {
         inputSchema: MCP_TOOL_SCHEMAS.describe_api,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    list_requests: {
+        name: "list_requests",
+        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: {
+        name: "request_vehicle",
+        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: {
+        name: "request_feature",
+        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: {
+        name: "get_request",
+        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: {
+        name: "upvote_request",
+        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: {
+        name: "comment_on_request",
+        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: {
+        name: "share_building",
+        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: {
+        name: "share_referral",
+        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 },
+    },
 };
 export const MCP_TOOL_LIST = Object.values(MCP_TOOLS);
 /** Compact, hand-maintained mirror of /openapi.json for agents that cannot fetch it. */
@@ -190,7 +580,7 @@ export const API_REFERENCE = [
         params: [
             "make (required)",
             "model (required)",
-            "year (required, 1990-2026)",
+            `year (required, ${CATALOG_YEARS})`,
             `view (${VIEWS.join("|")}; default front-3-4)`,
             `color (${COLORS.join("|")}; default silver)`,
             "size (thumb=256|small=512|medium=768|large=1024)",
@@ -209,20 +599,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}",
+        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)", "renew (auto-renew past the TTL at 1 credit per opened window; requires max_uses 0)", "renew_days (1-365; default 365)"],
+        returns: "201 {data:[{id,url,expires_at,max_uses,renews_until,vehicle}], billing:{charged_on:'creation',credits_charged,credits_remaining,renewal?}, 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",
+        sdk: "client.createImageUrls([{ make, model, year }], { ttlSeconds, maxUses, renew, renewDays })",
+        cli: "car-image url --make BMW --model M3 --year 2022 --ttl 86400 [--renew]",
     },
     {
         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",
@@ -267,6 +657,86 @@ export const API_REFERENCE = [
         sdk: "client.feedback({ requestId, verdict: 'good' })",
         cli: "car-image feedback --request-id <id> --good",
     },
+    {
+        method: "GET",
+        path: "/api/v1/requests",
+        summary: "Public board of vehicle and feature requests (votes, comments, status).",
+        auth: "public",
+        credits: "free",
+        params: ["kind (vehicle|feature)", "status (open|planned|in_progress|done|declined; default: all but declined)", "sort (top|new; default top)", "limit (1-100; default 25)", "cursor (from next_cursor)"],
+        returns: "{data:[{id,kind,title,body,vehicle:{make,model,year}|null,status,votes,comments,author,url,created_at,updated_at,viewer?:{voted}}], next_cursor, request_id}. `viewer` appears when a key is sent.",
+        sdk: "client.listRequests({ kind: 'vehicle', sort: 'top' })",
+        cli: "car-image request list --kind vehicle",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/requests",
+        summary: "Request a missing vehicle or a feature.",
+        auth: "bearer",
+        credits: "free (scope account:read)",
+        params: ["kind: vehicle -> make, model (required), year?, body?", "kind: feature -> title (required), body?"],
+        returns: "201 {data: request, deduplicated:false} or 200 {data, deduplicated:true} when an open vehicle request for the same make/model/year already existed (it was upvoted instead)",
+        notes: "The creator's own vote counts. A new request sends the requester one thank-you email; dedup hits, upvotes and comments never email.",
+        sdk: "client.createRequest({ kind: 'vehicle', make: 'Rivian', model: 'R1T', year: 2024 })",
+        cli: "car-image request vehicle --make Rivian --model R1T --year 2024",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/requests/{id}",
+        summary: "One request with its comment thread.",
+        auth: "public",
+        credits: "free",
+        returns: "{data:{...request, comment_count, comments:[{id,request_id,body,author,created_at}]}, request_id}",
+        errors: ["404 unknown request"],
+        sdk: "client.getRequest(id)",
+        cli: "car-image request show <id>",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/requests/{id}/votes",
+        summary: "Upvote a request (idempotent). DELETE removes the vote.",
+        auth: "bearer",
+        credits: "free (scope account:read)",
+        returns: "200 {data: request with viewer.voted, request_id}",
+        errors: ["404 unknown request"],
+        sdk: "client.voteRequest(id) / client.unvoteRequest(id)",
+        cli: "car-image request upvote <id>",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/requests/{id}/comments",
+        summary: "Comment on a request; GET lists the thread (public).",
+        auth: "bearer",
+        credits: "free (scope account:read)",
+        params: ["body (1-1000 chars)"],
+        returns: "201 {data:{id,request_id,body,author,created_at}, request_id}",
+        errors: ["400 empty or long body", "404 unknown request", "429 too many comments"],
+        sdk: "client.commentOnRequest(id, body)",
+        cli: "car-image request comment <id> \"…\"",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/account/building",
+        summary: "Tell us what you are building (private; overwrites).",
+        auth: "bearer",
+        credits: "free (scope account:read)",
+        params: ["building (1-2000 chars)"],
+        returns: "200 {data:{building, updated_at}, request_id}",
+        notes: "Never returned by any public endpoint. First answer earns one thank-you email.",
+        sdk: "client.shareBuilding('A dealer site…')",
+        cli: "car-image about building \"A dealer site…\"",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/account/referral",
+        summary: "Tell us how you found us (private; overwrites).",
+        auth: "bearer",
+        credits: "free (scope account:read)",
+        params: [`source (${REFERRAL_SOURCES.join("|")})`, "detail (optional, <= 500 chars)"],
+        returns: "200 {data:{source, detail, updated_at}, request_id}",
+        sdk: "client.shareReferral({ source: 'github' })",
+        cli: "car-image about referral github --detail \"the vehicle-db README\"",
+    },
     {
         method: "GET",
         path: "/api/v1/account",