@shippo/shippo-mcp 2.0.3 → 2.0.18

package/src/funcs/ordersGetPackingSlip.ts

@@ -0,0 +1,176 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ShippoSDKCore } from "../core.js";
+import { encodeSimple } from "../lib/encodings.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  GetOrderPackingSlipRequest,
+  GetOrderPackingSlipRequest$zodSchema,
+  GetOrderPackingSlipResponse,
+  GetOrderPackingSlipResponse$zodSchema,
+} from "../models/getorderpackingslipop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Generate a packing slip for an order
+ *
+ * @remarks
+ * Generates a packing slip PDF for the specified order. Returns a signed URL to download the PDF. The URL expires after 24 hours.
+ */
+export function ordersGetPackingSlip(
+  client$: ShippoSDKCore,
+  request: GetOrderPackingSlipRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    GetOrderPackingSlipResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: ShippoSDKCore,
+  request: GetOrderPackingSlipRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      GetOrderPackingSlipResponse,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => GetOrderPackingSlipRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+
+  const pathParams$ = {
+    OrderId: encodeSimple("OrderId", payload$.OrderId, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path$ = pathToFunc("/orders/{OrderId}/packingslip/")(
+    pathParams$,
+  );
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+    "SHIPPO-API-VERSION": encodeSimple(
+      "SHIPPO-API-VERSION",
+      client$._options.shippoApiVersion,
+      { explode: false, charEncoding: "none" },
+    ),
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "GetOrderPackingSlip",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  const response = doResult.value;
+  const responseFields$ = {
+    HttpMeta: { Response: response, Request: req$ },
+  };
+
+  const [result$] = await M.match<
+    GetOrderPackingSlipResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json(200, GetOrderPackingSlipResponse$zodSchema, { key: "object" }),
+    M.json(400, GetOrderPackingSlipResponse$zodSchema, { key: "BadRequest" }),
+    M.nil(404, GetOrderPackingSlipResponse$zodSchema),
+  )(response, req$, { extraFields: responseFields$ });
+
+  return [result$, { status: "complete", request: req$, response }];
+}

package/src/lib/config.ts

@@ -67,8 +67,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "2018-02-08",
-  sdkVersion: "2.0.3",
-  genVersion: "2.788.5",
+  sdkVersion: "2.0.18",
+  genVersion: "2.791.1",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 2.0.3 2.788.5 2018-02-08 @shippo/shippo-mcp",
+    "speakeasy-sdk/mcp-typescript 2.0.18 2.791.1 2018-02-08 @shippo/shippo-mcp",
 } as const;

package/src/mcp-server/mcp-server.ts

@@ -19,7 +19,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "2.0.3",
+    currentVersion: "2.0.18",
   },
 });
 

package/src/mcp-server/server.ts

@@ -13,10 +13,13 @@ import {
 } from "./resources.js";
 import { MCPScope } from "./scopes.js";
 import { createRegisterTool } from "./tools.js";
-import { tool$addressesCreate } from "./tools/addressesCreate.js";
+import { tool$addressesCreateV1 } from "./tools/addressesCreateV1.js";
+import { tool$addressesCreateV2 } from "./tools/addressesCreateV2.js";
 import { tool$addressesGet } from "./tools/addressesGet.js";
 import { tool$addressesList } from "./tools/addressesList.js";
+import { tool$addressesParse } from "./tools/addressesParse.js";
 import { tool$addressesValidate } from "./tools/addressesValidate.js";
+import { tool$addressesValidateV2 } from "./tools/addressesValidateV2.js";
 import { tool$batchesAddShipments } from "./tools/batchesAddShipments.js";
 import { tool$batchesCreate } from "./tools/batchesCreate.js";
 import { tool$batchesGet } from "./tools/batchesGet.js";
@@ -42,6 +45,7 @@ import { tool$manifestsGet } from "./tools/manifestsGet.js";
 import { tool$manifestsList } from "./tools/manifestsList.js";
 import { tool$ordersCreate } from "./tools/ordersCreate.js";
 import { tool$ordersGet } from "./tools/ordersGet.js";
+import { tool$ordersGetPackingSlip } from "./tools/ordersGetPackingSlip.js";
 import { tool$ordersList } from "./tools/ordersList.js";
 import { tool$parcelsCreate } from "./tools/parcelsCreate.js";
 import { tool$parcelsGet } from "./tools/parcelsGet.js";
@@ -96,7 +100,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "ShippoSDK",
-    version: "2.0.3",
+    version: "2.0.18",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -141,9 +145,12 @@ export function createMCPServer(deps: {
   void register; // suppress unused warnings
 
   tool(tool$addressesList);
-  tool(tool$addressesCreate);
+  tool(tool$addressesCreateV1);
   tool(tool$addressesGet);
   tool(tool$addressesValidate);
+  tool(tool$addressesParse);
+  tool(tool$addressesValidateV2);
+  tool(tool$addressesCreateV2);
   tool(tool$batchesCreate);
   tool(tool$batchesGet);
   tool(tool$batchesAddShipments);
@@ -172,6 +179,7 @@ export function createMCPServer(deps: {
   tool(tool$ordersList);
   tool(tool$ordersCreate);
   tool(tool$ordersGet);
+  tool(tool$ordersGetPackingSlip);
   tool(tool$carrierParcelTemplatesList);
   tool(tool$carrierParcelTemplatesGet);
   tool(tool$parcelsList);

package/src/mcp-server/tools/addressesCreateV1.ts

@@ -0,0 +1,58 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesCreateV1 } from "../../funcs/addressesCreateV1.js";
+import { AddressCreateRequest$zodSchema } from "../../models/addresscreaterequest.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: AddressCreateRequest$zodSchema,
+};
+
+export const tool$addressesCreateV1: ToolDefinition<typeof args> = {
+  name: "addresses-create-v1",
+  description:
+    `**DEPRECATED - Use \`addresses-create-v2\` instead for cleaner API format.**
+
+This is the legacy v1 address creation endpoint. It uses different field names
+(street1, city, state, zip) compared to the newer v2 format.
+
+**Prefer \`addresses-create-v2\`** which uses standardized field names:
+- \`address_line_1\` instead of \`street1\`
+- \`city_locality\` instead of \`city\`
+- \`state_province\` instead of \`state\`
+- \`postal_code\` instead of \`zip\`
+
+**For address validation, use \`addresses-validate-v2\`.**
+
+Only use this tool if you specifically need v1 API compatibility.
+`,
+  scopes: ["write"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesCreateV1(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/addressesCreateV2.ts

@@ -0,0 +1,92 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesCreateV2 } from "../../funcs/addressesCreateV2.js";
+import { AddressCreateRequestV2$zodSchema } from "../../models/addresscreaterequestv2.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: AddressCreateRequestV2$zodSchema,
+};
+
+export const tool$addressesCreateV2: ToolDefinition<typeof args> = {
+  name: "addresses-create-v2",
+  description:
+    `**PRIMARY ADDRESS CREATION TOOL** - Use this tool to create and save address records.
+
+This is the recommended v2 endpoint for creating addresses with a cleaner, standardized format.
+
+**Required Fields:**
+- \`name\`: The addressee's name (max 64 chars)
+- \`address_line_1\`: Street address (1-100 chars)
+- \`country_code\`: ISO 3166 country code (2 chars, e.g., "US")
+
+**Optional Fields:**
+- \`organization\`: Company/organization name
+- \`email\`: Email address
+- \`phone\`: Phone number
+- \`address_line_2\`: Apt, suite, unit, etc.
+- \`city_locality\`: City name
+- \`state_province\`: State/province abbreviation
+- \`postal_code\`: ZIP/postal code
+- \`address_type\`: unknown, residential, commercial, po_box, military
+
+**Example Request:**
+\`\`\`json
+{
+  "name": "Wilson",
+  "organization": "Shippo",
+  "email": "user@shippo.com",
+  "phone": "+1-4155550132",
+  "address_line_1": "731 Market Street",
+  "address_line_2": "#200",
+  "city_locality": "San Francisco",
+  "state_province": "CA",
+  "postal_code": "94103",
+  "country_code": "US",
+  "address_type": "commercial"
+}
+\`\`\`
+
+**Response includes:**
+- \`id\`: Unique address identifier for future reference
+- \`address\`: The saved address data
+- \`created_at\`/\`updated_at\`: Timestamps
+
+**Use Cases:**
+- Save addresses for reuse in shipments
+- Build an address book
+- Store customer shipping addresses
+
+**For address validation, use \`addresses-validate-v2\`** which provides
+confidence scores, geo coordinates, and recommended corrections.
+`,
+  scopes: ["write"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesCreateV2(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/addressesParse.ts

@@ -0,0 +1,76 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesParse } from "../../funcs/addressesParse.js";
+import { ParseAddressRequest$zodSchema } from "../../models/parseaddressop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: ParseAddressRequest$zodSchema,
+};
+
+export const tool$addressesParse: ToolDefinition<typeof args> = {
+  name: "addresses-parse",
+  description:
+    `**ADDRESS PARSER** - Converts an unstructured address string into a structured address object.
+
+Use this tool when you have a single address string (like from customer input, emails, 
+or CSV imports) and need to parse it into structured components.
+
+**Input Format Tips:**
+- Use commas (,) as delimiters between address parts
+- Follow this order: street address, city, state, postal code, country
+- Phone and email can be anywhere in the string
+
+**Example Input:**
+"Shippo 731 Market St #200, San Francisco, CA 94103 US shippo@shippo.com +1-555-999-8888"
+
+**Example Output:**
+\`\`\`json
+{
+  "address_line_1": "731 MARKET ST",
+  "address_line_2": "#200",
+  "city_locality": "SAN FRANCISCO",
+  "state_province": "CA",
+  "postal_code": "94103",
+  "country_code": "US",
+  "email": "shippo@shippo.com",
+  "phone": "+1-555-999-8888"
+}
+\`\`\`
+
+**Use Cases:**
+- Parse addresses from customer contact forms
+- Extract structured data from email signatures
+- Process bulk address imports
+- Clean up poorly formatted address data
+`,
+  scopes: ["read"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesParse(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/addressesValidate.ts

@@ -13,10 +13,19 @@ const args = {
 export const tool$addressesValidate: ToolDefinition<typeof args> = {
   name: "addresses-validate-existing",
   description:
-    `**SECONDARY VALIDATION TOOL** - Validates an already created address using its ID.
+    `**DEPRECATED - Use \`addresses-validate-v2\` instead for better validation results.**
 
-Use this tool only when you have an existing address ID and need to re-validate it.
-For new address validation, prefer the addresses-create tool with validate=true.
+This v1 endpoint validates an already created address using its ID.
+It only works on addresses that have been saved to Shippo's address book.
+
+**Prefer \`addresses-validate-v2\`** which:
+- Validates any address (no need to create first)
+- Returns confidence scores (high/medium/low)
+- Provides recommended address corrections
+- Returns geo coordinates (latitude/longitude)
+- Identifies residential vs commercial addresses
+
+Only use this tool if you specifically need to re-validate an existing address record by ID.
 `,
   scopes: ["read", "validation"],
   annotations: {

package/src/mcp-server/tools/addressesValidateV2.ts

@@ -0,0 +1,105 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesValidateV2 } from "../../funcs/addressesValidateV2.js";
+import { ValidateAddressV2Request$zodSchema } from "../../models/validateaddressv2op.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: ValidateAddressV2Request$zodSchema,
+};
+
+export const tool$addressesValidateV2: ToolDefinition<typeof args> = {
+  name: "addresses-validate-v2",
+  description:
+    `**PRIMARY ADDRESS VALIDATION TOOL** - Use this tool whenever asked to validate an address.
+
+This is the recommended v2 validation endpoint that provides comprehensive results:
+- Original address as submitted
+- Recommended address with corrections
+- Confidence score (high/medium/low)
+- Validation result (valid/invalid/unknown)
+- Address type (residential/commercial/unknown)
+- List of changed attributes
+- Geographic coordinates (latitude/longitude)
+
+**Required Fields:**
+- \`address_line_1\`: The street address (required)
+- \`country_code\`: ISO 3166 country code (required)
+
+**US Address Requirements (one of):**
+- state_province + city_locality + address_line_1
+- OR address_line_1 + postal_code
+
+**International Requirements:**
+- city_locality + address_line_1
+
+**Example Request:**
+\`\`\`
+address_line_1: "731 Market Street"
+address_line_2: "#200"
+city_locality: "San Francisco"
+state_province: "CA"
+postal_code: "94103"
+country_code: "US"
+\`\`\`
+
+**Example Response:**
+\`\`\`json
+{
+  "recommended_address": {
+    "address_line_1": "731 MARKET ST",
+    "city_locality": "SAN FRANCISCO",
+    "state_province": "CA",
+    "postal_code": "94103-2007",
+    "country_code": "US",
+    "confidence_result": {
+      "score": "high",
+      "description": "Address verified"
+    }
+  },
+  "analysis": {
+    "validation_result": {"value": "valid"},
+    "address_type": "commercial",
+    "changed_attributes": ["address_line_1", "postal_code"]
+  },
+  "geo": {"latitude": 37.7879, "longitude": -122.4074}
+}
+\`\`\`
+
+**Use Cases:**
+- Validate customer shipping addresses before label purchase
+- Get corrected/standardized address formatting
+- Determine if address is residential or commercial
+- Get ZIP+4 extended postal codes
+- Geocode addresses for mapping
+`,
+  scopes: ["read", "validation"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesValidateV2(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/ordersGetPackingSlip.ts

@@ -0,0 +1,76 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ordersGetPackingSlip } from "../../funcs/ordersGetPackingSlip.js";
+import { GetOrderPackingSlipRequest$zodSchema } from "../../models/getorderpackingslipop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetOrderPackingSlipRequest$zodSchema,
+};
+
+export const tool$ordersGetPackingSlip: ToolDefinition<typeof args> = {
+  name: "orders-get-packing-slip",
+  description:
+    `**GENERATE PACKING SLIP** - Creates a downloadable packing slip PDF for an order.
+
+Use this tool when a customer needs a packing slip document for order fulfillment.
+
+**Required Parameter:**
+- \`OrderId\`: The order object ID (from orders-list or orders-create)
+
+**Response:**
+\`\`\`json
+{
+  "slip_url": "https://shippo-delivery-east.s3.amazonaws.com/packingslip_{hash}.pdf?{signed_params}",
+  "created": "2026-01-07T16:58:46.350467",
+  "expires": "2026-01-08T16:58:46.350468"
+}
+\`\`\`
+
+**Key Fields:**
+- \`slip_url\`: Signed S3 URL to download the packing slip PDF (valid for 24 hours)
+- \`created\`: When the packing slip was generated
+- \`expires\`: When the download URL expires
+
+**⚠️ URL HANDLING - CRITICAL:**
+The \`slip_url\` is a signed S3 URL that contains required authentication parameters.
+When displaying this URL:
+- ALWAYS show the COMPLETE URL - NEVER truncate or replace parts with "..."
+- S3 signed URLs will NOT work if modified or truncated
+- Display the URL in a code block AND as a clickable hyperlink
+
+**Example Usage:**
+1. List orders: \`orders-list\` → Get an order ID
+2. Generate packing slip: \`orders-get-packing-slip\` with OrderId
+3. Download PDF from the returned \`slip_url\`
+`,
+  scopes: ["read"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await ordersGetPackingSlip(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};