@shippo/shippo-mcp 2.0.3 → 2.0.8

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/ordersList.ts

@@ -14,13 +14,31 @@ export const tool$ordersList: ToolDefinition<typeof args> = {
   name: "orders-list",
   description: `List all orders
 
-Returns a list of all order objects.`,
+Returns a list of all order objects.
+
+**Available Filters:**
+- \`orderStatus\`: Filter by order status. Can pass multiple values as an array.
+  - Values: UNKNOWN, AWAITPAY, PAID, REFUNDED, CANCELLED, PARTIALLY_FULFILLED, SHIPPED
+- \`shop_app\`: Filter by platform/source where order was created
+  - Values: Amazon, Bigcommerce, CSV_Import, eBay, ePages, Etsy, Godaddy, Magento, Shippo, Shopify, Spreecommerce, StripeRelay, Walmart, Weebly, WooCommerce
+- \`start_date\`: Filter orders placed AFTER this date/time (ISO 8601 UTC format, e.g., "2025-01-01T00:00:00Z")
+- \`end_date\`: Filter orders placed BEFORE this date/time (ISO 8601 UTC format)
+- \`page/results\`: Pagination controls
+
+**Example Use Cases:**
+- "Show all paid orders" → filter by \`orderStatus: ["PAID"]\`
+- "Show Shopify orders from last week" → combine \`shop_app: "Shopify"\` with date filters
+- "Show orders ready to ship" → filter by \`orderStatus: ["PAID"]\`
+- "Show cancelled or refunded orders" → filter by \`orderStatus: ["CANCELLED", "REFUNDED"]\`
+
+**Note:** Date filters are based on \`placed_at\` field (when order was placed), not when the order object was created in Shippo.
+`,
   annotations: {
     "title": "",
     "destructiveHint": false,
     "idempotentHint": false,
     "openWorldHint": false,
-    "readOnlyHint": true,
+    "readOnlyHint": false,
   },
   args,
   tool: async (client, args, ctx) => {

package/src/models/addressanalysisv2.ts

@@ -0,0 +1,41 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+import {
+  ValidationResultV2,
+  ValidationResultV2$zodSchema,
+} from "./validationresultv2.js";
+
+export const AddressAnalysisV2AddressType = {
+  Residential: "residential",
+  Commercial: "commercial",
+  Unknown: "unknown",
+} as const;
+export type AddressAnalysisV2AddressType = ClosedEnum<
+  typeof AddressAnalysisV2AddressType
+>;
+
+export const AddressAnalysisV2AddressType$zodSchema = z.enum([
+  "residential",
+  "commercial",
+  "unknown",
+]);
+
+/**
+ * Analysis details for the address validation
+ */
+export type AddressAnalysisV2 = {
+  validation_result?: ValidationResultV2 | undefined;
+  address_type?: AddressAnalysisV2AddressType | null | undefined;
+  changed_attributes?: Array<string> | null | undefined;
+};
+
+export const AddressAnalysisV2$zodSchema: z.ZodType<AddressAnalysisV2> = z
+  .object({
+    address_type: AddressAnalysisV2AddressType$zodSchema.nullable().optional(),
+    changed_attributes: z.array(z.string()).nullable().optional(),
+    validation_result: ValidationResultV2$zodSchema.optional(),
+  }).describe("Analysis details for the address validation");

package/src/models/addresscreaterequestv2.ts

@@ -0,0 +1,64 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * The category of the address. May affect carrier charges.
+ */
+export const AddressCreateRequestV2AddressType = {
+  Unknown: "unknown",
+  Residential: "residential",
+  Commercial: "commercial",
+  PoBox: "po_box",
+  Military: "military",
+} as const;
+/**
+ * The category of the address. May affect carrier charges.
+ */
+export type AddressCreateRequestV2AddressType = ClosedEnum<
+  typeof AddressCreateRequestV2AddressType
+>;
+
+export const AddressCreateRequestV2AddressType$zodSchema = z.enum([
+  "unknown",
+  "residential",
+  "commercial",
+  "po_box",
+  "military",
+]).describe("The category of the address. May affect carrier charges.");
+
+/**
+ * Request body for creating a new address (v2)
+ */
+export type AddressCreateRequestV2 = {
+  name: string;
+  organization?: string | null | undefined;
+  email?: string | null | undefined;
+  phone?: string | null | undefined;
+  address_line_1: string;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code: string;
+  address_type?: AddressCreateRequestV2AddressType | undefined;
+};
+
+export const AddressCreateRequestV2$zodSchema: z.ZodType<
+  AddressCreateRequestV2
+> = z.object({
+  address_line_1: z.string(),
+  address_line_2: z.string().nullable().optional(),
+  address_type: AddressCreateRequestV2AddressType$zodSchema.default("unknown"),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string(),
+  email: z.string().nullable().optional(),
+  name: z.string(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Request body for creating a new address (v2)");

package/src/models/addressdatav2.ts

@@ -0,0 +1,56 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const AddressDataV2AddressType = {
+  Unknown: "unknown",
+  Residential: "residential",
+  Commercial: "commercial",
+  PoBox: "po_box",
+  Military: "military",
+} as const;
+export type AddressDataV2AddressType = ClosedEnum<
+  typeof AddressDataV2AddressType
+>;
+
+export const AddressDataV2AddressType$zodSchema = z.enum([
+  "unknown",
+  "residential",
+  "commercial",
+  "po_box",
+  "military",
+]);
+
+/**
+ * Address data in v2 format
+ */
+export type AddressDataV2 = {
+  name?: string | null | undefined;
+  email?: string | null | undefined;
+  phone?: string | null | undefined;
+  organization?: string | null | undefined;
+  address_line_1?: string | null | undefined;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code?: string | null | undefined;
+  address_type?: AddressDataV2AddressType | null | undefined;
+};
+
+export const AddressDataV2$zodSchema: z.ZodType<AddressDataV2> = z.object({
+  address_line_1: z.string().nullable().optional(),
+  address_line_2: z.string().nullable().optional(),
+  address_type: AddressDataV2AddressType$zodSchema.nullable().optional(),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Address data in v2 format");

package/src/models/addressv2.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+/**
+ * Address object in v2 format
+ */
+export type AddressV2 = {
+  address_line_1?: string | null | undefined;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code?: string | null | undefined;
+  name?: string | null | undefined;
+  organization?: string | null | undefined;
+  phone?: string | null | undefined;
+  email?: string | null | undefined;
+};
+
+export const AddressV2$zodSchema: z.ZodType<AddressV2> = z.object({
+  address_line_1: z.string().nullable().optional(),
+  address_line_2: z.string().nullable().optional(),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Address object in v2 format");

package/src/models/addressvalidationresultv2.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  AddressAnalysisV2,
+  AddressAnalysisV2$zodSchema,
+} from "./addressanalysisv2.js";
+import { AddressV2, AddressV2$zodSchema } from "./addressv2.js";
+import { GeoCoordinates, GeoCoordinates$zodSchema } from "./geocoordinates.js";
+import {
+  RecommendedAddressV2,
+  RecommendedAddressV2$zodSchema,
+} from "./recommendedaddressv2.js";
+
+/**
+ * Address validation result from v2 API
+ */
+export type AddressValidationResultV2 = {
+  original_address?: AddressV2 | undefined;
+  recommended_address?: RecommendedAddressV2 | undefined;
+  analysis?: AddressAnalysisV2 | undefined;
+  geo?: GeoCoordinates | undefined;
+};
+
+export const AddressValidationResultV2$zodSchema: z.ZodType<
+  AddressValidationResultV2
+> = z.object({
+  analysis: AddressAnalysisV2$zodSchema.optional(),
+  geo: GeoCoordinates$zodSchema.optional(),
+  original_address: AddressV2$zodSchema.optional(),
+  recommended_address: RecommendedAddressV2$zodSchema.optional(),
+}).describe("Address validation result from v2 API");

package/src/models/addresswithmetadataresponse.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { AddressDataV2, AddressDataV2$zodSchema } from "./addressdatav2.js";
+
+/**
+ * Response from creating a new address (v2)
+ */
+export type AddressWithMetadataResponse = {
+  id?: string | undefined;
+  address?: AddressDataV2 | undefined;
+  updated_at?: string | undefined;
+  created_at?: string | undefined;
+};
+
+export const AddressWithMetadataResponse$zodSchema: z.ZodType<
+  AddressWithMetadataResponse
+> = z.object({
+  address: AddressDataV2$zodSchema.optional(),
+  created_at: z.iso.datetime({ offset: true }).optional(),
+  id: z.string().optional(),
+  updated_at: z.iso.datetime({ offset: true }).optional(),
+}).describe("Response from creating a new address (v2)");

package/src/models/confidenceresult.ts

@@ -0,0 +1,36 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const Score = {
+  High: "high",
+  Medium: "medium",
+  Low: "low",
+} as const;
+export type Score = ClosedEnum<typeof Score>;
+
+export const Score$zodSchema = z.enum([
+  "high",
+  "medium",
+  "low",
+]);
+
+/**
+ * Confidence score and details for the address validation
+ */
+export type ConfidenceResult = {
+  score?: Score | null | undefined;
+  code?: string | null | undefined;
+  description?: string | null | undefined;
+};
+
+export const ConfidenceResult$zodSchema: z.ZodType<ConfidenceResult> = z.object(
+  {
+    code: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    score: Score$zodSchema.nullable().optional(),
+  },
+).describe("Confidence score and details for the address validation");