# Discord Integration for Poke

An MCP (Model Context Protocol) server that connects your Discord account to [Poke](https://poke.com), allowing you to interact with Discord through natural conversation in Apple Messages, Telegram, WhatsApp, and RCS.

## Features

- **Read Messages** — Ask Poke "What's happening in #general?"
- **Send Messages** — "Send a message to #announcements that the deploy is done"
- **DMs** — "DM @alice and ask if she's free at 3pm"
- **Server Management** — "List my servers" or "Show channels in My Server"
- **Message Actions** — "Delete that message", "Edit my last message", "Add a 👍 reaction"
- **User Lookup** — "Who is @bob on Discord?"

## Prerequisites

- **Node.js** 22+ (or Docker)
- A **Discord Bot Token**
- A publicly accessible URL (use ngrok for local development, or deploy to Railway/Fly.io)

### Creating a Discord Bot

1. Go to https://discord.com/developers/applications and click **New Application**
2. Go to the **Bot** tab, click **Add Bot**, then **Reset Token** to get your token
3. Under **Privileged Gateway Intents**, enable **Message Content Intent**
4. Go to **OAuth2 > URL Generator**, select `bot` scope, add permissions:
   - Read Messages
   - Send Messages
   - Read Message History
   - Add Reactions
   - Manage Messages
5. Use the generated URL to invite the bot to your servers

## Quick Start

```bash
# Copy the env template and fill in your values
cp .env.example .env

# Run with Docker (pulls from GHCR)
docker compose --env-file .env up -d
```

Your Poke MCP Server URL will be `http://localhost:3000/sse` (expose with [ngrok](#ngrok) or deploy to a cloud provider).

### Run locally (no Docker)

```bash
git clone https://github.com/thesammykins/poke_discord.git discord-poke
cd discord-poke
pnpm install
pnpm build
cp .env.example .env  # fill in DISCORD_TOKEN
source .env && node dist/index.js
```

### Connect to Poke

1. Go to https://poke.com/integrations/new
2. Enter **Name**: Discord
3. Enter **MCP Server URL**: your server URL with `/sse` (e.g. `https://abc123.ngrok-free.app/sse`)
4. Enter **API Key**: Your Discord bot token
5. Click **Create Integration**
6. Try "List my Discord servers" in Poke

## Development

```bash
pnpm install       # Install dependencies
pnpm dev           # Run with hot reload
pnpm typecheck     # TypeScript check
pnpm test          # Run tests
pnpm build         # Production build
```

## Tools

| Tool | Description |
|------|-------------|
| discord_list_guilds | List servers the bot is in |
| discord_list_channels | List channels in a server |
| discord_read_messages | Read recent messages with optional keyword filter |
| discord_send_message | Send a message with optional embeds |
| discord_send_dm | Send a direct message to a user |
| discord_get_user | Get user profile info |
| discord_add_reaction | Add an emoji reaction to a message |
| discord_delete_message | Delete a message |
| discord_edit_message | Edit a message |
| discord_search_guild_members | Search server members |
| discord_pin_message | Pin a message to a channel |
| discord_unpin_message | Unpin a message |

## Docker Image

Prebuilt images are published to GitHub Container Registry:

```
ghcr.io/thesammykins/poke_discord:main
```

Tags available: `main`, `v1.0.0`, `v1.0`, `v1`, and per-commit SHA.

## Deployment

Ready-to-use configs live in [deploy/](deploy/).

### ngrok (local dev / free tier)

```bash
ngrok http --config=deploy/ngrok.yml 3000
```

Use your ngrok domain as `PUBLIC_URL`.

### Pangolin (self-hosted)

```bash
docker compose -f deploy/docker-compose.pangolin.yml --env-file .env up -d
```

Adds Traefik labels for automatic routing. Set `PANGOLIN_HOST` to your domain.

### Fly.io (free tier)

```bash
fly deploy -c deploy/fly.toml
```

Free allowance: 3 shared-cpu-1x VMs, 256MB RAM. Set `DISCORD_TOKEN` via `fly secrets set`.

### Railway (free tier)

One-click from `deploy/railway.json`. Connect your GitHub repo and Railway auto-deploys on push.

### Render (free tier)

Uses `deploy/render.yaml` as a Blueprint. Connect your repo and Render builds + deploys automatically.

## Architecture

```
User (Messages) ←→ Poke (AI) ←→ MCP Server (SSE) ←→ Discord REST API
```

## License

MIT