@shippo/shippo-mcp 0.5.0

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

@@ -0,0 +1,116 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { transactionsCreate } from "../../funcs/transactionsCreate.js";
+import { CreateTransactionRequest$zodSchema } from "../../models/createtransactionop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: CreateTransactionRequest$zodSchema,
+};
+
+export const tool$transactionsCreate: ToolDefinition<typeof args> = {
+  name: "transactions-create",
+  description: `Creates a shipping label by purchasing an existing rate.
+
+**IMPORTANT:** The request parameter must be a JSON object, not a string.
+
+**Usage:**
+This tool creates shipping labels by purchasing existing rates from shipments.
+First create a shipment to get rates, then use this tool with the rate ID.
+
+**Required Format:**
+\`\`\`json
+{
+  "rate": "rate_id_here"
+}
+\`\`\`
+
+**Working Example:**
+\`\`\`json
+{
+  "rate": "b3b719ce08754a249a1fc20db7a61f4b",
+  "async": false
+}
+\`\`\`
+
+**INTERNATIONAL SHIPMENTS - CRITICAL NOTES:**
+- **ALWAYS use \`async: true\` for international shipments** to avoid timeouts
+- **Server load can cause 500/504 errors** - retry with async processing
+- **Customs declaration must be attached to shipment** before label creation
+
+**International Example:**
+\`\`\`json
+{
+  "rate": "international_rate_id",
+  "async": true
+}
+\`\`\`
+
+**Error Handling:**
+- If you get 504 Gateway timeout → Use \`async: true\`
+- If you get 500 Internal Server Error → Retry with \`async: true\`
+- If customs error → Ensure shipment has valid customs_declaration
+
+**Optional Parameters:**
+- \`async\`: **Set to true for international** (default: false)
+- \`label_file_type\`: PDF_4x6, PNG, etc.
+- \`metadata\`: Custom metadata string
+- \`order\`: Order ID reference
+
+**Workflow:**
+1. Create shipment → Get rates
+2. **For international: Attach customs declaration**
+3. Choose rate → Use this tool with rate ID
+4. **For international: Use async=true**
+5. **If async: Poll transaction status until complete**
+
+**Async Processing Pattern:**
+\`\`\`javascript
+// 1. Create async transaction
+{"rate": "rate_id", "async": true}
+
+// 2. Get transaction ID from response
+// Response: {"object_id": "txn_123", "status": "QUEUED"}
+
+// 3. Poll using transactions-get until done
+// Use: mcp_shippo-node_transactions-get with TransactionId
+// Keep checking until status changes from "QUEUED" to "SUCCESS"
+
+// 4. Once SUCCESS: label_url, tracking_number will be populated
+\`\`\`
+
+**Status Flow:**
+- \`QUEUED\` → Processing (keep polling)
+- \`SUCCESS\` → ✅ Label ready! Check label_url and tracking_number
+- \`ERROR\` → ❌ Check messages for details
+`,
+  scopes: ["write"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await transactionsCreate(
+      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/transactionsGet.ts

@@ -0,0 +1,73 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { transactionsGet } from "../../funcs/transactionsGet.js";
+import { GetTransactionRequest$zodSchema } from "../../models/gettransactionop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetTransactionRequest$zodSchema,
+};
+
+export const tool$transactionsGet: ToolDefinition<typeof args> = {
+  name: "transactions-get",
+  description: `Retrieve a shipping label transaction by its ID.
+
+**PRIMARY USE: Polling async transaction status**
+
+**Async Transaction Polling Pattern:**
+\`\`\`javascript
+// After creating async transaction, poll until complete:
+
+// 1. Create async transaction → Get transaction_id
+// 2. Poll this endpoint until status != "QUEUED"
+
+// Poll example:
+{TransactionId: "5bd872675aee4e7fb19f961d319fac44"}
+\`\`\`
+
+**Transaction Status Values:**
+- \`QUEUED\` → Still processing (keep polling)
+- \`SUCCESS\` → ✅ Label ready! Check response for:
+  - \`label_url\`: Download link for shipping label
+  - \`tracking_number\`: Package tracking number  
+  - \`tracking_url_provider\`: Carrier tracking URL
+- \`ERROR\` → ❌ Failed (check \`messages\` field for details)
+
+**Polling Best Practice:**
+- Poll every 2-3 seconds until status changes
+- International shipments typically take 10-30 seconds
+- Domestic shipments typically take 2-5 seconds
+
+**Required Parameter:**
+- \`TransactionId\`: The transaction object ID from transaction creation
+`,
+  scopes: ["read"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await transactionsGet(
+      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/transactionsList.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { transactionsList } from "../../funcs/transactionsList.js";
+import { ListTransactionsRequest$zodSchema } from "../../models/listtransactionsop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: ListTransactionsRequest$zodSchema.optional(),
+};
+
+export const tool$transactionsList: ToolDefinition<typeof args> = {
+  name: "transactions-list",
+  description: `List all shipping labels
+
+Returns a list of all transaction objects.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await transactionsList(
+      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/userParcelTemplatesCreate.ts

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { userParcelTemplatesCreate } from "../../funcs/userParcelTemplatesCreate.js";
+import { UserParcelTemplateCreateRequest$zodSchema } from "../../models/userparceltemplatecreaterequest.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: UserParcelTemplateCreateRequest$zodSchema,
+};
+
+export const tool$userParcelTemplatesCreate: ToolDefinition<typeof args> = {
+  name: "user-parcel-templates-create",
+  description: `Create a new user parcel template
+
+Creates a new user parcel template. <br>You can choose to create a
+parcel template using a preset carrier template as a starting point, or
+you can create an entirely custom one. To use a preset carrier template,
+pass in a unique template token from <a href="#tag/Parcel-Templates">this list</a>
+plus the weight fields (**weight** and **weight_unit**). Otherwise, omit
+the template field and pass the other fields, for the weight, length, height,
+and depth, as well as their units."`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await userParcelTemplatesCreate(
+      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/userParcelTemplatesDelete.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { userParcelTemplatesDelete } from "../../funcs/userParcelTemplatesDelete.js";
+import { DeleteUserParcelTemplateRequest$zodSchema } from "../../models/deleteuserparceltemplateop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: DeleteUserParcelTemplateRequest$zodSchema,
+};
+
+export const tool$userParcelTemplatesDelete: ToolDefinition<typeof args> = {
+  name: "user-parcel-templates-delete",
+  description: `Delete a user parcel template
+
+Deletes a user parcel template using an object ID.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": true,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await userParcelTemplatesDelete(
+      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/userParcelTemplatesGet.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { userParcelTemplatesGet } from "../../funcs/userParcelTemplatesGet.js";
+import { GetUserParcelTemplateRequest$zodSchema } from "../../models/getuserparceltemplateop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetUserParcelTemplateRequest$zodSchema,
+};
+
+export const tool$userParcelTemplatesGet: ToolDefinition<typeof args> = {
+  name: "user-parcel-templates-get",
+  description: `Retrieves a user parcel template
+
+Returns the parcel template information for a specific user parcel
+template, identified by the object ID.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await userParcelTemplatesGet(
+      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/userParcelTemplatesList.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { userParcelTemplatesList } from "../../funcs/userParcelTemplatesList.js";
+import { ListUserParcelTemplatesRequest$zodSchema } from "../../models/listuserparceltemplatesop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: ListUserParcelTemplatesRequest$zodSchema.optional(),
+};
+
+export const tool$userParcelTemplatesList: ToolDefinition<typeof args> = {
+  name: "user-parcel-templates-list",
+  description: `List all user parcel templates
+
+Returns a list all of all user parcel template objects.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await userParcelTemplatesList(
+      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/userParcelTemplatesUpdate.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { userParcelTemplatesUpdate } from "../../funcs/userParcelTemplatesUpdate.js";
+import { UpdateUserParcelTemplateRequest$zodSchema } from "../../models/updateuserparceltemplateop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: UpdateUserParcelTemplateRequest$zodSchema,
+};
+
+export const tool$userParcelTemplatesUpdate: ToolDefinition<typeof args> = {
+  name: "user-parcel-templates-update",
+  description: `Update an existing user parcel template
+
+Updates an existing user parcel template.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await userParcelTemplatesUpdate(
+      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/webhooksCreate.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { webhooksCreate } from "../../funcs/webhooksCreate.js";
+import { WebhookUpdateRequest$zodSchema } from "../../models/webhookupdaterequest.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: WebhookUpdateRequest$zodSchema,
+};
+
+export const tool$webhooksCreate: ToolDefinition<typeof args> = {
+  name: "webhooks-create",
+  description: `Create a new webhook
+
+Creates a new webhook to send notifications to a URL when a specific event occurs.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await webhooksCreate(
+      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/webhooksDelete.ts

@@ -0,0 +1,42 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { webhooksDelete } from "../../funcs/webhooksDelete.js";
+import { DeleteWebhookRequest$zodSchema } from "../../models/deletewebhookop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: DeleteWebhookRequest$zodSchema,
+};
+
+export const tool$webhooksDelete: ToolDefinition<typeof args> = {
+  name: "webhooks-delete",
+  description: `Delete a specific webhook
+
+Deletes a specific webhook using the webhook object ID.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": true,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await webhooksDelete(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    return formatResult(void 0, apiCall);
+  },
+};

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

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { webhooksGet } from "../../funcs/webhooksGet.js";
+import { GetWebhookRequest$zodSchema } from "../../models/getwebhookop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: GetWebhookRequest$zodSchema,
+};
+
+export const tool$webhooksGet: ToolDefinition<typeof args> = {
+  name: "webhooks-get",
+  description: `Retrieve a specific webhook
+
+Returns the details of a specific webhook using the webhook object ID.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await webhooksGet(
+      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/webhooksList.ts

@@ -0,0 +1,37 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { webhooksList } from "../../funcs/webhooksList.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+export const tool$webhooksList: ToolDefinition = {
+  name: "webhooks-list",
+  description: `List all webhooks
+
+Returns a list of all webhooks you have created.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": true,
+  },
+  tool: async (client, ctx) => {
+    const [result, apiCall] = await webhooksList(
+      client,
+      { 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/webhooksUpdate.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { webhooksUpdate } from "../../funcs/webhooksUpdate.js";
+import { UpdateWebhookRequest$zodSchema } from "../../models/updatewebhookop.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: UpdateWebhookRequest$zodSchema,
+};
+
+export const tool$webhooksUpdate: ToolDefinition<typeof args> = {
+  name: "webhooks-update",
+  description: `Update an existing webhook
+
+Updates an existing webhook using the webhook object ID.`,
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await webhooksUpdate(
+      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);
+  },
+};