Discord Decision MCP — 아키텍처 설계문서

discord-decision/
├── discord_mcp/              # 메인 패키지
│   ├── __init__.py
│   ├── server.py             # MCP 서버 진입점
│   ├── config.py             # 환경변수 설정 관리
│   │
│   ├── bot/                  # Discord API 클라이언트
│   │   ├── __init__.py
│   │   ├── client.py         # REST API 클라이언트 (httpx)
│   │   └── gateway.py        # WebSocket 게이트웨이 (수신 전용)
│   │
│   ├── decision/             # 결정 요청 관리
│   │   ├── __init__.py
│   │   ├── manager.py        # 결정 요청 생명주기 관리
│   │   ├── poller.py         # Discord Polling 및 응답 대기
│   │   ├── parser.py         # 사용자 응답 파싱
│   │   └── state.py          # 상태 영속화 (JSON 파일)
│   │
│   ├── tools/                # MCP Tools 구현
│   │   ├── __init__.py
│   │   ├── ask.py            # discord_ask_decision
│   │   ├── notify.py         # discord_notify
│   │   ├── report.py         # discord_report_progress
│   │   ├── status.py         # discord_check_pending
│   │   ├── inbox.py          # discord_read_inbox, discord_clear_inbox
│   │   └── _templates.py     # Discord 메시지 템플릿
│   │
│   └── daemon/               # 감시 데몬
│       ├── __init__.py
│       ├── watcher.py        # Discord 채널 감시 (discord-watch CLI)
│       └── inbox.py          # Inbox 파일 관리
│
├── scripts/                  # 유틸리티 스크립트
│   └── start-discord-watch.sh
│
├── tests/                    # 테스트 스위트
│   ├── __init__.py
│   ├── test_parser.py
│   └── test_state.py
│
├── CLAUDE.md                 # Claude Code 프로젝트 지침
├── README.md                 # 프로젝트 설명
├── pyproject.toml            # 프로젝트 설정 및 의존성
└── mcp.json.example          # MCP 설정 예시

mcp = FastMCP(name="discord-decision-mcp")
# Tool 등록
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

discord-mcp  # 또는 python -m discord_mcp.server

class DiscordClient:
    async def send_message(channel_id, content, embeds=None)
    async def get_messages(channel_id, after=None, limit=50)
    async def create_thread(channel_id, name, first_message)
    async def archive_thread(thread_id)

class GatewayClient:
    async def run()     # 이벤트 수신 시작
    async def stop()    # 연결 종료

class DecisionManager:
    async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
    async def restore_pending() -> list[DecisionState]

class DecisionPoller:
    async def wait(state: DecisionState) -> PollResult

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str  # 재질문 메시지 생성

class DecisionState(BaseModel):
    question_id: str
    project: str
    question: str
    context: str
    options: list[str]
    timeout_seconds: float | None
    thread_id: str
    message_id: str
    asked_at: str
    status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
    clarify_attempts: int
    resolved_at: str | None
    resolution: str | None
    selected_option: str | None

class StateStore:
    def save(state: DecisionState)
    def load(question_id: str) -> DecisionState | None
    def load_all_pending() -> list[DecisionState]
    def resolve(question_id, resolution, selected_option)
    def is_duplicate(question: str) -> bool

discord-watch --interval 10
# 또는
tmux new-session -d -s discord-watch 'uv run discord-watch'

class InboxMessage:
    message_id: str
    channel_id: str
    thread_id: str | None
    author: str
    author_id: str
    content: str
    timestamp: str
    read: bool

class InboxStore:
    def add_message(msg: InboxMessage)
    def get_unread() -> list[InboxMessage]
    def mark_read(message_id: str)
    def clear_read()  # 읽은 메시지 삭제

┌─────────────────┐
│  Claude Code    │
└────────┬────────┘
         │ discord_ask_decision()
         ▼
┌─────────────────────────────────────┐
│  MCP Server (server.py)             │
│  ┌───────────────────────────────┐  │
│  │ DecisionManager.ask()         │  │
│  │  1. 중복 확인                  │  │
│  │  2. Thread 생성               │  │
│  │  3. 상태 파일 저장             │  │
│  └───────────────┬───────────────┘  │
└──────────────────┼──────────────────┘
                   ▼
┌─────────────────────────────────────┐
│  DecisionPoller.wait()              │
│  ┌───────────────────────────────┐  │
│  │ Polling 루프                   │  │
│  │  1. tmux 상태 업데이트         │  │
│  │  2. Discord API 호출          │  │
│  │  3. 응답 파싱                  │  │
│  │  4. 모호하면 재질문            │  │
│  └───────────────┬───────────────┘  │
└──────────────────┼──────────────────┘
                   │
         ┌─────────┴─────────┐
         ▼                   ▼
┌───────────────────┐  ┌──────────────────┐
│  Discord REST API │  │  Discord Thread  │
│    (client.py)    │  │                  │
└───────────────────┘  └────────┬─────────┘
                                 │
                        ┌────────▼────────┐
                        │  사용자 응답    │
                        └────────┬────────┘
                                 ▼
                        ┌─────────────────┐
                        │  parser.py      │
                        │  - 선택지 매칭  │
                        │  - 모호성 감지  │
                        └────────┬────────┘
                                 ▼
                        ┌─────────────────┐
                        │  store.resolve()│
                        └────────┬────────┘
                                 ▼
                        ┌─────────────────┐
                        │  PollResult     │
                        │  반환           │
                        └─────────────────┘

┌─────────────────────────────────────────────┐
│  DiscordWatcher (daemon/watcher.py)         │
│  ┌───────────────────────────────────────┐  │
│  │ 1. 초기 메시지 ID 설정                 │  │
│  │ 2. 주기적 Polling (기본 10초)         │  │
│  │ 3. 새 메시지 감지                     │  │
│  │ 4. InboxStore.add_message()           │  │
│  └───────────────────┬───────────────────┘  │
└──────────────────────┼──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  ~/.claude/discord_inbox.json               │
│  {                                          │
│    "last_message_id": "...",                │
│    "messages": [                            │
│      { "message_id": "...", ... }           │
│    ]                                        │
│  }                                          │
└──────────────────────┬──────────────────────┘
                       ▲
                       │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│  Claude Code                                │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│  Claude Code 세션 시작                      │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  discord_check_pending()                    │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  DecisionManager.restore_pending()          │
│  ┌───────────────────────────────────────┐  │
│  │ 1. ~/.claude/pending_decisions/*.json │  │
│  │ 2. Discord API로 Thread 확인          │  │
│  │ 3. 답변 있으면 → 자동 해결            │  │
│  │ 4. 답변 없으면 → 재시작 알림          │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

{
  "success": true,
  "answer": "A) 지금 실행",
  "selected_option": "A) 지금 실행",
  "question_id": "project_20260301_abc123",
  "timed_out": false,
  "aborted": false
}

{
  "has_pending": true,
  "pending_questions": [
    {
      "question_id": "project_20260301_abc123",
      "question": "배포할까요?",
      "thread_id": "1234567890",
      "asked_at": "2026-03-01T10:30:00Z",
      "status": "pending"
    }
  ]
}

discord-mcp      # MCP 서버 실행
discord-watch    # 감시 데몬 실행

{
  "question_id": "project_20260301_abc123",
  "project": "my-project",
  "question": "DB 마이그레이션을 실행할까요?",
  "context": "v1→v2 스키마 변경",
  "options": ["A) 지금 실행", "B) 스테이징 먼저", "C) 보류"],
  "timeout_seconds": null,
  "thread_id": "1234567890",
  "message_id": "0987654321",
  "asked_at": "2026-03-01T10:30:00Z",
  "status": "pending",
  "clarify_attempts": 0,
  "resolved_at": null,
  "resolution": null,
  "selected_option": null
}

{
  "last_message_id": "1234567890",
  "messages": [
    {
      "message_id": "1234567890",
      "channel_id": "1234567890",
      "thread_id": null,
      "author": "username",
      "author_id": "1234567890",
      "content": "메시지 내용",
      "timestamp": "2026-03-01T00:00:00Z",
      "read": false
    }
  ]
}