Smartpress MCP Server

Run (enqueue) a file check for a file in a file session: the proof service preflights the file against the product's print specs and produces a report of errors/warnings. Unlike create_proof it makes NO proof file — the report is the whole result, and there is nothing to approve. Use it when the session is NOT proofable but isFileCheckAvailable is true (read get_file_session_proofs first). When the session is proofable, prefer create_proof. Returns { checkId, ... } once enqueued. A check takes tens of seconds — after calling this, poll get_file_session_proofs until the `checks` entry whose `id` equals checkId reaches status COMPLETED, then report its errors/warnings. Refuses (tool error, nothing queued) when the session or file isn't eligible for a file check — do not retry a refusal. ONLY call this on the customer's explicit go-ahead (a run-file-check quick-action click or a clear yes) — never unprompted. The file must already be uploaded to the session.

Create a file session for uploading proof/artwork files. Returns a **fileSessionId**. Once it is joined to a configuration session, add_to_cart attaches its files without you passing the ID. **Two workflows:** - **File-first** (no product chosen yet): call with no arguments. A placeholder product is used. When the product is chosen, you MUST pass this fileSessionId to create_config_session (or call link_file_session): nothing joins them otherwise, and the configuration has no files. The real product is then reconciled automatically. - **Config-first** (configuration session already exists): pass productConfigSessionId (and ideally the productId). The file session is created and linked immediately, so add_to_cart needs only the configuration sessionId. Once joined, the link is persisted server-side, so later tools (add_to_cart) need only the configuration sessionId.

Fetch the status/results of a file analysis started by analyze_file (use the uploadId it returned). Returns the full results object once status is "ready".

Read the persisted structured analysis summary for a file session. Returns { analysis } where analysis is the AnalysisSummary written by analyze_file (page count, trim size, classification, color palette, and recommended file-derived selections), or null when the file session carries no stored analysis. Use this on a fresh product-page arrival to decide whether to open with a file summary and offer to match the configuration. Absence of a summary means "no analysis → start from scratch".

Read the proof AND file-check state for a file session. Returns a compact view: - isProofable: whether the session's product/config supports proofing. - isFileCheckAvailable: whether a file check can run. A file check is a preflight report only (no proof file) and is often available when proofing is not. - files: [{ fileName, isProofable, isFileCheckAvailable }] per uploaded file. - proofs: newest-first, each { id, fileName, type, status, approvalStatus, invalid, invalidReason, errors[], warnings[], noReport, createdAt, proofFileUrl, totalPages }. - checks: newest-first file checks, each { id, fileName, type, status, invalid, errors[], warnings[], noReport, createdAt }. `id` is the proofId / checkId the create call returned — match on it to find the job you just started (an older proof or check for the same file may still be listed). A proof or check is "ready to report" when status is COMPLETED. `invalid: true` means a later configuration change made it stale and it needs re-running — it is computed server-side; just read it. Checks carry no invalidReason (only one reason is kept per session, chosen for proofs, so it reads wrong for checks), so describe a stale check in your own words. `errors`/`warnings` are the preflight messages shown to the customer (capped for length). `noReport: true` means a COMPLETED proof or check has no preflight report (for example a proof copied from a past order), so its errors and warnings are unknown, not empty: never tell the customer it has no issues. `proofFileUrl` is a signed link to the proof PDF. For each file currently in the session, only the latest proof that is neither invalid nor failed can carry it, and only once that proof is COMPLETED. While a newer proof of that file is still running, or if the file was replaced or removed, there is no link. It stops working within 24 hours of this read, possibly sooner; read again for a fresh one. If you pass it on, use it exactly as returned: never shorten, rebuild, or guess it, or the signature breaks. Use this to suggest a proof (or a file check when not proofable), report issues, answer questions about them, and detect when a config change invalidated a proof or check.

Mint a short-lived presigned URL that a client (a browser, an app, or the user) can use to upload a file directly to storage, attached to a file session. Use this when the bytes are NOT on the machine running this server — e.g. the remote/hosted server, or a file the user has in a browser. (If this server also offers a tool that uploads a file from the local machine, prefer it for local files: it performs the upload for you.) **Easiest for a person:** if the response includes **uploadPageUrl**, give that link to the user. It opens a simple Smartpress upload page in their browser where they pick the file; the page uploads it directly and securely (the file never passes through the chat). **For a programmatic client:** issue a single HTTP **PUT** to **url** with the raw file bytes as the body and **no extra headers** — do not set Content-Type and do not add x-amz-* headers; everything required is already baked into the URL. The URL expires (default 15 minutes), so use it promptly. Confirm the result with list_session_files. Returns **uploadPageUrl** (when the server has a public base URL configured), the raw **url**, the assigned **sessionFileId**, the storage **key**, and **expiresAt**.

Create a new product configuration session to begin iterative configuration. This starts a server-side session that tracks your selection changes with version history. **Workflow:** 1. Call this tool with a productId (or productConfigId to clone an existing config) and optional initial selections 2. The response includes the full ProductConfiguration with a productConfigSessionId 3. Review the validation messages in the response to see if selections are valid 4. Call update_config_session to refine selections based on validation feedback 5. Repeat steps 3-4 until validation is clean 6. Once satisfied, use add_to_cart to add the configured product to a shopping cart The response includes a **configurationUrl** field: a direct link to view the configuration on the storefront website (when available). You must provide either a productId (to start from product defaults) or a productConfigId (to bootstrap from an existing blueprint or configuration). **IMPORTANT — selections structure:** The selections object must use nested objects that mirror the structure of the selections field in the response. Flat keys are silently ignored (no error returned). Always verify the response's selections match what you requested. Known selection keys and their required structure: - **Size** — nested sizeSelection object: {"sizeSelection": {"width": 6, "height": 9, "presetDimensionsId": 15}} For custom dimensions, omit presetDimensionsId or set it to null. - **Quantity & Pages** — flat top-level keys (these DO work as simple values): {"quantity": 1200, "pages": 20} - **Paper** — nested paperSelection object: {"paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5, "coverPressSheetTypeId": 78, "coverPressSheetWeightId": 3}} - **Ink** — nested objects per ink position: {"coverSide1Ink": {"id": 146}, "coverSide2Ink": {"id": 146}, "interiorSide1AndSide2Ink": {"id": 146}} - **Proof** — nested proofSelection: {"proofSelection": {"proofId": 1}} - **Turnaround** — nested turnTimeSelection: {"turnTimeSelection": {"turnTimeId": 13}} - **Operations** — nested operationSelections with operation name keys: {"operationSelections": {"laminatingCoverOnly": {"operationId": 81, "itemId": 2323}}} An entry accepts ONLY operationId, itemId, operationName, itemName, followUpQuestionAnswer, followUpQuestion and followUpQuestionDataType — any other key is rejected with a validation error. - **Follow-up answers** — when an operation in availableOptions has a followUpQuestion (e.g. shrink-wrapping "How many pieces per bundle do you want?", drilling "Please note placement."), put the customer's answer in followUpQuestionAnswer on the SAME entry, as a string even for integer questions: {"operationSelections": {"shrinkwrappingService": {"operationId": 14, "itemId": 42, "followUpQuestionAnswer": "20"}}} Each update replaces the whole entry, so resend followUpQuestionAnswer whenever you resend that operation. Ask the customer if they chose the operation without answering its question. **General rule:** Look at the selections object in the response — use the same key names and nesting structure when sending updates. Invalid or unrecognized keys are silently ignored.

Update a configuration session with new selections. Saves the updated selections and returns the full ProductConfiguration response. **IMPORTANT — selections structure:** The selections object must use nested objects that mirror the structure of the selections field in the response. Flat keys are silently ignored (no error returned). Always verify the response's selections match what you requested. Known selection keys and their required structure: - **Size** — nested sizeSelection object: {"sizeSelection": {"width": 6, "height": 9, "presetDimensionsId": 15}} For custom dimensions, omit presetDimensionsId or set it to null. - **Quantity & Pages** — flat top-level keys (these DO work as simple values): {"quantity": 1200, "pages": 20} - **Paper** — nested paperSelection object: {"paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5, "coverPressSheetTypeId": 78, "coverPressSheetWeightId": 3}} - **Ink** — nested objects per ink position: {"coverSide1Ink": {"id": 146}, "coverSide2Ink": {"id": 146}, "interiorSide1AndSide2Ink": {"id": 146}} - **Proof** — nested proofSelection: {"proofSelection": {"proofId": 1}} - **Turnaround** — nested turnTimeSelection: {"turnTimeSelection": {"turnTimeId": 13}} - **Operations** — nested operationSelections with operation name keys: {"operationSelections": {"laminatingCoverOnly": {"operationId": 81, "itemId": 2323}}} An entry accepts ONLY operationId, itemId, operationName, itemName, followUpQuestionAnswer, followUpQuestion and followUpQuestionDataType — any other key is rejected with a validation error. - **Follow-up answers** — when an operation in availableOptions has a followUpQuestion (e.g. shrink-wrapping "How many pieces per bundle do you want?", drilling "Please note placement."), put the customer's answer in followUpQuestionAnswer on the SAME entry, as a string even for integer questions: {"operationSelections": {"shrinkwrappingService": {"operationId": 14, "itemId": 42, "followUpQuestionAnswer": "20"}}} Each update replaces the whole entry, so resend followUpQuestionAnswer whenever you resend that operation. Ask the customer if they chose the operation without answering its question. **General rule:** Look at the selections object in the response — use the same key names and nesting structure when sending updates. Invalid or unrecognized keys are silently ignored. **Example — multiple changes in one call:** {"quantity": 500, "sizeSelection": {"width": 8.5, "height": 11, "presetDimensionsId": 1}, "paperSelection": {"pressSheetTypeId": 78, "pressSheetWeightId": 5}, "turnTimeSelection": {"turnTimeId": 13}} The response includes: - **validation**: Messages indicating issues with current selections. Check globalMessages and fieldMessages to understand what needs to change. - **availableOptions**: Updated to reflect which options are now enabled or disabled based on your current selections. Options may appear or disappear as dependencies are resolved. - **selectionChangeMessages**: Indicates if any of your selections were automatically adjusted by the system. Always check these after every update — the system may change your selections due to dependency rules. - **availableOptionChangeMessages**: Indicates which available options changed as a result of your selections. - **configurationUrl**: A direct link to view the configuration on the storefront website (when available). Use this iteratively: update selections, review validation, update again until validation is clean. **Send ONLY the selections you are changing.** Every field you send counts as something you asked for, and the server now holds it to that (below). **⚠ SELECTION_CONFLICT — a refusal, never a transport failure.** If a rule would remove a selection you just changed, the call fails with code `SELECTION_CONFLICT` and **nothing is saved** — the session still holds exactly what it held before, so there is no partial state to clean up. The error carries `conflicts: [{ requested, ruleId, ruleName, message }]`, where `message` is the rule's own explanation, e.g. "Not compatible with textured papers". When you see it: 1. **Do NOT retry the same call.** It is not a network or server error and will fail identically every time. 2. Tell the customer what is incompatible, using the conflict `message`. 3. Either pick a compatible alternative, or change the blocking selection first (e.g. move to a coatable stock before selecting coating) — then update again. **Avoid the conflict up front: never select an option whose `disabled` is true** in `availableOptions`. Disabled options carry a `disabledReason` explaining why. Reading `disabled` before choosing is the difference between a smooth change and a refused one. Note the server only refuses selections you CHANGED. A rule removing something you did not touch (e.g. raising the quantity past a turnaround band, which drops a turnaround you never mentioned) still succeeds with a 200 and reports it in `selectionChangeMessages` — so keep checking those.

Retrieve the default product configuration for a given product ID. Returns the full ProductConfiguration response including: - **availableOptions**: All configurable options organized by category: - **pressSheets**: Nested hierarchy of press sheet options (type -> weight -> color). Each press sheet defines the printable substrate. - **operations**: A map keyed by camelCase operation name (e.g. "cutting", "folding", "binding"). Each operation contains its own selectable options. - **inks**: Available ink configurations for front and back of the press sheet. - **proofs**: Proof approval workflow options. - **turnaroundTimes**: Delivery timeline options. - **selections**: The current default selections for the product. - **validation**: Validation messages indicating any issues with the current selections. - **quote**: Pricing information based on current selections. Use this tool to understand what options are available for a product before starting a configuration session.

Get the downloadable print templates and design guides for a Smartpress product. Returns: - **summary**: a one-line description of what this product has — paraphrase this rather than counting the arrays yourself. - **designGuides**: instructional PDFs about how to set artwork up (bleed, folding). Not tied to a size. - **templateGroups**: the print templates, in the groups the layout team defined (e.g. "Flat", "Single Fold"). `group` is omitted when a product's templates are not grouped, which is common. - Each entry has a **label** (what to call it to the customer) and **files** (format -> download URL, e.g. `{"pdf": "https://...", "idml": "https://..."}`). Use this when a customer asks for a template, a layout guide, artwork setup help, dimensions to design to, or an InDesign file. If you only know the product by name, call find_products first and pass its "id" (e.g. "SLS_7") here. Rules: - Give customers the exact URLs this tool returned. Never construct, guess, or edit a template URL. - Use the **label** verbatim when naming a template. Labels are display text written by the layout team — do NOT parse them as dimensions or assume a label matches the customer's configured size. - Only offer a format that appears in that entry's **files**. Most templates have PDF and InDesign, but some have only one, and a few are Illustrator or spreadsheets. - If a product has none, say so plainly. Many products have no templates yet — that is normal, not an error, and you must not substitute another product's template.

Generate (enqueue) a preflight proof for a file in a file session: the proof service checks the file against the product's print specs and produces a proof with any errors/warnings. Returns { proofId, sessionId } once enqueued. Proof generation takes tens of seconds — after calling this, poll get_file_session_proofs until the proof whose `id` equals proofId reaches status COMPLETED, then report its errors/warnings. **Artwork orientation (checked before every proof).** If the artwork is turned against the configured size (e.g. 6 x 4 landscape art on a 4 x 6 portrait postcard) and swapping width and height fits it, this tool CHANGES THE CONFIGURED SIZE to match the artwork before proofing. The result then carries `orientation`: - `changedNow` (on the swap actions) is true only when THIS call changed the size. Announce a size change to the customer ONLY when `changedNow` is true, never otherwise. - `action: "swapped"` (`changedNow: true`): the size was changed (`from` → `to`, plus the new `price`) and the proof uses the new size. You MUST tell the customer the size changed, and the price if it changed, in your next message. - `action: "swapped-not-synced"` (`changedNow: true`): this call changed the size (`from` → `to`) but NO proof was started yet (no proofId) because the file service hasn't picked it up. Tell the customer the size changed, then call create_proof again in a few seconds. - `action: "swapped-earlier"` (`changedNow: false`): the configuration already had the size that fits the artwork (an earlier create_proof changed it, or the customer chose it); nothing was changed now and this proof uses it. Don't announce it as a new change. - `action: "warned"`: the artwork is turned but the size was NOT changed (`message` says why; `reason: "config-not-synced"` means the file service had not caught up with the configuration, so the proof may come back invalid and need re-running). The proof will show the artwork unrotated, possibly cut off, with a warning. Tell the customer before they review it; offer a corrected file or a different size. `orientation.message` states what happened in plain words. No `orientation` means the artwork already fits the size's orientation. ONLY call this on the customer's explicit go-ahead (a create-proof quick-action click or a clear yes) — never unprompted. The file must already be uploaded to the session and the session must be proofable (check get_file_session_proofs / isProofable first).

Record the customer's decision on a proof: APPROVED (they sign off on the proof as shown), FURTHER_REVIEW (a Smartpress expert checks the file before printing), or DECLINED. An approved proof is what prints: when the order is placed, the approved proof file goes to production and the order item is marked "User approved their instant proof through an AI assistant." Before calling this, ALL of these must be true: 1. The customer has seen the proof: you gave them its `proofFileUrl` from get_file_session_proofs (exactly as returned) or they opened it on smartpress.com. "It's in the file area" alone is not enough. 2. In the same message as the offer, you restated the product, the proof, and every preflight error and warning. 3. The customer then confirmed with an approve / expert-review action click or a clear yes to that restatement. Never call this unprompted or on an ambiguous reply. Which statuses to offer: if the proof has preflight ERRORS, or `noReport: true` (no report, so its errors are unknown), do not offer approval. Offer expert review (FURTHER_REVIEW) first, or a corrected file and a new proof. If it has only WARNINGS (or nothing), offer approval and expert review side by side. Declining is always available. The tool re-reads the session and refuses (tool error, nothing written) when the proof isn't in this file session, isn't COMPLETED, or is out of date (`invalid`); refuses APPROVED and FURTHER_REVIEW when the proof carries no `proofFileUrl` (not the current proof the customer could have opened); and refuses APPROVED when the proof has errors or no report. Don't retry a refusal; explain it and offer what it suggests. Approving or requesting review of one proof clears that status from the session's other proofs. Returns { proofId, fileSessionId, approvalStatus, approvalOrigin }.

Retrieve the latest state of a configuration session. Returns the full ProductConfiguration response with current selections, validation messages, and available options. Use this to check session state without making changes.

List the files currently attached to a file session, including each file's name, size, type, and sessionFileId. Use this to confirm an upload landed or to show the user what is attached.

Analyze a file already uploaded to a file session and return its analysis: PDF metadata (page size/count), extracted text, image labels, color palette, quality scores, and an AI classification (productCategory, industry, designStyle, targetAudience, marketingIntent). The file is analyzed in place from the file session's storage — no re-upload. Analysis typically takes 30–90 seconds; this tool waits up to waitSeconds and otherwise returns a pending status with an uploadId — resume with get_file_analysis. Feed the results to recommend_products to get product candidates.

Add the current session configuration to the cart. Calls the add-to-cart endpoint which translates the session's selections into the format required by the external cart service. On success, returns a **clientKey** (anonymous cart identifier) and a **cartLink** (shareable URL to view the cart). These are also persisted on the session and will appear in all subsequent session responses. If neither clientKey nor userId is provided, a new anonymous cart is created. Repeat calls add the item again (no idempotency). **Files are attached automatically.** If the session was linked to a file session (via create_file_session with productConfigSessionId, link_file_session, or create_config_session called with a fileSessionId), the backend resolves the file session from the configuration session — you do NOT need to pass fileSessionId. Only pass fileSessionId to override that durable link with a specific file session. The cartLink opens the cart on the Smartpress website, where the customer reviews the order and checks out.

Copy a file session — files, approved proofs, and completed check results — into a NEW file session, leaving the original and its configuration join untouched. Optionally link the CLONE to a configuration session in the same call. Use this instead of link_file_session whenever the source file session is one a page is currently displaying: linking would MOVE the single join pointer and strip the files off that page, while cloning gives the target configuration its own copy. Typical case: the customer is on a product page and selects a recommended candidate — clone the page's file session and link the clone to the candidate's configuration session. Returns the new **fileSessionId** (the clone), the sourceFileSessionId, and fileCount.

Durably join a file session to a configuration session (last-write-wins). Use this when files were uploaded in one context and the configuration was created in another, or to re-link a configuration to a different file session. After linking, add_to_cart needs only the configuration sessionId — the backend resolves the file session automatically. The real productId is reconciled onto the file session from the configuration session.

Find Smartpress products matching a name or description. Returns matching products with their id, name, and description (plus group, link, image and a relevance score). Only products that can be configured through this assistant are returned. If nothing fits, say so and point the customer to smartpress.com rather than suggesting a product from memory. Use this to discover products by what the user is trying to print (e.g. "saddle stitch booklet", "matte business cards"). Take the "id" of the best match (e.g. "SLS_7") and pass it to create_config_session as productId to configure the product, then add_to_cart.

Map a file analysis (from analyze_file) to Smartpress product candidates: productId, productName, a rationale citing the analysis evidence, a 0-1 confidence, and machine-readable matchSignals. Candidates are ordered by confidence (max 5). Pass the analysis object returned by analyze_file (or just the uploadId to have it fetched). Use get_product_config on a candidate's productId to see its options before creating a configuration session for the user's chosen candidate.