easypost-mcp 2.1.0 → 3.1.0

package/src/services/ShipmentService.js

@@ -1,13 +1,25 @@
 import { mapShipment, mapRate, mapCollection } from "../adapters/easypost/responseMappers.js";
 import { NotFoundError } from "../errors/AppError.js";
+import { createFallbackResponse } from "../elicitation/fallback.js";
+
+function mapSelectableRates(rates) {
+  return rates.map((rate, index) => ({
+    option: index + 1,
+    ...mapRate(rate),
+  }));
+}
 
 class ShipmentService {
-  constructor(easypostClient) {
+  constructor(easypostClient, { confirmations, elicitation, idempotency } = {}) {
     this.easypost = easypostClient;
+    this.confirmations = confirmations;
+    this.elicitation = elicitation;
+    this.idempotency = idempotency;
   }
 
   async createShipment(input, context) {
-    const shipment = await this.easypost.execute(
+    const operation = async () => {
+      const shipment = await this.easypost.execute(
       "shipment.create",
       (client) => client.Shipment.create({
         from_address: input.from_address,
@@ -19,9 +31,30 @@ class ShipmentService {
         reference: input.reference,
       }),
       context
-    );
-
-    return { ok: true, shipment: mapShipment(shipment), rates: (shipment.rates || []).map(mapRate) };
+      );
+
+      const rawRates = shipment.rates || [];
+      const rates = mapSelectableRates(rawRates);
+      context.audit?.record("rates_returned", {
+        correlationId: context.correlationId,
+        shipment_id: shipment.id,
+        rate_count: rates.length,
+        rate_ids: rates.map((rate) => rate.id),
+      });
+
+      return {
+        ok: true,
+        shipment: mapShipment(shipment),
+        rates,
+        next_step: rates.length
+          ? "Choose a numbered rate option or exact rate_id from rates and call buy_shipping_label with confirm=true."
+          : "No rates were returned by the carrier accounts for this shipment.",
+      };
+    };
+
+    if (!this.idempotency || !input.idempotency_key) return operation();
+    const { reused, result } = await this.idempotency.run(`create_shipment:${input.idempotency_key}`, operation);
+    return reused ? { ...result, idempotent_replay: true } : result;
   }
 
   async buyShippingLabel(input, context) {
@@ -33,19 +66,104 @@ class ShipmentService {
 
     if (!shipment) throw new NotFoundError("shipment", input.shipment_id);
 
-    const rate = input.rate_id
-      ? (shipment.rates || []).find((candidate) => candidate.id === input.rate_id)
-      : (shipment.rates || []).find((candidate) => candidate.carrier === input.carrier && candidate.service === input.service);
-
-    if (!rate) throw new NotFoundError("rate", input.rate_id || `${input.carrier}/${input.service}`);
+    const rates = shipment.rates || [];
+    if (!input.rate_id && !input.rate_option) {
+      const elicited = await this.elicitation?.selectRateForLabel({
+        server: context.server,
+        shipmentId: input.shipment_id,
+        rates,
+        confirmDefault: input.confirm === true,
+      });
+
+      if (elicited?.selected) {
+        input.rate_option = elicited.rate_option;
+        input.confirm = elicited.confirm;
+        context.audit?.record("rate_selection_elicited", {
+          correlationId: context.correlationId,
+          shipment_id: input.shipment_id,
+          rate_option: input.rate_option,
+          confirmed: input.confirm,
+        });
+      } else {
+        context.audit?.record("rate_selection_fallback", {
+          correlationId: context.correlationId,
+          shipment_id: input.shipment_id,
+          reason: elicited?.reason,
+        });
+        return {
+          ...createFallbackResponse({
+            errorCode: "RATE_SELECTION_REQUIRED",
+            message: "Select a rate using the client form if available, or provide one numbered rate_option from available_rates.",
+            missingFields: ["rate_option"],
+            availableOptions: mapSelectableRates(rates),
+            examples: { rate_option: [1, 2] },
+            nextAction: "Choose one available option and retry with rate_option, or use a client that supports elicitation.form.",
+            metadata: {
+              elicitation_supported: this.elicitation?.supportsForm(context.server) === true,
+              fallback_reason: elicited?.reason,
+            },
+          }),
+        };
+      }
+    }
 
-    const bought = await this.easypost.execute(
-      "shipment.buy",
-      (client) => client.Shipment.buy(input.shipment_id, rate, input.insurance),
-      context
-    );
-
-    return { ok: true, shipment: mapShipment(bought), purchased_rate: mapRate(rate) };
+    const rate = input.rate_id
+      ? rates.find((candidate) => candidate.id === input.rate_id)
+      : rates[input.rate_option - 1];
+
+    if (!rate) {
+      context.audit?.record("rate_selection_failed", {
+        correlationId: context.correlationId,
+        shipment_id: input.shipment_id,
+        requested_rate_id: input.rate_id,
+        requested_rate_option: input.rate_option,
+        available_rate_ids: rates.map((candidate) => candidate.id),
+      });
+      return {
+        ...createFallbackResponse({
+          errorCode: "RATE_ID_NOT_AVAILABLE",
+          message: "The requested rate selection is not available on this shipment. Select one option number or exact id from available_rates.",
+          missingFields: ["rate_option"],
+          availableOptions: mapSelectableRates(rates),
+          examples: { rate_option: [1], rate_id: rates[0]?.id ? [rates[0].id] : [] },
+          nextAction: "Retry with a valid rate_option or exact rate_id from available_options.",
+          metadata: {
+            requested_rate_id: input.rate_id,
+            requested_rate_option: input.rate_option,
+          },
+        }),
+      };
+    }
+
+    await this.confirmations?.requireConfirmed(input, {
+      action: "buy_shipping_label",
+      message: `You are about to buy a ${rate.carrier} ${rate.service} label for ${rate.rate} ${rate.currency || "USD"}. Proceed?`,
+      details: {
+        shipment_id: input.shipment_id,
+        rate: mapRate(rate),
+      },
+    }, context);
+
+    const operation = async () => {
+      context.audit?.record("label_purchase_confirmed", {
+        correlationId: context.correlationId,
+        shipment_id: input.shipment_id,
+        rate_id: rate.id,
+        rate_option: input.rate_option,
+      });
+
+      const bought = await this.easypost.execute(
+        "shipment.buy",
+        (client) => client.Shipment.buy(input.shipment_id, rate, input.insurance),
+        context
+      );
+
+      return { ok: true, shipment: mapShipment(bought), purchased_rate: mapRate(rate) };
+    };
+
+    if (!this.idempotency || !input.idempotency_key) return operation();
+    const { reused, result } = await this.idempotency.run(`buy_shipping_label:${input.idempotency_key}`, operation);
+    return reused ? { ...result, idempotent_replay: true } : result;
   }
 
   async getShipment(input, context) {
@@ -72,6 +190,13 @@ class ShipmentService {
   }
 
   async refundShipment(input, context) {
+    await this.confirmations?.requireConfirmed(input, {
+      action: "refund_shipment",
+      message: `You are about to void/refund shipment ${input.shipment_id}. Proceed?`,
+      details: { shipment_id: input.shipment_id },
+      typedConfirmation: "REFUND",
+    }, context);
+
     const shipment = await this.easypost.execute(
       "shipment.refund",
       (client) => client.Shipment.refund(input.shipment_id),
@@ -85,6 +210,13 @@ class ShipmentService {
   }
 
   async insureShipment(input, context) {
+    await this.confirmations?.requireConfirmed(input, {
+      action: "insure_shipment",
+      message: `You are about to add insurance for ${input.amount} to shipment ${input.shipment_id}. Proceed?`,
+      details: { shipment_id: input.shipment_id, amount: input.amount },
+      typedConfirmation: Number(input.amount) >= 500 ? "INSURE" : undefined,
+    }, context);
+
     const shipment = await this.easypost.execute(
       "shipment.insure",
       (client) => client.Shipment.insure(input.shipment_id, input.amount),

package/src/services/WorkflowStateStore.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+
+class WorkflowStateStore {
+  constructor({ ttlMs = 30 * 60 * 1000 } = {}) {
+    this.ttlMs = ttlMs;
+    this.entries = new Map();
+  }
+
+  _purgeExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.expiresAt <= now) this.entries.delete(key);
+    }
+  }
+
+  create({ toolName, input = {}, reason, correlationId }) {
+    this._purgeExpired();
+    const workflowId = `wf_${randomUUID()}`;
+    this.entries.set(workflowId, {
+      toolName,
+      input,
+      reason,
+      correlationId,
+      createdAt: new Date().toISOString(),
+      expiresAt: Date.now() + this.ttlMs,
+    });
+    return workflowId;
+  }
+
+  get(workflowId) {
+    if (!workflowId) return null;
+    this._purgeExpired();
+    return this.entries.get(workflowId) || null;
+  }
+
+  merge(workflowId, input = {}) {
+    const state = this.get(workflowId);
+    if (!state) return input;
+    return deepMerge(state.input, input);
+  }
+
+  update(workflowId, input) {
+    const state = this.get(workflowId);
+    if (!state) return;
+    this.entries.set(workflowId, {
+      ...state,
+      input,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepMerge(base, override) {
+  const output = { ...(isPlainObject(base) ? base : {}) };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (key === "workflow_id") continue;
+    if (isPlainObject(value) && isPlainObject(output[key])) {
+      output[key] = deepMerge(output[key], value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+export { WorkflowStateStore, deepMerge };

package/src/services/index.js

@@ -1,4 +1,9 @@
 import { EasyPostClient } from "../adapters/easypost/EasyPostClient.js";
+import { ResourceManager } from "../resources/ResourceManager.js";
+import { ConfirmationService } from "./ConfirmationService.js";
+import { ElicitationService } from "./ElicitationService.js";
+import { IdempotencyStore } from "./IdempotencyStore.js";
+import { WorkflowStateStore } from "./WorkflowStateStore.js";
 import { ShipmentService } from "./ShipmentService.js";
 import { AddressService } from "./AddressService.js";
 import { TrackingService } from "./TrackingService.js";
@@ -9,14 +14,24 @@ import { OrderService } from "./OrderService.js";
 
 function createServices() {
   const easypostClient = new EasyPostClient();
+  const resources = new ResourceManager(easypostClient);
+  const confirmations = new ConfirmationService();
+  const elicitation = new ElicitationService();
+  const idempotency = new IdempotencyStore();
+  const workflowState = new WorkflowStateStore();
 
   return {
-    shipments: new ShipmentService(easypostClient),
-    addresses: new AddressService(easypostClient),
+    resources,
+    confirmations,
+    elicitation,
+    idempotency,
+    workflowState,
+    shipments: new ShipmentService(easypostClient, { confirmations, elicitation, idempotency }),
+    addresses: new AddressService(easypostClient, { confirmations }),
     tracking: new TrackingService(easypostClient),
-    returns: new ReturnService(easypostClient),
-    pickups: new PickupService(easypostClient),
-    batches: new BatchService(easypostClient),
+    returns: new ReturnService(easypostClient, { confirmations, elicitation }),
+    pickups: new PickupService(easypostClient, { confirmations, idempotency }),
+    batches: new BatchService(easypostClient, { confirmations }),
     orders: new OrderService(easypostClient),
   };
 }

package/src/tools/ToolDefinition.js

@@ -1,13 +1,15 @@
 import { toInputSchema, validateInput } from "../validators/validate.js";
+import { riskForTool } from "../constants/toolRisk.js";
 
 class ToolDefinition {
-  constructor({ name, title, description, category, schema, handler, annotations = {} }) {
+  constructor({ name, title, description, category, schema, handler, risk, annotations = {} }) {
     this.name = name;
     this.title = title;
     this.description = description;
     this.category = category;
     this.schema = schema;
     this.handler = handler;
+    this.risk = risk || riskForTool(name);
     this.annotations = annotations;
   }
 
@@ -19,13 +21,22 @@ class ToolDefinition {
       inputSchema: toInputSchema(this.schema, this.name),
       annotations: {
         category: this.category,
+        risk: this.risk,
         ...this.annotations,
       },
     };
   }
 
   async execute(args, context) {
-    const input = validateInput(this.schema, args);
+    if (context?.pipeline) {
+      return context.pipeline.run(this, args, context);
+    }
+
+    const input = validateInput(this.schema, args, {
+      resourceManager: context?.resources,
+      toolName: this.name,
+      risk: this.risk,
+    });
     return this.handler(input, context);
   }
 }

package/src/tools/definitions/pickups.js

@@ -8,7 +8,7 @@ function pickupTools(services) {
       name: "schedule_pickup",
       title: "Schedule Pickup",
       category: categories.PICKUPS,
-      description: "Schedule a carrier pickup for one or more shipments.",
+      description: "Create a carrier pickup request for one or more shipments. Requires confirm=true and never auto-buys a pickup rate.",
       schema: schedulePickupSchema,
       handler: (input, context) => services.pickups.schedulePickup(input, context),
     }),
@@ -16,7 +16,7 @@ function pickupTools(services) {
       name: "cancel_pickup",
       title: "Cancel Pickup",
       category: categories.PICKUPS,
-      description: "Cancel a scheduled carrier pickup.",
+      description: "Cancel a scheduled carrier pickup. Requires confirm=true.",
       schema: cancelPickupSchema,
       handler: (input, context) => services.pickups.cancelPickup(input, context),
     }),

package/src/tools/definitions/resources.js

@@ -0,0 +1,59 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { TOOL_RISK } from "../../constants/toolRisk.js";
+import { listResourcesSchema, validateCarrierSchema, validateServiceSchema } from "../../schemas/resourceSchemas.js";
+
+function resourceTools(services) {
+  return [
+    new ToolDefinition({
+      name: "get_carriers",
+      title: "Get Carriers",
+      category: categories.SHIPMENTS,
+      risk: TOOL_RISK.LOW,
+      description: "Return compact authoritative carrier metadata from the server-side resource cache.",
+      schema: listResourcesSchema,
+      handler: async (input, context) => {
+        if (input.refresh) await services.resources.refresh(context);
+        return {
+          ok: true,
+          carriers: services.resources.getCarriers(),
+          resource_context: services.resources.getOperationalContext(),
+        };
+      },
+    }),
+    new ToolDefinition({
+      name: "validate_carrier",
+      title: "Validate Carrier",
+      category: categories.SHIPMENTS,
+      risk: TOOL_RISK.LOW,
+      description: "Validate a carrier with exact matching. Fuzzy matches are returned only as suggestions.",
+      schema: validateCarrierSchema,
+      handler: async (input) => {
+        const result = services.resources.validateCarrier(input.carrier);
+        return {
+          ok: result.valid,
+          validation: result,
+          clarification_required: !result.valid && result.suggestions.length > 0,
+        };
+      },
+    }),
+    new ToolDefinition({
+      name: "validate_service",
+      title: "Validate Service",
+      category: categories.SHIPMENTS,
+      risk: TOOL_RISK.LOW,
+      description: "Validate an exact carrier/service combination against cached authoritative resources.",
+      schema: validateServiceSchema,
+      handler: async (input) => {
+        const result = services.resources.validateService(input.carrier, input.service);
+        return {
+          ok: result.valid,
+          validation: result,
+          clarification_required: !result.valid && result.suggestions.length > 0,
+        };
+      },
+    }),
+  ];
+}
+
+export { resourceTools };

package/src/tools/definitions/shipments.js

@@ -16,7 +16,7 @@ function shipmentTools(services) {
       name: "buy_shipping_label",
       title: "Buy Shipping Label",
       category: categories.SHIPMENTS,
-      description: "Buy a shipping label for an existing shipment using a rate id or carrier/service pair.",
+      description: "Buy a shipping label for an existing shipment using client elicitation, exact returned rate_id, or numbered rate_option. Requires confirmation and idempotency_key.",
       schema: schemas.buyShippingLabelSchema,
       handler: (input, context) => services.shipments.buyShippingLabel(input, context),
     }),
@@ -40,7 +40,7 @@ function shipmentTools(services) {
       name: "cancel_shipment",
       title: "Cancel Shipment",
       category: categories.SHIPMENTS,
-      description: "Cancel or void a shipment when supported by the carrier. Uses EasyPost refund semantics for purchased labels.",
+      description: "Cancel or void a shipment when supported by the carrier. Requires confirm=true and uses EasyPost refund semantics for purchased labels.",
       schema: schemas.cancelShipmentSchema,
       handler: (input, context) => services.shipments.cancelShipment(input, context),
     }),
@@ -48,7 +48,7 @@ function shipmentTools(services) {
       name: "refund_shipment",
       title: "Refund Shipment",
       category: categories.SHIPMENTS,
-      description: "Request a refund for a purchased shipment label.",
+      description: "Request a refund for a purchased shipment label. Requires confirm=true.",
       schema: schemas.refundShipmentSchema,
       handler: (input, context) => services.shipments.refundShipment(input, context),
     }),

package/src/tools/index.js

@@ -6,6 +6,7 @@ import { returnTools } from "./definitions/returns.js";
 import { pickupTools } from "./definitions/pickups.js";
 import { batchTools } from "./definitions/batches.js";
 import { orderTools } from "./definitions/orders.js";
+import { resourceTools } from "./definitions/resources.js";
 
 function createToolRegistry(services) {
   const registry = new ToolRegistry();
@@ -17,6 +18,7 @@ function createToolRegistry(services) {
     ...pickupTools(services),
     ...batchTools(services),
     ...orderTools(services),
+    ...resourceTools(services),
   ]);
   return registry;
 }

package/src/validators/antiHallucination.js

@@ -4,17 +4,31 @@ const PLACEHOLDER_PATTERNS = [
   /\b(unknown|n\/a|na|null|none|tbd|todo|test|sample|example|placeholder)\b/i,
   /\b(123 main|main street|fake street|any street|your address|shipping address)\b/i,
   /\b(john doe|jane doe|acme|foo|bar)\b/i,
-  /^(.)\1{4,}$/,
+  /^(.)\1{4,}$/i,
+  /^(0{6,}|1{6,}|9{6,}|123456\d*|987654\d*)$/i,
+  /\b(lorem ipsum|asdf|qwerty|abcdef)\b/i,
 ];
 
+function issue(path, code, message, confidence = 0.2, suggestions = []) {
+  return { path, code, message, confidence, suggestions };
+}
+
 function inspectString(path, value, issues) {
   if (!value.trim()) {
-    issues.push({ path, reason: "Empty string" });
+    issues.push(issue(path, "EMPTY_STRING", "Empty string", 0));
     return;
   }
 
   if (PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(value))) {
-    issues.push({ path, reason: "Looks like autogenerated placeholder data" });
+    issues.push(issue(path, "SUSPICIOUS_PLACEHOLDER", "Looks like autogenerated placeholder data", 0.1));
+  }
+
+  if (/(.)\1{5,}/i.test(value.replace(/\s+/g, ""))) {
+    issues.push(issue(path, "REPEATED_CHARACTER_GARBAGE", "Contains repeated-character garbage", 0.1));
+  }
+
+  if (value.length > 8 && /^[^a-z0-9]+$/i.test(value)) {
+    issues.push(issue(path, "NON_SEMANTIC_STRING", "String contains no semantic content", 0.1));
   }
 }
 
@@ -34,16 +48,103 @@ function inspectObject(value, path, issues) {
   }
 }
 
-function assertNotHallucinated(input) {
+function inspectResources(input, resourceManager, issues) {
+  if (!resourceManager || !input || typeof input !== "object") return;
+
+  inspectResourceFields(input, "", resourceManager, issues);
+
+  if (Array.isArray(input.carrier_accounts)) {
+    for (const [index, carrierAccount] of input.carrier_accounts.entries()) {
+      const result = resourceManager.validateCarrierAccount(carrierAccount);
+      if (!result.valid) {
+        issues.push(issue(`carrier_accounts[${index}]`, "UNKNOWN_CARRIER_ACCOUNT", `Unknown carrier account: ${carrierAccount}`, 0, result.suggestions));
+      }
+    }
+  }
+
+}
+
+function inspectResourceFields(value, path, resourceManager, issues) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => inspectResourceFields(item, `${path}[${index}]`, resourceManager, issues));
+    return;
+  }
+
+  if (!value || typeof value !== "object") return;
+
+  if (value.country) {
+    const result = resourceManager.validateCountry(value.country);
+    if (!result.valid) {
+      issues.push(issue(path ? `${path}.country` : "country", "UNKNOWN_COUNTRY", `Unknown country: ${value.country}`, 0, result.suggestions));
+    }
+  }
+
+  if (value.country && value.state) {
+    const result = resourceManager.validateState(value.country, value.state);
+    if (!result.valid) {
+      issues.push(issue(path ? `${path}.state` : "state", "UNKNOWN_STATE", `Unknown state/province for ${value.country}: ${value.state}`, 0, result.suggestions));
+    }
+  }
+
+  if (value.payment_method) {
+    const result = resourceManager.validatePaymentMethod(value.payment_method);
+    if (!result.valid) {
+      issues.push(issue(path ? `${path}.payment_method` : "payment_method", "UNKNOWN_PAYMENT_METHOD", `Unknown payment method: ${value.payment_method}`, 0, result.suggestions));
+    }
+  }
+
+  if (value.predefined_package) {
+    const result = resourceManager.validatePackageType(value.predefined_package);
+    if (!result.valid) {
+      issues.push(issue(path ? `${path}.predefined_package` : "predefined_package", "UNKNOWN_PACKAGE_TYPE", `Unknown package type: ${value.predefined_package}`, 0, result.suggestions));
+    }
+  }
+
+  if (value.carrier) {
+    const result = resourceManager.validateCarrier(value.carrier);
+    if (!result.valid) {
+      issues.push(issue(path ? `${path}.carrier` : "carrier", "UNKNOWN_CARRIER", `Unsupported carrier: ${value.carrier}`, 0, result.suggestions));
+    } else if (value.service) {
+      const serviceResult = resourceManager.validateService(value.carrier, value.service);
+      if (!serviceResult.valid) {
+        issues.push(issue(path ? `${path}.service` : "service", "UNSUPPORTED_SERVICE_FOR_CARRIER", serviceResult.issues?.[0]?.message || "Unsupported carrier/service combination", 0, serviceResult.suggestions));
+      }
+    }
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    inspectResourceFields(nested, path ? `${path}.${key}` : key, resourceManager, issues);
+  }
+}
+
+function validateAntiHallucination(input, options = {}) {
   const issues = [];
   inspectObject(input, "", issues);
+  if (!["validate_carrier", "validate_service"].includes(options.toolName)) {
+    inspectResources(input, options.resourceManager, issues);
+  }
+
+  const confidence = issues.length
+    ? Math.min(...issues.map((item) => item.confidence ?? 0.2))
+    : 1;
+
+  return {
+    valid: issues.length === 0,
+    confidence,
+    issues,
+    suggestions: issues.flatMap((item) => item.suggestions || []),
+  };
+}
+
+function assertNotHallucinated(input, options = {}) {
+  const result = validateAntiHallucination(input, options);
 
-  if (issues.length) {
+  if (!result.valid) {
     throw new AntiHallucinationError(
-      "Input appears to contain placeholder or AI-generated shipping data. Provide real, verified shipment details.",
-      issues
+      "Input appears unsupported, ambiguous, or AI-generated. Provide exact values from verified resources.",
+      result
     );
   }
 }
 
-export { assertNotHallucinated };
+export { assertNotHallucinated, validateAntiHallucination };

package/src/validators/validate.js

@@ -3,7 +3,7 @@ import { ValidationError } from "../errors/AppError.js";
 import { sanitizeInput } from "../utils/sanitize.js";
 import { assertNotHallucinated } from "./antiHallucination.js";
 
-function validateInput(schema, input) {
+function validateInput(schema, input, options = {}) {
   const sanitized = sanitizeInput(input || {});
   const result = schema.safeParse(sanitized);
 
@@ -11,7 +11,7 @@ function validateInput(schema, input) {
     throw new ValidationError("Tool input validation failed", result.error.issues);
   }
 
-  assertNotHallucinated(result.data);
+  assertNotHallucinated(result.data, options);
   return result.data;
 }