@codespar/mcp-andreani 0.1.0 → 0.2.0-alpha.2

package/README.md

@@ -1,5 +1,8 @@
 # MCP Andreani
 
+
+> **Alpha release** — published under the `alpha` npm dist-tag. Endpoint paths follow public docs and BACEN/provider conventions but have not been fully live-validated. Pin exact versions during `0.x.x-alpha`. Install with `npm install <pkg>@alpha`.
+
 MCP server for **Andreani** — the largest Argentine courier and logistics company, providing domestic and international shipping services.
 
 ## Quick Start
@@ -27,18 +30,28 @@ npx tsx packages/argentina/andreani/src/index.ts --http
 | `MCP_HTTP` | No | Set to `"true"` to enable HTTP transport |
 | `MCP_PORT` | No | HTTP port (default: 3000) |
 
-## Tools
+## Tools (18)
 
-| Tool | Description |
-|------|-------------|
+| Tool | Purpose |
+|---|---|
 | `create_shipment` | Create a new shipment |
 | `get_shipment` | Get shipment details by ID |
 | `track_shipment` | Track a shipment by tracking number |
 | `get_rates` | Get shipping rates/quotes |
 | `list_branches` | List Andreani branches/sucursales |
-| `create_label` | Generate a shipping label |
-| `get_tracking_history` | Get full tracking history |
+| `create_label` | Generate a shipping label for a shipment |
+| `get_tracking_history` | Get full tracking history for a shipment |
 | `cancel_shipment` | Cancel a shipment |
+| `get_label_pdf` | Download a shipping label as PDF (base64-encoded) |
+| `list_tracking_by_date` | List tracking events for a contract within a date range |
+| `validate_postal_code` | Validate CP coverage and list available services for a postal code |
+| `create_pickup` | Create a pickup/collection request (retiro) |
+| `list_pickups` | List pickup/collection requests |
+| `cancel_pickup` | Cancel a pickup/collection request |
+| `create_return` | Create a reverse logistics shipment (logística inversa / devolución) |
+| `list_returns` | List reverse logistics shipments (returns) |
+| `list_products` | List contracted products/services available on the account |
+| `get_invoice` | Get billing/invoice details |
 
 ## Auth
 

package/dist/index.d.ts

@@ -2,15 +2,25 @@
 /**
  * MCP Server for Andreani — largest Argentine courier/logistics provider.
  *
- * Tools:
+ * Tools (18):
  * - create_shipment: Create a new shipment
  * - get_shipment: Get shipment details by ID
  * - track_shipment: Track a shipment by tracking number
  * - get_rates: Get shipping rates/quotes
  * - list_branches: List Andreani branches/sucursales
  * - create_label: Generate a shipping label
+ * - get_label_pdf: Download label as PDF (base64)
  * - get_tracking_history: Get full tracking history
+ * - list_tracking_by_date: List tracking events for a date range
  * - cancel_shipment: Cancel a shipment
+ * - validate_postal_code: Validate CP coverage and list available services
+ * - create_pickup: Create a pickup/collection request
+ * - list_pickups: List pickup requests
+ * - cancel_pickup: Cancel a pickup request
+ * - create_return: Create a reverse logistics shipment (return)
+ * - list_returns: List return shipments
+ * - list_products: List contracted products/services
+ * - get_invoice: Get billing/invoice details
  *
  * Environment:
  *   ANDREANI_API_KEY  — API key

package/dist/index.js

@@ -2,15 +2,25 @@
 /**
  * MCP Server for Andreani — largest Argentine courier/logistics provider.
  *
- * Tools:
+ * Tools (18):
  * - create_shipment: Create a new shipment
  * - get_shipment: Get shipment details by ID
  * - track_shipment: Track a shipment by tracking number
  * - get_rates: Get shipping rates/quotes
  * - list_branches: List Andreani branches/sucursales
  * - create_label: Generate a shipping label
+ * - get_label_pdf: Download label as PDF (base64)
  * - get_tracking_history: Get full tracking history
+ * - list_tracking_by_date: List tracking events for a date range
  * - cancel_shipment: Cancel a shipment
+ * - validate_postal_code: Validate CP coverage and list available services
+ * - create_pickup: Create a pickup/collection request
+ * - list_pickups: List pickup requests
+ * - cancel_pickup: Cancel a pickup request
+ * - create_return: Create a reverse logistics shipment (return)
+ * - list_returns: List return shipments
+ * - list_products: List contracted products/services
+ * - get_invoice: Get billing/invoice details
  *
  * Environment:
  *   ANDREANI_API_KEY  — API key
@@ -62,7 +72,7 @@ async function andreaniRequest(method, path, body) {
     }
     return res.json();
 }
-const server = new Server({ name: "mcp-andreani", version: "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "mcp-andreani", version: "0.2.0-alpha.2" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -188,6 +198,176 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["shipmentId"],
             },
         },
+        {
+            name: "get_label_pdf",
+            description: "Download a shipping label as PDF (base64-encoded)",
+            inputSchema: {
+                type: "object",
+                properties: { shipmentId: { type: "string", description: "Shipment ID" } },
+                required: ["shipmentId"],
+            },
+        },
+        {
+            name: "list_tracking_by_date",
+            description: "List tracking events for a contract within a date range",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Contract/account number" },
+                    from_date: { type: "string", description: "Start date (YYYY-MM-DD)" },
+                    to_date: { type: "string", description: "End date (YYYY-MM-DD)" },
+                },
+                required: ["contract", "from_date", "to_date"],
+            },
+        },
+        {
+            name: "validate_postal_code",
+            description: "Validate CP coverage and list available services for a postal code",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    postal_code: { type: "string", description: "Argentine postal code" },
+                },
+                required: ["postal_code"],
+            },
+        },
+        {
+            name: "create_pickup",
+            description: "Create a pickup/collection request (retiro)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Contract number" },
+                    pickup_date: { type: "string", description: "Pickup date (YYYY-MM-DD)" },
+                    address: {
+                        type: "object",
+                        description: "Pickup address",
+                        properties: {
+                            postal_code: { type: "string" },
+                            street: { type: "string" },
+                            number: { type: "string" },
+                            city: { type: "string" },
+                            province: { type: "string" },
+                            contact_name: { type: "string" },
+                            contact_phone: { type: "string" },
+                        },
+                        required: ["postal_code", "contact_name"],
+                    },
+                    packages_count: { type: "number", description: "Number of packages to pick up" },
+                    notes: { type: "string", description: "Additional notes" },
+                },
+                required: ["contract", "pickup_date", "address", "packages_count"],
+            },
+        },
+        {
+            name: "list_pickups",
+            description: "List pickup/collection requests",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Filter by contract" },
+                    from_date: { type: "string", description: "Filter from date (YYYY-MM-DD)" },
+                    to_date: { type: "string", description: "Filter to date (YYYY-MM-DD)" },
+                    status: { type: "string", description: "Filter by status" },
+                },
+            },
+        },
+        {
+            name: "cancel_pickup",
+            description: "Cancel a pickup/collection request",
+            inputSchema: {
+                type: "object",
+                properties: { pickupId: { type: "string", description: "Pickup request ID" } },
+                required: ["pickupId"],
+            },
+        },
+        {
+            name: "create_return",
+            description: "Create a reverse logistics shipment (logística inversa / devolución)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Contract number" },
+                    original_shipment_id: { type: "string", description: "Original shipment ID being returned" },
+                    origin: {
+                        type: "object",
+                        description: "Pickup address (where to collect from)",
+                        properties: {
+                            postal_code: { type: "string" },
+                            street: { type: "string" },
+                            number: { type: "string" },
+                            city: { type: "string" },
+                            province: { type: "string" },
+                            contact_name: { type: "string" },
+                            contact_phone: { type: "string" },
+                        },
+                        required: ["postal_code", "contact_name"],
+                    },
+                    destination: {
+                        type: "object",
+                        description: "Return destination address",
+                        properties: {
+                            postal_code: { type: "string" },
+                            street: { type: "string" },
+                            number: { type: "string" },
+                            city: { type: "string" },
+                            province: { type: "string" },
+                        },
+                        required: ["postal_code"],
+                    },
+                    packages: {
+                        type: "array",
+                        description: "Packages to return",
+                        items: {
+                            type: "object",
+                            properties: {
+                                weight: { type: "number" },
+                                height: { type: "number" },
+                                width: { type: "number" },
+                                length: { type: "number" },
+                            },
+                            required: ["weight"],
+                        },
+                    },
+                    reason: { type: "string", description: "Return reason" },
+                },
+                required: ["contract", "origin", "destination", "packages"],
+            },
+        },
+        {
+            name: "list_returns",
+            description: "List reverse logistics shipments (returns)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Filter by contract" },
+                    from_date: { type: "string", description: "Filter from date (YYYY-MM-DD)" },
+                    to_date: { type: "string", description: "Filter to date (YYYY-MM-DD)" },
+                },
+            },
+        },
+        {
+            name: "list_products",
+            description: "List contracted products/services available on the account",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    contract: { type: "string", description: "Contract/account number" },
+                },
+                required: ["contract"],
+            },
+        },
+        {
+            name: "get_invoice",
+            description: "Get billing/invoice details",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    invoice_id: { type: "string", description: "Invoice/factura ID or number" },
+                },
+                required: ["invoice_id"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -234,6 +414,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/envios/${args?.shipmentId}/trazas`), null, 2) }] };
             case "cancel_shipment":
                 return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("DELETE", `/envios/${args?.shipmentId}`), null, 2) }] };
+            case "get_label_pdf":
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/envios/${args?.shipmentId}/etiquetas?formato=pdf`), null, 2) }] };
+            case "list_tracking_by_date": {
+                const params = new URLSearchParams({
+                    contrato: args?.contract,
+                    fechaDesde: args?.from_date,
+                    fechaHasta: args?.to_date,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/trazas?${params}`), null, 2) }] };
+            }
+            case "validate_postal_code":
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/cobertura/${args?.postal_code}`), null, 2) }] };
+            case "create_pickup": {
+                const payload = {
+                    contrato: args?.contract,
+                    fechaRetiro: args?.pickup_date,
+                    direccion: args?.address,
+                    cantidadBultos: args?.packages_count,
+                    observaciones: args?.notes,
+                };
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("POST", "/retiros", payload), null, 2) }] };
+            }
+            case "list_pickups": {
+                const params = new URLSearchParams();
+                if (args?.contract)
+                    params.set("contrato", args.contract);
+                if (args?.from_date)
+                    params.set("fechaDesde", args.from_date);
+                if (args?.to_date)
+                    params.set("fechaHasta", args.to_date);
+                if (args?.status)
+                    params.set("estado", args.status);
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/retiros?${params}`), null, 2) }] };
+            }
+            case "cancel_pickup":
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("DELETE", `/retiros/${args?.pickupId}`), null, 2) }] };
+            case "create_return": {
+                const payload = {
+                    contrato: args?.contract,
+                    envioOriginal: args?.original_shipment_id,
+                    origen: args?.origin,
+                    destino: args?.destination,
+                    bultos: args?.packages,
+                    motivo: args?.reason,
+                };
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("POST", "/logistica-inversa", payload), null, 2) }] };
+            }
+            case "list_returns": {
+                const params = new URLSearchParams();
+                if (args?.contract)
+                    params.set("contrato", args.contract);
+                if (args?.from_date)
+                    params.set("fechaDesde", args.from_date);
+                if (args?.to_date)
+                    params.set("fechaHasta", args.to_date);
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/logistica-inversa?${params}`), null, 2) }] };
+            }
+            case "list_products": {
+                const params = new URLSearchParams({ contrato: args?.contract });
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/productos?${params}`), null, 2) }] };
+            }
+            case "get_invoice":
+                return { content: [{ type: "text", text: JSON.stringify(await andreaniRequest("GET", `/facturas/${args?.invoice_id}`), null, 2) }] };
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
@@ -260,7 +503,7 @@ async function main() {
                 const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
                 t.onclose = () => { if (t.sessionId)
                     transports.delete(t.sessionId); };
-                const s = new Server({ name: "mcp-andreani", version: "0.1.0" }, { capabilities: { tools: {} } });
+                const s = new Server({ name: "mcp-andreani", version: "0.2.0-alpha.2" }, { capabilities: { tools: {} } });
                 server._requestHandlers.forEach((v, k) => s._requestHandlers.set(k, v));
                 server._notificationHandlers?.forEach((v, k) => s._notificationHandlers.set(k, v));
                 await s.connect(t);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@codespar/mcp-andreani",
-  "version": "0.1.0",
-  "description": "MCP server for Andreani — Argentine courier and logistics",
+  "version": "0.2.0-alpha.2",
+  "description": "MCP server for Andreani \u2014 Argentine courier and logistics",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "mcp-andreani": "dist/index.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js"
@@ -20,6 +22,13 @@
     "typescript": "^5.8.0"
   },
   "license": "MIT",
-  "keywords": ["andreani", "courier", "logistics", "argentina", "shipping", "mcp"],
+  "keywords": [
+    "andreani",
+    "courier",
+    "logistics",
+    "argentina",
+    "shipping",
+    "mcp"
+  ],
   "mcpName": "io.github.codespar/mcp-andreani"
 }