@shippo/shippo-mcp 0.8.0 → 0.8.3

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

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

package/src/mcp-server/server.ts

@@ -96,7 +96,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "ShippoSDK",
-    version: "0.1.9",
+    version: "0.8.3",
   });
 
   const getClient = deps.getSDK || (() =>

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

@@ -12,32 +12,44 @@ const args = {
 
 export const tool$shipmentsList: ToolDefinition<typeof args> = {
   name: "shipments-list",
-  description: `List all shipments
-
-Returns a list of all shipment objects.<br><br>
-In order to filter results, you must use the below path parameters. 
-A maximum date range of 90 days is permitted. 
-Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).<br><br>
-
-Optional path parameters:<br>
-  \`object_created_gt\`- object(s) created greater than a provided date time<br>
-  \`object_created_gte\` - object(s) created greater than or equal to a provided date time<br>
-  \`object_created_lt\` - object(s) created less than a provided date time<br>
-  \`object_created_lte\` - object(s) created less than or equal to a provided date time<br>
-
-  Date format examples:<br>
-    \`2017-01-01\`<br>
-    \`2017-01-01T03:30:30\` or \`2017-01-01T03:30:30.5\`<br>
-    \`2017-01-01T03:30:30Z\`<br><br>
-
-  Example URL:<br>
-    \`https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30\``,
+  description:
+    `**LIST SHIPMENTS (Rate Quotes)** - NOT for finding delivered packages!
+
+This tool lists shipment objects, which represent rate shopping sessions. Each shipment contains:
+- Sender/recipient addresses
+- Parcel dimensions
+- Available shipping rates from carriers
+
+**IMPORTANT DISTINCTIONS:**
+- Shipments = Rate quotes/shopping sessions
+- Shipments do NOT have tracking or delivery status
+- Use \`transactions-list\` to find purchased labels with tracking status
+
+**When to use this tool:**
+- List recent rate shopping sessions
+- Find a shipment to view its rates
+- Review shipment details before purchasing a label
+
+**When NOT to use this tool:**
+- ❌ Finding "delivered" shipments (use transactions-list instead)
+- ❌ Getting tracking information (use tracking-status-get)
+- ❌ Finding purchased labels (use transactions-list)
+
+**Available Filters:**
+- \`object_created_gt/gte/lt/lte\`: Filter by creation date
+- \`page/results\`: Pagination
+
+**Example Use Case:**
+"Show me shipments I created this week" → Use this tool
+"Show me delivered packages" → Use transactions-list with tracking_status filter
+`,
+  scopes: ["read"],
   annotations: {
     "title": "",
     "destructiveHint": false,
     "idempotentHint": false,
     "openWorldHint": false,
-    "readOnlyHint": true,
+    "readOnlyHint": false,
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -12,15 +12,47 @@ const args = {
 
 export const tool$transactionsList: ToolDefinition<typeof args> = {
   name: "transactions-list",
-  description: `List all shipping labels
+  description:
+    `**LIST TRANSACTIONS (Purchased Labels)** - Use this for finding shipped/delivered packages!
 
-Returns a list of all transaction objects.`,
+This tool lists transaction objects, which represent purchased shipping labels. Each transaction contains:
+- Tracking number and tracking URL
+- Label URL for printing
+- Tracking status (UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED, FAILURE)
+- Purchase date and carrier info
+
+**IMPORTANT DISTINCTIONS:**
+- Transactions = Purchased shipping labels
+- Transactions HAVE tracking status and tracking numbers
+- Use \`shipments-list\` for rate quotes (unpurchased shipments)
+
+**When to use this tool:**
+- Find delivered packages → filter by \`tracking_status: "DELIVERED"\`
+- Find packages in transit → filter by \`tracking_status: "TRANSIT"\`
+- List all purchased labels
+- Find a specific label by rate ID
+
+**Available Filters:**
+- \`tracking_status\`: UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED, FAILURE
+- \`object_status\`: WAITING, QUEUED, SUCCESS, ERROR, REFUNDED, REFUNDPENDING, REFUNDREJECTED
+- \`rate\`: Filter by rate ID
+- \`page/results\`: Pagination
+
+**Example Use Cases:**
+- "Show delivered shipments" → \`{tracking_status: "DELIVERED"}\`
+- "Show packages in transit" → \`{tracking_status: "TRANSIT"}\`
+- "Show all labels" → \`{results: 25}\`
+
+**Note on Test Mode:**
+Test transactions will always show \`tracking_status: "UNKNOWN"\` because they don't receive real carrier tracking updates.
+`,
+  scopes: ["read"],
   annotations: {
     "title": "",
     "destructiveHint": false,
     "idempotentHint": false,
     "openWorldHint": false,
-    "readOnlyHint": true,
+    "readOnlyHint": false,
   },
   args,
   tool: async (client, args, ctx) => {

package/src/models/batchshipment.ts

@@ -27,14 +27,14 @@ export const BatchShipmentStatus$zodSchema = z.enum([
 export type BatchShipmentStatus = z.infer<typeof BatchShipmentStatus$zodSchema>;
 
 export type BatchShipment = {
-  carrier_account?: string | undefined;
+  carrier_account?: string | null | undefined;
   metadata?: string | undefined;
-  servicelevel_token?: string | undefined;
+  servicelevel_token?: string | null | undefined;
   messages?: Array<any> | undefined;
   object_id: string;
   shipment: string;
   status: BatchShipmentStatus;
-  transaction?: string | undefined;
+  transaction?: string | null | undefined;
 };
 
 export const BatchShipment$zodSchema: z.ZodType<
@@ -42,12 +42,12 @@ export const BatchShipment$zodSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  carrier_account: z.string().optional(),
+  carrier_account: z.string().nullable().optional(),
   messages: z.array(z.any()).optional(),
   metadata: z.string().optional(),
   object_id: z.string(),
-  servicelevel_token: z.string().optional(),
+  servicelevel_token: z.string().nullable().optional(),
   shipment: z.string(),
   status: BatchShipmentStatus$zodSchema,
-  transaction: z.string().optional(),
+  transaction: z.string().nullable().optional(),
 });

package/src/models/batchshipmentcreaterequest.ts

@@ -9,9 +9,9 @@ import {
 } from "./shipmentcreaterequest.js";
 
 export type BatchShipmentCreateRequest = {
-  carrier_account?: string | undefined;
+  carrier_account?: string | null | undefined;
   metadata?: string | undefined;
-  servicelevel_token?: string | undefined;
+  servicelevel_token?: string | null | undefined;
   shipment: ShipmentCreateRequest;
 };
 
@@ -20,8 +20,8 @@ export const BatchShipmentCreateRequest$zodSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  carrier_account: z.string().optional(),
+  carrier_account: z.string().nullable().optional(),
   metadata: z.string().optional(),
-  servicelevel_token: z.string().optional(),
+  servicelevel_token: z.string().nullable().optional(),
   shipment: ShipmentCreateRequest$zodSchema,
 });

package/src/models/rate.ts

@@ -29,7 +29,7 @@ export type Rate = {
   attributes: Array<Attribute>;
   carrier_account: string;
   duration_terms?: string | undefined;
-  estimated_days?: number | undefined;
+  estimated_days?: number | null | undefined;
   included_insurance_price?: string | null | undefined;
   messages?: Array<ResponseMessage> | undefined;
   object_created: string;
@@ -53,7 +53,7 @@ export const Rate$zodSchema: z.ZodType<Rate, z.ZodTypeDef, unknown> = z.object({
   currency: z.string(),
   currency_local: z.string(),
   duration_terms: z.string().optional(),
-  estimated_days: z.number().int().optional(),
+  estimated_days: z.number().int().nullable().optional(),
   included_insurance_price: z.string().nullable().optional(),
   messages: z.array(ResponseMessage$zodSchema).optional(),
   object_created: z.string().datetime({ offset: true }),

package/tsconfig.json

@@ -28,7 +28,6 @@
     "sourceMap": true,
     "strict": true,
     "target": "es2022",
-    "tsBuildInfoFile": ".tsbuildinfo",
     "useUnknownInCatchVariables": true,
   },
   "exclude": ["node_modules"],