aura-courier-mcp 2.2.0 → 2.3.1

package/dist/adapters/paperfly.d.ts

@@ -0,0 +1,16 @@
+import { CourierAdapter } from "./base.js";
+import { BalanceResponse, ParcelCreateRequest, ParcelResponse, SupportedCourier, TrackingResponse } from "../types.js";
+export declare class PaperflyAdapter implements CourierAdapter {
+    courierName: SupportedCourier;
+    private apiKey;
+    private username;
+    private password;
+    private storeName;
+    private client;
+    private enabled;
+    constructor(apiKey: string, username: string, password: string, storeName: string, baseUrl: string);
+    isConfigured(): boolean;
+    createParcel(req: ParcelCreateRequest): Promise<ParcelResponse>;
+    trackParcel(trackingCode: string): Promise<TrackingResponse>;
+    getBalance(): Promise<BalanceResponse>;
+}

package/dist/adapters/paperfly.js

@@ -0,0 +1,96 @@
+import axios from "axios";
+export class PaperflyAdapter {
+    courierName = "paperfly";
+    apiKey;
+    username;
+    password;
+    storeName;
+    client;
+    enabled;
+    constructor(apiKey, username, password, storeName, baseUrl) {
+        this.apiKey = apiKey;
+        this.username = username;
+        this.password = password;
+        this.storeName = storeName;
+        this.enabled = Boolean(apiKey && username && password);
+        this.client = axios.create({
+            baseURL: baseUrl,
+            timeout: 15000,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    isConfigured() {
+        return this.enabled;
+    }
+    async createParcel(req) {
+        if (!this.enabled) {
+            throw new Error("Paperfly credentials (paperflykey + merchant username & password) are not configured.");
+        }
+        if (!this.storeName) {
+            throw new Error("Paperfly store name is required to create a parcel.");
+        }
+        const payload = {
+            merchantOrderReference: req.invoice,
+            storeName: this.storeName,
+            productBrief: req.item_type || "Product",
+            packagePrice: String(req.value ?? req.cod_amount ?? 0),
+            max_weight: String(req.item_weight ?? 0.5),
+            customerName: req.recipient_name,
+            customerAddress: req.recipient_address,
+            customerPhone: req.recipient_phone,
+        };
+        const response = await this.client.post("/merchant/api/service/new_order_v2.php", payload, {
+            headers: { paperflykey: this.apiKey },
+            auth: { username: this.username, password: this.password },
+        });
+        const data = response.data;
+        const ok = data?.success;
+        if (!ok?.tracking_number) {
+            throw new Error(`Paperfly API error: ${JSON.stringify(data?.error || data?.message || data)}`);
+        }
+        return {
+            success: true,
+            courier: "paperfly",
+            tracking_code: ok.tracking_number,
+            consignment_id: ok.tracking_barcode || ok.tracking_number,
+            invoice: req.invoice,
+            status: ok.message || "created",
+            cod_amount: req.cod_amount,
+            created_at: new Date().toISOString(),
+            raw_response: data,
+        };
+    }
+    async trackParcel(trackingCode) {
+        if (!this.enabled) {
+            throw new Error("Paperfly credentials are not configured.");
+        }
+        if (!this.username || !this.password) {
+            throw new Error("Paperfly tracking needs your merchant-panel username & password (Basic Auth). Add them to use track_parcel.");
+        }
+        // Paperfly tracks by your merchant order reference (merchantOrderReference), not its tracking number.
+        const response = await this.client.post("/API-Order-Tracking", { ReferenceNumber: trackingCode }, { headers: { paperflykey: this.apiKey }, auth: { username: this.username, password: this.password } });
+        const data = response.data;
+        const st = data?.success?.trackingStatus?.[0] || {};
+        const stages = [
+            [st.Delivered, "delivered"],
+            [st.Partial, "partial-delivery"],
+            [st.Returned, "returned"],
+            [st.PickedForDelivery, "out-for-delivery"],
+            [st.inTransit, "in-transit"],
+            [st.ReceivedAtPoint, "received-at-point"],
+            [st.Pick, "picked-up"],
+        ];
+        const status = stages.find(([v]) => v && String(v).trim())?.[1] || data?.success?.message || "pending";
+        return {
+            success: true,
+            courier: "paperfly",
+            tracking_code: trackingCode,
+            status,
+            updated_at: new Date().toISOString(),
+            raw_response: data,
+        };
+    }
+    async getBalance() {
+        throw new Error("Paperfly does not expose a merchant balance endpoint via its public API — check the Paperfly merchant panel.");
+    }
+}

package/dist/config.d.ts

@@ -20,6 +20,14 @@ export interface CourierConfig {
         pickupStoreId: string;
         enabled: boolean;
     };
+    paperfly: {
+        apiKey: string;
+        username: string;
+        password: string;
+        storeName: string;
+        baseUrl: string;
+        enabled: boolean;
+    };
 }
 export type EnvSource = Record<string, string | undefined>;
 /**

package/dist/config.js

@@ -32,5 +32,13 @@ export function loadConfig(src = process.env) {
             pickupStoreId: src.REDX_PICKUP_STORE_ID || "",
             enabled: Boolean(src.REDX_API_TOKEN),
         },
+        paperfly: {
+            apiKey: src.PAPERFLY_API_KEY || "",
+            username: src.PAPERFLY_USERNAME || "",
+            password: src.PAPERFLY_PASSWORD || "",
+            storeName: src.PAPERFLY_STORE_NAME || "",
+            baseUrl: src.PAPERFLY_BASE_URL || "https://api.paperfly.com.bd",
+            enabled: Boolean(src.PAPERFLY_API_KEY && src.PAPERFLY_STORE_NAME),
+        },
     };
 }

package/dist/http.js

@@ -33,6 +33,10 @@ function keysFromRequest(req) {
         REDX_API_TOKEN: pick("x-redx-api-token", "redx_token"),
         REDX_BASE_URL: pick("x-redx-base-url", "redx_base_url"),
         REDX_PICKUP_STORE_ID: pick("x-redx-pickup-store-id", "redx_pickup_store_id"),
+        PAPERFLY_API_KEY: pick("x-paperfly-api-key", "paperfly_key"),
+        PAPERFLY_USERNAME: pick("x-paperfly-username", "paperfly_username"),
+        PAPERFLY_PASSWORD: pick("x-paperfly-password", "paperfly_password"),
+        PAPERFLY_STORE_NAME: pick("x-paperfly-store-name", "paperfly_store"),
     };
 }
 const app = express();
@@ -40,7 +44,7 @@ app.use(express.json({ limit: "1mb" }));
 // Allow browser-based and cross-origin MCP clients.
 app.use((req, res, next) => {
     res.header("Access-Control-Allow-Origin", "*");
-    res.header("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization, mcp-session-id, mcp-protocol-version, x-steadfast-api-key, x-steadfast-secret-key, x-steadfast-base-url, x-pathao-client-id, x-pathao-client-secret, x-pathao-username, x-pathao-password, x-pathao-store-id, x-pathao-base-url, x-redx-api-token, x-redx-base-url, x-redx-pickup-store-id");
+    res.header("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization, mcp-session-id, mcp-protocol-version, x-steadfast-api-key, x-steadfast-secret-key, x-steadfast-base-url, x-pathao-client-id, x-pathao-client-secret, x-pathao-username, x-pathao-password, x-pathao-store-id, x-pathao-base-url, x-redx-api-token, x-redx-base-url, x-redx-pickup-store-id, x-paperfly-api-key, x-paperfly-username, x-paperfly-password, x-paperfly-store-name");
     res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
     res.header("Access-Control-Expose-Headers", "mcp-session-id");
     if (req.method === "OPTIONS") {

package/dist/registry.js

@@ -2,6 +2,7 @@ import { SteadfastAdapter } from "./adapters/steadfast.js";
 import { PathaoAdapter } from "./adapters/pathao.js";
 import { FraudRiskEngine } from "./adapters/fraud_engine.js";
 import { RedxAdapter } from "./adapters/redx.js";
+import { PaperflyAdapter } from "./adapters/paperfly.js";
 import { loadConfig } from "./config.js";
 export class CourierRegistry {
     adapters = new Map();
@@ -12,6 +13,8 @@ export class CourierRegistry {
         this.adapters.set("pathao", pathao);
         const redx = new RedxAdapter(config.redx.apiToken, config.redx.baseUrl, config.redx.pickupStoreId);
         this.adapters.set("redx", redx);
+        const paperfly = new PaperflyAdapter(config.paperfly.apiKey, config.paperfly.username, config.paperfly.password, config.paperfly.storeName, config.paperfly.baseUrl);
+        this.adapters.set("paperfly", paperfly);
     }
     listCouriers() {
         return Array.from(this.adapters.entries()).map(([name, adapter]) => ({

package/dist/server.js

@@ -9,11 +9,11 @@ export const TOOLS = [
     },
     {
         name: "create_parcel",
-        description: "Book a new parcel delivery across Bangladesh (Steadfast, Pathao or RedX) with normalized response.",
+        description: "Book a new parcel delivery across Bangladesh (Steadfast, Pathao, RedX or Paperfly) with normalized response.",
         inputSchema: {
             type: "object",
             properties: {
-                courier: { type: "string", enum: ["steadfast", "pathao", "redx", "auto"], description: "Target courier or 'auto' for AI smart routing (default: auto)" },
+                courier: { type: "string", enum: ["steadfast", "pathao", "redx", "paperfly", "auto"], description: "Target courier or 'auto' for AI smart routing (default: auto)" },
                 invoice: { type: "string", description: "Unique order invoice number (e.g. INV-1002)" },
                 recipient_name: { type: "string", description: "Customer full name" },
                 recipient_phone: { type: "string", description: "11-digit Bangladeshi mobile number (e.g. 017XXXXXXXX)" },
@@ -36,7 +36,7 @@ export const TOOLS = [
             type: "object",
             properties: {
                 tracking_code: { type: "string", description: "Consignment ID or tracking code" },
-                courier: { type: "string", enum: ["steadfast", "pathao", "redx"], description: "Optional courier name if known" },
+                courier: { type: "string", enum: ["steadfast", "pathao", "redx", "paperfly"], description: "Optional courier name if known" },
             },
             required: ["tracking_code"],
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aura-courier-mcp",
-  "version": "2.2.0",
-  "description": "Universal Bangladesh courier MCP server — Steadfast, Pathao & RedX with a built-in fraud-risk engine — for Claude, Antigravity, Cursor & n8n AI agents. Runs as a local npx (STDIO) server or a remote HTTP endpoint.",
+  "version": "2.3.1",
+  "description": "Universal Bangladesh courier MCP server — Steadfast, Pathao, RedX & Paperfly with a built-in fraud-risk engine — for Claude, Antigravity, Cursor & n8n AI agents. Runs as a local npx (STDIO) server or a remote HTTP endpoint.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "steadfast",
     "pathao",
     "redx",
+    "paperfly",
     "bangladesh",
     "antigravity",
     "claude",