easypost-mcp 2.1.0

package/src/services/ShipmentService.js

@@ -0,0 +1,97 @@
+import { mapShipment, mapRate, mapCollection } from "../adapters/easypost/responseMappers.js";
+import { NotFoundError } from "../errors/AppError.js";
+
+class ShipmentService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async createShipment(input, context) {
+    const shipment = await this.easypost.execute(
+      "shipment.create",
+      (client) => client.Shipment.create({
+        from_address: input.from_address,
+        to_address: input.to_address,
+        parcel: input.parcel,
+        carrier_accounts: input.carrier_accounts,
+        customs_info: input.customs_info,
+        options: input.options,
+        reference: input.reference,
+      }),
+      context
+    );
+
+    return { ok: true, shipment: mapShipment(shipment), rates: (shipment.rates || []).map(mapRate) };
+  }
+
+  async buyShippingLabel(input, context) {
+    const shipment = await this.easypost.execute(
+      "shipment.retrieve",
+      (client) => client.Shipment.retrieve(input.shipment_id),
+      context
+    );
+
+    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 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) };
+  }
+
+  async getShipment(input, context) {
+    const shipment = await this.easypost.execute(
+      "shipment.retrieve",
+      (client) => client.Shipment.retrieve(input.shipment_id),
+      context
+    );
+    return { ok: true, shipment: mapShipment(shipment) };
+  }
+
+  async listShipments(input, context) {
+    const collection = await this.easypost.execute(
+      "shipment.list",
+      (client) => client.Shipment.all(input),
+      context
+    );
+    return { ok: true, ...mapCollection(collection, mapShipment) };
+  }
+
+  async estimateRates(input, context) {
+    const result = await this.createShipment(input, context);
+    return { ok: true, shipment_id: result.shipment.id, rates: result.rates };
+  }
+
+  async refundShipment(input, context) {
+    const shipment = await this.easypost.execute(
+      "shipment.refund",
+      (client) => client.Shipment.refund(input.shipment_id),
+      context
+    );
+    return { ok: true, shipment: mapShipment(shipment), refund_status: shipment.refund_status };
+  }
+
+  async cancelShipment(input, context) {
+    return this.refundShipment(input, context);
+  }
+
+  async insureShipment(input, context) {
+    const shipment = await this.easypost.execute(
+      "shipment.insure",
+      (client) => client.Shipment.insure(input.shipment_id, input.amount),
+      context
+    );
+    return { ok: true, shipment: mapShipment(shipment), insured_amount: input.amount };
+  }
+}
+
+export { ShipmentService };

package/src/services/TrackingService.js

@@ -0,0 +1,34 @@
+import { mapTracker } from "../adapters/easypost/responseMappers.js";
+
+class TrackingService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async trackPackage(input, context) {
+    const tracker = await this.easypost.execute(
+      "tracker.create",
+      (client) => client.Tracker.create({
+        tracking_code: input.tracking_code,
+        carrier: input.carrier,
+      }),
+      context
+    );
+
+    return { ok: true, tracker: mapTracker(tracker) };
+  }
+
+  async getTrackingHistory(input, context) {
+    const tracker = await this.easypost.execute(
+      "tracker.retrieve",
+      (client) => input.tracker_id
+        ? client.Tracker.retrieve(input.tracker_id)
+        : client.Tracker.create({ tracking_code: input.tracking_code, carrier: input.carrier }),
+      context
+    );
+
+    return { ok: true, tracker: mapTracker(tracker), history: mapTracker(tracker)?.tracking_details || [] };
+  }
+}
+
+export { TrackingService };

package/src/services/index.js

@@ -0,0 +1,24 @@
+import { EasyPostClient } from "../adapters/easypost/EasyPostClient.js";
+import { ShipmentService } from "./ShipmentService.js";
+import { AddressService } from "./AddressService.js";
+import { TrackingService } from "./TrackingService.js";
+import { ReturnService } from "./ReturnService.js";
+import { PickupService } from "./PickupService.js";
+import { BatchService } from "./BatchService.js";
+import { OrderService } from "./OrderService.js";
+
+function createServices() {
+  const easypostClient = new EasyPostClient();
+
+  return {
+    shipments: new ShipmentService(easypostClient),
+    addresses: new AddressService(easypostClient),
+    tracking: new TrackingService(easypostClient),
+    returns: new ReturnService(easypostClient),
+    pickups: new PickupService(easypostClient),
+    batches: new BatchService(easypostClient),
+    orders: new OrderService(easypostClient),
+  };
+}
+
+export { createServices };

package/src/tools/ToolDefinition.js

@@ -0,0 +1,33 @@
+import { toInputSchema, validateInput } from "../validators/validate.js";
+
+class ToolDefinition {
+  constructor({ name, title, description, category, schema, handler, annotations = {} }) {
+    this.name = name;
+    this.title = title;
+    this.description = description;
+    this.category = category;
+    this.schema = schema;
+    this.handler = handler;
+    this.annotations = annotations;
+  }
+
+  toMcpTool() {
+    return {
+      name: this.name,
+      title: this.title,
+      description: this.description,
+      inputSchema: toInputSchema(this.schema, this.name),
+      annotations: {
+        category: this.category,
+        ...this.annotations,
+      },
+    };
+  }
+
+  async execute(args, context) {
+    const input = validateInput(this.schema, args);
+    return this.handler(input, context);
+  }
+}
+
+export { ToolDefinition };

package/src/tools/definitions/address.js

@@ -0,0 +1,26 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { verifyAddressSchema, createAddressSchema } from "../../schemas/addressSchemas.js";
+
+function addressTools(services) {
+  return [
+    new ToolDefinition({
+      name: "verify_address",
+      title: "Verify Address",
+      category: categories.ADDRESS,
+      description: "Verify a real shipping address and return normalized verification status and messages.",
+      schema: verifyAddressSchema,
+      handler: (input, context) => services.addresses.verifyAddress(input, context),
+    }),
+    new ToolDefinition({
+      name: "create_address",
+      title: "Create Address",
+      category: categories.ADDRESS,
+      description: "Create an EasyPost address object, optionally requesting provider verification.",
+      schema: createAddressSchema,
+      handler: (input, context) => services.addresses.createAddress(input, context),
+    }),
+  ];
+}
+
+export { addressTools };

package/src/tools/definitions/batches.js

@@ -0,0 +1,34 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { createBatchSchema, buyBatchSchema, batchStatusSchema } from "../../schemas/batchSchemas.js";
+
+function batchTools(services) {
+  return [
+    new ToolDefinition({
+      name: "create_batch",
+      title: "Create Batch",
+      category: categories.BATCHES,
+      description: "Create a batch from multiple shipments.",
+      schema: createBatchSchema,
+      handler: (input, context) => services.batches.createBatch(input, context),
+    }),
+    new ToolDefinition({
+      name: "buy_batch",
+      title: "Buy Batch",
+      category: categories.BATCHES,
+      description: "Buy labels for all purchasable shipments in a batch.",
+      schema: buyBatchSchema,
+      handler: (input, context) => services.batches.buyBatch(input, context),
+    }),
+    new ToolDefinition({
+      name: "batch_status",
+      title: "Batch Status",
+      category: categories.BATCHES,
+      description: "Get current batch processing and purchase status.",
+      schema: batchStatusSchema,
+      handler: (input, context) => services.batches.batchStatus(input, context),
+    }),
+  ];
+}
+
+export { batchTools };

package/src/tools/definitions/orders.js

@@ -0,0 +1,26 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { createOrderSchema, getOrderSchema } from "../../schemas/orderSchemas.js";
+
+function orderTools(services) {
+  return [
+    new ToolDefinition({
+      name: "create_order",
+      title: "Create Order",
+      category: categories.ORDERS,
+      description: "Create an EasyPost order with multiple shipments using business order fields.",
+      schema: createOrderSchema,
+      handler: (input, context) => services.orders.createOrder(input, context),
+    }),
+    new ToolDefinition({
+      name: "get_order",
+      title: "Get Order",
+      category: categories.ORDERS,
+      description: "Retrieve an order by id.",
+      schema: getOrderSchema,
+      handler: (input, context) => services.orders.getOrder(input, context),
+    }),
+  ];
+}
+
+export { orderTools };

package/src/tools/definitions/pickups.js

@@ -0,0 +1,26 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { schedulePickupSchema, cancelPickupSchema } from "../../schemas/pickupSchemas.js";
+
+function pickupTools(services) {
+  return [
+    new ToolDefinition({
+      name: "schedule_pickup",
+      title: "Schedule Pickup",
+      category: categories.PICKUPS,
+      description: "Schedule a carrier pickup for one or more shipments.",
+      schema: schedulePickupSchema,
+      handler: (input, context) => services.pickups.schedulePickup(input, context),
+    }),
+    new ToolDefinition({
+      name: "cancel_pickup",
+      title: "Cancel Pickup",
+      category: categories.PICKUPS,
+      description: "Cancel a scheduled carrier pickup.",
+      schema: cancelPickupSchema,
+      handler: (input, context) => services.pickups.cancelPickup(input, context),
+    }),
+  ];
+}
+
+export { pickupTools };

package/src/tools/definitions/returns.js

@@ -0,0 +1,18 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { createReturnLabelSchema } from "../../schemas/returnSchemas.js";
+
+function returnTools(services) {
+  return [
+    new ToolDefinition({
+      name: "create_return_label",
+      title: "Create Return Label",
+      category: categories.RETURNS,
+      description: "Create and optionally buy a return label using business return fields.",
+      schema: createReturnLabelSchema,
+      handler: (input, context) => services.returns.createReturnLabel(input, context),
+    }),
+  ];
+}
+
+export { returnTools };

package/src/tools/definitions/shipments.js

@@ -0,0 +1,74 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import * as schemas from "../../schemas/shipmentSchemas.js";
+
+function shipmentTools(services) {
+  return [
+    new ToolDefinition({
+      name: "create_shipment",
+      title: "Create Shipment",
+      category: categories.SHIPMENTS,
+      description: "Create an EasyPost shipment and return normalized shipment details plus available carrier rates. Does not buy a label.",
+      schema: schemas.createShipmentSchema,
+      handler: (input, context) => services.shipments.createShipment(input, context),
+    }),
+    new ToolDefinition({
+      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.",
+      schema: schemas.buyShippingLabelSchema,
+      handler: (input, context) => services.shipments.buyShippingLabel(input, context),
+    }),
+    new ToolDefinition({
+      name: "get_shipment",
+      title: "Get Shipment",
+      category: categories.SHIPMENTS,
+      description: "Retrieve a shipment by id with normalized label, rate, parcel, and tracking fields.",
+      schema: schemas.getShipmentSchema,
+      handler: (input, context) => services.shipments.getShipment(input, context),
+    }),
+    new ToolDefinition({
+      name: "list_shipments",
+      title: "List Shipments",
+      category: categories.SHIPMENTS,
+      description: "List shipments with bounded pagination.",
+      schema: schemas.listShipmentsSchema,
+      handler: (input, context) => services.shipments.listShipments(input, context),
+    }),
+    new ToolDefinition({
+      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.",
+      schema: schemas.cancelShipmentSchema,
+      handler: (input, context) => services.shipments.cancelShipment(input, context),
+    }),
+    new ToolDefinition({
+      name: "refund_shipment",
+      title: "Refund Shipment",
+      category: categories.SHIPMENTS,
+      description: "Request a refund for a purchased shipment label.",
+      schema: schemas.refundShipmentSchema,
+      handler: (input, context) => services.shipments.refundShipment(input, context),
+    }),
+    new ToolDefinition({
+      name: "estimate_rates",
+      title: "Estimate Rates",
+      category: categories.SHIPMENTS,
+      description: "Create an unrated purchase-free shipment quote and return available carrier rates.",
+      schema: schemas.estimateRatesSchema,
+      handler: (input, context) => services.shipments.estimateRates(input, context),
+    }),
+    new ToolDefinition({
+      name: "insure_shipment",
+      title: "Insure Shipment",
+      category: categories.INSURANCE,
+      description: "Add insurance to an existing shipment.",
+      schema: schemas.insureShipmentSchema,
+      handler: (input, context) => services.shipments.insureShipment(input, context),
+    }),
+  ];
+}
+
+export { shipmentTools };

package/src/tools/definitions/tracking.js

@@ -0,0 +1,26 @@
+import { ToolDefinition } from "../ToolDefinition.js";
+import categories from "../../constants/toolCategories.js";
+import { trackPackageSchema, getTrackingHistorySchema } from "../../schemas/trackingSchemas.js";
+
+function trackingTools(services) {
+  return [
+    new ToolDefinition({
+      name: "track_package",
+      title: "Track Package",
+      category: categories.TRACKING,
+      description: "Create or refresh tracking for a package using a tracking code and optional carrier.",
+      schema: trackPackageSchema,
+      handler: (input, context) => services.tracking.trackPackage(input, context),
+    }),
+    new ToolDefinition({
+      name: "get_tracking_history",
+      title: "Get Tracking History",
+      category: categories.TRACKING,
+      description: "Return normalized tracking events by tracker id or tracking code.",
+      schema: getTrackingHistorySchema,
+      handler: (input, context) => services.tracking.getTrackingHistory(input, context),
+    }),
+  ];
+}
+
+export { trackingTools };

package/src/tools/index.js

@@ -0,0 +1,24 @@
+import { ToolRegistry } from "./registry.js";
+import { shipmentTools } from "./definitions/shipments.js";
+import { addressTools } from "./definitions/address.js";
+import { trackingTools } from "./definitions/tracking.js";
+import { returnTools } from "./definitions/returns.js";
+import { pickupTools } from "./definitions/pickups.js";
+import { batchTools } from "./definitions/batches.js";
+import { orderTools } from "./definitions/orders.js";
+
+function createToolRegistry(services) {
+  const registry = new ToolRegistry();
+  registry.registerMany([
+    ...shipmentTools(services),
+    ...trackingTools(services),
+    ...addressTools(services),
+    ...returnTools(services),
+    ...pickupTools(services),
+    ...batchTools(services),
+    ...orderTools(services),
+  ]);
+  return registry;
+}
+
+export { createToolRegistry };

package/src/tools/registry.js

@@ -0,0 +1,37 @@
+import { AppError } from "../errors/AppError.js";
+
+class ToolRegistry {
+  constructor() {
+    this.tools = new Map();
+  }
+
+  register(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Duplicate tool registered: ${tool.name}`);
+    }
+
+    this.tools.set(tool.name, tool);
+  }
+
+  registerMany(tools) {
+    tools.forEach((tool) => this.register(tool));
+  }
+
+  list() {
+    return Array.from(this.tools.values()).map((tool) => tool.toMcpTool());
+  }
+
+  get(name) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new AppError(`Unknown tool: ${name}`, {
+        code: "UNKNOWN_TOOL",
+        statusCode: 404,
+        safeMessage: `Unknown tool: ${name}`,
+      });
+    }
+    return tool;
+  }
+}
+
+export { ToolRegistry };

package/src/utils/correlation.js

@@ -0,0 +1,7 @@
+import { randomUUID } from "node:crypto";
+
+function createCorrelationId(prefix = "mcp") {
+  return `${prefix}_${randomUUID()}`;
+}
+
+export { createCorrelationId };

package/src/utils/sanitize.js

@@ -0,0 +1,53 @@
+const SECRET_KEYS = new Set([
+  "authorization",
+  "api_key",
+  "apiKey",
+  "token",
+  "password",
+  "EASYPOST_API_KEY",
+]);
+
+const PII_KEYS = new Set([
+  "street1",
+  "street2",
+  "name",
+  "company",
+  "phone",
+  "email",
+]);
+
+function maskValue(value) {
+  if (typeof value !== "string") return value;
+  if (value.length <= 4) return "***";
+  return `${value.slice(0, 2)}***${value.slice(-2)}`;
+}
+
+function sanitizeString(value) {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function sanitizeInput(value) {
+  if (Array.isArray(value)) return value.map(sanitizeInput);
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" ? sanitizeString(value) : value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, nested]) => [key, sanitizeInput(nested)])
+  );
+}
+
+function redactForLogs(value) {
+  if (Array.isArray(value)) return value.map(redactForLogs);
+  if (!value || typeof value !== "object") return value;
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, nested]) => {
+      if (SECRET_KEYS.has(key)) return [key, "***REDACTED***"];
+      if (PII_KEYS.has(key)) return [key, maskValue(nested)];
+      return [key, redactForLogs(nested)];
+    })
+  );
+}
+
+export { sanitizeInput, redactForLogs };

package/src/validators/antiHallucination.js

@@ -0,0 +1,49 @@
+import { AntiHallucinationError } from "../errors/AppError.js";
+
+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,}$/,
+];
+
+function inspectString(path, value, issues) {
+  if (!value.trim()) {
+    issues.push({ path, reason: "Empty string" });
+    return;
+  }
+
+  if (PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(value))) {
+    issues.push({ path, reason: "Looks like autogenerated placeholder data" });
+  }
+}
+
+function inspectObject(value, path, issues) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => inspectObject(item, `${path}[${index}]`, issues));
+    return;
+  }
+
+  if (!value || typeof value !== "object") {
+    if (typeof value === "string") inspectString(path, value, issues);
+    return;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    inspectObject(nested, path ? `${path}.${key}` : key, issues);
+  }
+}
+
+function assertNotHallucinated(input) {
+  const issues = [];
+  inspectObject(input, "", issues);
+
+  if (issues.length) {
+    throw new AntiHallucinationError(
+      "Input appears to contain placeholder or AI-generated shipping data. Provide real, verified shipment details.",
+      issues
+    );
+  }
+}
+
+export { assertNotHallucinated };

package/src/validators/validate.js

@@ -0,0 +1,28 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { ValidationError } from "../errors/AppError.js";
+import { sanitizeInput } from "../utils/sanitize.js";
+import { assertNotHallucinated } from "./antiHallucination.js";
+
+function validateInput(schema, input) {
+  const sanitized = sanitizeInput(input || {});
+  const result = schema.safeParse(sanitized);
+
+  if (!result.success) {
+    throw new ValidationError("Tool input validation failed", result.error.issues);
+  }
+
+  assertNotHallucinated(result.data);
+  return result.data;
+}
+
+function toInputSchema(schema, name) {
+  const jsonSchema = zodToJsonSchema(schema, {
+    name,
+    target: "jsonSchema7",
+    $refStrategy: "none",
+  });
+
+  return jsonSchema.definitions?.[name] || jsonSchema;
+}
+
+export { validateInput, toInputSchema };