{"id":29152892,"url":"https://github.com/freightcognition/mcp-slackbot","last_synced_at":"2026-03-10T09:41:06.860Z","repository":{"id":292396032,"uuid":"950653796","full_name":"freightCognition/mcp-slackbot","owner":"freightCognition","description":"A Slackbot to execute Carrier Risk Assessments directly in your Public or Private channels.","archived":false,"fork":false,"pushed_at":"2025-06-16T09:46:24.000Z","size":693,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T01:04:17.631Z","etag":null,"topics":["freight","javascript","logistics","mcp","slack","slackbot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freightCognition.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-18T13:44:51.000Z","updated_at":"2025-06-16T05:28:26.000Z","dependencies_parsed_at":"2025-06-05T11:43:32.202Z","dependency_job_id":null,"html_url":"https://github.com/freightCognition/mcp-slackbot","commit_stats":null,"previous_names":["freightcognition/mcp-slackbot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/freightCognition/mcp-slackbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freightCognition%2Fmcp-slackbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freightCognition%2Fmcp-slackbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freightCognition%2Fmcp-slackbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freightCognition%2Fmcp-slackbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freightCognition","download_url":"https://codeload.github.com/freightCognition/mcp-slackbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freightCognition%2Fmcp-slackbot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262876917,"owners_count":23378140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["freight","javascript","logistics","mcp","slack","slackbot"],"created_at":"2025-07-01T01:03:26.168Z","updated_at":"2026-03-10T09:41:06.807Z","avatar_url":"https://github.com/freightCognition.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Slackbot\r\n\r\nA Slack bot for executing Carrier Risk Assessments using the MyCarrierPortal API within your Slack environment.\r\n\r\n*Brought to you by Anthony Fecarotta of freightCognition \u0026 linehaul.ai*\r\n\r\n![MCP Slackbot Screenshot](./MCP-Slackbot-Screenshot.png)\r\n\r\n## Prerequisites\r\n\r\n- Docker and Docker Compose (Recommended)\r\n- A Slack workspace with permissions to add apps\r\n- MyCarrierPortal API access (including Bearer Token, Refresh Token, and Token Endpoint URL)\r\n- Node.js \u003e= 18.0.0 (if not using Docker)\r\n\r\n## Quick Start with Docker Compose\r\n\r\n1.  **Clone the repository:**\r\n    ```bash\r\n    git clone https://github.com/freightcognition/mcp-slackbot.git\r\n    cd mcp-slackbot\r\n    ```\r\n2.  **Configure environment variables:**\r\n    *   Copy `.env.example` to `.env`:\r\n        ```bash\r\n        cp .env.example .env\r\n        ```\r\n    *   Edit `.env` and fill in your credentials:\r\n        *   `BEARER_TOKEN`: Your MyCarrierPortal API bearer token.\r\n        *   `REFRESH_TOKEN`: Your MyCarrierPortal API refresh token.\r\n        *   `TOKEN_ENDPOINT_URL`: The URL for the MyCarrierPortal token endpoint (e.g., `https://api.mycarrierpackets.com/token`).\r\n        *   `SLACK_BOT_TOKEN`: Your Slack bot's token (starts with `xoxb-`).\r\n        *   `SLACK_SIGNING_SECRET`: Your Slack app's signing secret.\r\n        *   `SLACK_WEBHOOK_URL`: Your Slack incoming webhook URL (optional, if used for specific notifications).\r\n        *   `PORT`: The port number for the application (default: `3001`). You usually don't need to change this unless there's a port conflict on your server.\r\n\r\n3.  **Start the application:**\r\n    *   **Production mode:**\r\n        ```bash\r\n        docker compose up -d\r\n        ```\r\n    *   **Development mode (with hot-reloading and debugging):**\r\n        If you have a `docker-compose.debug.yml` (or similar for development):\r\n        ```bash\r\n        docker compose -f docker-compose.debug.yml up\r\n        ```\r\n        (Adjust the command if your development compose file has a different name.)\r\n\r\n4.  **Verify the application is running:**\r\n    ```bash\r\n    # Check container status\r\n    docker compose ps\r\n\r\n    # View logs\r\n    docker compose logs -f mcpslackbot\r\n    ```\r\n    (Assuming your service is named `mcpslackbot` in `docker-compose.yml`)\r\n\r\n## Alternative Deployment Methods (Without Docker)\r\n\r\nIf you prefer not to use Docker, you can run the application directly using Node.js.\r\n\r\n### Prerequisites for Direct Deployment\r\n- Node.js \u003e= 18.0.0\r\n- npm (Node Package Manager)\r\n\r\n### Setup and Running\r\n\r\n1.  **Install dependencies:**\r\n    ```bash\r\n    npm install\r\n    ```\r\n\r\n2.  **Configure environment variables:**\r\n    Create a `.env` file in the root of the project (as described in step 2 of the Docker setup) with all the necessary tokens and URLs.\r\n\r\n3.  **Run the application:**\r\n    *   **Development mode (e.g., using `nodemon` if configured in `package.json`):**\r\n        ```bash\r\n        npm run dev\r\n        ```\r\n        (Check your `package.json` for the exact development script command.)\r\n    *   **Production mode (e.g., using `pm2` or just `node`):**\r\n        ```bash\r\n        npm start\r\n        ```\r\n        or, if using PM2 (ensure it's installed: `npm install -g pm2`):\r\n        ```bash\r\n        npm run pm2:start  # Or pm2 start app.js --name mcp-slackbot\r\n        npm run pm2:logs   # Or pm2 logs mcp-slackbot\r\n        npm run pm2:stop   # Or pm2 stop mcp-slackbot\r\n        ```\r\n        (Check your `package.json` for `pm2` scripts.)\r\n\r\n\r\n## Slack App Configuration\r\n\r\nTo use this bot, you need to create a Slack App:\r\n\r\n1.  Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click \"Create New App\".\r\n2.  Choose \"From scratch\".\r\n3.  Name your app (e.g., \"MCP Bot\") and select your workspace.\r\n4.  **Slash Commands:**\r\n    *   Navigate to \"Features\" -\u003e \"Slash Commands\".\r\n    *   Click \"Create New Command\".\r\n    *   **Command:** `/mcp` (or your preferred command)\r\n    *   **Request URL:** `https://your-public-url.com/slack/commands` (This needs to be the publicly accessible URL where your bot is running. For local development, you'll need a tunneling service like ngrok: `ngrok http 3001`).\r\n    *   **Short Description:** e.g., \"Fetch MCP Carrier Risk Assessment\"\r\n    *   Save the command.\r\n5.  **Event Subscriptions (Optional but Recommended for more interactive features):**\r\n    *   Navigate to \"Features\" -\u003e \"Event Subscriptions\".\r\n    *   Toggle \"Enable Events\" to ON.\r\n    *   **Request URL:** `https://your-public-url.com/slack/events` (If using Event Subscriptions, update this to your events endpoint. It's often the same as Slash Commands but can be different). The URL will be verified.\r\n    *   You might subscribe to specific bot events if needed by your bot's functionality.\r\n6.  **Permissions (OAuth \u0026 Permissions):**\r\n    *   Navigate to \"Features\" -\u003e \"OAuth \u0026 Permissions\".\r\n    *   **Bot Token Scopes:** Add necessary scopes. At a minimum, you'll likely need:\r\n        *   `commands` (for slash commands)\r\n        *   `chat:write` (to send messages)\r\n        *   Possibly others depending on functionality (e.g., `users:read` if you need user info).\r\n    *   Install the app to your workspace. This will generate the **Bot User OAuth Token** (`SLACK_BOT_TOKEN` starting with `xoxb-`). \r\n7.  **App Credentials:**\r\n    *   Navigate to \"Settings\" -\u003e \"Basic Information\".\r\n    *   Find your **Signing Secret** under \"App Credentials\" (`SLACK_SIGNING_SECRET`).\r\n\r\n## Environment Variables Summary\r\n\r\n-   **`BEARER_TOKEN`**\r\n    -   **Description:** MyCarrierPortal API bearer token.\r\n    -   **Example:** `your_long_bearer_token_here`\r\n    -   **Required:** Yes\r\n\r\n-   **`REFRESH_TOKEN`**\r\n    -   **Description:** MyCarrierPortal API refresh token.\r\n    -   **Example:** `your_refresh_token_here`\r\n    -   **Required:** Yes\r\n\r\n-   **`TOKEN_ENDPOINT_URL`**\r\n    -   **Description:** MyCarrierPortal API token refresh endpoint.\r\n    -   **Example:** `https://api.mycarrierpackets.com/token`\r\n    -   **Required:** Yes\r\n\r\n-   **`SLACK_BOT_TOKEN`**\r\n    -   **Description:** Slack Bot User OAuth Token.\r\n    -   **Example:** `xoxb-your-slack-bot-token`\r\n    -   **Required:** Yes\r\n\r\n-   **`SLACK_SIGNING_SECRET`**\r\n    -   **Description:** Slack App Signing Secret.\r\n    -   **Example:** `your_slack_signing_secret`\r\n    -   **Required:** Yes\r\n\r\n-   **`SLACK_WEBHOOK_URL`**\r\n    -   **Description:** Slack Incoming Webhook URL (optional).\r\n    -   **Example:** `https://hooks.slack.com/services/...`\r\n    -   **Required:** No\r\n\r\n-   **`PORT`**\r\n    -   **Description:** Port the application listens on.\r\n    -   **Example:** `3001`\r\n    -   **Required:** No\r\n\r\n## Testing\r\n\r\nThe `package.json` might contain test scripts. For example, to test your MyCarrierPortal API token:\r\n\r\n```bash\r\n# Using Docker (if a test script is configured in your Docker setup)\r\n# docker compose run --rm mcpslackbot npm run test:token\r\n\r\n# Without Docker\r\nnpm run test:token\r\n```\r\n(This assumes a `test:token` script exists in `package.json`. Adapt as necessary.)\r\n\r\n## Security Notes\r\n\r\n-   **Never commit your `.env` file (or any file with real credentials) to version control.** The `.gitignore` file should already list `.env`.\r\n-   Keep your API tokens and secrets secure.\r\n-   Consider using a secrets management solution for production environments.\r\n-   Regularly rotate your credentials if possible.\r\n-   The `.env.example` file is a template and should **never** contain real credentials.\r\n\r\n## License\r\n\r\nThis project is licensed under version 3 of the GNU Affero General Public License (AGPL-3.0). See the `LICENSE.TXT` file for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreightcognition%2Fmcp-slackbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreightcognition%2Fmcp-slackbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreightcognition%2Fmcp-slackbot/lists"}