# Parcel MCP Server

A mock MCP (Model Context Protocol) server that simulates small parcel and package operations. Designed for use with AI agents, it exposes 12 tools covering the common actions a driver or package processing centre would need to remedy recipient issues.

## Live Server

Hosted on Railway — always on, no setup required.

| | |
|---|---|
| **Health check** | https://parcel-mcp-server-production.up.railway.app/health |
| **MCP endpoint** | https://parcel-mcp-server-production.up.railway.app/mcp |
| **OAuth token URL** | https://parcel-mcp-server-production.up.railway.app/oauth/token |

## Salesforce Agentforce Registry Connection

To register this server in the Salesforce Agentforce Registry, use the following settings:

| Field | Value |
|---|---|
| MCP Server Name | Parcel MCP Server |
| Server URL | `https://parcel-mcp-server-production.up.railway.app/mcp` |
| Authentication Method | OAuth 2.0 |
| Identity Provider URL | `https://parcel-mcp-server-production.up.railway.app/oauth/token` |
| Scope | `read` |
| Client ID | any value |
| Client Secret | any value |

> The OAuth endpoint is a mock — it accepts any client ID and secret and returns a valid bearer token.

## Tools

| Tool | Description |
|---|---|
| `list_drivers` | List all active drivers with IDs, names, routes, and package counts — use this first to look up a driver by name |
| `track_package` | Look up status, location history, and delivery details by tracking number |
| `list_packages_for_driver` | List all packages assigned to a driver with status and recipient info |
| `update_delivery_status` | Log delivery attempts, exceptions, or completions |
| `correct_delivery_address` | Submit a corrected address for an invalid or undeliverable package |
| `schedule_redelivery` | Book a redelivery with preferred date and time window |
| `request_hold_for_pickup` | Hold a package at the nearest facility for recipient pickup |
| `initiate_return_to_sender` | Mark a package for return with a reason code |
| `update_recipient_contact` | Update phone or email for delivery notifications |
| `report_damaged_package` | File a damage claim with severity level |
| `get_facility_info` | Get hours, address, and accessibility info for the holding facility |
| `send_delivery_notification` | Send SMS or email notification to the recipient |
| `get_route_summary` | Get a driver's route stats — delivered, pending, exceptions |

## Mock Data

Ten packages across four driver routes cover all major delivery scenarios:

| Tracking # | Status | Recipient | Driver |
|---|---|---|---|
| `1Z999AA10123456784` | OUT_FOR_DELIVERY | Jane Smith, Denver CO | DRV-101 Carlos Rivera |
| `1Z999AA10234567895` | DELIVERY_EXCEPTION | Bob Johnson, Denver CO | DRV-101 Carlos Rivera |
| `1Z999AA10567890128` | DELIVERED | Susan Park, Denver CO | DRV-101 Carlos Rivera |
| `1Z999AA10345678906` | HELD_AT_FACILITY | Maria Garcia, Aurora CO | DRV-102 Priya Patel |
| `1Z999AA10456789017` | PENDING_ADDRESS_CORRECTION | Tom Lee, Denver CO | DRV-102 Priya Patel |
| `1Z999AA10678901239` | DELIVERED | David Kim, Aurora CO | DRV-102 Priya Patel |
| `1Z999AA10789012340` | OUT_FOR_DELIVERY | Rachel Torres, Denver CO | DRV-103 Marcus Webb |
| `1Z999AA10890123451` | DELIVERY_EXCEPTION | Kevin Nguyen, Denver CO | DRV-103 Marcus Webb |
| `1Z999AA10901234562` | IN_TRANSIT | Amanda Foster, Denver CO | DRV-104 Lisa Chen |
| `1Z999AA11012345673` | REDELIVERY_SCHEDULED | Chris Mendoza, Denver CO | DRV-104 Lisa Chen |

Four drivers are pre-loaded:

| Driver ID | Name | Route | Packages |
|---|---|---|---|
| `DRV-101` | Carlos Rivera | ROUTE-A | 3 |
| `DRV-102` | Priya Patel | ROUTE-B | 3 |
| `DRV-103` | Marcus Webb | ROUTE-C | 2 |
| `DRV-104` | Lisa Chen | ROUTE-D | 2 |

Use `list_drivers` to look up driver IDs by name before calling driver-specific tools.

## Architecture

The diagram below shows the full request flow from Agentforce through the Salesforce Apex invocable action to this MCP server.

```
┌─────────────────┐     invoke action      ┌──────────────────────┐
│   Agentforce    │ ─────────────────────► │  TrackParcelAction   │
│  Agent Studio   │ ◄─────────────────────  │  (@InvocableMethod)  │
└─────────────────┘     response           └──────────┬───────────┘
                                                       │
                              POST /oauth/token        │  POST /mcp
                         ┌─────────────────────────────┤
                         ▼                             ▼
               ┌──────────────────┐       ┌───────────────────────┐
               │   OAuth Server   │       │   Parcel MCP Server   │
               │ client_creds JWT │       │   JSON-RPC 2.0        │
               └──────────────────┘       │   tools/call          │
                                          └───────────┬───────────┘
                                                      │
                                          ┌───────────▼───────────┐
                                          │   Tool Handler        │
                                          │  track_package etc.   │
                                          └───────────────────────┘
```

An interactive HTML visualization (`mcp-visualization.html`) is included in the repo — open it in a browser to animate the full request/response flow, explore all 12 tools, and inspect parsed and raw JSON-RPC responses.

## Running Locally

No npm install required — the server uses only Node.js built-ins.

```bash
node server.js
# Server runs on http://localhost:3333
```

Or use the included launcher which starts the server and an ngrok tunnel together:

```bash
bash launch.command
```

The launcher prints your public ngrok URL and the Salesforce connection settings automatically.

## Redeploying to Railway

Any changes to `server.js` can be redeployed with:

```bash
railway up
```

Make sure you have the [Railway CLI](https://docs.railway.app/develop/cli) installed and are logged in (`railway login`).