easypost-mcp 2.1.0

package/bin/easypost-mcp.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli/index.js";
+
+runCli(process.argv).catch((error) => {
+  process.stderr.write(
+    `${JSON.stringify({
+      level: "fatal",
+      msg: error.message,
+      stack: error.stack,
+    })}\n`
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "easypost-mcp",
+  "version": "2.1.0",
+  "description": "Production-grade EasyPost Model Context Protocol (MCP) server for Claude, Cursor, and programmatic agents",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "easypost-mcp": "./bin/easypost-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "PUBLISHING.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/easypost-mcp.js start",
+    "start:stdio": "node bin/easypost-mcp.js start --mode=stdio",
+    "start:http": "node bin/easypost-mcp.js start --mode=http",
+    "test": "node --test",
+    "prepack": "node scripts/verify-pack.js",
+    "check:mcp:safe": "node scripts/manual-safe-mcp-check.js",
+    "check:mcp:full": "node scripts/full-mcp-tool-check.js",
+    "inspect:tools": "node bin/easypost-mcp.js --help"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "easypost",
+    "shipping",
+    "logistics",
+    "claude",
+    "cursor",
+    "stdio",
+    "ai-agent"
+  ],
+  "author": "Surya",
+  "publishConfig": {
+  "access": "public"
+},
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/easypost-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/easypost-mcp/issues"
+  },
+  "homepage": "https://github.com/your-org/easypost-mcp#readme",
+  "dependencies": {
+    "@easypost/api": "^8.8.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "express": "^5.2.1",
+    "pino": "^9.6.0",
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.16.6"
+  }
+}

package/src/adapters/easypost/EasyPostClient.js

@@ -0,0 +1,75 @@
+import EasyPost from "@easypost/api";
+import { getConfig } from "../../config/index.js";
+import { getLoggerSync } from "../../logging/logger.js";
+import { mapEasyPostError } from "../../errors/easypostErrorMapper.js";
+import { redactForLogs } from "../../utils/sanitize.js";
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function withTimeout(promise, timeoutMs) {
+  let timeout;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeout = setTimeout(() => {
+      const error = new Error("EasyPost request timed out");
+      error.statusCode = 504;
+      error.code = "EASYPOST_TIMEOUT";
+      reject(error);
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timeout));
+}
+
+class EasyPostClient {
+  constructor(options = {}) {
+    const config = getConfig();
+    const {
+      apiKey = config.easypost.apiKey,
+      timeoutMs = config.easypost.timeoutMs,
+      retryAttempts = config.easypost.retryAttempts,
+    } = options;
+
+    this.client = new EasyPost(apiKey);
+    this.timeoutMs = timeoutMs;
+    this.retryAttempts = retryAttempts;
+  }
+
+  async execute(operation, fn, context = {}) {
+    const childLogger = getLoggerSync().child({
+      correlationId: context.correlationId,
+      operation,
+      provider: "easypost",
+    });
+
+    for (let attempt = 0; attempt <= this.retryAttempts; attempt += 1) {
+      const startedAt = Date.now();
+
+      try {
+        childLogger.debug({ attempt }, "EasyPost request started");
+        const result = await withTimeout(fn(this.client), this.timeoutMs);
+        childLogger.debug({ attempt, durationMs: Date.now() - startedAt }, "EasyPost request completed");
+        return result;
+      } catch (error) {
+        const mapped = mapEasyPostError(error);
+
+        childLogger.warn(
+          { attempt, retryable: mapped.retryable, err: redactForLogs(mapped.details) },
+          "EasyPost request failed"
+        );
+
+        if (!mapped.retryable || attempt === this.retryAttempts) {
+          throw mapped;
+        }
+        await wait(100 * 2 ** attempt);
+      }
+    }
+  }
+
+  get raw() {
+    return this.client;
+  }
+}
+
+export { EasyPostClient };

package/src/adapters/easypost/responseMappers.js

@@ -0,0 +1,105 @@
+function mapRate(rate) {
+  if (!rate) return null;
+  return {
+    id: rate.id,
+    carrier: rate.carrier,
+    service: rate.service,
+    rate: rate.rate,
+    currency: rate.currency || "USD",
+    delivery_days: rate.delivery_days,
+    delivery_date: rate.delivery_date,
+    delivery_date_guaranteed: rate.delivery_date_guaranteed,
+  };
+}
+
+function mapAddress(address) {
+  if (!address) return null;
+  return {
+    id: address.id,
+    street1: address.street1,
+    street2: address.street2,
+    city: address.city,
+    state: address.state,
+    zip: address.zip,
+    country: address.country,
+    residential: address.residential,
+    verifications: address.verifications,
+  };
+}
+
+function mapShipment(shipment) {
+  if (!shipment) return null;
+  return {
+    id: shipment.id,
+    mode: shipment.mode,
+    status: shipment.status,
+    tracking_code: shipment.tracking_code,
+    reference: shipment.reference,
+    from_address: mapAddress(shipment.from_address),
+    to_address: mapAddress(shipment.to_address),
+    parcel: shipment.parcel
+      ? {
+          id: shipment.parcel.id,
+          length: shipment.parcel.length,
+          width: shipment.parcel.width,
+          height: shipment.parcel.height,
+          weight: shipment.parcel.weight,
+        }
+      : null,
+    selected_rate: mapRate(shipment.selected_rate),
+    rates: Array.isArray(shipment.rates) ? shipment.rates.map(mapRate) : [],
+    postage_label: shipment.postage_label
+      ? {
+          label_url: shipment.postage_label.label_url,
+          label_pdf_url: shipment.postage_label.label_pdf_url,
+          label_zpl_url: shipment.postage_label.label_zpl_url,
+          label_file_type: shipment.postage_label.label_file_type,
+        }
+      : null,
+    tracker: mapTracker(shipment.tracker),
+  };
+}
+
+function mapTracker(tracker) {
+  if (!tracker) return null;
+  return {
+    id: tracker.id,
+    tracking_code: tracker.tracking_code,
+    carrier: tracker.carrier,
+    status: tracker.status,
+    status_detail: tracker.status_detail,
+    estimated_delivery_date: tracker.est_delivery_date,
+    signed_by: tracker.signed_by,
+    public_url: tracker.public_url,
+    tracking_details: Array.isArray(tracker.tracking_details)
+      ? tracker.tracking_details.map((detail) => ({
+          message: detail.message,
+          status: detail.status,
+          status_detail: detail.status_detail,
+          datetime: detail.datetime,
+          source: detail.source,
+          tracking_location: detail.tracking_location
+            ? {
+                city: detail.tracking_location.city,
+                state: detail.tracking_location.state,
+                country: detail.tracking_location.country,
+                zip: detail.tracking_location.zip,
+              }
+            : null,
+        }))
+      : [],
+  };
+}
+
+function mapCollection(collection, mapper) {
+  return {
+    has_more: Boolean(collection?.has_more),
+    items: Array.isArray(collection?.shipments)
+      ? collection.shipments.map(mapper)
+      : Array.isArray(collection)
+        ? collection.map(mapper)
+        : [],
+  };
+}
+
+export { mapAddress, mapRate, mapShipment, mapTracker, mapCollection };

package/src/cli/commands/start.js

@@ -0,0 +1,47 @@
+import { applyBootstrapOptions } from "../../config/bootstrap.js";
+import { getConfig } from "../../config/index.js";
+import { getLogger, initLogger } from "../../logging/logger.js";
+import { startStdioTransport } from "../../server/transports/stdio.js";
+import { startHttpTransport } from "../../server/transports/http.js";
+
+function normalizeTransportMode(mode) {
+  const value = String(mode || "stdio").toLowerCase();
+  if (value === "stdio" || value === "http") {
+    return value;
+  }
+  throw new Error(`Invalid --mode "${mode}". Use "stdio" or "http".`);
+}
+
+export async function runStartCommand(options) {
+  applyBootstrapOptions({
+    apiKey: options.apiKey,
+    mode: options.easypostMode,
+    logLevel: options.logLevel,
+    timeoutMs: options.timeoutMs ? Number(options.timeoutMs) : undefined,
+    retryAttempts: options.retryAttempts ? Number(options.retryAttempts) : undefined,
+    rateLimitPerMinute: options.rateLimit ? Number(options.rateLimit) : undefined,
+    httpPort: options.port ? Number(options.port) : undefined,
+    httpHost: options.host,
+  });
+
+  const config = getConfig();
+  const logger = initLogger(config);
+  const transportMode = normalizeTransportMode(options.mode);
+
+  logger.info(
+    {
+      transport: transportMode,
+      easypostMode: config.easypost.mode,
+      nodeEnv: config.env,
+      http: transportMode === "http" ? config.http : undefined,
+    },
+    "Starting EasyPost MCP server"
+  );
+
+  if (transportMode === "stdio") {
+    await startStdioTransport({ logger });
+    return;
+  }
+
+  await startHttpTransport({ logger, config });
+}

package/src/cli/index.js

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { runStartCommand } from "./commands/start.js";
+
+function readPackageVersion() {
+  const pkgPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../../package.json"
+  );
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
+export function createProgram() {
+  const program = new Command();
+
+  program
+    .name("easypost-mcp")
+    .description("EasyPost Model Context Protocol (MCP) server")
+    .version(readPackageVersion(), "-V, --version", "Show version");
+
+  program
+    .command("start")
+    .description("Start the EasyPost MCP server")
+    .option("--api-key <key>", "EasyPost API key (or set EASYPOST_API_KEY)")
+    .option("--mode <transport>", "Transport mode: stdio or http", "stdio")
+    .option("--easypost-mode <mode>", "EasyPost environment: sandbox or production", "sandbox")
+    .option("--log-level <level>", "Log level (trace, debug, info, warn, error)")
+    .option("--port <port>", "HTTP port when --mode=http", "3000")
+    .option("--host <host>", "HTTP bind host when --mode=http", "127.0.0.1")
+    .option("--timeout-ms <ms>", "EasyPost request timeout in milliseconds", "30000")
+    .option("--retry-attempts <n>", "EasyPost retry attempts", "2")
+    .option("--rate-limit <n>", "MCP tool calls per minute", "60")
+    .action(async (options) => {
+      await runStartCommand(options);
+    });
+
+  return program;
+}
+
+export async function runCli(argv) {
+  const program = createProgram();
+  await program.parseAsync(argv);
+}

package/src/config/bootstrap.js

@@ -0,0 +1,42 @@
+/**
+ * Apply CLI options to process.env before config validation runs.
+ * Priority at runtime: CLI flags → existing env → dotenv file (loaded earlier).
+ */
+
+export function applyBootstrapOptions(options = {}) {
+  if (options.apiKey) {
+    process.env.EASYPOST_API_KEY = options.apiKey;
+  }
+
+  if (options.mode) {
+    process.env.EASYPOST_MODE = options.mode;
+  }
+
+  if (options.logLevel) {
+    process.env.LOG_LEVEL = options.logLevel;
+  }
+
+  if (options.nodeEnv) {
+    process.env.NODE_ENV = options.nodeEnv;
+  }
+
+  if (options.timeoutMs != null) {
+    process.env.EASYPOST_TIMEOUT_MS = String(options.timeoutMs);
+  }
+
+  if (options.retryAttempts != null) {
+    process.env.EASYPOST_RETRY_ATTEMPTS = String(options.retryAttempts);
+  }
+
+  if (options.rateLimitPerMinute != null) {
+    process.env.MCP_RATE_LIMIT_PER_MINUTE = String(options.rateLimitPerMinute);
+  }
+
+  if (options.httpPort != null) {
+    process.env.MCP_HTTP_PORT = String(options.httpPort);
+  }
+
+  if (options.httpHost) {
+    process.env.MCP_HTTP_HOST = options.httpHost;
+  }
+}

package/src/config/index.js

@@ -0,0 +1,17 @@
+import { loadConfig } from "./loadConfig.js";
+
+let cachedConfig = null;
+
+export function getConfig() {
+  if (!cachedConfig) {
+    cachedConfig = loadConfig();
+  }
+  return cachedConfig;
+}
+
+export function resetConfigForTests() {
+  cachedConfig = null;
+}
+
+export { loadConfig } from "./loadConfig.js";
+export { applyBootstrapOptions } from "./bootstrap.js";

package/src/config/loadConfig.js

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadDotenv } from "dotenv";
+import { z } from "zod";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let dotenvLoaded = false;
+
+function ensureDotenv() {
+  if (dotenvLoaded) return;
+  dotenvLoaded = true;
+  loadDotenv({
+    path: path.resolve(__dirname, "../../.env"),
+  });
+}
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  EASYPOST_API_KEY: z.string().min(1, "EASYPOST_API_KEY is required (use --api-key or env)"),
+  EASYPOST_MODE: z.enum(["sandbox", "production"]).default("sandbox"),
+  LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"]).default("info"),
+  DEBUG: z.string().optional(),
+  EASYPOST_TIMEOUT_MS: z.coerce.number().int().positive().default(30000),
+  EASYPOST_RETRY_ATTEMPTS: z.coerce.number().int().min(0).max(5).default(2),
+  MCP_RATE_LIMIT_PER_MINUTE: z.coerce.number().int().positive().default(60),
+  MCP_HTTP_PORT: z.coerce.number().int().positive().default(3000),
+  MCP_HTTP_HOST: z.string().default("127.0.0.1"),
+});
+
+export function loadConfig() {
+  ensureDotenv();
+
+  const parsed = envSchema.safeParse(process.env);
+
+  if (!parsed.success) {
+    const message = parsed.error.issues
+      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      .join("; ");
+    throw new Error(`Invalid configuration: ${message}`);
+  }
+
+  const env = parsed.data;
+
+  return {
+    env: env.NODE_ENV,
+    isProduction: env.NODE_ENV === "production",
+    debug: env.DEBUG === "true" || env.LOG_LEVEL === "debug",
+    easypost: {
+      apiKey: env.EASYPOST_API_KEY,
+      mode: env.EASYPOST_MODE,
+      timeoutMs: env.EASYPOST_TIMEOUT_MS,
+      retryAttempts: env.EASYPOST_RETRY_ATTEMPTS,
+    },
+    logging: {
+      level: env.LOG_LEVEL,
+    },
+    rateLimit: {
+      perMinute: env.MCP_RATE_LIMIT_PER_MINUTE,
+    },
+    http: {
+      port: env.MCP_HTTP_PORT,
+      host: env.MCP_HTTP_HOST,
+    },
+  };
+}

package/src/constants/toolCategories.js

@@ -0,0 +1,10 @@
+export default Object.freeze({
+  SHIPMENTS: "shipments",
+  TRACKING: "tracking",
+  ADDRESS: "address",
+  RETURNS: "returns",
+  PICKUPS: "pickups",
+  INSURANCE: "insurance",
+  BATCHES: "batches",
+  ORDERS: "orders",
+});

package/src/errors/AppError.js

@@ -0,0 +1,57 @@
+class AppError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code || "APP_ERROR";
+    this.statusCode = options.statusCode || 500;
+    this.details = options.details;
+    this.retryable = Boolean(options.retryable);
+    this.safeMessage = options.safeMessage || message;
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message, details) {
+    super(message, {
+      code: "VALIDATION_ERROR",
+      statusCode: 400,
+      details,
+      safeMessage: "Input validation failed",
+    });
+  }
+}
+
+class AntiHallucinationError extends AppError {
+  constructor(message, details) {
+    super(message, {
+      code: "SUSPICIOUS_INPUT",
+      statusCode: 400,
+      details,
+      safeMessage: message,
+    });
+  }
+}
+
+class ExternalServiceError extends AppError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code || "EASYPOST_ERROR",
+      statusCode: options.statusCode || 502,
+      details: options.details,
+      retryable: options.retryable,
+      safeMessage: options.safeMessage || "Shipping provider request failed",
+    });
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource, id) {
+    super(`${resource} not found`, {
+      code: "NOT_FOUND",
+      statusCode: 404,
+      details: { resource, id },
+    });
+  }
+}
+
+export { AppError, ValidationError, AntiHallucinationError, ExternalServiceError, NotFoundError };

package/src/errors/easypostErrorMapper.js

@@ -0,0 +1,21 @@
+import { ExternalServiceError } from "./AppError.js";
+
+function mapEasyPostError(error) {
+  const statusCode = error.statusCode || error.status || error.response?.statusCode || 502;
+  const code = error.code || error.error?.code || "EASYPOST_ERROR";
+  const message = error.message || error.error?.message || "EasyPost request failed";
+  const retryable = statusCode === 429 || statusCode >= 500;
+
+  return new ExternalServiceError(message, {
+    code,
+    statusCode,
+    retryable,
+    details: {
+      statusCode,
+      code,
+      errors: error.errors || error.error?.errors,
+    },
+  });
+}
+
+export { mapEasyPostError };

package/src/index.js

@@ -0,0 +1,6 @@
+export { createMcpServer } from "./server/createServer.js";
+export { createToolRegistry } from "./tools/index.js";
+export { createServices } from "./services/index.js";
+export { getConfig, loadConfig, resetConfigForTests, applyBootstrapOptions } from "./config/index.js";
+export { runCli, createProgram } from "./cli/index.js";
+export { runStartCommand } from "./cli/commands/start.js";

package/src/logging/logger.js

@@ -0,0 +1,77 @@
+import pino from "pino";
+import { redactForLogs } from "../utils/sanitize.js";
+
+let loggerInstance = null;
+
+function createFallbackLogger(config) {
+  const write = (level, obj, msg) => {
+    const payload = {
+      level,
+      time: new Date().toISOString(),
+      msg,
+      ...redactForLogs(obj || {}),
+    };
+    process.stderr.write(`${JSON.stringify(payload)}\n`);
+  };
+
+  const logger = {
+    trace: (obj, msg) => write("trace", obj, msg),
+    debug: (obj, msg) => write("debug", obj, msg),
+    info: (obj, msg) => write("info", obj, msg),
+    warn: (obj, msg) => write("warn", obj, msg),
+    error: (obj, msg) => write("error", obj, msg),
+    fatal: (obj, msg) => write("fatal", obj, msg),
+    child: (bindings) => {
+      const child = createFallbackLogger(config);
+      for (const level of ["trace", "debug", "info", "warn", "error", "fatal"]) {
+        const original = child[level];
+        child[level] = (obj, msg) => original({ ...bindings, ...(obj || {}) }, msg);
+      }
+      return child;
+    },
+  };
+
+  return logger;
+}
+
+export function initLogger(config) {
+  loggerInstance = pino(
+  {
+    level: config.logging.level,
+    redact: {
+      paths: [
+        "*.authorization",
+        "*.api_key",
+        "*.apiKey",
+        "*.token",
+        "*.password",
+        "req.headers.authorization",
+      ],
+      censor: "***REDACTED***",
+    },
+    base: {
+      service: "easypost-mcp",
+      environment: config.env,
+      easypostMode: config.easypost.mode,
+    },
+  },
+  process.stderr
+);
+
+  return loggerInstance;
+}
+
+export function getLogger() {
+  if (!loggerInstance) {
+    throw new Error("Logger not initialized. Call initLogger() during server startup.");
+  }
+  return loggerInstance;
+}
+
+// Sync getter used after initLogger in startup path
+export function getLoggerSync() {
+  if (!loggerInstance) {
+    throw new Error("Logger not initialized. Call initLogger() during server startup.");
+  }
+  return loggerInstance;
+}