easypost-mcp 2.1.0

package/src/middleware/errorHandler.js

@@ -0,0 +1,49 @@
+import { AppError } from "../errors/AppError.js";
+import { getLoggerSync } from "../logging/logger.js";
+
+function toSafeError(error, correlationId) {
+  if (error instanceof AppError) {
+    return {
+      ok: false,
+      error: {
+        code: error.code,
+        message: error.safeMessage,
+        details: error.details,
+        retryable: error.retryable,
+        correlation_id: correlationId,
+      },
+    };
+  }
+
+  getLoggerSync().error(
+    { err: { message: error.message, stack: error.stack }, correlationId },
+    "Unhandled tool error"
+  );
+
+  return {
+    ok: false,
+    error: {
+      code: "INTERNAL_ERROR",
+      message: "An unexpected server error occurred",
+      retryable: false,
+      correlation_id: correlationId,
+    },
+  };
+}
+
+async function withErrorHandling(context, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    context.logger?.error(
+      {
+        err: { name: error.name, message: error.message, code: error.code },
+        correlationId: context.correlationId,
+      },
+      "Tool execution failed"
+    );
+    return toSafeError(error, context.correlationId);
+  }
+}
+
+export { toSafeError, withErrorHandling };

package/src/middleware/rateLimiter.js

@@ -0,0 +1,29 @@
+import { AppError } from "../errors/AppError.js";
+
+function createInMemoryRateLimiter({ limit, windowMs }) {
+  const buckets = new Map();
+
+  return {
+    consume(key) {
+      const now = Date.now();
+      const bucket = buckets.get(key);
+
+      if (!bucket || bucket.resetAt <= now) {
+        buckets.set(key, { count: 1, resetAt: now + windowMs });
+        return;
+      }
+
+      bucket.count += 1;
+      if (bucket.count > limit) {
+        throw new AppError("MCP rate limit exceeded", {
+          code: "RATE_LIMITED",
+          statusCode: 429,
+          retryable: true,
+          details: { reset_at: new Date(bucket.resetAt).toISOString() },
+        });
+      }
+    },
+  };
+}
+
+export { createInMemoryRateLimiter };

package/src/schemas/addressSchemas.js

@@ -0,0 +1,27 @@
+import { z, nonEmptyString, optionalNonEmptyString } from "./commonSchemas.js";
+
+const addressSchema = z.object({
+  name: optionalNonEmptyString,
+  company: optionalNonEmptyString,
+  street1: nonEmptyString,
+  street2: optionalNonEmptyString,
+  city: nonEmptyString,
+  state: nonEmptyString,
+  zip: nonEmptyString,
+  country: z.string().trim().min(2).max(2).transform((value) => value.toUpperCase()),
+  phone: optionalNonEmptyString,
+  email: z.string().trim().email().optional(),
+  residential: z.boolean().optional(),
+}).strict();
+
+const verifyAddressSchema = z.object({
+  address: addressSchema,
+  verifications: z.array(z.enum(["delivery", "zip4"])).default(["delivery"]),
+}).strict();
+
+const createAddressSchema = z.object({
+  address: addressSchema,
+  verify: z.boolean().default(false),
+}).strict();
+
+export { addressSchema, verifyAddressSchema, createAddressSchema };

package/src/schemas/batchSchemas.js

@@ -0,0 +1,24 @@
+import { z, easypostId } from "./commonSchemas.js";
+import { createShipmentSchema } from "./shipmentSchemas.js";
+
+const batchShipmentCreateSchema = createShipmentSchema.extend({
+  carrier: z.string().trim().min(1).optional(),
+  service: z.string().trim().min(1).optional(),
+});
+
+const batchShipmentSchema = z.union([
+  batchShipmentCreateSchema,
+  z.object({ shipment_id: easypostId }).strict(),
+]);
+
+const createBatchSchema = z.object({
+  shipments: z.array(batchShipmentSchema).min(1).max(100),
+}).strict();
+
+const buyBatchSchema = z.object({
+  batch_id: easypostId,
+}).strict();
+
+const batchStatusSchema = buyBatchSchema;
+
+export { createBatchSchema, buyBatchSchema, batchStatusSchema };

package/src/schemas/commonSchemas.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().trim().min(1).max(255);
+const optionalNonEmptyString = nonEmptyString.optional();
+const easypostId = z.string().trim().regex(/^[a-z]+_[A-Za-z0-9]+$/, "Invalid EasyPost id format");
+
+const currencyAmount = z.union([z.string().trim().regex(/^\d+(\.\d{1,2})?$/), z.number().nonnegative()]);
+
+const paginationSchema = z.object({
+  page_size: z.number().int().min(1).max(100).optional(),
+  before_id: z.string().trim().optional(),
+  after_id: z.string().trim().optional(),
+}).strict();
+
+export { z, nonEmptyString, optionalNonEmptyString, easypostId, currencyAmount, paginationSchema };

package/src/schemas/orderSchemas.js

@@ -0,0 +1,15 @@
+import { z, easypostId } from "./commonSchemas.js";
+import { addressSchema } from "./addressSchemas.js";
+import { parcelSchema } from "./parcelSchemas.js";
+
+const createOrderSchema = z.object({
+  from_address: addressSchema,
+  to_address: addressSchema,
+  shipments: z.array(z.object({ parcel: parcelSchema }).strict()).min(1).max(100),
+}).strict();
+
+const getOrderSchema = z.object({
+  order_id: easypostId,
+}).strict();
+
+export { createOrderSchema, getOrderSchema };

package/src/schemas/parcelSchemas.js

@@ -0,0 +1,13 @@
+import { z, optionalNonEmptyString } from "./commonSchemas.js";
+
+const parcelSchema = z.object({
+  length: z.number().positive().max(120),
+  width: z.number().positive().max(120),
+  height: z.number().positive().max(120),
+  weight: z.number().positive().max(1120),
+  predefined_package: optionalNonEmptyString,
+}).strict().refine((parcel) => parcel.length * parcel.width * parcel.height > 0, {
+  message: "Parcel dimensions must be greater than zero",
+});
+
+export { parcelSchema };

package/src/schemas/pickupSchemas.js

@@ -0,0 +1,17 @@
+import { z, easypostId, nonEmptyString } from "./commonSchemas.js";
+import { addressSchema } from "./addressSchemas.js";
+
+const schedulePickupSchema = z.object({
+  shipment_ids: z.array(easypostId).min(1),
+  address: addressSchema,
+  min_datetime: nonEmptyString,
+  max_datetime: nonEmptyString,
+  instructions: z.string().trim().max(500).optional(),
+  carrier_accounts: z.array(nonEmptyString).optional(),
+}).strict();
+
+const cancelPickupSchema = z.object({
+  pickup_id: easypostId,
+}).strict();
+
+export { schedulePickupSchema, cancelPickupSchema };

package/src/schemas/returnSchemas.js

@@ -0,0 +1,14 @@
+import { z, easypostId } from "./commonSchemas.js";
+import { addressSchema } from "./addressSchemas.js";
+import { parcelSchema } from "./parcelSchemas.js";
+
+const createReturnLabelSchema = z.object({
+  original_shipment_id: easypostId.optional(),
+  from_address: addressSchema,
+  to_address: addressSchema,
+  parcel: parcelSchema,
+  carrier: z.string().trim().optional(),
+  service: z.string().trim().optional(),
+}).strict();
+
+export { createReturnLabelSchema };

package/src/schemas/shipmentSchemas.js

@@ -0,0 +1,56 @@
+import { z, easypostId, nonEmptyString, paginationSchema, currencyAmount } from "./commonSchemas.js";
+import { addressSchema } from "./addressSchemas.js";
+import { parcelSchema } from "./parcelSchemas.js";
+
+const customsInfoSchema = z.record(z.any()).optional();
+
+const shipmentOptionsSchema = z.object({
+  label_format: z.enum(["PDF", "PNG", "ZPL", "EPL2"]).optional(),
+  delivery_confirmation: z.string().trim().optional(),
+  print_custom_1: z.string().trim().max(255).optional(),
+  print_custom_2: z.string().trim().max(255).optional(),
+}).strict().optional();
+
+const createShipmentSchema = z.object({
+  from_address: addressSchema,
+  to_address: addressSchema,
+  parcel: parcelSchema,
+  carrier_accounts: z.array(nonEmptyString).optional(),
+  customs_info: customsInfoSchema,
+  options: shipmentOptionsSchema,
+  reference: z.string().trim().max(255).optional(),
+}).strict();
+
+const buyShippingLabelSchema = z.object({
+  shipment_id: easypostId,
+  rate_id: easypostId.optional(),
+  carrier: nonEmptyString.optional(),
+  service: nonEmptyString.optional(),
+  insurance: currencyAmount.optional(),
+}).strict().refine((input) => input.rate_id || (input.carrier && input.service), {
+  message: "Provide either rate_id or carrier and service",
+});
+
+const getShipmentSchema = z.object({
+  shipment_id: easypostId,
+}).strict();
+
+const listShipmentsSchema = paginationSchema.extend({
+  purchased: z.boolean().optional(),
+  include_children: z.boolean().optional(),
+});
+
+const estimateRatesSchema = createShipmentSchema;
+
+const refundShipmentSchema = z.object({
+  shipment_id: easypostId,
+}).strict();
+
+const cancelShipmentSchema = refundShipmentSchema;
+
+const insureShipmentSchema = z.object({
+  shipment_id: easypostId,
+  amount: currencyAmount,
+}).strict();
+
+export { createShipmentSchema, buyShippingLabelSchema, getShipmentSchema, listShipmentsSchema, estimateRatesSchema, refundShipmentSchema, cancelShipmentSchema, insureShipmentSchema };

package/src/schemas/trackingSchemas.js

@@ -0,0 +1,16 @@
+import { z, easypostId, nonEmptyString } from "./commonSchemas.js";
+
+const trackPackageSchema = z.object({
+  tracking_code: nonEmptyString,
+  carrier: nonEmptyString.optional(),
+}).strict();
+
+const getTrackingHistorySchema = z.object({
+  tracker_id: easypostId.optional(),
+  tracking_code: nonEmptyString.optional(),
+  carrier: nonEmptyString.optional(),
+}).strict().refine((input) => input.tracker_id || input.tracking_code, {
+  message: "Provide tracker_id or tracking_code",
+});
+
+export { trackPackageSchema, getTrackingHistorySchema };

package/src/server/createServer.js

@@ -0,0 +1,90 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { getConfig } from "../config/index.js";
+import { getLoggerSync } from "../logging/logger.js";
+import { createCorrelationId } from "../utils/correlation.js";
+import { withErrorHandling } from "../middleware/errorHandler.js";
+import { createInMemoryRateLimiter } from "../middleware/rateLimiter.js";
+import { createServices } from "../services/index.js";
+import { createToolRegistry } from "../tools/index.js";
+import { redactForLogs } from "../utils/sanitize.js";
+
+function readPackageVersion() {
+  const pkgPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../../package.json"
+  );
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
+function asMcpJson(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+export function createMcpServer() {
+  const config = getConfig();
+  const logger = getLoggerSync();
+  const services = createServices();
+  const registry = createToolRegistry(services);
+  const limiter = createInMemoryRateLimiter({
+    limit: config.rateLimit.perMinute,
+    windowMs: 60 * 1000,
+  });
+
+  const server = new Server(
+    {
+      name: "easypost-mcp",
+      version: readPackageVersion(),
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    logger.debug({ toolCount: registry.list().length }, "Listing MCP tools");
+    return { tools: registry.list() };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const correlationId = createCorrelationId();
+    const toolName = request.params.name;
+    const childLogger = logger.child({ correlationId, toolName });
+
+    return asMcpJson(
+      await withErrorHandling({ correlationId, logger: childLogger }, async () => {
+        limiter.consume(toolName);
+        childLogger.info(
+          { arguments: redactForLogs(request.params.arguments) },
+          "MCP tool called"
+        );
+
+        const tool = registry.get(toolName);
+        const result = await tool.execute(request.params.arguments, {
+          correlationId,
+          logger: childLogger,
+        });
+
+        childLogger.info({ result: redactForLogs(result) }, "MCP tool completed");
+        return {
+          ...result,
+          correlation_id: correlationId,
+        };
+      })
+    );
+  });
+
+  return server;
+}

package/src/server/transports/http.js

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createMcpServer } from "../createServer.js";
+
+export async function startHttpTransport({ logger, config }) {
+  const app = createMcpExpressApp({ host: config.http.host });
+  const transports = new Map();
+
+  const mcpPostHandler = async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"];
+
+    try {
+      let transport;
+
+      if (sessionId && transports.has(sessionId)) {
+        transport = transports.get(sessionId);
+      } else if (!sessionId && isInitializeRequest(req.body)) {
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (id) => {
+            transports.set(id, transport);
+            logger.debug({ sessionId: id }, "MCP HTTP session initialized");
+          },
+        });
+
+        transport.onclose = () => {
+          const id = transport.sessionId;
+          if (id && transports.has(id)) {
+            transports.delete(id);
+            logger.debug({ sessionId: id }, "MCP HTTP session closed");
+          }
+        };
+
+        const server = createMcpServer();
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        return;
+      } else {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Bad Request: No valid session ID provided",
+          },
+          id: null,
+        });
+        return;
+      }
+
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      logger.error(
+        { err: { message: error.message, stack: error.stack } },
+        "MCP HTTP request failed"
+      );
+
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: "Internal server error",
+          },
+          id: null,
+        });
+      }
+    }
+  };
+
+  const mcpGetHandler = async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"];
+    const transport = sessionId ? transports.get(sessionId) : undefined;
+
+    if (!transport) {
+      res.status(400).send("Invalid or missing session ID");
+      return;
+    }
+
+    await transport.handleRequest(req, res);
+  };
+
+  app.post("/mcp", mcpPostHandler);
+  app.get("/mcp", mcpGetHandler);
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true, service: "easypost-mcp" });
+  });
+
+  const httpServer = createServer(app);
+  const { port, host } = config.http;
+
+  await new Promise((resolve, reject) => {
+    httpServer.listen(port, host, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+
+  logger.info({ host, port, path: "/mcp" }, "EasyPost MCP server running on HTTP");
+}

package/src/server/transports/stdio.js

@@ -0,0 +1,10 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "../createServer.js";
+
+export async function startStdioTransport({ logger }) {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+  logger.info("EasyPost MCP server running on stdio");
+}

package/src/services/AddressService.js

@@ -0,0 +1,36 @@
+import { mapAddress } from "../adapters/easypost/responseMappers.js";
+
+class AddressService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async verifyAddress(input, context) {
+    const address = await this.easypost.execute(
+      "address.verify",
+      (client) => client.Address.createAndVerify
+        ? client.Address.createAndVerify(input.address)
+        : client.Address.create({ ...input.address, verify: input.verifications }),
+      context
+    );
+
+    return {
+      ok: true,
+      address: mapAddress(address),
+      verification_status: address.verifications?.delivery?.success === true ? "verified" : "review_required",
+      messages: address.verifications?.delivery?.errors || [],
+    };
+  }
+
+  async createAddress(input, context) {
+    const address = await this.easypost.execute(
+      "address.create",
+      (client) => client.Address.create({ ...input.address, verify: input.verify }),
+      context
+    );
+
+    return { ok: true, address: mapAddress(address) };
+  }
+}
+
+export { AddressService };

package/src/services/BatchService.js

@@ -0,0 +1,38 @@
+class BatchService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async createBatch(input, context) {
+    const shipments = input.shipments.map((shipment) => (
+      shipment.shipment_id ? { id: shipment.shipment_id } : shipment
+    ));
+
+    const batch = await this.easypost.execute(
+      "batch.create",
+      (client) => client.Batch.create({ shipments }),
+      context
+    );
+    return { ok: true, batch };
+  }
+
+  async buyBatch(input, context) {
+    const batch = await this.easypost.execute(
+      "batch.buy",
+      (client) => client.Batch.buy(input.batch_id),
+      context
+    );
+    return { ok: true, batch };
+  }
+
+  async batchStatus(input, context) {
+    const batch = await this.easypost.execute(
+      "batch.retrieve",
+      (client) => client.Batch.retrieve(input.batch_id),
+      context
+    );
+    return { ok: true, batch };
+  }
+}
+
+export { BatchService };

package/src/services/OrderService.js

@@ -0,0 +1,25 @@
+class OrderService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async createOrder(input, context) {
+    const order = await this.easypost.execute(
+      "order.create",
+      (client) => client.Order.create(input),
+      context
+    );
+    return { ok: true, order };
+  }
+
+  async getOrder(input, context) {
+    const order = await this.easypost.execute(
+      "order.retrieve",
+      (client) => client.Order.retrieve(input.order_id),
+      context
+    );
+    return { ok: true, order };
+  }
+}
+
+export { OrderService };

package/src/services/PickupService.js

@@ -0,0 +1,42 @@
+class PickupService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async schedulePickup(input, context) {
+    const pickup = await this.easypost.execute(
+      "pickup.create",
+      (client) => client.Pickup.create({
+        shipment: { id: input.shipment_ids[0] },
+        address: input.address,
+        min_datetime: input.min_datetime,
+        max_datetime: input.max_datetime,
+        instructions: input.instructions,
+        carrier_accounts: input.carrier_accounts,
+      }),
+      context
+    );
+
+    const pickupRate = pickup.lowestRate?.() || pickup.pickup_rates?.[0];
+    const scheduled = pickupRate
+      ? await this.easypost.execute(
+          "pickup.buy",
+          (client) => client.Pickup.buy(pickup.id, pickupRate.carrier, pickupRate.service),
+          context
+        )
+      : pickup;
+
+    return { ok: true, pickup: scheduled, pickup_rate: pickupRate || null };
+  }
+
+  async cancelPickup(input, context) {
+    const pickup = await this.easypost.execute(
+      "pickup.cancel",
+      (client) => client.Pickup.cancel(input.pickup_id),
+      context
+    );
+    return { ok: true, pickup };
+  }
+}
+
+export { PickupService };

package/src/services/ReturnService.js

@@ -0,0 +1,33 @@
+import { mapShipment, mapRate } from "../adapters/easypost/responseMappers.js";
+
+class ReturnService {
+  constructor(easypostClient) {
+    this.easypost = easypostClient;
+  }
+
+  async createReturnLabel(input, context) {
+    const shipment = await this.easypost.execute(
+      "return.create",
+      (client) => client.Shipment.create({
+        from_address: input.from_address,
+        to_address: input.to_address,
+        parcel: input.parcel,
+        is_return: true,
+        options: input.original_shipment_id ? { original_shipment_id: input.original_shipment_id } : undefined,
+      }),
+      context
+    );
+
+    const rate = input.carrier && input.service
+      ? (shipment.rates || []).find((candidate) => candidate.carrier === input.carrier && candidate.service === input.service)
+      : shipment.lowestRate?.();
+
+    const bought = rate
+      ? await this.easypost.execute("return.buy", (client) => client.Shipment.buy(shipment.id, rate), context)
+      : shipment;
+
+    return { ok: true, shipment: mapShipment(bought), purchased_rate: mapRate(rate) };
+  }
+}
+
+export { ReturnService };