@meterapp/car-image-sdk 1.25.0 → 1.26.0

package/dist/mcp/index.js

@@ -45,8 +45,11 @@ export const MCP_SERVER_INFO = {
 export const MCP_SERVER_CAPABILITIES = { tools: { listChanged: false } };
 /**
  * Which tools a server exposes. `core`, the default, is what an agent needs to
- * look a vehicle up, render it and watch the balance: the 2026-09-29 audit of
- * the public surface found these seven carrying all of the MCP traffic. `all`
+ * look a vehicle up, render it and watch the balance (the 2026-09-29 audit of
+ * the public surface found those carrying all of the MCP traffic), plus the
+ * four feedback tools every fleet product puts in its default list
+ * (docs/customer-feedback.md): request a feature, report an issue, upvote,
+ * review. `all`
  * adds make logos, 3D models, image options, the API reference, pricing, help
  * and billing links, plus the tools that are served but kept out of the public
  * reference ({@link MCP_UNLISTED_TOOLS}), for hosts that opt in (`?toolset=all`
@@ -55,7 +58,19 @@ export const MCP_SERVER_CAPABILITIES = { tools: { listChanged: false } };
  * the core tools first: tools/list order is what a host shows.
  */
 export const MCP_TOOLSETS = {
-    core: ["resolve_vehicle", "search_vehicles", "decode_vin", "check_vehicles", "get_car_image", "create_car_image_urls", "get_account"],
+    core: [
+        "resolve_vehicle",
+        "search_vehicles",
+        "decode_vin",
+        "check_vehicles",
+        "get_car_image",
+        "create_car_image_urls",
+        "get_account",
+        "request_feature",
+        "report_issue",
+        "upvote_feedback",
+        "submit_review",
+    ],
     all: [
         "resolve_vehicle",
         "search_vehicles",
@@ -64,6 +79,16 @@ export const MCP_TOOLSETS = {
         "get_car_image",
         "create_car_image_urls",
         "get_account",
+        "request_feature",
+        "report_issue",
+        "upvote_feedback",
+        "submit_review",
+        "list_feedback",
+        "get_feedback",
+        "list_my_feedback",
+        "remove_feedback_vote",
+        "comment_on_feedback",
+        "list_reviews",
         "get_make_logo",
         "create_3d_model",
         "get_3d_model",
@@ -80,7 +105,6 @@ export const MCP_TOOLSETS = {
         "rate_image",
         "list_requests",
         "request_vehicle",
-        "request_feature",
         "get_request",
         "upvote_request",
         "comment_on_request",
@@ -90,8 +114,9 @@ export const MCP_TOOLSETS = {
 };
 /**
  * Served on `all`, absent from the public reference since the 2026-09-30
- * audit: image feedback (the dashboard rates images now), the request board
- * and the two "about you" tools. The docs, both READMEs, the OpenAPI
+ * audit: image feedback (the dashboard rates images now), the original
+ * request-board tools (the canonical feedback tools replace them; they keep
+ * working) and the two "about you" tools. The docs, both READMEs, the OpenAPI
  * description and the plugin skills never name them
  * (app/_lib/client-surface-contract.test.ts), and what the reference says
  * `?toolset=all` adds is {@link MCP_DOCUMENTED_EXTRAS}.
@@ -100,7 +125,6 @@ export const MCP_UNLISTED_TOOLS = [
     "rate_image",
     "list_requests",
     "request_vehicle",
-    "request_feature",
     "get_request",
     "upvote_request",
     "comment_on_request",
@@ -136,6 +160,8 @@ export const MCP_INSTRUCTIONS_HEAD_LIMIT = 2048;
  * instructions no longer steer an agent to them.
  */
 const HEAD_MISSING = "tell the human the catalog does not carry it and stop";
+/** When to use the feedback tools, which every toolset has. */
+const HEAD_FEEDBACK = "Feedback (free): when a call fails in a way that looks like our bug, offer report_issue with its request_id; when the human wishes the API did something, request_feature. Both return similar items first: upvote_feedback a match instead. After real use, offer submit_review.";
 /** The 3D cost rule, shown only where create_3d_model is a tool the host has. */
 const HEAD_3D = `create_3d_model costs ${MODEL_3D_PRICE}, free once that vehicle/color is owned: confirm with the human before calling it. `;
 function toolsetHas(toolset, tool) {
@@ -151,7 +177,9 @@ For an image in chat, call create_car_image_urls once with vehicle: "veh_…", v
 
 If lookup confidence is low or the year differs from the request, ask before spending credits. If no match, ${HEAD_MISSING}; never silently substitute a car.
 
-Costs: ${CREDITS_PER_IMAGE} credit per image or signed URL; lookups are free. Confirm the count and cost before a batch the human did not size. ${toolsetHas(toolset, "create_3d_model") ? HEAD_3D : ""}On (402) stop and give the human its checkout_url and price; buy credits or change a plan only when the human asks or a spending mandate they set covers it.`;
+Costs: ${CREDITS_PER_IMAGE} credit per image or signed URL; lookups are free. Confirm the count and cost before a batch the human did not size. ${toolsetHas(toolset, "create_3d_model") ? HEAD_3D : ""}On (402) stop and give the human its checkout_url and price; buy credits or change a plan only when the human asks or a spending mandate they set covers it.
+
+${HEAD_FEEDBACK}`;
 }
 /** The tools that never cost a credit, named in the Plans paragraph for the toolset that has them. */
 const FREE_TOOLS = ["search_vehicles", "resolve_vehicle", "decode_vin", "check_vehicles", "list_image_options", "get_account", "get_3d_model", "publish_3d_model", "describe_api"];
@@ -448,8 +476,73 @@ export const MCP_TOOL_SCHEMAS = {
         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."),
+        title: z.string().min(1).max(140).describe('Short summary, e.g. "Interior views".'),
+        body: z.string().max(5000).optional().describe("Details: the use case, what the output should look like."),
+        force: z.boolean().optional().describe("File it even though similar items exist. Only after checking that none of the returned similar items matches."),
+    }),
+    report_issue: z.object({
+        title: z.string().min(1).max(140).describe('What went wrong, in a line, e.g. "Side views of the 2024 Camry return 502". No keys or personal data.'),
+        body: z.string().max(5000).optional().describe("What was called, what was expected, what happened."),
+        request_id: z.string().min(1).max(100).optional().describe("The request_id of the failed call (from its error or X-Request-Id). The single most useful thing to attach."),
+        context: z
+            .object({
+            endpoint: z.string().max(200).optional().describe("The tool or path that failed, e.g. get_car_image or /api/v1/images/car."),
+            error_code: z.string().max(80).optional().describe("The error code or status the call returned."),
+            vehicle: z.string().max(32).optional().describe("The vehicle id (veh_…) involved."),
+            view: z.string().max(24).optional().describe("The view involved, e.g. side."),
+            color: z.string().max(24).optional().describe("The paint color involved."),
+            asset_id: z.string().max(36).optional().describe("The image asset id, when one was returned."),
+            model_3d_id: z.string().max(36).optional().describe("The 3D request id, for a 3D model problem."),
+            client: z.string().max(80).optional().describe("The host or client, e.g. Claude Code."),
+            client_version: z.string().max(40).optional().describe("Its version."),
+        })
+            .optional()
+            .describe("The identifiers of what went wrong. Checked against the account's own requests; never shown publicly."),
+        force: z.boolean().optional().describe("File it even though similar reports exist."),
+    }),
+    list_feedback: z.object({
+        kind: z.enum(REQUEST_KINDS).optional().describe("feature, issue (published ones only) or vehicle. Omit for all."),
+        status: z.enum(REQUEST_STATUSES).optional().describe("Filter by status. Omit for everything that is not declined or merged."),
+        sort: z.enum(REQUEST_SORTS).default("top").describe("top = most votes (default); new = newest; recent_activity = latest vote, comment or change."),
+        q: z.string().max(200).optional().describe("Search titles and bodies."),
+        limit: z.coerce.number().int().min(1).max(100).default(25).describe("Maximum number of items (1-100)."),
+        cursor: z.string().max(200).optional().describe("next_cursor from a previous page."),
+    }),
+    get_feedback: z.object({
+        id: z.string().uuid().describe("The item id from list_feedback, request_feature or report_issue."),
+    }),
+    list_my_feedback: z.object({
+        kind: z.enum(REQUEST_KINDS).optional().describe("Only one kind. Omit for all."),
+        status: z.enum(REQUEST_STATUSES).optional().describe("Only one status. Omit for all."),
+        limit: z.coerce.number().int().min(1).max(100).default(25).describe("Maximum number of items (1-100)."),
+        cursor: z.string().max(200).optional().describe("next_cursor from a previous page."),
+    }),
+    upvote_feedback: z.object({
+        id: z.string().uuid().describe("The item id to upvote. Idempotent."),
+    }),
+    remove_feedback_vote: z.object({
+        id: z.string().uuid().describe("The item id to remove the vote from. Idempotent."),
+    }),
+    comment_on_feedback: z.object({
+        id: z.string().uuid().describe("The item id to comment on."),
+        body: z.string().min(1).max(2000).describe("The comment (1-2000 characters)."),
+    }),
+    submit_review: z.object({
+        rating: z.coerce.number().int().min(1).max(5).describe("1 to 5 stars, the human's own rating."),
+        title: z.string().max(120).optional().describe("A headline, in the human's words."),
+        body: z.string().max(2000).optional().describe("The review, in the human's words."),
+        likes: z.string().max(1000).optional().describe("What works well."),
+        dislikes: z.string().max(1000).optional().describe("What could be better."),
+        use_case: z.string().max(200).optional().describe("What they use the API for."),
+        display_name: z.string().max(80).optional().describe("The name to show. Defaults to their first name."),
+        display_company: z.string().max(120).optional().describe("A company to show, only if they want one."),
+        marketing_consent: z.boolean().optional().describe("true only if the human agreed that Car Image may quote it in marketing. Default false."),
+    }),
+    list_reviews: z.object({
+        sort: z.enum(["newest", "highest", "lowest"]).default("newest").describe("Order of the reviews."),
+        rating: z.coerce.number().int().min(1).max(5).optional().describe("Only reviews with this rating."),
+        limit: z.coerce.number().int().min(1).max(100).default(20).describe("Maximum number of reviews (1-100)."),
+        cursor: z.string().max(200).optional().describe("next_cursor from a previous page."),
     }),
     get_request: z.object({
         id: z.string().uuid().describe("The request id from list_requests, request_vehicle or request_feature."),
@@ -459,7 +552,7 @@ export const MCP_TOOL_SCHEMAS = {
     }),
     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)."),
+        body: z.string().min(1).max(2000).describe("The comment (1-2000 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)."),
@@ -623,6 +716,23 @@ const requestFields = {
     updated_at: z.string(),
     viewer: z.looseObject({ voted: z.boolean() }).optional(),
 };
+/** create results on the canonical tools: the new item, or nothing and the matches to upvote. */
+const filedFeedbackResult = z.looseObject({
+    created: z.boolean(),
+    data: z.looseObject({ ...requestFields, comments: z.number().int() }).nullable(),
+    similar: z.array(z.looseObject({ ...requestFields, comments: z.number().int() })),
+    request_id: z.string(),
+});
+const publicReviewSchema = z.looseObject({
+    id: z.string(),
+    rating: z.number().int(),
+    title: z.string().nullable(),
+    body: z.string().nullable(),
+    display_name: z.string(),
+    created_at: z.string(),
+    response: z.looseObject({ body: z.string(), responded_at: z.string() }).nullable(),
+});
+const reviewSummarySchema = z.looseObject({ count: z.number().int(), average: z.number().nullable(), distribution: z.looseObject({}) });
 const requestCommentSchema = z.looseObject({
     id: z.string(),
     request_id: z.string(),
@@ -649,6 +759,7 @@ const createdRequestResult = z.looseObject({
     deduplicated: z.boolean(),
     request_id: z.string(),
 });
+const timelineSchema = z.array(z.looseObject({ at: z.string(), type: z.string() }));
 /** The response of GET /api/v1/vin/{vin}: every key present, unknown values null. */
 const vinResultSchema = z.looseObject({
     vin: z.string(),
@@ -928,7 +1039,16 @@ export const MCP_TOOL_OUTPUT_SCHEMAS = {
     publish_3d_model: z.looseObject({ data: model3dSchema, request_id: z.string() }),
     list_requests: requestListResult,
     request_vehicle: createdRequestResult,
-    request_feature: createdRequestResult,
+    request_feature: filedFeedbackResult,
+    report_issue: filedFeedbackResult,
+    list_feedback: requestListResult,
+    list_my_feedback: requestListResult,
+    get_feedback: z.looseObject({ data: z.looseObject({ ...requestDetailSchema.shape, timeline: timelineSchema }), request_id: z.string() }),
+    upvote_feedback: requestResult,
+    remove_feedback_vote: requestResult,
+    comment_on_feedback: z.looseObject({ data: requestCommentSchema, request_id: z.string() }),
+    submit_review: z.looseObject({ data: publicReviewSchema.extend({ status: z.string(), marketing_consent: z.boolean() }), created: z.boolean(), request_id: z.string() }),
+    list_reviews: z.looseObject({ data: z.array(publicReviewSchema), summary: reviewSummarySchema, next_cursor: z.string().nullable(), request_id: z.string() }),
     get_request: z.looseObject({ data: requestDetailSchema, request_id: z.string() }),
     upvote_request: requestResult,
     comment_on_request: z.looseObject({ data: requestCommentSchema, request_id: z.string() }),
@@ -1275,11 +1395,83 @@ export const MCP_TOOLS = {
     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.",
+        description: "Free. When the human wishes the API did something it does not (new views, formats, endpoints, anything), file it on the public feedback board. Similar items are checked first: when some exist nothing is filed (created: false) and similar lists them; upvote_feedback the one that matches, or call again with force: true if none does. A new request returns its page URL; the human gets a thank-you email and one for every status change until it ships.",
         inputSchema: MCP_TOOL_SCHEMAS.request_feature,
         outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.request_feature,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
+    report_issue: {
+        name: "report_issue",
+        title: "Report an issue",
+        description: "Free. Report a problem with Car Image itself (a failed or wrong render, an error that looks like a bug, a broken endpoint), with the human's agreement. Pass the failed call's request_id and what you know in context (endpoint, error_code, vehicle id, view, color): the team sees exactly what happened. Private to the human and the team. Similar open reports come back first, as with request_feature: upvote_feedback one that matches. The human gets an acknowledgement and an email when it is picked up and when it is fixed. Not for a vehicle the catalog lacks, and never include API keys.",
+        inputSchema: MCP_TOOL_SCHEMAS.report_issue,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.report_issue,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    list_feedback: {
+        name: "list_feedback",
+        title: "List the feedback board",
+        description: "Free, public. The feedback board: feature requests, vehicle requests and published issues, with votes, comments, status (open, planned, in_progress, done, declined, duplicate) and a page URL. Search with q, filter by kind or status, sort by top, new or recent_activity.",
+        inputSchema: MCP_TOOL_SCHEMAS.list_feedback,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_feedback,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    get_feedback: {
+        name: "get_feedback",
+        title: "Get a feedback item",
+        description: "Free. One item with its comments (official: true marks the team's responses) and its timeline of status changes. A private issue is readable by its reporter only, with the context it was filed with.",
+        inputSchema: MCP_TOOL_SCHEMAS.get_feedback,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.get_feedback,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    list_my_feedback: {
+        name: "list_my_feedback",
+        title: "List my feedback",
+        description: "Free. What the human filed (private issues included) and what they vote on, comment on or follow, any status: use it to tell them where their requests and reports stand.",
+        inputSchema: MCP_TOOL_SCHEMAS.list_my_feedback,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_my_feedback,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    upvote_feedback: {
+        name: "upvote_feedback",
+        title: "Upvote a feedback item",
+        description: "Free. Add the human's vote to a feature, vehicle request or published issue (idempotent): the way to say \"me too\" instead of filing a duplicate. They follow it from then on and hear about every status change. A vote on a merged item lands on the item it was merged into.",
+        inputSchema: MCP_TOOL_SCHEMAS.upvote_feedback,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.upvote_feedback,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    remove_feedback_vote: {
+        name: "remove_feedback_vote",
+        title: "Remove a vote",
+        description: "Free. Remove the human's vote from an item (idempotent); they stop following it unless they commented.",
+        inputSchema: MCP_TOOL_SCHEMAS.remove_feedback_vote,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.remove_feedback_vote,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    comment_on_feedback: {
+        name: "comment_on_feedback",
+        title: "Comment on a feedback item",
+        description: "Free. Add a comment to an item, e.g. the use case or detail that matters; shown with the human's first name only.",
+        inputSchema: MCP_TOOL_SCHEMAS.comment_on_feedback,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.comment_on_feedback,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    submit_review: {
+        name: "submit_review",
+        title: "Review Car Image",
+        description: "Free. Post or edit the human's public review of Car Image (one per account, 1-5 stars, their own words; never invent or nudge a rating). Shown on the reviews page with the team's answer once it passes a quick check. Set marketing_consent only when they agree to be quoted. One edit an hour; the first post gets a thank-you email.",
+        inputSchema: MCP_TOOL_SCHEMAS.submit_review,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.submit_review,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    list_reviews: {
+        name: "list_reviews",
+        title: "List reviews",
+        description: "Free, public. Published reviews of Car Image with the team's responses, plus the average rating and the 1-5 distribution.",
+        inputSchema: MCP_TOOL_SCHEMAS.list_reviews,
+        outputSchema: MCP_TOOL_OUTPUT_SCHEMAS.list_reviews,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
     get_request: {
         name: "get_request",
         title: "Get a request",