mermaid graph TD subgraph "Clients" AI["AI Client / MCP Client"] DU["Discord User"] end subgraph "Platform" MCPS["MCP Server
66 tools"] GW["Discord Gateway
WebSocket"] PE["Policy Engine"] AGENT["Agent Service
~60 tools"] SVC["Discord Service Layer
107 async REST methods"] end AI -->|MCP call| MCPS DU -->|"@mention"| GW MCPS --> PE GW --> AGENT AGENT --> PE PE --> SVC SVC -->|API v10| DISC["Discord API"] ``` ```mermaid graph LR subgraph "Authorization Flow" direction TB A1["1. MCP client auth"] --> A2["2. Workspace membership"] A2 --> A3["3. Guild installation check"] A3 --> A4["4. Platform role/permission"] A4 --> A5["5. Channel policy check"] A5 --> A6["6. Discord bot permission"] A6 --> A7["7. Rate-limit check"] A7 --> A8["8. Execute & audit"] end ``` ## Features ### MCP Server (66 tools) ```mermaid graph LR subgraph "MCP Tools by Domain" G["Guild
4 tools"] CH["Channel
7 tools"] MSG["Message
7 tools"] MOD["Moderation
2 tools"] THR["Thread
1 tool"] ROLE["Role
7 tools"] MEM["Member
6 tools"] WH["Webhook
6 tools"] INV["Invite
8 tools"] AUTO["Automation
1 tool"] AUD["Audit
1 tool"] REA["Reaction
4 tools"] EVT["Event
6 tools"] AMOD["Automod
5 tools"] end ``` | Domain | Tools | |--------|-------| | Guild | list, get, modify, incident_actions (lockdown) | | Channel | list, get, create, edit, delete, edit_permissions, delete_permissions | | Message | list_recent, send, get, edit, send_embed, delete, bulk_delete | | Moderation | delete, bulk_delete | | Thread | create | | Role | list, create, modify, delete, reorder, assign, remove | | Member | get, list, kick, ban, timeout, unban | | Webhook | create, list, get, modify, delete, execute | | Invite | create, list, get, delete, target.add, target.remove, target.bulk_add, target.bulk_remove | | Automation | draft | | Audit | list | | Reaction | add, remove, list, remove_user | | Event | list, get, create, update, delete, list_users | | Automod | list, get, create, update, delete | | Pins | pin.list, pin.add, pin.remove | All state-changing tools support dry-run (default on). Risky operations require explicit confirmation. Every write is audited. ### Conversational Agent ```mermaid sequenceDiagram participant U as Discord User participant GW as Gateway participant AG as Agent Service participant LLM as LLM API participant BOT as Discord Bot U->>GW: @mention bot GW->>AG: MESSAGE_CREATE event AG->>AG: Check guild + channel allowlist AG->>AG: Load channel conversation history AG->>LLM: Send history + 60 tool definitions loop Tool-use loop (max 10 iterations) LLM-->>AG: Tool call or text response AG->>BOT: Execute tool call BOT-->>AG: Tool result AG->>LLM: Send tool result end AG->>BOT: Send final response to channel BOT-->>U: Bot reply ``` - ~60 agent tools covering the full Discord API surface - Per-channel conversation history - Per-user cooldown - Admin-controlled via `/allow-chat` and `/disallow-chat` slash commands ### Data Model ```mermaid erDiagram User ||--o{ WorkspaceMembership : "belongs to" User ||--o{ OAuthAccount : "has" Workspace ||--o{ WorkspaceMembership : "contains" Workspace ||--o{ GuildInstallation : "owns" Workspace ||--o{ MCPClient : "issues" GuildInstallation ||--o{ BotConfig : "has" GuildInstallation ||--o{ GuildPolicy : "enforces" GuildInstallation ||--o{ ChannelPolicy : "enforces" GuildInstallation ||--o{ Automation : "runs" GuildInstallation ||--o{ AllowedChatChannel : "allows" AuditEvent }o--|| Workspace : "records in" ``` ### Infrastructure - Discord Gateway WebSocket with auto-reconnect - Discord REST client with rate limit tracking and automatic retry - Scope-based permission engine with guild/channel allowlists - Audit logging with PII redaction - 14 database models (PostgreSQL) - Redis for caching and rate-limit coordination ## Quick Start ```bash cp .env.example .env # Edit .env with your Discord bot token and other settings docker compose up --build ``` Health check: ```bash curl http://localhost:8000/health ``` ## Development ```bash make install # install dependencies make dev # run dev server with reload make test # run tests (no real Discord token needed) make lint # ruff check make format # ruff format make typecheck # mypy make version # print the current version make up # docker compose up --build (dev: source mounted, auto-reload) make down # docker compose down ``` `docker compose up` automatically merges `docker-compose.override.yml`, which mounts the source tree and enables `--reload`. For a production-like run without dev conveniences: `docker compose -f docker-compose.yml up --build`. ## Spec Coverage The official [Discord OpenAPI spec](https://github.com/discord/discord-api-spec) is vendored at `specs/openapi.json` and treated as the source of truth for endpoint coverage. - [`specs/COVERAGE.md`](specs/COVERAGE.md) — generated report comparing spec endpoints with the REST client and MCP tools (regenerate with `python3 scripts/coverage_report.py`). - `scripts/fetch-discord-spec.sh` — refreshes the vendored spec; a scheduled agent (Hermes cron, Saturdays 06:00 America/Sao_Paulo) opens a sync PR whenever Discord publishes spec changes. - `python3 scripts/coverage_report.py --check` — regression guard: fails if the number of in-scope implemented endpoints drops below the baseline in `specs/.coverage-baseline`. ## Releases & Versioning The version lives in exactly one place: `src/discord_mcp_platform/_version.py`. `pyproject.toml` declares `dynamic = ["version"]` and hatchling reads it from there; the FastAPI app and `/health` report the same value. To cut a release: ```bash # 1. Bump the version and refresh the committed lockfile $EDITOR src/discord_mcp_platform/_version.py # __version__ = "0.2.0" uv lock make release-check # tests + lint + mypy # 2. Commit and tag git add src/discord_mcp_platform/_version.py uv.lock git commit -m "chore(release): v0.2.0" git tag v0.2.0 git push origin main --tags ``` Pushing a `v*` tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml), which: 1. runs the test suite, ruff and mypy; 2. fails if the tag does not match `__version__` (or the lockfile is stale); 3. builds and pushes `ghcr.io/rastrian/discord-mcp-platform` with tags ``, `.` and `latest` — pre-release tags (e.g. `v1.2.0-rc1`) only get the full version tag, never the rolling ones; 4. creates a GitHub Release with auto-generated notes. The recommended way to deploy (e.g. the k3s cluster) is to pin the versioned image: ```text ghcr.io/rastrian/discord-mcp-platform:0.2.0 # exact pin ghcr.io/rastrian/discord-mcp-platform:0.2 # track patch releases ``` The image is multi-stage, runs as a non-root user, and serves `/health` for probes. Currently `linux/amd64` only (`arm64` is a follow-up). ## Environment Variables Key variables (see `.env.example` for full list): | Variable | Description | |----------|-------------| | `DISCORD_BOT_TOKEN` | Discord bot token | | `DISCORD_CLIENT_ID` | Discord OAuth client ID | | `DISCORD_CLIENT_SECRET` | Discord OAuth client secret | | `DATABASE_URL` | PostgreSQL connection string | | `REDIS_URL` | Redis connection string | | `ALLOWED_GUILD_IDS` | Comma-separated guild allowlist (empty = all) | | `MCP_TRANSPORT` | `http` or `stdio` | | `ENABLE_GATEWAY` | Enable Discord Gateway WebSocket | | `AGENT_ENABLED` | Enable conversational AI agent | | `AGENT_API_KEY` | LLM API key for the agent | ## MCP Client Configuration Local STDIO mode: ```json { "mcpServers": { "discord": { "command": "uv", "args": ["run", "python", "-m", "discord_mcp_platform.mcp.server"], "env": { "DISCORD_BOT_TOKEN": "your-bot-token" } } } }

Discord MCP Server

Installation