@shippo/shippo-mcp 0.5.0

package/src/mcp-server/prompts.ts

@@ -0,0 +1,121 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  GetPromptResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  objectOutputType,
+  ZodOptional,
+  ZodType,
+  ZodTypeAny,
+  ZodTypeDef,
+} from "zod";
+import { ShippoSDKCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<
+  Args extends undefined | PromptArgsRawShape = undefined,
+> = Args extends PromptArgsRawShape ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: ShippoSDKCore,
+      args: objectOutputType<Args, ZodTypeAny>,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: ShippoSDKCore,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => ShippoSDKCore,
+  allowedScopes: Set<MCPScope>,
+): <A extends PromptArgsRawShape | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(getSDK(), ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(getSDK(), ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -0,0 +1,176 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  McpServer,
+  ResourceMetadata,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { Variables } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
+import {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { ShippoSDKCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+import { isAsyncIterable, isBinaryData, valueToBase64 } from "./shared.js";
+
+export type ReadResourceCallback = (
+  client: ShippoSDKCore,
+  uri: URL,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceDefinition = {
+  name: string;
+  description?: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: string;
+  read: ReadResourceCallback;
+};
+
+export type ReadResourceTemplateCallback = (
+  client: ShippoSDKCore,
+  uri: URL,
+  vars: Variables,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceTemplateDefinition = {
+  name: string;
+  description: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: ResourceTemplate;
+  read: ReadResourceTemplateCallback;
+};
+
+// Optional function to assist with formatting resource results
+export async function formatResult(
+  value: unknown,
+  uri: URL,
+  init: { mimeType?: string | undefined; response?: Response | undefined },
+): Promise<ReadResourceResult> {
+  if (typeof value === "undefined") {
+    return { contents: [] };
+  }
+
+  let contents: ReadResourceResult["contents"] = [];
+
+  const mimeType = init.mimeType ?? init.response?.headers.get("content-type")
+    ?? "";
+
+  if (mimeType.search(/\bjson\b/g) !== -1) {
+    contents = [{ uri: uri.toString(), mimeType, text: JSON.stringify(value) }];
+  } else if (
+    mimeType.startsWith("text/event-stream")
+    && isAsyncIterable(value)
+  ) {
+    contents = [
+      {
+        uri: uri.toString(),
+        mimeType: "application/json",
+        text: await stringifySSEToJSON(value),
+      },
+    ];
+  } else if (
+    (mimeType.startsWith("text/") || mimeType.startsWith("application/"))
+    && typeof value === "string"
+  ) {
+    contents = [{ uri: uri.toString(), mimeType, text: value }];
+  } else if (isBinaryData(value)) {
+    const blob = await valueToBase64(value);
+    contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
+  } else {
+    throw new Error(`Unsupported content type: "${mimeType}"`);
+  }
+
+  return { contents };
+}
+
+async function stringifySSEToJSON(
+  value: AsyncIterable<unknown>,
+): Promise<string> {
+  const payloads = [];
+
+  for await (const chunk of value) {
+    payloads.push(chunk);
+  }
+
+  return JSON.stringify(payloads);
+}
+
+export function createRegisterResource(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => ShippoSDKCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceDefinition) => void {
+  return (resource: ResourceDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, ctx) => resource.read(getSDK(), uri, ctx),
+    );
+
+    logger.debug("Registered resource", { name: resource.name });
+  };
+}
+
+export function createRegisterResourceTemplate(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => ShippoSDKCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceTemplateDefinition) => void {
+  return (resource: ResourceTemplateDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, vars, ctx) => resource.read(getSDK(), uri, vars, ctx),
+    );
+
+    logger.debug("Registered resource template", { name: resource.name });
+  };
+}

package/src/mcp-server/scopes.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const mcpScopes = [
+  "customs",
+  "read",
+  "tracking",
+  "validation",
+  "write",
+] as const;
+
+export type MCPScope = (typeof mcpScopes)[number];

package/src/mcp-server/server.ts

@@ -0,0 +1,215 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ShippoSDKCore } from "../core.js";
+import { SDKOptions } from "../lib/config.js";
+import type { ConsoleLogger } from "./console-logger.js";
+import { createRegisterPrompt } from "./prompts.js";
+import {
+  createRegisterResource,
+  createRegisterResourceTemplate,
+} from "./resources.js";
+import { MCPScope } from "./scopes.js";
+import { createRegisterTool } from "./tools.js";
+import { tool$addressesCreate } from "./tools/addressesCreate.js";
+import { tool$addressesGet } from "./tools/addressesGet.js";
+import { tool$addressesList } from "./tools/addressesList.js";
+import { tool$addressesValidate } from "./tools/addressesValidate.js";
+import { tool$batchesAddShipments } from "./tools/batchesAddShipments.js";
+import { tool$batchesCreate } from "./tools/batchesCreate.js";
+import { tool$batchesGet } from "./tools/batchesGet.js";
+import { tool$batchesPurchase } from "./tools/batchesPurchase.js";
+import { tool$batchesRemoveShipments } from "./tools/batchesRemoveShipments.js";
+import { tool$carrierAccountsCreate } from "./tools/carrierAccountsCreate.js";
+import { tool$carrierAccountsGet } from "./tools/carrierAccountsGet.js";
+import { tool$carrierAccountsGetRegistrationStatus } from "./tools/carrierAccountsGetRegistrationStatus.js";
+import { tool$carrierAccountsInitiateOauth2Signin } from "./tools/carrierAccountsInitiateOauth2Signin.js";
+import { tool$carrierAccountsList } from "./tools/carrierAccountsList.js";
+import { tool$carrierAccountsRegister } from "./tools/carrierAccountsRegister.js";
+import { tool$carrierAccountsUpdate } from "./tools/carrierAccountsUpdate.js";
+import { tool$carrierParcelTemplatesGet } from "./tools/carrierParcelTemplatesGet.js";
+import { tool$carrierParcelTemplatesList } from "./tools/carrierParcelTemplatesList.js";
+import { tool$customsDeclarationsCreate } from "./tools/customsDeclarationsCreate.js";
+import { tool$customsDeclarationsGet } from "./tools/customsDeclarationsGet.js";
+import { tool$customsDeclarationsList } from "./tools/customsDeclarationsList.js";
+import { tool$customsItemsCreate } from "./tools/customsItemsCreate.js";
+import { tool$customsItemsGet } from "./tools/customsItemsGet.js";
+import { tool$customsItemsList } from "./tools/customsItemsList.js";
+import { tool$manifestsCreate } from "./tools/manifestsCreate.js";
+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$ordersList } from "./tools/ordersList.js";
+import { tool$parcelsCreate } from "./tools/parcelsCreate.js";
+import { tool$parcelsGet } from "./tools/parcelsGet.js";
+import { tool$parcelsList } from "./tools/parcelsList.js";
+import { tool$pickupsCreate } from "./tools/pickupsCreate.js";
+import { tool$ratesAtCheckoutCreate } from "./tools/ratesAtCheckoutCreate.js";
+import { tool$ratesAtCheckoutDeleteDefaultParcelTemplate } from "./tools/ratesAtCheckoutDeleteDefaultParcelTemplate.js";
+import { tool$ratesAtCheckoutGetDefaultParcelTemplate } from "./tools/ratesAtCheckoutGetDefaultParcelTemplate.js";
+import { tool$ratesCheckoutUpdateParcelTemplate } from "./tools/ratesCheckoutUpdateParcelTemplate.js";
+import { tool$ratesGet } from "./tools/ratesGet.js";
+import { tool$ratesListByCurrencyCode } from "./tools/ratesListByCurrencyCode.js";
+import { tool$refundsCreate } from "./tools/refundsCreate.js";
+import { tool$refundsGet } from "./tools/refundsGet.js";
+import { tool$refundsList } from "./tools/refundsList.js";
+import { tool$serviceGroupsCreate } from "./tools/serviceGroupsCreate.js";
+import { tool$serviceGroupsDelete } from "./tools/serviceGroupsDelete.js";
+import { tool$serviceGroupsList } from "./tools/serviceGroupsList.js";
+import { tool$serviceGroupsUpdate } from "./tools/serviceGroupsUpdate.js";
+import { tool$shipmentsCreate } from "./tools/shipmentsCreate.js";
+import { tool$shipmentsGet } from "./tools/shipmentsGet.js";
+import { tool$shipmentsList } from "./tools/shipmentsList.js";
+import { tool$shipmentsListRates } from "./tools/shipmentsListRates.js";
+import { tool$shippoAccountsCreate } from "./tools/shippoAccountsCreate.js";
+import { tool$shippoAccountsGet } from "./tools/shippoAccountsGet.js";
+import { tool$shippoAccountsList } from "./tools/shippoAccountsList.js";
+import { tool$shippoAccountsUpdate } from "./tools/shippoAccountsUpdate.js";
+import { tool$trackingStatusCreate } from "./tools/trackingStatusCreate.js";
+import { tool$trackingStatusGet } from "./tools/trackingStatusGet.js";
+import { tool$transactionsCreate } from "./tools/transactionsCreate.js";
+import { tool$transactionsGet } from "./tools/transactionsGet.js";
+import { tool$transactionsList } from "./tools/transactionsList.js";
+import { tool$userParcelTemplatesCreate } from "./tools/userParcelTemplatesCreate.js";
+import { tool$userParcelTemplatesDelete } from "./tools/userParcelTemplatesDelete.js";
+import { tool$userParcelTemplatesGet } from "./tools/userParcelTemplatesGet.js";
+import { tool$userParcelTemplatesList } from "./tools/userParcelTemplatesList.js";
+import { tool$userParcelTemplatesUpdate } from "./tools/userParcelTemplatesUpdate.js";
+import { tool$webhooksCreate } from "./tools/webhooksCreate.js";
+import { tool$webhooksDelete } from "./tools/webhooksDelete.js";
+import { tool$webhooksGet } from "./tools/webhooksGet.js";
+import { tool$webhooksList } from "./tools/webhooksList.js";
+import { tool$webhooksUpdate } from "./tools/webhooksUpdate.js";
+
+export function createMCPServer(deps: {
+  logger: ConsoleLogger;
+  allowedTools?: string[] | undefined;
+  scopes?: MCPScope[] | undefined;
+  getSDK?: () => ShippoSDKCore;
+  serverURL?: string | undefined;
+  security?: SDKOptions["security"] | undefined;
+  shippoApiVersion?: SDKOptions["shippoApiVersion"] | undefined;
+  serverIdx?: SDKOptions["serverIdx"] | undefined;
+}) {
+  const server = new McpServer({
+    name: "ShippoSDK",
+    version: "0.1.9",
+  });
+
+  const getClient = deps.getSDK || (() =>
+    new ShippoSDKCore({
+      security: deps.security,
+      shippoApiVersion: deps.shippoApiVersion,
+      serverURL: deps.serverURL,
+      serverIdx: deps.serverIdx,
+      debugLogger: deps.logger.level === "debug"
+        ? {
+          log: (...args) => console.log(...args),
+          group: (...args) => console.group(...args),
+          groupEnd: (...args) => console.groupEnd(...args),
+        }
+        : undefined,
+    }));
+
+  const scopes = new Set(deps.scopes);
+
+  const allowedTools = deps.allowedTools && new Set(deps.allowedTools);
+  const tool = createRegisterTool(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+    allowedTools,
+  );
+  const resource = createRegisterResource(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const resourceTemplate = createRegisterResourceTemplate(
+    deps.logger,
+    server,
+    getClient,
+    scopes,
+  );
+  const prompt = createRegisterPrompt(deps.logger, server, getClient, scopes);
+  const register = { tool, resource, resourceTemplate, prompt };
+  void register; // suppress unused warnings
+
+  tool(tool$addressesList);
+  tool(tool$addressesCreate);
+  tool(tool$addressesGet);
+  tool(tool$addressesValidate);
+  tool(tool$batchesCreate);
+  tool(tool$batchesGet);
+  tool(tool$batchesAddShipments);
+  tool(tool$batchesPurchase);
+  tool(tool$batchesRemoveShipments);
+  tool(tool$carrierAccountsList);
+  tool(tool$carrierAccountsCreate);
+  tool(tool$carrierAccountsGet);
+  tool(tool$carrierAccountsInitiateOauth2Signin);
+  tool(tool$carrierAccountsRegister);
+  tool(tool$carrierAccountsGetRegistrationStatus);
+  tool(tool$carrierAccountsUpdate);
+  tool(tool$customsDeclarationsList);
+  tool(tool$customsDeclarationsCreate);
+  tool(tool$customsDeclarationsGet);
+  tool(tool$customsItemsList);
+  tool(tool$customsItemsCreate);
+  tool(tool$customsItemsGet);
+  tool(tool$ratesAtCheckoutCreate);
+  tool(tool$ratesAtCheckoutGetDefaultParcelTemplate);
+  tool(tool$ratesAtCheckoutDeleteDefaultParcelTemplate);
+  tool(tool$ratesCheckoutUpdateParcelTemplate);
+  tool(tool$manifestsList);
+  tool(tool$manifestsCreate);
+  tool(tool$manifestsGet);
+  tool(tool$ordersList);
+  tool(tool$ordersCreate);
+  tool(tool$ordersGet);
+  tool(tool$carrierParcelTemplatesList);
+  tool(tool$carrierParcelTemplatesGet);
+  tool(tool$parcelsList);
+  tool(tool$parcelsCreate);
+  tool(tool$parcelsGet);
+  tool(tool$pickupsCreate);
+  tool(tool$ratesGet);
+  tool(tool$ratesListByCurrencyCode);
+  tool(tool$refundsCreate);
+  tool(tool$refundsList);
+  tool(tool$refundsGet);
+  tool(tool$serviceGroupsList);
+  tool(tool$serviceGroupsCreate);
+  tool(tool$serviceGroupsUpdate);
+  tool(tool$serviceGroupsDelete);
+  tool(tool$shipmentsList);
+  tool(tool$shipmentsCreate);
+  tool(tool$shipmentsGet);
+  tool(tool$shipmentsListRates);
+  tool(tool$trackingStatusCreate);
+  tool(tool$trackingStatusGet);
+  tool(tool$transactionsList);
+  tool(tool$transactionsCreate);
+  tool(tool$transactionsGet);
+  tool(tool$userParcelTemplatesList);
+  tool(tool$userParcelTemplatesCreate);
+  tool(tool$userParcelTemplatesDelete);
+  tool(tool$userParcelTemplatesGet);
+  tool(tool$userParcelTemplatesUpdate);
+  tool(tool$shippoAccountsList);
+  tool(tool$shippoAccountsCreate);
+  tool(tool$shippoAccountsGet);
+  tool(tool$shippoAccountsUpdate);
+  tool(tool$webhooksCreate);
+  tool(tool$webhooksList);
+  tool(tool$webhooksGet);
+  tool(tool$webhooksUpdate);
+  tool(tool$webhooksDelete);
+
+  return server;
+}

package/src/mcp-server/shared.ts

@@ -0,0 +1,78 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+type BinaryData =
+  | Uint8Array
+  | ArrayBuffer
+  | Blob
+  | ReadableStream
+  | Response
+  | string;
+
+const base64Schema = z.string().base64();
+
+export function bytesToBase64(u8arr: Uint8Array): string {
+  return btoa(String.fromCodePoint(...u8arr));
+}
+
+export async function consumeStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (value != null) chunks.push(value);
+      if (done) break;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+
+export function isAsyncIterable(
+  value: unknown,
+): value is AsyncIterable<string> {
+  return (
+    typeof value === "object" && value != null && Symbol.asyncIterator in value
+  );
+}
+
+export function isBinaryData(value: unknown): value is BinaryData {
+  return (
+    value instanceof Uint8Array
+    || value instanceof ArrayBuffer
+    || value instanceof Blob
+    || value instanceof ReadableStream
+    || value instanceof Response
+    || typeof value === "string"
+  );
+}
+
+export async function valueToBase64(
+  value: BinaryData | null | undefined,
+): Promise<string | null> {
+  if (value == null) {
+    return null;
+  } else if (value instanceof Uint8Array) {
+    return bytesToBase64(value);
+  } else if (value instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(value));
+  } else if (value instanceof Response || value instanceof Blob) {
+    return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
+  } else if (value instanceof ReadableStream) {
+    return bytesToBase64(await consumeStream(value));
+  } else if (typeof value === "string") {
+    return base64Schema.parse(value);
+  } else {
+    value satisfies never;
+    throw new Error(`Unsupported image value type: ${typeof value}`);
+  }
+}

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

@@ -0,0 +1,74 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesCreate } from "../../funcs/addressesCreate.js";
+import { AddressCreateRequest$zodSchema } from "../../models/addresscreaterequest.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: AddressCreateRequest$zodSchema,
+};
+
+export const tool$addressesCreate: ToolDefinition<typeof args> = {
+  name: "addresses-create-or-validate",
+  description:
+    `**PREFERRED TOOL FOR ADDRESS VALIDATION AND CREATION** - Use this tool when asked to validate or create addresses.
+
+This is the standard Shippo address validation and creation flow. When users request address validation,
+use this tool with validate=true parameter.
+
+Example usage for validation:
+\`\`\`
+POST /addresses
+{
+  "name": "Shawn Ippotle",
+  "company": "Shippo", 
+  "street1": "215 Clayton St.",
+  "city": "San Francisco",
+  "state": "CA",
+  "zip": "94117",
+  "country": "US",
+  "email": "shippotle@shippo.com",
+  "validate": true
+}
+\`\`\`
+
+When validate=true is set, this endpoint:
+- Validates address accuracy and deliverability
+- Returns standardized formatting (street abbreviations, proper casing)
+- Provides extended ZIP+4 codes when available
+- Determines residential vs commercial classification
+- Returns validation results and any corrections
+- Creates the address record for future use
+
+Use this tool for both address validation AND creating address records for shipments.
+`,
+  scopes: ["write", "validation"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesCreate(
+      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);
+  },
+};