@shippo/shippo-mcp 2.0.2 → 2.0.8

package/src/funcs/addressesParse.ts

@@ -0,0 +1,178 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ShippoSDKCore } from "../core.js";
+import { encodeFormQuery, 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 {
+  ParseAddressRequest,
+  ParseAddressRequest$zodSchema,
+  ParseAddressResponse,
+  ParseAddressResponse$zodSchema,
+} from "../models/parseaddressop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Parse an address string
+ *
+ * @remarks
+ * Parses an unstructured address string into a structured address object.
+ * The parser extracts address components like street, city, state, postal code, country, email, and phone.
+ *
+ * For best results:
+ * - Use a comma (,) as a delimiter between address parts
+ * - Follow this order: address_line_1, address_line_2, city_locality, state_province, postal_code, country_code
+ * - Phone and email can be in any part of the string
+ *
+ * Example input: "Shippo 731 Market St #200, San Francisco, CA 94103 US shippo@shippo.com +1-555-999-8888"
+ */
+export function addressesParse(
+  client$: ShippoSDKCore,
+  request: ParseAddressRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    ParseAddressResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: ShippoSDKCore,
+  request: ParseAddressRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      ParseAddressResponse,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => ParseAddressRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/v2/addresses/parse")();
+  const query$ = encodeFormQuery({
+    "address": payload$.address,
+  });
+
+  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: "ParseAddress",
+    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$,
+    query: query$,
+    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<
+    ParseAddressResponse,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json(200, ParseAddressResponse$zodSchema, { key: "ParsedAddress" }),
+    M.json(400, ParseAddressResponse$zodSchema, { key: "BadRequest" }),
+  )(response, req$, { extraFields: responseFields$ });
+
+  return [result$, { status: "complete", request: req$, response }];
+}

package/src/funcs/addressesValidateV2.ts

@@ -0,0 +1,188 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ShippoSDKCore } from "../core.js";
+import { encodeFormQuery, 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 {
+  ValidateAddressV2Request,
+  ValidateAddressV2Request$zodSchema,
+  ValidateAddressV2Response,
+  ValidateAddressV2Response$zodSchema,
+} from "../models/validateaddressv2op.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Validate an address (v2)
+ *
+ * @remarks
+ * Returns validation test results along with a recommended address.
+ * Validates both US and international addresses.
+ *
+ * **US required combinations:**
+ * - state_province + city_locality + address_line_1
+ * - OR address_line_1 + postal_code
+ *
+ * **International required combinations:**
+ * - city_locality + address_line_1
+ */
+export function addressesValidateV2(
+  client$: ShippoSDKCore,
+  request: ValidateAddressV2Request,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    ValidateAddressV2Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: ShippoSDKCore,
+  request: ValidateAddressV2Request,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      ValidateAddressV2Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => ValidateAddressV2Request$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/v2/addresses/validate")();
+  const query$ = encodeFormQuery({
+    "address_line_1": payload$.address_line_1,
+    "address_line_2": payload$.address_line_2,
+    "city_locality": payload$.city_locality,
+    "country_code": payload$.country_code,
+    "name": payload$.name,
+    "organization": payload$.organization,
+    "postal_code": payload$.postal_code,
+    "state_province": payload$.state_province,
+  });
+
+  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: "ValidateAddressV2",
+    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$,
+    query: query$,
+    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<
+    ValidateAddressV2Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >(
+    M.json(200, ValidateAddressV2Response$zodSchema, {
+      key: "AddressValidationResultV2",
+    }),
+    M.json(422, ValidateAddressV2Response$zodSchema, { key: "object" }),
+    M.nil("5XX", ValidateAddressV2Response$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.2",
+  sdkVersion: "2.0.8",
   genVersion: "2.788.5",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 2.0.2 2.788.5 2018-02-08 @shippo/shippo-mcp",
+    "speakeasy-sdk/mcp-typescript 2.0.8 2.788.5 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.2",
+    currentVersion: "2.0.8",
   },
 });
 

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";
@@ -96,7 +99,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "ShippoSDK",
-    version: "2.0.2",
+    version: "2.0.8",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -141,9 +144,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);

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: {