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

package/README.md

@@ -1,5 +1,8 @@
 # MCP Coordinadora
 
+
+> **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 **Coordinadora** — one of Colombia's largest courier and logistics companies, offering domestic and international shipping services.
 
 ## Quick Start
@@ -25,18 +28,29 @@ npx tsx packages/colombia/coordinadora/src/index.ts --http
 | `MCP_HTTP` | No | Set to `"true"` to enable HTTP transport |
 | `MCP_PORT` | No | HTTP port (default: 3000) |
 
-## Tools
+## Tools (19)
 
-| Tool | Description |
-|------|-------------|
+| Tool | Purpose |
+|---|---|
 | `create_shipment` | Create a new shipment |
 | `get_shipment` | Get shipment details by guide number |
-| `track_shipment` | Track a shipment |
+| `track_shipment` | Track a shipment by guide number |
 | `get_rates` | Get shipping rates/quotes |
 | `list_cities` | List available cities for shipping |
-| `create_pickup` | Schedule a pickup |
-| `get_coverage` | Check coverage for a location |
+| `create_pickup` | Schedule a pickup at an address |
+| `get_coverage` | Check if a location is within coverage area |
 | `cancel_shipment` | Cancel a shipment |
+| `get_guia_pdf` | Download a guía label as PDF (returns base64 or URL) |
+| `get_pickup` | Get pickup (recolección) details by id |
+| `cancel_pickup` | Cancel a scheduled pickup (recolección) |
+| `get_tracking_history` | Get full tracking event history for a guía |
+| `list_shipments_by_date` | List guías created within a date range |
+| `validate_coverage` | Validate that a city + postal code combination is covered |
+| `list_services` | List available service types for a given origin/destination |
+| `list_offices` | List Coordinadora branch offices (oficinas) |
+| `create_return` | Create a reverse-logistics return guía |
+| `list_returns` | List existing return guías |
+| `create_bulk_guias` | Create multiple guías in a single batch operation |
 
 ## Auth
 

package/dist/index.d.ts

@@ -11,6 +11,17 @@
  * - create_pickup: Schedule a pickup
  * - get_coverage: Check coverage for a location
  * - cancel_shipment: Cancel a shipment
+ * - get_guia_pdf: Download guía label as PDF
+ * - get_pickup: Get pickup/recolección details
+ * - cancel_pickup: Cancel a scheduled pickup
+ * - get_tracking_history: Full tracking event history
+ * - list_shipments_by_date: List shipments within a date range
+ * - validate_coverage: Validate coverage for a city + postal code
+ * - list_services: List available service types per coverage
+ * - list_offices: List Coordinadora branch offices (oficinas)
+ * - create_return: Create a reverse-logistics return guía
+ * - list_returns: List existing return guías
+ * - create_bulk_guias: Create multiple guías in a single batch
  *
  * Environment:
  *   COORDINADORA_API_KEY — API key

package/dist/index.js

@@ -11,6 +11,17 @@
  * - create_pickup: Schedule a pickup
  * - get_coverage: Check coverage for a location
  * - cancel_shipment: Cancel a shipment
+ * - get_guia_pdf: Download guía label as PDF
+ * - get_pickup: Get pickup/recolección details
+ * - cancel_pickup: Cancel a scheduled pickup
+ * - get_tracking_history: Full tracking event history
+ * - list_shipments_by_date: List shipments within a date range
+ * - validate_coverage: Validate coverage for a city + postal code
+ * - list_services: List available service types per coverage
+ * - list_offices: List Coordinadora branch offices (oficinas)
+ * - create_return: Create a reverse-logistics return guía
+ * - list_returns: List existing return guías
+ * - create_bulk_guias: Create multiple guías in a single batch
  *
  * Environment:
  *   COORDINADORA_API_KEY — API key
@@ -42,7 +53,7 @@ async function coordinadoraRequest(method, path, body) {
     }
     return res.json();
 }
-const server = new Server({ name: "mcp-coordinadora", version: "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "mcp-coordinadora", version: "0.2.0-alpha.2" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -186,6 +197,162 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["guideNumber"],
             },
         },
+        {
+            name: "get_guia_pdf",
+            description: "Download a guía label as PDF (returns base64 or URL)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    guideNumber: { type: "string", description: "Guide number" },
+                    format: { type: "string", description: "Label format (pdf, zpl). Default pdf." },
+                },
+                required: ["guideNumber"],
+            },
+        },
+        {
+            name: "get_pickup",
+            description: "Get pickup (recolección) details by id",
+            inputSchema: {
+                type: "object",
+                properties: { pickupId: { type: "string", description: "Pickup id" } },
+                required: ["pickupId"],
+            },
+        },
+        {
+            name: "cancel_pickup",
+            description: "Cancel a scheduled pickup (recolección)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pickupId: { type: "string", description: "Pickup id" },
+                    reason: { type: "string", description: "Cancellation reason" },
+                },
+                required: ["pickupId"],
+            },
+        },
+        {
+            name: "get_tracking_history",
+            description: "Get full tracking event history for a guía",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    guideNumber: { type: "string", description: "Guide number" },
+                    include_proof: { type: "boolean", description: "Include proof of delivery image/signature" },
+                },
+                required: ["guideNumber"],
+            },
+        },
+        {
+            name: "list_shipments_by_date",
+            description: "List guías created within a date range",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    date_from: { type: "string", description: "Start date (YYYY-MM-DD)" },
+                    date_to: { type: "string", description: "End date (YYYY-MM-DD)" },
+                    status: { type: "string", description: "Filter by shipment status" },
+                    page: { type: "number", description: "Page number" },
+                    page_size: { type: "number", description: "Items per page" },
+                },
+                required: ["date_from", "date_to"],
+            },
+        },
+        {
+            name: "validate_coverage",
+            description: "Validate that a city + postal code combination is covered",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    city: { type: "string", description: "City DANE code or name" },
+                    postal_code: { type: "string", description: "Postal code" },
+                    service_type: { type: "string", description: "Optional service type to validate" },
+                },
+                required: ["city", "postal_code"],
+            },
+        },
+        {
+            name: "list_services",
+            description: "List available service types for a given origin/destination",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    origin_city: { type: "string", description: "Origin city DANE code" },
+                    destination_city: { type: "string", description: "Destination city DANE code" },
+                },
+                required: ["origin_city", "destination_city"],
+            },
+        },
+        {
+            name: "list_offices",
+            description: "List Coordinadora branch offices (oficinas)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    city: { type: "string", description: "Filter by city DANE code" },
+                    department: { type: "string", description: "Filter by department" },
+                },
+            },
+        },
+        {
+            name: "create_return",
+            description: "Create a reverse-logistics return guía",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    original_guide: { type: "string", description: "Original guide number being returned" },
+                    origin_city: { type: "string", description: "Origin (current location) city DANE code" },
+                    destination_city: { type: "string", description: "Destination city DANE code" },
+                    sender: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            phone: { type: "string" },
+                            address: { type: "string" },
+                        },
+                        required: ["name", "phone", "address"],
+                    },
+                    recipient: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            phone: { type: "string" },
+                            address: { type: "string" },
+                        },
+                        required: ["name", "phone", "address"],
+                    },
+                    reason: { type: "string", description: "Return reason" },
+                    weight: { type: "number", description: "Weight in kg" },
+                },
+                required: ["origin_city", "destination_city", "sender", "recipient", "weight"],
+            },
+        },
+        {
+            name: "list_returns",
+            description: "List existing return guías",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    date_from: { type: "string", description: "Start date (YYYY-MM-DD)" },
+                    date_to: { type: "string", description: "End date (YYYY-MM-DD)" },
+                    status: { type: "string", description: "Filter by status" },
+                },
+            },
+        },
+        {
+            name: "create_bulk_guias",
+            description: "Create multiple guías in a single batch operation",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    shipments: {
+                        type: "array",
+                        description: "Array of shipment objects (same shape as create_shipment payload)",
+                        items: { type: "object" },
+                    },
+                },
+                required: ["shipments"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -255,6 +422,88 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     payload.motivo = args.reason;
                 return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("DELETE", `/guias/${args?.guideNumber}`, payload), null, 2) }] };
             }
+            case "get_guia_pdf": {
+                const params = new URLSearchParams();
+                if (args?.format)
+                    params.set("formato", args.format);
+                const qs = params.toString() ? `?${params}` : "";
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/guias/${args?.guideNumber}/pdf${qs}`), null, 2) }] };
+            }
+            case "get_pickup":
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/recolecciones/${args?.pickupId}`), null, 2) }] };
+            case "cancel_pickup": {
+                const payload = {};
+                if (args?.reason)
+                    payload.motivo = args.reason;
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("DELETE", `/recolecciones/${args?.pickupId}`, payload), null, 2) }] };
+            }
+            case "get_tracking_history": {
+                const params = new URLSearchParams();
+                if (args?.include_proof)
+                    params.set("incluirEvidencia", "true");
+                const qs = params.toString() ? `?${params}` : "";
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/guias/${args?.guideNumber}/eventos${qs}`), null, 2) }] };
+            }
+            case "list_shipments_by_date": {
+                const params = new URLSearchParams();
+                params.set("fechaDesde", args?.date_from);
+                params.set("fechaHasta", args?.date_to);
+                if (args?.status)
+                    params.set("estado", args.status);
+                if (args?.page)
+                    params.set("pagina", String(args.page));
+                if (args?.page_size)
+                    params.set("tamanoPagina", String(args.page_size));
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/guias?${params}`), null, 2) }] };
+            }
+            case "validate_coverage": {
+                const params = new URLSearchParams();
+                params.set("ciudad", args?.city);
+                params.set("codigoPostal", args?.postal_code);
+                if (args?.service_type)
+                    params.set("tipoServicio", args.service_type);
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/cobertura/validar?${params}`), null, 2) }] };
+            }
+            case "list_services": {
+                const params = new URLSearchParams();
+                params.set("ciudadOrigen", args?.origin_city);
+                params.set("ciudadDestino", args?.destination_city);
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/servicios?${params}`), null, 2) }] };
+            }
+            case "list_offices": {
+                const params = new URLSearchParams();
+                if (args?.city)
+                    params.set("ciudad", args.city);
+                if (args?.department)
+                    params.set("departamento", args.department);
+                const qs = params.toString() ? `?${params}` : "";
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/oficinas${qs}`), null, 2) }] };
+            }
+            case "create_return":
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("POST", "/devoluciones", {
+                                guiaOriginal: args?.original_guide,
+                                ciudadOrigen: args?.origin_city,
+                                ciudadDestino: args?.destination_city,
+                                remitente: args?.sender,
+                                destinatario: args?.recipient,
+                                motivo: args?.reason,
+                                peso: args?.weight,
+                            }), null, 2) }] };
+            case "list_returns": {
+                const params = new URLSearchParams();
+                if (args?.date_from)
+                    params.set("fechaDesde", args.date_from);
+                if (args?.date_to)
+                    params.set("fechaHasta", args.date_to);
+                if (args?.status)
+                    params.set("estado", args.status);
+                const qs = params.toString() ? `?${params}` : "";
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("GET", `/devoluciones${qs}`), null, 2) }] };
+            }
+            case "create_bulk_guias":
+                return { content: [{ type: "text", text: JSON.stringify(await coordinadoraRequest("POST", "/guias/lote", {
+                                guias: args?.shipments,
+                            }), null, 2) }] };
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
@@ -281,7 +530,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-coordinadora", version: "0.1.0" }, { capabilities: { tools: {} } });
+                const s = new Server({ name: "mcp-coordinadora", 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-coordinadora",
-  "version": "0.1.0",
-  "description": "MCP server for Coordinadora — Colombian courier and logistics",
+  "version": "0.2.0-alpha.2",
+  "description": "MCP server for Coordinadora \u2014 Colombian courier and logistics",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "mcp-coordinadora": "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": ["coordinadora", "courier", "logistics", "colombia", "shipping", "mcp"],
+  "keywords": [
+    "coordinadora",
+    "courier",
+    "logistics",
+    "colombia",
+    "shipping",
+    "mcp"
+  ],
   "mcpName": "io.github.codespar/mcp-coordinadora"
 }