Content
# MyCarrierPortal-Alerts by freightCognition
<img width="496" alt="Screenshot 2025-05-31 at 4 52 33 PM" src="https://github.com/user-attachments/assets/c701f446-8181-4e32-8ddd-7dcb895cddfd" /> <p>
Version 0.1.2
This application integrates MyCarrierPackets (MCP) webhooks with Slack using Socket Mode. It listens for MCP webhook events and forwards formatted messages to a specified Slack channel.
## Author
This application was built by Anthony Fecarotta (https://github.com/fakebizprez) of `freight.Cognition`.
## Features
* Receives MCP webhooks.
* Verifies webhook signatures for security.
* Uses Slack Socket Mode for real-time messaging.
* Formats messages for various MCP event types.
* Includes a health check endpoint (`/health`).
* Configured for Docker deployment.
## Prerequisites
Before you begin, ensure you have the following installed:
* [Node.js](https://nodejs.org/) (version 14.0.0 or higher, as specified in `package.json`)
* [pnpm](https://pnpm.io/installation)
## Installation and Configuration
1. **Clone the repository:**
```bash
git clone https://github.com/your-username/mcp-alerts.git # Replace with the actual repo URL if different
cd mcp-alerts
```
2. **Install dependencies:**
```bash
pnpm install
```
3. **Create and Configure the Slack App:**
Before you can configure the environment variables, you need to create a Slack app and obtain the necessary tokens. Follow these steps:
a. **Go to Your Slack Apps:**
Navigate to [https://api.slack.com/apps](https://api.slack.com/apps) and click "Create New App".
b. **Create an App:**
Choose "From scratch".
Enter an "App Name" (e.g., "MCP Alerts") and select the Slack workspace where you want to install the app.
Click "Create App".
c. **Enable Socket Mode:**
In the left sidebar, under "Settings", click on "Socket Mode".
Toggle the switch to "Enable Socket Mode".
You'll be prompted to generate an App-Level Token. Enter a name for the token (e.g., "mcp-socket-token") and click "Generate".
**Copy this token (it will start with `xapp-`) and save it. This will be your `SLACK_APP_TOKEN`.**
d. **Add Bot Scopes:**
In the left sidebar, under "Features", click on "OAuth & Permissions".
Scroll down to the "Scopes" section.
Under "Bot Token Scopes", click "Add an OAuth Scope" and add the following scope:
* `chat:write`: Allows the app to send messages to channels it's a part of.
e. **Install App to Workspace:**
At the top of the "OAuth & Permissions" page, click "Install to Workspace".
Follow the prompts to authorize the app.
Once installed, you will see a "Bot User OAuth Token".
**Copy this token (it will start with `xoxb-`) and save it. This will be your `SLACK_BOT_TOKEN`.**
f. **Add Bot to Channel(s):**
Open your Slack client.
Go to the channel where you want the MCP alerts to be posted.
Type `/invite @your-app-name` (replace `your-app-name` with the name you gave your Slack app) and send the message, or use the channel settings to add the app/bot user.
4. **Configure environment variables:**
Create a `.env` file in the root of the project by copying the example file:
```bash
cp .env.example .env
```
Then, open the `.env` file and update it with your specific credentials and settings:
* `SLACK_BOT_TOKEN`: Your Slack Bot Token (starts with `xoxb-`). This token is used by the app to interact with the Slack API.
* `SLACK_APP_TOKEN`: Your Slack App-Level Token (starts with `xapp-`). This token is used for Socket Mode connections.
* `SLACK_CHANNEL`: The ID or name of the Slack channel where messages will be posted (e.g., `C1234567890` or `mcp-alerts`).
* `MCP_WEBHOOK_SECRET`: Your MCP Webhook Signing Secret. This is used to verify the authenticity of incoming webhooks from MyCarrierPackets.
* `MCP_WEBHOOK_URL_PATH`: The path on your server where the application will listen for MCP webhooks (default is `/webhooks/mcp`).
* `PORT`: The port on which the Express server will run (default is `3001`).
* `PUBLIC_APP_URL`: (Optional) The public URL of your application, especially useful if you're using Cloudflare Tunnel for on-premise deployment. If set, the application will log this URL at startup.
## Running the Application
* **To start the application in production mode:**
```bash
pnpm start
```
* **To start the application in development mode (with hot reloading using nodemon):**
```bash
pnpm dev
```
The application will be accessible at `http://localhost:PORT` (e.g., `http://localhost:3001` if using the default port).
## Testing
This application includes a utility to test the webhook signature verification and message formatting.
1. Ensure your application is running (`pnpm start` or `pnpm dev`).
2. You can send a test payload to your local webhook endpoint. The `test/webhook.js` script can be used for this. Modify `test-payload.json` with the desired event type and data.
3. Run the test script:
```bash
pnpm test:webhook
```
This script will send the payload defined in `test-payload.json` to the `/webhooks/mcp` endpoint of your locally running application.
## Docker Deployment
This application includes a `Dockerfile` and `docker-compose.yml` for containerized deployment. Refer to those files for more details on building and running the application with Docker.
### On-Premise Deployment with Cloudflare Tunnel
If you plan to run this application on an on-premise server and need to expose it to the public internet (e.g., to receive webhooks from MyCarrierPackets), using Cloudflare Tunnel is a recommended approach for security and simplicity.
1. **Set up Cloudflare Tunnel:** Follow Cloudflare's documentation to install `cloudflared` on your on-premise server and create a tunnel. Configure the tunnel to point to your application's local address (e.g., `http://localhost:3001` if your application is listening on port 3001).
2. **Public URL:** Cloudflare Tunnel will provide you with a public URL (e.g., `https://your-tunnel-subdomain.trycloudflare.com` or a custom domain like `https://mcp-alerts.linehaul.cloud`).
3. **Configure MCP Webhook Provider:** Update your MyCarrierPackets webhook configuration to send webhooks to your public Cloudflare Tunnel URL, appending the `MCP_WEBHOOK_URL_PATH`. For example: `https://mcp-alerts.linehaul.cloud/webhooks/mcp`.
4. **Environment Variable for Public URL (Optional but Recommended):**
You can set the `PUBLIC_APP_URL` in your `.env` file to your Cloudflare Tunnel's base URL (e.g., `PUBLIC_APP_URL=https://mcp-alerts.linehaul.cloud`). If set, the application will log this public URL at startup for clarity.
## Webhook Event Types Handled
* `carrier.packet.completed`
* `carrier.incident_report.created`
* `carrier.incident_report.updated`
* `carrier.incident_report.retracted`
* `carrier.vin_verification.completed`
* `carrier.user_verification.completed`
