The Claude Code team designed a Discord Gateway Service for user communication via Discord. This article summarizes the key architecture decisions and user_comm Agent design.

1. Overall Architecture

Components

Message Flow

flowchart LR
    subgraph D[Discord]
        U[User]
    end
    subgraph G[Gateway :8081]
        WS[WebSocket]
        API[REST API]
        SSE[SSE]
    end
    subgraph A[Claude Code Team]
        UC[user_comm]
        GCP[gcp-mcp]
        OCI[oci-mcp]
        DB[db-mcp]
    end

    U --> WS
    WS --> UC
    UC --> API
    API --> GCP
    API --> OCI
    API --> DB
    GCP --> UC
    OCI --> UC
    DB --> UC
    UC --> SSE
    SSE --> U

2. user_comm Agent (User Communication Handler)

Role and Responsibilities

The user_comm Agent is a member of the Claude Code team, communicating with users through Discord channels and collaborating with other agents.

Internal Structure

flowchart TB
    subgraph UC[user_comm Agent]
        DBot[Discord Bot]
        Agent[UserCommAgent]
        TComm[TeamCommunicator]
        DBot <--> Agent
        Agent <--> TComm
    end
    subgraph DAPI[Discord API]
        M[Messages]
        B[Buttons]
        T[Threads]
    end
    subgraph O[Other Agents]
        GCP[gcp-mcp]
        OCI[oci-mcp]
        AL[alert-mcp]
    end

    DBot <--> M
    DBot <--> B
    DBot <--> T
    TComm --> GCP
    TComm --> OCI
    TComm --> AL

Message Types

class MessageType(Enum):
    TASK_REQUEST = "task_request"       # Task request
    NOTIFICATION = "notification"        # Notification
    OPINION_REQUEST = "opinion_request"  # Opinion request
    OPINION_RESPONSE = "opinion_response" # Opinion response
    STATUS_REPORT = "status_report"      # Status report
    ERROR = "error"                      # Error

Key Function Flows

Input Reception (Discord -> Agent)

User: "@gcp-monitor check server status"
  -> DiscordBot.on_message
  -> UserCommAgent._parse_command (target: gcp-monitor)
  -> TeamCommunicator.send_to_agent
  -> Discord: "Request forwarded to gcp-monitor."

Opinion Request (Agent -> Discord)

gcp-monitor: "Clean up disk?" -> user_comm
  -> DiscordBot.ask_opinion (wait for button or reply)
  -> User response
  -> TeamCommunicator.send_to_agent (forward response)

Notification/Report (Agent -> Discord)

oci-monitor: "Disk 92% warning" -> user_comm
  -> DiscordBot.send_message (Embed format)

3. Lightweight Architecture Without Redis

Why Remove Redis?

Conclusion: In-memory is sufficient for single-instance environments

Gateway Structure

flowchart TB
    subgraph GW[Gateway Service]
        Bot[Discord Bot]
        subgraph C[Core Components]
            Lock[Thread Lock]
            Cache[Message Cache]
            SSEMgr[SSE Manager]
        end
    end
    DAPI[Discord API] <--> Bot
    Bot --> Lock
    Bot --> Cache
    Bot --> SSEMgr
    SSEMgr --> Clients[WebSocket Clients]

Component Details

4. MCP Selection: 4-Stage Hybrid

Selection Priority

Fallback Order

flowchart TD
    A[Message Received] --> B{Slash Command?}
    B -->|Yes| C[Route to MCP]
    B -->|No| D{Mention?}
    D -->|Yes| C
    D -->|No| E{Keyword?}
    E -->|Yes| C
    E -->|No| F{Channel Default?}
    F -->|Yes| C
    F -->|No| G[Broadcast]

Slash Command List

5. Thread Lock Rules

Lock Behavior

sequenceDiagram
    participant M1 as gcp-mcp
    participant GW as Gateway
    participant M2 as oci-mcp
    participant DT as Discord Thread

    Note over M1,DT: Lock Acquisition
    M1->>+GW: Lock request
    GW-->>-M1: Lock acquired
    M1->>DT: Send response

    Note over M2,GW: Lock Conflict
    M2->>GW: Lock request
    GW-->>M2: Lock failed

    Note over M1,GW: 5min timeout
    GW->>GW: Auto-release lock

    Note over M2,GW: Lock Retry
    M2->>+GW: Lock request
    GW-->>-M2: Lock acquired

Lock API

Request/Response Example

Lock Acquire Request

POST /api/threads/123456/acquire
{
  "agent_name": "gcp-mcp",
  "timeout": 300
}

Lock Acquire Response

{
  "acquired": true,
  "thread_id": "123456",
  "agent": "gcp-mcp"
}

6. MCP Tools (8)

Tool List

Tool Relationships

flowchart LR
    subgraph Lock[Lock Tools]
        Acquire[acquire_thread]
        Release[release_thread]
    end
    subgraph Thread[Thread Tools]
        Create[create_thread]
        List[list_threads]
        Archive[archive_thread]
    end
    subgraph Msg[Message Tools]
        Send[send_message]
        Get[get_messages]
        Wait[wait_for_message]
    end

    Acquire --> Create
    Create --> Send
    Send --> Release

Usage Examples

# Send message
discord_send_message(
    channel_id="123456789",
    content="Server status: OK"
)

# Create thread
discord_create_thread(
    channel_id="123456789",
    message_id="987654321",
    name="Status Check"
)

# Acquire lock
discord_acquire_thread(
    thread_id="111222333",
    agent_name="gcp-mcp",
    timeout=300
)

7. File Structure

flowchart TB
    subgraph P[server_monitor/]
        subgraph Gw[gateway/]
            M1[main.py]
            M2[discord_ws.py]
            M3[thread_lock.py]
            M4[sse.py]
        end
        subgraph Uc[user_comm/]
            A1[agent.py]
            A2[discord_bot.py]
            A3[team_comm.py]
        end
        subgraph Mcp[discord_mcp/]
            S1[server.py]
        end
        subgraph Sh[mcp_shared/]
            MO[monitor/]
        end
        subgraph Doc[docs/]
            D1[MCP_SELECTION_STRATEGY.md]
            D2[MCP_ROUTING_POLICY.md]
        end
    end

Directory Description

8. How to Run

Local Execution

# Start Gateway Service
uvicorn gateway.main:app --host 0.0.0.0 --port 8081

# Start user_comm Agent (standalone mode)
python main.py --standalone

# Start user_comm Agent (team mode)
python main.py --team server-monitor

# Health check
curl http://localhost:8081/health

# Response
{"status": "healthy", "discord_connected": true}

Claude Code MCP Configuration

// ~/.claude/settings.json
{
  "mcpServers": {
    "discord-gateway": {
      "command": "python3",
      "args": ["/path/to/discord_mcp/server.py"],
      "env": {
        "GATEWAY_URL": "http://localhost:8081"
      }
    }
  }
}

9. Roadmap

Phase 1: Complete

• FastAPI Gateway Service
• Discord WebSocket connection
• Thread Lock (In-Memory)
• SSE broadcast
• MCP Server (8 tools)

Phase 2: In Progress

• user_comm Agent implementation
• Slash command implementation
• Channel default MCP settings
• Keyword auto-detection
• Routing configuration file

Phase 3: Optional

• API authentication (API Key)
• Rate Limiting
• Message persistence (SQLite)

Conclusion

We chose a strategy of starting with a lightweight architecture and expanding when needed.

The current structure is sufficient for single instances, and we plan to expand incrementally as traffic grows. The user_comm Agent systematizes user communication and improves collaboration with other agents on the team.

Korean Version: 한국어 버전