graph TD
    subgraph "Clients"
        AI["AI Client / MCP Client"]
        DU["Discord User"]
    end

    subgraph "Platform"
        MCPS["MCP Server<br/>66 tools"]
        GW["Discord Gateway<br/>WebSocket"]
        PE["Policy Engine"]
        AGENT["Agent Service<br/>~60 tools"]
        SVC["Discord Service Layer<br/>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"]

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

graph LR
    subgraph "MCP Tools by Domain"
        G["Guild<br/>4 tools"]
        CH["Channel<br/>7 tools"]
        MSG["Message<br/>7 tools"]
        MOD["Moderation<br/>2 tools"]
        THR["Thread<br/>1 tool"]
        ROLE["Role<br/>7 tools"]
        MEM["Member<br/>6 tools"]
        WH["Webhook<br/>6 tools"]
        INV["Invite<br/>8 tools"]
        AUTO["Automation<br/>1 tool"]
        AUD["Audit<br/>1 tool"]
        REA["Reaction<br/>4 tools"]
        EVT["Event<br/>6 tools"]
        AMOD["Automod<br/>5 tools"]
    end

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

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"

cp .env.example .env
# Edit .env with your Discord bot token and other settings
docker compose up --build

curl http://localhost:8000/health

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

# 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

ghcr.io/rastrian/discord-mcp-platform:0.2.0   # exact pin
ghcr.io/rastrian/discord-mcp-platform:0.2     # track patch releases

{
  "mcpServers": {
    "discord": {
      "command": "uv",
      "args": ["run", "python", "-m", "discord_mcp_platform.mcp.server"],
      "env": {
        "DISCORD_BOT_TOKEN": "your-bot-token"
      }
    }
  }
}