@meterapp/car-image-sdk 1.0.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Shared MCP tool definitions for the Car Image API.
+ *
+ * Both MCP servers import from here so agents see identical tools:
+ *   - the stdio server in `@meterapp/car-image` (`car-image mcp`), which calls the REST API, and
+ *   - the remote Streamable HTTP server at https://car-imgs.vercel.app/api/mcp, which executes
+ *     against the server libraries directly.
+ *
+ * This module needs `zod` (an optional peer dependency of the SDK). The main
+ * entry point of the SDK has no runtime dependencies.
+ */
+import * as z from "zod";
+export declare const MCP_SERVER_INFO: {
+    readonly name: "car-image-api";
+    readonly title: "Car Image API";
+    readonly version: "1.0.0";
+    readonly websiteUrl: "https://car-imgs.vercel.app";
+};
+export declare const MCP_INSTRUCTIONS: string;
+export declare const imageInputSchema: z.ZodObject<{
+    make: z.ZodString;
+    model: z.ZodString;
+    year: z.ZodCoercedNumber<unknown>;
+    view: z.ZodDefault<z.ZodEnum<{
+        front: "front";
+        "front-3-4": "front-3-4";
+        side: "side";
+        "side-right": "side-right";
+        rear: "rear";
+        "rear-3-4": "rear-3-4";
+    }>>;
+    color: z.ZodDefault<z.ZodEnum<{
+        white: "white";
+        black: "black";
+        gray: "gray";
+        silver: "silver";
+        blue: "blue";
+        red: "red";
+        green: "green";
+        brown: "brown";
+        beige: "beige";
+        tan: "tan";
+        orange: "orange";
+        yellow: "yellow";
+        gold: "gold";
+        burgundy: "burgundy";
+        purple: "purple";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        thumb: "thumb";
+        small: "small";
+        medium: "medium";
+        large: "large";
+    }>>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodDefault<z.ZodEnum<{
+        png: "png";
+        webp: "webp";
+        jpg: "jpg";
+    }>>;
+}, z.core.$strip>;
+export type ImageInput = z.infer<typeof imageInputSchema>;
+export declare const MCP_TOOL_SCHEMAS: {
+    readonly get_car_image: z.ZodObject<{
+        make: z.ZodString;
+        model: z.ZodString;
+        year: z.ZodCoercedNumber<unknown>;
+        view: z.ZodDefault<z.ZodEnum<{
+            front: "front";
+            "front-3-4": "front-3-4";
+            side: "side";
+            "side-right": "side-right";
+            rear: "rear";
+            "rear-3-4": "rear-3-4";
+        }>>;
+        color: z.ZodDefault<z.ZodEnum<{
+            white: "white";
+            black: "black";
+            gray: "gray";
+            silver: "silver";
+            blue: "blue";
+            red: "red";
+            green: "green";
+            brown: "brown";
+            beige: "beige";
+            tan: "tan";
+            orange: "orange";
+            yellow: "yellow";
+            gold: "gold";
+            burgundy: "burgundy";
+            purple: "purple";
+        }>>;
+        size: z.ZodOptional<z.ZodEnum<{
+            thumb: "thumb";
+            small: "small";
+            medium: "medium";
+            large: "large";
+        }>>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodDefault<z.ZodEnum<{
+            png: "png";
+            webp: "webp";
+            jpg: "jpg";
+        }>>;
+    }, z.core.$strip>;
+    readonly create_car_image_urls: z.ZodObject<{
+        images: z.ZodArray<z.ZodObject<{
+            make: z.ZodString;
+            model: z.ZodString;
+            year: z.ZodCoercedNumber<unknown>;
+            view: z.ZodDefault<z.ZodEnum<{
+                front: "front";
+                "front-3-4": "front-3-4";
+                side: "side";
+                "side-right": "side-right";
+                rear: "rear";
+                "rear-3-4": "rear-3-4";
+            }>>;
+            color: z.ZodDefault<z.ZodEnum<{
+                white: "white";
+                black: "black";
+                gray: "gray";
+                silver: "silver";
+                blue: "blue";
+                red: "red";
+                green: "green";
+                brown: "brown";
+                beige: "beige";
+                tan: "tan";
+                orange: "orange";
+                yellow: "yellow";
+                gold: "gold";
+                burgundy: "burgundy";
+                purple: "purple";
+            }>>;
+            size: z.ZodOptional<z.ZodEnum<{
+                thumb: "thumb";
+                small: "small";
+                medium: "medium";
+                large: "large";
+            }>>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            format: z.ZodDefault<z.ZodEnum<{
+                png: "png";
+                webp: "webp";
+                jpg: "jpg";
+            }>>;
+        }, z.core.$strip>>;
+        ttl_seconds: z.ZodOptional<z.ZodNumber>;
+        max_uses: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly search_vehicles: z.ZodObject<{
+        query: z.ZodString;
+        year: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly resolve_vehicle: z.ZodObject<{
+        query: z.ZodString;
+    }, z.core.$strip>;
+    readonly list_image_options: z.ZodObject<{}, z.core.$strip>;
+    readonly get_account: z.ZodObject<{}, z.core.$strip>;
+    readonly rate_image: z.ZodObject<{
+        request_id: z.ZodOptional<z.ZodString>;
+        make: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        year: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        view: z.ZodOptional<z.ZodEnum<{
+            front: "front";
+            "front-3-4": "front-3-4";
+            side: "side";
+            "side-right": "side-right";
+            rear: "rear";
+            "rear-3-4": "rear-3-4";
+        }>>;
+        color: z.ZodOptional<z.ZodEnum<{
+            white: "white";
+            black: "black";
+            gray: "gray";
+            silver: "silver";
+            blue: "blue";
+            red: "red";
+            green: "green";
+            brown: "brown";
+            beige: "beige";
+            tan: "tan";
+            orange: "orange";
+            yellow: "yellow";
+            gold: "gold";
+            burgundy: "burgundy";
+            purple: "purple";
+        }>>;
+        rating: z.ZodOptional<z.ZodNumber>;
+        verdict: z.ZodOptional<z.ZodEnum<{
+            good: "good";
+            bad: "bad";
+        }>>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly describe_api: z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+export type McpToolName = keyof typeof MCP_TOOL_SCHEMAS;
+export type McpToolInput<N extends McpToolName> = z.infer<(typeof MCP_TOOL_SCHEMAS)[N]>;
+export interface McpToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface McpToolDefinition<N extends McpToolName = McpToolName> {
+    name: N;
+    title: string;
+    description: string;
+    inputSchema: (typeof MCP_TOOL_SCHEMAS)[N];
+    annotations: McpToolAnnotations;
+}
+export declare const MCP_TOOLS: {
+    [N in McpToolName]: McpToolDefinition<N>;
+};
+export declare const MCP_TOOL_LIST: McpToolDefinition[];
+export interface ApiEndpointReference {
+    method: "GET" | "POST";
+    path: string;
+    summary: string;
+    auth: "bearer" | "public";
+    credits: string;
+    params?: string[];
+    returns?: string;
+    errors?: string[];
+    notes?: string;
+    sdk?: string;
+    cli?: string;
+}
+/** Compact, hand-maintained mirror of /openapi.json for agents that cannot fetch it. */
+export declare const API_REFERENCE: ApiEndpointReference[];
+/** Human/agent-readable rendering of {@link API_REFERENCE}, optionally filtered. */
+export declare function formatApiReference(filter?: string): string;
+/** Text content block as used in MCP tool results. */
+export type McpTextContent = {
+    type: "text";
+    text: string;
+};
+/** Image content block as used in MCP tool results. */
+export type McpImageContent = {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export type McpToolResult = {
+    content: Array<McpTextContent | McpImageContent>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+};
+/** A JSON payload as both readable text and structured content. */
+export declare function jsonToolResult(value: Record<string, unknown>, summary?: string): McpToolResult;
+/** An `isError` result whose text tells the agent what to do next. */
+export declare function errorToolResult(message: string, extra?: Record<string, unknown>): McpToolResult;
+/** Standard guidance appended to error results, keyed by HTTP-ish status. */
+export declare function nextStepFor(status: number | null | undefined): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp/index.js

@@ -0,0 +1,404 @@
+/**
+ * Shared MCP tool definitions for the Car Image API.
+ *
+ * Both MCP servers import from here so agents see identical tools:
+ *   - the stdio server in `@meterapp/car-image` (`car-image mcp`), which calls the REST API, and
+ *   - the remote Streamable HTTP server at https://car-imgs.vercel.app/api/mcp, which executes
+ *     against the server libraries directly.
+ *
+ * This module needs `zod` (an optional peer dependency of the SDK). The main
+ * 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 { SDK_VERSION } from "../version.js";
+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.
+
+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.
+
+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.
+
+Security: never place the API key in URLs, HTML, logs, screenshots or client-side code. Signed delivery URLs are the only thing that should ever reach a browser.
+
+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.`;
+const yearSchema = z.coerce
+    .number()
+    .int()
+    .min(MIN_YEAR)
+    .max(2100)
+    .describe(`Model year, e.g. 2024. The catalog covers ${MIN_YEAR} through next year.`);
+export const imageInputSchema = z.object({
+    make: z.string().min(1).max(80).describe('Manufacturer, e.g. "Porsche", "BMW", "Toyota". Case and punctuation do not matter.'),
+    model: z.string().min(1).max(80).describe('Model as listed in the catalog, e.g. "911", "M3", "Corolla".'),
+    year: yearSchema,
+    view: z
+        .enum(VIEWS)
+        .default("front-3-4")
+        .describe("Camera angle: front (0°), front-3-4 (35°, the classic hero angle), side (profile, nose left), side-right (profile, nose right), rear (180°), rear-3-4 (145°)."),
+    color: z.enum(COLORS).default("silver").describe("Paint color; one of the fifteen presets."),
+    size: z
+        .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.`),
+    height: z.number().int().min(1).max(MAX_DIMENSION).optional().describe(`Explicit height in px (1-${MAX_DIMENSION}).`),
+    format: z
+        .enum(FORMATS)
+        .default("png")
+        .describe("png keeps the transparent background (default); webp is smallest; jpg is flattened onto white."),
+});
+export const MCP_TOOL_SCHEMAS = {
+    get_car_image: imageInputSchema,
+    create_car_image_urls: z.object({
+        images: z
+            .array(imageInputSchema)
+            .min(1)
+            .max(50)
+            .describe("One to fifty image requests. Each URL costs 1 credit when created."),
+        ttl_seconds: z
+            .number()
+            .int()
+            .min(60)
+            .max(7 * 24 * 60 * 60)
+            .optional()
+            .describe("How long the URLs stay valid, 60 to 604800 seconds (7 days). Default 3600."),
+        max_uses: z
+            .number()
+            .int()
+            .min(0)
+            .max(1_000_000)
+            .optional()
+            .describe("Maximum redemptions per URL; 0 (default) means unlimited until expiry."),
+    }),
+    search_vehicles: z.object({
+        query: z
+            .string()
+            .min(1)
+            .max(120)
+            .describe('Free text: make and/or model, optional year, typos tolerated, e.g. "porshe 911" or "2019 f150".'),
+        year: z.number().int().min(MIN_YEAR).max(2100).optional().describe("Restrict results to one model year."),
+        limit: z.number().int().min(1).max(50).default(10).describe("Maximum number of results (1-50)."),
+    }),
+    resolve_vehicle: z.object({
+        query: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('Natural-language description of the wanted image, e.g. "red 2024 porsche 911 side view".'),
+    }),
+    list_image_options: z.object({}),
+    get_account: z.object({}),
+    rate_image: z.object({
+        request_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("The request_id returned by get_car_image or create_car_image_urls (preferred way to identify the image)."),
+        make: z.string().min(1).max(80).optional().describe("Alternative to request_id: identify the image by vehicle."),
+        model: z.string().min(1).max(80).optional(),
+        year: z.coerce.number().int().min(MIN_YEAR).max(2100).optional(),
+        view: z.enum(VIEWS).optional(),
+        color: z.enum(COLORS).optional(),
+        rating: z.number().int().min(1).max(5).optional().describe("1 (unusable) to 5 (perfect)."),
+        verdict: z.enum(["good", "bad"]).optional().describe("Quick thumbs up/down; provide this or rating."),
+        reason: z.string().max(500).optional().describe("What was wrong or right, e.g. 'wrong body style', 'perfect angle'."),
+    }),
+    describe_api: z.object({
+        endpoint: z
+            .string()
+            .max(120)
+            .optional()
+            .describe('Filter by path fragment or keyword, e.g. "images/car", "image-urls", "feedback". Omit for the full compact reference.'),
+    }),
+};
+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,
+        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.",
+        inputSchema: MCP_TOOL_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.",
+        inputSchema: MCP_TOOL_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.',
+        inputSchema: MCP_TOOL_SCHEMAS.resolve_vehicle,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    list_image_options: {
+        name: "list_image_options",
+        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,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    get_account: {
+        name: "get_account",
+        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,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    rate_image: {
+        name: "rate_image",
+        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,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    describe_api: {
+        name: "describe_api",
+        title: "Describe the REST API",
+        description: "Free. Return a compact reference of the Car Image REST API (methods, paths, parameters, credit costs, response headers, error codes, agent notes) for writing code that calls the API directly, with SDK (`@meterapp/car-image-sdk`) and CLI (`npx @meterapp/car-image`) equivalents. Optional endpoint filter.",
+        inputSchema: MCP_TOOL_SCHEMAS.describe_api,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+};
+export const MCP_TOOL_LIST = Object.values(MCP_TOOLS);
+/** Compact, hand-maintained mirror of /openapi.json for agents that cannot fetch it. */
+export const API_REFERENCE = [
+    {
+        method: "GET",
+        path: "/api/v1/images/car",
+        summary: "Get a billed vehicle image (bytes, or a signed URL with Accept: application/json).",
+        auth: "bearer",
+        credits: "1 per call (cached or generated)",
+        params: [
+            "make (required)",
+            "model (required)",
+            "year (required, 1990-2026)",
+            `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)`,
+        ],
+        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}",
+        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(...)",
+        cli: "car-image get --make Porsche --model 911 --year 2024 --view side --color red --out car.png",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/image-urls",
+        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",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/delivery/{token}",
+        summary: "Redeem a signed URL; public within its TTL and max_uses.",
+        auth: "public",
+        credits: "free",
+        returns: "image bytes with public Cache-Control for the remaining lifetime",
+        errors: ["404/410 expired, exhausted or invalid token"],
+    },
+    {
+        method: "GET",
+        path: "/api/v1/images/options",
+        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}}}",
+        sdk: "client.options()",
+        cli: "car-image options",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/images/resolve",
+        summary: "Resolve free text to exact image parameters.",
+        auth: "bearer",
+        credits: "free",
+        params: ['query: "red 2024 porsche 911 side view"'],
+        returns: "{data:{params:{make,model,year,view,color}, candidates:[...], confidence:0-1}}",
+        sdk: "client.resolve(query)",
+        cli: "car-image resolve red 2024 porsche 911 side view",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/vehicles",
+        summary: "Browse or search the catalog.",
+        auth: "public",
+        credits: "free",
+        params: ["(none) -> years", "year -> makes [{id,name}]", "year + makeId -> models", "q (+ limit) -> fuzzy search results"],
+        returns: "{data:{years}} | {data:{year,makes}} | {data:{year,make_id,models}} | {data:{results}}",
+        sdk: "client.vehicles({ year, makeId }) / client.searchVehicles(q, { limit })",
+        cli: "car-image search porsche 911",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/feedback",
+        summary: "Rate a delivered image.",
+        auth: "bearer",
+        credits: "free",
+        params: ["request_id OR make, model, year (+ view, color)", "rating 1-5 and/or verdict good|bad", "reason (optional)"],
+        returns: "201 {data:{...}, request_id}",
+        sdk: "client.feedback({ requestId, verdict: 'good' })",
+        cli: "car-image feedback --request-id <id> --good",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/account",
+        summary: "Credits, auto-reload, payment method, 30-day usage, key scopes.",
+        auth: "bearer",
+        credits: "free",
+        returns: "{data:{credits, auto_reload, has_payment_method, pricing, usage_30d:{requests,images,cache_hit_rate}, key:{prefix,scopes}}, links, request_id}",
+        sdk: "client.account()",
+        cli: "car-image whoami",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/billing/checkout",
+        summary: "Hosted Stripe Checkout URL for a credit pack (5000|10000|25000|100000).",
+        auth: "bearer",
+        credits: "free (scope billing:write; CLI keys have it)",
+        params: ["credits"],
+        returns: "201 {data:{url,credits,amount_cents}}",
+        notes: "A human must complete the purchase in the browser. Agents must not initiate purchases without explicit approval.",
+        sdk: "client.createCheckout(5000)",
+        cli: "car-image billing --credits 5000",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/billing/portal",
+        summary: "Stripe Customer Portal URL (invoices, cards, auto-reload).",
+        auth: "bearer",
+        credits: "free (scope billing:write)",
+        returns: "201 {data:{url}}",
+        sdk: "client.billingPortal()",
+        cli: "car-image billing --portal",
+    },
+    {
+        method: "POST",
+        path: "/api/auth/device/code",
+        summary: "Start browser-assisted CLI login (device flow).",
+        auth: "public",
+        credits: "free",
+        params: ["client_name (optional)"],
+        returns: "201 {device_code,user_code,verification_uri,verification_uri_complete,expires_in,interval}",
+        cli: "car-image login",
+    },
+    {
+        method: "POST",
+        path: "/api/auth/device/token",
+        summary: "Poll the device flow; returns a revocable API key once approved.",
+        auth: "public",
+        credits: "free",
+        params: ["device_code"],
+        returns: "200 {access_token,token_type:'Bearer',scope} | 400 {error:'authorization_pending'|'expired_token'}",
+    },
+    {
+        method: "GET",
+        path: "/api/health",
+        summary: "Service health.",
+        auth: "public",
+        credits: "free",
+        returns: "{status:'ok'|'degraded', checks, version}",
+        cli: "car-image doctor",
+    },
+    {
+        method: "GET",
+        path: "/openapi.json",
+        summary: "Full OpenAPI 3.1 contract (also /agents.md, /llms.txt, /errors.md).",
+        auth: "public",
+        credits: "free",
+        cli: "car-image describe all",
+    },
+];
+/** Human/agent-readable rendering of {@link API_REFERENCE}, optionally filtered. */
+export function formatApiReference(filter) {
+    const needle = filter?.trim().toLowerCase();
+    const endpoints = needle
+        ? API_REFERENCE.filter((endpoint) => endpoint.path.toLowerCase().includes(needle) ||
+            endpoint.summary.toLowerCase().includes(needle) ||
+            `${endpoint.method} ${endpoint.path}`.toLowerCase().includes(needle))
+        : API_REFERENCE;
+    const header = [
+        `Car Image API — base URL ${DEFAULT_BASE_URL}`,
+        `Auth: Authorization: Bearer cimg_… (never in URLs). Errors: application/problem+json {type,title,status,detail,request_id}.`,
+        `Pricing: ${CREDITS_PER_IMAGE} credit per delivered image, $1 = ${CREDITS_PER_DOLLAR} credits, ${FREE_CREDITS} free credits, no subscription.`,
+        "",
+    ];
+    if (endpoints.length === 0) {
+        return `${header.join("\n")}No endpoint matches "${filter}". Known paths:\n${API_REFERENCE.map((e) => `  ${e.method} ${e.path}`).join("\n")}`;
+    }
+    const body = endpoints.map((endpoint) => {
+        const lines = [`${endpoint.method} ${endpoint.path}`, `  ${endpoint.summary}`, `  auth: ${endpoint.auth}; credits: ${endpoint.credits}`];
+        if (endpoint.params?.length)
+            lines.push(`  params: ${endpoint.params.join("; ")}`);
+        if (endpoint.returns)
+            lines.push(`  returns: ${endpoint.returns}`);
+        if (endpoint.errors?.length)
+            lines.push(`  errors: ${endpoint.errors.join("; ")}`);
+        if (endpoint.notes)
+            lines.push(`  notes: ${endpoint.notes}`);
+        if (endpoint.sdk)
+            lines.push(`  sdk: ${endpoint.sdk}`);
+        if (endpoint.cli)
+            lines.push(`  cli: ${endpoint.cli}`);
+        return lines.join("\n");
+    });
+    return `${header.join("\n")}${body.join("\n\n")}`;
+}
+/** A JSON payload as both readable text and structured content. */
+export function jsonToolResult(value, summary) {
+    const text = summary ? `${summary}\n\n${JSON.stringify(value, null, 2)}` : JSON.stringify(value, null, 2);
+    return { content: [{ type: "text", text }], structuredContent: value };
+}
+/** An `isError` result whose text tells the agent what to do next. */
+export function errorToolResult(message, extra = {}) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: message, ...extra },
+    };
+}
+/** Standard guidance appended to error results, keyed by HTTP-ish status. */
+export function nextStepFor(status) {
+    switch (status) {
+        case 401:
+            return "The API key is missing or invalid. Set CAR_IMAGE_API_KEY (or run `car-image login`); never paste keys into prompts.";
+        case 402:
+            return `Insufficient credits. Stop and ask a human to buy credits at ${DEFAULT_BASE_URL}/billing (or run \`car-image billing\`). Do not purchase credits autonomously.`;
+        case 403:
+            return "This key lacks the required scope. Ask the human to create a key with the right scopes in the dashboard.";
+        case 404:
+            return "The vehicle is not in the catalog. Use search_vehicles or resolve_vehicle to find the canonical make/model/year.";
+        case 429:
+            return "Rate limited. Wait the retry_after seconds before retrying; do not hammer the API.";
+        default:
+            return "Retry once if this looks transient; otherwise report the detail and request_id to the human.";
+    }
+}
+//# sourceMappingURL=index.js.map