easypost-mcp 2.1.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easypost-mcp",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "Production-grade EasyPost Model Context Protocol (MCP) server for Claude, Cursor, and programmatic agents",
   "type": "module",
   "main": "./src/index.js",

package/src/audit/AuditLogger.js

@@ -0,0 +1,20 @@
+import { redactForLogs } from "../utils/sanitize.js";
+
+class AuditLogger {
+  constructor(logger) {
+    this.logger = logger;
+  }
+
+  record(event, payload = {}) {
+    this.logger.info(
+      {
+        audit: true,
+        event,
+        ...redactForLogs(payload),
+      },
+      `audit.${event}`
+    );
+  }
+}
+
+export { AuditLogger };

package/src/constants/toolRisk.js

@@ -0,0 +1,36 @@
+const TOOL_RISK = Object.freeze({
+  LOW: "LOW",
+  MEDIUM: "MEDIUM",
+  HIGH: "HIGH",
+});
+
+const TOOL_RISK_BY_NAME = Object.freeze({
+  verify_address: TOOL_RISK.LOW,
+  create_address: TOOL_RISK.LOW,
+  estimate_rates: TOOL_RISK.LOW,
+  get_shipment: TOOL_RISK.LOW,
+  list_shipments: TOOL_RISK.LOW,
+  track_package: TOOL_RISK.LOW,
+  get_tracking_history: TOOL_RISK.LOW,
+  get_order: TOOL_RISK.LOW,
+  batch_status: TOOL_RISK.LOW,
+
+  create_shipment: TOOL_RISK.MEDIUM,
+  create_return_label: TOOL_RISK.MEDIUM,
+  insure_shipment: TOOL_RISK.MEDIUM,
+  create_batch: TOOL_RISK.MEDIUM,
+  create_order: TOOL_RISK.MEDIUM,
+
+  buy_shipping_label: TOOL_RISK.HIGH,
+  schedule_pickup: TOOL_RISK.HIGH,
+  cancel_pickup: TOOL_RISK.HIGH,
+  cancel_shipment: TOOL_RISK.HIGH,
+  refund_shipment: TOOL_RISK.HIGH,
+  buy_batch: TOOL_RISK.HIGH,
+});
+
+function riskForTool(name) {
+  return TOOL_RISK_BY_NAME[name] || TOOL_RISK.MEDIUM;
+}
+
+export { TOOL_RISK, TOOL_RISK_BY_NAME, riskForTool };

package/src/elicitation/fallback.js

@@ -0,0 +1,37 @@
+import { examplesForFields, getFieldMetadata } from "./fields/catalog.js";
+
+function createFallbackResponse({
+  errorCode,
+  message,
+  missingFields = [],
+  ambiguousFields = [],
+  availableOptions = [],
+  examples,
+  nextAction,
+  workflowId,
+  validValues = {},
+  metadata = {},
+}) {
+  return {
+    ok: false,
+    success: false,
+    error_code: errorCode,
+    message,
+    workflow_id: workflowId,
+    missing_fields: missingFields,
+    ambiguous_fields: ambiguousFields,
+    available_options: availableOptions,
+    examples: examples || examplesForFields(missingFields),
+    valid_values: validValues,
+    field_metadata: {
+      ...Object.fromEntries(
+        [...missingFields, ...ambiguousFields.map((field) => field.path || field.field).filter(Boolean)]
+          .map((path) => [path, getFieldMetadata(path)])
+      ),
+      ...metadata,
+    },
+    next_action: nextAction,
+  };
+}
+
+export { createFallbackResponse };

package/src/elicitation/fields/catalog.js

@@ -0,0 +1,171 @@
+const FIELD_CATALOG = Object.freeze({
+  carrier: {
+    title: "Carrier",
+    description: "Exact supported carrier code or name. Do not use abbreviations unless listed.",
+    examples: ["USPS", "FedEx", "UPS"],
+    validation_rules: ["Must match an authoritative carrier exactly."],
+    formatting_hints: ["Use the value returned by get_carriers or validate_carrier."],
+  },
+  service: {
+    title: "Service level",
+    description: "Exact carrier service level returned by carrier resources or shipment rates.",
+    examples: ["GroundAdvantage", "FEDEX_GROUND", "Priority"],
+    validation_rules: ["Must be valid for the selected carrier."],
+    formatting_hints: ["Do not use vague terms like ground unless that exact service exists."],
+  },
+  predefined_package: {
+    title: "Package type",
+    description: "Carrier/package predefined package type.",
+    examples: ["Parcel", "FlatRateEnvelope", "FlatRateSmallBox"],
+    validation_rules: ["Must match a known package type exactly."],
+  },
+  country: {
+    title: "Country",
+    description: "ISO 3166-1 alpha-2 country code.",
+    examples: ["US", "CA", "GB"],
+    validation_rules: ["Two-letter country code."],
+    formatting_hints: ["Use uppercase country codes."],
+  },
+  state: {
+    title: "State or province",
+    description: "State, province, or region code appropriate for the destination country.",
+    examples: ["CA", "NY", "ON"],
+    validation_rules: ["Use country-specific state/province format where required."],
+  },
+  zip: {
+    title: "Postal code",
+    description: "Country-specific postal or ZIP code.",
+    examples: ["94104", "10001", "M5V 2T6"],
+    validation_rules: ["Must match the destination country postal format."],
+    formatting_hints: ["For US addresses use 5-digit or ZIP+4 format."],
+  },
+  street1: {
+    title: "Street address",
+    description: "Primary street address line.",
+    examples: ["417 Montgomery St"],
+    validation_rules: ["Must be a real operational shipping address, not a placeholder."],
+  },
+  city: {
+    title: "City",
+    description: "Destination or origin city.",
+    examples: ["San Francisco", "New York"],
+    validation_rules: ["Required for address creation and shipment workflows."],
+  },
+  weight: {
+    title: "Weight",
+    description: "Parcel weight in ounces.",
+    examples: [16, 32.5],
+    validation_rules: ["Must be greater than 0 and at most 1120 ounces."],
+    formatting_hints: ["EasyPost parcel weight is in ounces."],
+  },
+  length: {
+    title: "Length",
+    description: "Parcel length in inches.",
+    examples: [10],
+    validation_rules: ["Must be greater than 0 and at most 120 inches."],
+  },
+  width: {
+    title: "Width",
+    description: "Parcel width in inches.",
+    examples: [8],
+    validation_rules: ["Must be greater than 0 and at most 120 inches."],
+  },
+  height: {
+    title: "Height",
+    description: "Parcel height in inches.",
+    examples: [4],
+    validation_rules: ["Must be greater than 0 and at most 120 inches."],
+  },
+  rate_option: {
+    title: "Rate option",
+    description: "Numbered option from the shipment's actual returned rates.",
+    examples: [1, 2],
+    validation_rules: ["Must refer to one of the returned rate options for the shipment."],
+  },
+  confirm: {
+    title: "Confirmation",
+    description: "Explicit approval for high-risk or irreversible operations.",
+    examples: [true],
+    validation_rules: ["Must be true before execution continues."],
+  },
+  insurance_amount: {
+    title: "Insurance amount",
+    description: "Shipment insurance amount in USD unless otherwise specified.",
+    examples: ["100.00", "250.00"],
+    validation_rules: ["Must be non-negative currency with at most two decimals."],
+  },
+  tracking_code: {
+    title: "Tracking code",
+    description: "Carrier tracking number.",
+    examples: ["EZ1000000001"],
+    validation_rules: ["Must be supplied by the carrier or EasyPost."],
+  },
+  min_datetime: {
+    title: "Pickup start",
+    description: "Earliest pickup datetime.",
+    examples: ["2026-05-25T10:00:00-07:00"],
+    validation_rules: ["Must be an operational pickup datetime accepted by the carrier."],
+  },
+  max_datetime: {
+    title: "Pickup end",
+    description: "Latest pickup datetime.",
+    examples: ["2026-05-25T14:00:00-07:00"],
+    validation_rules: ["Must be after pickup start."],
+  },
+});
+
+function getFieldMetadata(path) {
+  const parts = String(path || "").split(".");
+  const last = parts[parts.length - 1];
+  if (last === "zip") return FIELD_CATALOG.zip;
+  if (last === "country") return FIELD_CATALOG.country;
+  if (last === "state") return FIELD_CATALOG.state;
+  if (last === "predefined_package") return FIELD_CATALOG.predefined_package;
+  if (last === "amount") return FIELD_CATALOG.insurance_amount;
+  return FIELD_CATALOG[last] || {
+    title: last || "Field",
+    description: `Required field: ${path}`,
+    examples: [],
+    validation_rules: [],
+  };
+}
+
+function schemaForField(path) {
+  const metadata = getFieldMetadata(path);
+  const last = String(path).split(".").at(-1);
+
+  if (["length", "width", "height", "weight", "rate_option"].includes(last)) {
+    return {
+      type: last === "rate_option" ? "integer" : "number",
+      title: metadata.title,
+      description: metadata.description,
+      minimum: last === "rate_option" ? 1 : 0.01,
+      ...(last !== "rate_option" ? { maximum: last === "weight" ? 1120 : 120 } : {}),
+    };
+  }
+
+  if (last === "confirm") {
+    return {
+      type: "boolean",
+      title: metadata.title,
+      description: metadata.description,
+      default: false,
+    };
+  }
+
+  return {
+    type: "string",
+    title: metadata.title,
+    description: metadata.description,
+    minLength: 1,
+    maxLength: 255,
+  };
+}
+
+function examplesForFields(paths) {
+  return Object.fromEntries(
+    paths.map((path) => [path, getFieldMetadata(path).examples || []])
+  );
+}
+
+export { FIELD_CATALOG, getFieldMetadata, schemaForField, examplesForFields };

package/src/pipeline/ExecutionPipeline.js

@@ -0,0 +1,226 @@
+import { validateInput } from "../validators/validate.js";
+import { riskForTool, TOOL_RISK } from "../constants/toolRisk.js";
+import { AntiHallucinationError, ValidationError } from "../errors/AppError.js";
+import { createFallbackResponse } from "../elicitation/fallback.js";
+
+class ExecutionPipeline {
+  constructor({ resourceManager, elicitationService, workflowState, auditLogger }) {
+    this.resourceManager = resourceManager;
+    this.elicitation = elicitationService;
+    this.workflowState = workflowState;
+    this.auditLogger = auditLogger;
+  }
+
+  async run(tool, args, context) {
+    const risk = tool.risk || riskForTool(tool.name);
+    this.auditLogger.record("intent_extracted", {
+      correlationId: context.correlationId,
+      toolName: tool.name,
+      risk,
+    });
+
+    await this.resourceManager?.ensureFresh(context);
+    const originalArgs = args || {};
+    const workflowId = originalArgs.workflow_id;
+    const mergedArgs = this.workflowState?.merge(workflowId, originalArgs) || originalArgs;
+
+    const input = await this.validateOrElicit(tool, mergedArgs, {
+      ...context,
+      risk,
+      workflowId,
+    });
+
+    if (input?.__elicitationFallback) {
+      return input.__elicitationFallback;
+    }
+
+    this.auditLogger.record("validation_succeeded", {
+      correlationId: context.correlationId,
+      toolName: tool.name,
+      risk,
+    });
+
+    if (risk === TOOL_RISK.HIGH && input.confirm !== true) {
+      this.auditLogger.record("confirmation_missing", {
+        correlationId: context.correlationId,
+        toolName: tool.name,
+      });
+    }
+
+    const result = await tool.handler(input, {
+      ...context,
+      risk,
+      resources: this.resourceManager,
+      elicitation: this.elicitation,
+      audit: this.auditLogger,
+    });
+
+    this.auditLogger.record("execution_completed", {
+      correlationId: context.correlationId,
+      toolName: tool.name,
+      risk,
+      ok: result?.ok === true,
+    });
+
+    return result;
+  }
+
+  async validateOrElicit(tool, args, context) {
+    const validationArgs = stripWorkflowId(args);
+    try {
+      return validateInput(tool.schema, validationArgs, {
+        resourceManager: this.resourceManager,
+        toolName: tool.name,
+        risk: context.risk,
+      });
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        return this.handleValidationFailure(tool, args, context, error);
+      }
+
+      if (error instanceof AntiHallucinationError) {
+        return this.handleAmbiguityFailure(tool, args, context, error);
+      }
+
+      throw error;
+    }
+  }
+
+  async handleValidationFailure(tool, args, context, error) {
+    const validationArgs = stripWorkflowId(args);
+    const missingFields = extractMissingFields(error.details);
+    if (!missingFields.length) throw error;
+
+    const workflowId = context.workflowId || this.workflowState?.create({
+      toolName: tool.name,
+      input: validationArgs,
+      reason: "MISSING_FIELDS",
+      correlationId: context.correlationId,
+    });
+
+    this.auditLogger.record("missing_fields_detected", {
+      correlationId: context.correlationId,
+      toolName: tool.name,
+      missingFields,
+      workflowId,
+    });
+
+    const elicited = await this.elicitation?.requestMissingFields({
+      server: context.server,
+      toolName: tool.name,
+      missingFields,
+      partialInput: validationArgs,
+    });
+
+    if (elicited?.completed) {
+      this.workflowState?.update(workflowId, elicited.input);
+      return this.validateOrElicit(tool, elicited.input, { ...context, workflowId });
+    }
+
+    return {
+      __elicitationFallback: createFallbackResponse({
+        errorCode: "MISSING_REQUIRED_FIELDS",
+        message: "Required fields are missing. Provide only the missing fields and retry with workflow_id to resume.",
+        missingFields,
+        workflowId,
+        nextAction: "Provide missing_fields and include workflow_id in the next call, or use a client that supports elicitation.form.",
+      }),
+    };
+  }
+
+  async handleAmbiguityFailure(tool, args, context, error) {
+    const details = error.details || {};
+    const ambiguousFields = (details.issues || [])
+      .filter((issue) => Array.isArray(issue.suggestions) && issue.suggestions.length > 0)
+      .map((issue) => ({
+        path: issue.path,
+        code: issue.code,
+        message: issue.message,
+        suggestions: issue.suggestions,
+      }));
+
+    if (!ambiguousFields.length) throw error;
+
+    const workflowId = context.workflowId || this.workflowState?.create({
+      toolName: tool.name,
+        input: validationArgs,
+      reason: "AMBIGUOUS_FIELDS",
+      correlationId: context.correlationId,
+    });
+
+    const first = ambiguousFields[0];
+    this.auditLogger.record("ambiguity_detected", {
+      correlationId: context.correlationId,
+      toolName: tool.name,
+      ambiguousFields,
+      workflowId,
+    });
+
+    const clarified = await this.elicitation?.clarify({
+      server: context.server,
+      field: first.path,
+      suggestions: first.suggestions,
+      message: first.message || `Clarify ${first.path}`,
+    });
+
+    if (clarified?.selected) {
+      const clarifiedInput = setPath(validationArgs, first.path, clarified.value);
+      this.workflowState?.update(workflowId, clarifiedInput);
+      return this.validateOrElicit(tool, clarifiedInput, { ...context, workflowId });
+    }
+
+    return {
+      __elicitationFallback: createFallbackResponse({
+        errorCode: "AMBIGUOUS_OR_UNSUPPORTED_VALUES",
+        message: "One or more values are ambiguous or unsupported. Choose an exact suggested value or provide a different exact value.",
+        ambiguousFields,
+        availableOptions: ambiguousFields.flatMap((field) => field.suggestions || []),
+        workflowId,
+        nextAction: "Confirm one suggestion explicitly and include workflow_id in the next call, or use a client that supports elicitation.form.",
+      }),
+    };
+  }
+}
+
+function extractMissingFields(issues = []) {
+  const fields = [];
+  for (const issue of issues) {
+    const isMissing = issue.code === "invalid_type" && issue.received === "undefined";
+    if (!isMissing) continue;
+    fields.push(...expandRequiredPath(issue.path || []));
+  }
+  return [...new Set(fields)];
+}
+
+function expandRequiredPath(path) {
+  const joined = path.join(".");
+  if (["from_address", "to_address", "address"].includes(joined)) {
+    return ["street1", "city", "state", "zip", "country"].map((field) => `${joined}.${field}`);
+  }
+  if (joined === "parcel") {
+    return ["length", "width", "height", "weight"].map((field) => `parcel.${field}`);
+  }
+  if (!joined) return [];
+  return [joined];
+}
+
+function setPath(input, path, value) {
+  const output = structuredClone(input || {});
+  const parts = String(path).split(".");
+  let target = output;
+  for (const part of parts.slice(0, -1)) {
+    target[part] = target[part] && typeof target[part] === "object" ? target[part] : {};
+    target = target[part];
+  }
+  target[parts.at(-1)] = value;
+  return output;
+}
+
+function stripWorkflowId(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+  const output = { ...input };
+  delete output.workflow_id;
+  return output;
+}
+
+export { ExecutionPipeline };