Claude-Code on Yarang's Tech Lair

블로그 AI 자동 댓글 시스템 구축기 (1/3) — 아키텍처와 구현

Sun, 03 May 2026 01:00:00 +0900

개요

블로그 댓글에 AI가 자동으로 응답하는 시스템을 구축했습니다. 독자가 블로그 포스트에 댓글을 남기면, AI 어시스턴트가 포스트 컨텍스트를 분석하여 기술적으로 정확하면서도 친절한 답변을 자동으로 생성합니다.

이 시리즈는 3부작으로 구성됩니다:

1부 (이 글): 전체 아키텍처 설계와 핵심 코드 구현
2부: 파일 기반 인증, 권한 관리, 보안 강화
3부: systemd 배포, nginx 프록시, 트러블슈팅

시스템 아키텍처

전체 데이터 흐름

독자 댓글 작성
 ↓
[giscus] → GitHub Discussions에 댓글 생성
 ↓
[GitHub Webhook] → HTTP POST 전송
 ↓
[nginx reverse proxy] → 헤더 포워딩
 ↓
[Flask Worker] → 시그니처 검증 → 댓글 분석
 ↓
[Claude Code CLI] → AI 응답 생성
 ↓
[GitHub GraphQL API] → Discussion에 답변 게시
 ↓
[giscus] → 블로그에 답변 표시

이 아키텍처에서 핵심은 giscus가 GitHub Discussions를 댓글 저장소로 사용한다는 점입니다. 따라서 GitHub Webhook으로 새 댓글 이벤트를 수신하고, 같은 GitHub API로 응답을 게시할 수 있습니다.

구성 요소

구성 요소	역할	기술
giscus	블로그 댓글 위젯	GitHub Discussions 기반
GitHub Webhook	이벤트 전달	`discussion_comment` 이벤트
nginx	리버스 프록시	헤더 포워딩, SSL 터미네이션
Flask Worker	웹훅 수신 및 처리	Python, Flask, Flask-Limiter
Claude Code	AI 응답 생성	`--print` 모드 CLI 호출
GitHub GraphQL	응답 게시	Mutation API

giscus 설정

Hugo 블로그에 giscus를 통합하려면 hugo.toml에 다음 설정이 필요합니다:

[params]
 [params.comments]
 enabled = true
 provider = "giscus"
 [params.comments.giscus]
 repo = "yarang/blogs"
 repoId = "YOUR_REPO_ID"
 category = "General"
 categoryId = "YOUR_CATEGORY_ID"
 mapping = "pathname"
 strict = "0"
 reactionsEnabled = "1"
 emitMetadata = "0"
 inputPosition = "bottom"
 lang = "ko"
 theme = "noborder_gray"

mapping = "pathname"은 포스트 URL 경로를 기준으로 Discussion을 매핑합니다. 이렇게 하면 각 블로그 포스트마다 독립적인 Discussion이 생성됩니다.

GitHub Webhook 구성

GitHub 리포지토리 Settings > Webhooks에서:

Payload URL: https://your-domain/webhook
Content type: application/json
Secret: HMAC-SHA256 서명용 시크릿 (보안 편에서 상세히 다룸)
Events: Discussion comments 선택

Webhook은 댓글이 생성될 때마다 discussion_comment 이벤트를 Flask 워커로 전송합니다.

Flask 워커 구현

프로젝트 구조

auto-comment-worker/
├── scripts/
│ └── auto-comment-worker.py # 메인 워커
├── deploy/
│ └── auto-comment-worker.service # systemd 서비스
├── venv/ # Python 가상환경
└── logs/
 └── audit.log # 감사 로그

핵심 의존성

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from marshmallow import Schema, fields, validate, ValidationError

Flask: 경량 웹 프레임워크로 Webhook 엔드포인트 제공
Flask-Limiter: 속도 제한으로 남용 방지 (분당 10회)
marshmallow: 요청 스키마 검증으로 안전한 데이터 파싱

웹훅 엔드포인트

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 """GitHub Webhook 수신"""
 # 1. 시그니처 검증
 signature = request.headers.get('X-Hub-Signature-256')
 if not verify_webhook_signature(request.data, signature):
 log_audit('SIGNATURE_INVALID', {'ip': request.remote_addr})
 return jsonify({'status': 'unauthorized'}), 401

 # 2. 요청 스키마 검증
 schema = WebhookSchema()
 try:
 payload = schema.load(request.json)
 except ValidationError as err:
 return jsonify({'status': 'invalid'}), 400

 # 3. 댓글 정보 추출 및 필터링
 comment = payload.get('comment', {})
 discussion = payload.get('discussion', {})
 original_author = comment.get('user', {}).get('login', '사용자')

 # 블로그 소유주의 댓글이면 무시
 if _is_blog_owner(original_author):
 return jsonify({'status': 'owner_comment_ignored'}), 200

 # AI가 생성한 댓글이면 무시 (무한 루프 방지)
 if _is_ai_generated_comment(comment.get('body', '')):
 return jsonify({'status': 'ai_comment_ignored'}), 200

 # 4. AI 응답 생성 및 게시
 discussion_graphql_id = get_discussion_graphql_id(
 repo_owner, repo_name, discussion_number
 )
 context = f"제목: {discussion_title}\n\n내용: {discussion_body}"
 reply = analyze_comment(context, comment_body)
 post_reply_graphql(discussion_graphql_id, comment_body, original_author, reply)

핵심 흐름은 4단계입니다:

시그니처 검증: HMAC-SHA256으로 요청이 GitHub에서 왔는지 확인
스키마 검증: marshmallow로 페이로드 구조 검증
필터링: 블로그 소유주와 AI 자신의 댓글을 무시 (무한 루프 방지)
응답: Claude Code로 AI 응답 생성 후 GraphQL API로 게시

무한 루프 방지

AI가 생성한 댓글에 다시 AI가 응답하면 무한 루프에 빠집니다. 이를 방지하기 위해 마커 기반 감지를 사용합니다:

def _is_ai_generated_comment(body: str) -> bool:
 """AI가 생성한 댓글인지 식별"""
 ai_markers = [
 '🤖 AI 어시스턴트',
 'AI 어시스턴트',
 'AgentForge',
 'Claude Code로 자동 생성',
 '자동 생성되었습니다'
 ]
 body_lower = body.lower()
 return any(marker.lower() in body_lower for marker in ai_markers)

AI 응답을 게시할 때 반드시 이 마커들 중 하나를 본문에 포함합니다:

body = f"""---
**🤖 AI 어시스턴트**

{safe_reply}

*이 댓글은 AgentForge + Claude Code로 자동 생성되었습니다.*
---
"""

Claude Code CLI 호출

Claude Code의 --print 모드를 사용하여 비대화형으로 AI 응답을 생성합니다:

def analyze_comment(context: str, comment: str) -> str:
 """AgentForge 설정으로 Claude Code 실행"""
 prompt = f"""## 블로그 포스트 문맥
{context[:2000]}

## 독자 댓글
{comment}

이 댓글에 대한 응답을 작성해주세요.
- 기술 블로그 어시스턴트로서 전문적이면서 친절하게
- 200자 이내로 간결하게
- 필요한 경우 추가 정보나 링크 제시
"""

 cmd = [
 CLAUDE_CODE_PATH,
 '--settings', AGENTFORGE_CONFIG,
 '--print', prompt
 ]

 result = run(cmd, capture_output=True, text=True, timeout=60)

 if result.returncode == 0 and result.stdout.strip():
 return result.stdout.strip()

 return "의견 감사합니다! 기술적인 부분에 대해 더 논의해보면 좋을 것 같습니다. 🙏"

--settings 플래그로 AgentForge 전용 설정 파일을 지정합니다. 이 설정 파일에서 모델, 토큰 제한 등을 관리할 수 있습니다.

--print 플래그는 Claude Code를 비대화형 모드로 실행하여 결과를 stdout으로 출력합니다. 대화형 모드와 달리 프롬프트-응답 한 번으로 종료됩니다.

GitHub GraphQL API 통합

giscus는 GitHub Discussions를 사용하므로, 응답도 GitHub GraphQL API로 게시해야 합니다.

Discussion GraphQL ID 조회:

def get_discussion_graphql_id(repo_owner, repo_name, discussion_number):
 query = """
 query($owner: String!, $name: String!, $number: Int!) {
 repository(owner: $owner, name: $name) {
 discussion(number: $number) {
 id
 }
 }
 }
 """
 variables = {
 "owner": repo_owner,
 "name": repo_name,
 "number": discussion_number
 }

 response = requests.post(
 GITHUB_API_URL,
 json={"query": query, "variables": variables},
 headers={
 "Authorization": f"Bearer {GITHUB_TOKEN}",
 "Content-Type": "application/json"
 },
 timeout=10
 )

 if response.status_code == 200:
 data = response.json()
 return data["data"]["repository"]["discussion"]["id"]
 return None

Webhook 페이로드에는 Discussion의 REST API ID만 포함됩니다. 하지만 댓글을 게시하려면 GraphQL Node ID가 필요합니다. 따라서 먼저 GraphQL 쿼리로 Discussion의 Node ID를 조회한 뒤, 이를 사용하여 댓글을 게시합니다.

응답 게시 (Mutation):

def post_reply_graphql(discussion_graphql_id, original_comment, original_author, reply):
 query = """
 mutation($discussionId: ID!, $body: String!) {
 addDiscussionComment(input: {
 discussionId: $discussionId, body: $body
 }) {
 comment { id, databaseId }
 }
 }
 """
 # ... (요청 전송)

addDiscussionComment mutation은 Discussion 전체에 새 댓글을 추가합니다. 특정 댓글에 대한 답글(reply)이 아니라 Discussion 레벨의 댓글입니다.

입력 Sanitization

사용자 댓글은 외부 입력이므로 반드시 sanitize합니다:

def sanitize_comment(body: str) -> str:
 """사용자 입력 sanitization"""
 if not body:
 return body
 body = re.sub(r'<[^>]+>', '', body) # HTML 태그 제거
 body = html.escape(body) # HTML 엔티티 이스케이프
 body = body[:1000] # 길이 제한
 return body

XSS 공격을 방지하기 위해 HTML 태그를 제거하고, 남은 특수 문자를 이스케이프하며, 길이를 1000자로 제한합니다.

감사 로그

보안 이벤트를 추적하기 위한 감사 로그를 남깁니다:

def log_audit(event_type: str, details: dict):
 """보안 이벤트 감사 로그 기록"""
 with open(AUDIT_LOG, 'a') as f:
 f.write(json.dumps({
 'timestamp': datetime.utcnow().isoformat(),
 'event': event_type,
 'details': details
 }) + '\n')

기록하는 이벤트 유형:

SIGNATURE_INVALID: 웹훅 시그니처 검증 실패
INVALID_PAYLOAD: 잘못된 요청 페이로드
WEBHOOK_RECEIVED: 웹훅 수신 성공
AI_RESPONSE_SENT: AI 응답 게시 완료

마무리

이번 1부에서는 giscus, GitHub Webhook, Flask 워커, Claude Code CLI, GitHub GraphQL API를 연결하는 전체 아키텍처와 핵심 구현 코드를 다뤘습니다.

다음 2부에서는 이 시스템의 보안 강화 — 파일 기반 인증 관리, 파일 권한 검증, HMAC-SHA256 시그니처 검증 등을 상세히 다룹니다.

이 글은 AgentForge 블로그 자동 댓글 시스템 시리즈의 1부입니다.

Claude Code Discord MCP Plugin - asdf bun 경로 문제 해결

Thu, 26 Mar 2026 00:00:00 +0900

문제 상황

Claude Code CLI에서 Discord 채널 연결을 위해 discord 플러그인을 설치했는데 다음과 같은 에러가 발생했습니다.

> discord Plugin · claude-plugins-official · √ enabled
 └ discord MCP · × failed

플러그인은 활성화되었지만, MCP 서버는 실패 상태였습니다.

원인

이 문제는 asdf로 설치한 bun을 사용할 때 발생합니다. Claude Code CLI는 MCP 서버 실행을 위해 bun 명령어를 찾지만, asdf는 셸 래퍼를 사용하므로 시스템 전역 경로에서 실제 바이너리를 찾지 못합니다.

해결 방법

asdf로 설치한 bun의 절대 경로를 직접 입력하여 해결했습니다.

asdf로 설치한 bun 절대 경로 찾기

which bun

또는:

asdf where bun

출력 예시:

/Users/yarang/.asdf/installs/bun/1.x.x/bin/bun

설정 적용

이 절대 경로를 Discord MCP 설정의 실행 경로로 지정하면 문제가 해결됩니다.

핵심 정리

상황	해결 방법
시스템 전역 설치된 bun	`bun` 명령어 사용
asdf로 설치한 bun	절대 경로 직접 입력

asdf를 사용하는 경우, 셸 래퍼가 아닌 실제 바이너리 경로를 지정해야 MCP 서버가 정상적으로 실행됩니다.

참고 자료

Claude Code 플러그인 개발 완전 가이드 — plugin.json부터 배포까지

Mon, 23 Mar 2026 10:53:23 +0900

Claude Code 플러그인 개발 완전 가이드 — plugin.json부터 배포까지

Claude Code CLI는 v2.1.0부터 플러그인 시스템을 공식 지원한다. skills, agents, commands, hooks 네 가지 구성 요소를 조합하면 Claude의 동작을 도구처럼 패키징하고 팀 전체에 배포할 수 있다. 이 글에서는 실제 운영 중인 yarang-plugins 마켓플레이스 레포를 기반으로, 플러그인을 처음 만드는 개발자가 배포까지 완주할 수 있도록 단계별로 설명한다.

플러그인이란? — Claude Code 확장의 4가지 구성 요소

Claude Code 플러그인은 단순한 스크립트 번들이 아니다. 아래 네 가지 요소를 조합해 Claude의 역할과 행동을 선언적으로 정의한다.

구성 요소	디렉토리	역할
skills	`skills/<name>/SKILL.md`	Claude에게 특정 도메인 지식과 행동 규칙 주입
agents	`agents/<role>.md`	서브에이전트 페르소나 정의 (전문가 역할 부여)
commands	`commands/<verb>-<noun>.md`	`/slash-command` 단축키 등록
hooks	`hooks/hooks.json`	도구 호출 전후 자동 실행 트리거

graph TD
 A[사용자 요청] --> B[Command /create-post]
 B --> C[Skill blog-writer 로드]
 C --> D[Claude 작성 실행]
 D --> E{Write 도구 호출}
 E --> F[Hook PostToolUse 실행]
 F --> G[SEO 자동 검토]
 G --> H[최종 결과물]

1단계: 디렉토리 구조 만들기

플러그인 이름은 반드시 <domain>-<function> 형식의 kebab-case로 작성한다. 예: blog-writer, domain-checker.

plugins/blog-writer/
├── .claude-plugin/
│ └── plugin.json ← 플러그인 메타데이터 (필수)
├── skills/
│ └── blog-writer/
│ └── SKILL.md ← 스킬 파일명은 SKILL.md 고정
├── agents/
│ └── editor.md ← <role>.md 형식
├── commands/
│ └── create-post.md ← <verb>-<noun>.md 형식
├── hooks/
│ └── hooks.json ← hooks는 여기서만 선언
└── README.md

파일 명명 규칙을 어기면 Claude Code가 해당 파일을 인식하지 못한다.

2단계: plugin.json 작성 — 메타데이터의 핵심

plugin.json은 플러그인의 신원증명서다. skills, commands, agents 필드에 디렉토리 경로만 지정하면 내부 파일을 자동으로 탐색한다.

{
 "name": "blog-writer",
 "description": "SEO 최적화 블로그 글을 구조적으로 작성하는 스킬 플러그인",
 "author": {
 "name": "yarang",
 "url": "https://github.com/yarang"
 },
 "license": "MIT",
 "keywords": ["blog", "seo", "writing", "content"],
 "skills": "./skills/",
 "commands": "./commands/"
}

주의사항 3가지:

version 필드를 plugin.json에 넣지 않는다 — 내부 플러그인은 marketplace.json에서만 버전을 선언한다.
hooks 필드를 여기에 명시하지 않는다 — v2.1+는 hooks/hooks.json을 자동으로 감지한다.
../로 플러그인 디렉토리 밖을 참조하는 경로는 금지다.

3단계: SKILL.md 작성 — Claude의 전문성 주입

스킬은 Claude에게 특정 도메인의 행동 규칙과 지식을 주입하는 마크다운 문서다. blog-writer 플러그인의 SKILL.md를 예시로 본다.

# Blog Writer Skill

주어진 주제로 SEO 최적화된 블로그 포스트를 작성한다.

## 구조

1. **제목 (H1)**: 키워드 포함, 클릭 유도
2. **서론**: 독자 문제 제기, 글에서 다룰 내용 안내
3. **본문**: H2/H3 소제목으로 구조화, 핵심 키워드 자연스럽게 포함
4. **결론**: 핵심 요약, 행동 촉구(CTA)

## 지침

- 문장은 명확하게
- 단락은 충분히 설명을 작성
- 독자가 검색할 키워드를 제목과 첫 단락에 포함
- 실용적인 정보 위주로 작성
- 다이어그램도 포함

SKILL.md는 Claude가 해당 스킬로 호출될 때 시스템 프롬프트처럼 주입된다. 행동 지침이 구체적일수록 출력 품질이 높아진다.

4단계: agents/ — 전문가 서브에이전트 정의

에이전트 파일은 Claude Code의 서브에이전트에 페르소나를 부여한다. YAML frontmatter의 name과 description이 핵심이다.

---
name: blog-editor
description: |
 블로그 편집 전문 에이전트.
 글의 문체, 구조, SEO 최적화를 검토하고 개선안을 제안한다.
 사용 시점: 글 검토, 편집, 퇴고 요청 시.
---

# Technical Blog Editor Agent

당신은 전문 기술 블로그 편집자다. 아래 기준으로 글을 검토한다:

- Mermaid 다이어그램으로 동작 방식 시각화
- SEO 키워드 밀도 확인
- 참고 자료(References) 포함 여부 검증

description에 “사용 시점” 을 명시하면 Claude가 자동으로 적절한 시점에 해당 에이전트를 선택한다.

5단계: commands/ — 슬래시 커맨드 등록

커맨드 파일은 /blog-writer:create-post 같은 슬래시 커맨드를 등록한다. frontmatter로 허용 도구와 설명을 제한할 수 있다.

---
description: SEO 최적화 블로그 포스트 생성
allowed-tools: Read, Write, WebFetch
---

# /blog-writer:create-post

$ARGUMENTS에서 주제를 받아 SEO 최적화된 블로그 포스트를 작성한다.

주제가 없으면 사용자에게 주제를 물어본다.

blog-writer 스킬을 사용해 포스트를 작성하고, 완료 후 파일로 저장 여부를 확인한다.

$ARGUMENTS: 커맨드 뒤에 오는 인자를 자동으로 바인딩한다. /create-post AI 에이전트 설계처럼 사용.
allowed-tools: 보안을 위해 커맨드가 사용할 수 있는 도구를 명시적으로 제한한다.

6단계: hooks/hooks.json — 자동 트리거 설정

훅은 특정 도구 호출 전후에 Claude가 자동으로 실행할 프롬프트나 명령을 정의한다.

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Write",
 "hooks": [
 {
 "type": "prompt",
 "prompt": "작성된 파일을 확인하고 SEO 관점에서 제목과 첫 단락을 검토하라."
 }
 ]
 }
 ]
 }
}

Write 도구가 실행된 직후 SEO 검토를 자동으로 트리거하는 예시다. 훅 이벤트는 PreToolUse, PostToolUse, Notification, Stop 등을 지원한다.

sequenceDiagram
 participant U as 사용자
 participant C as Claude
 participant H as Hook Engine

 U->>C: /create-post 실행
 C->>C: Write 도구 호출
 C->>H: PostToolUse 이벤트 발생
 H->>C: SEO 검토 프롬프트 주입
 C->>U: SEO 검토 결과 반환

hooks 필드는 plugin.json에 선언하지 않는다. hooks/hooks.json 파일만 있으면 자동으로 인식된다 (v2.1.0+).

7단계: marketplace.json에 플러그인 등록

내부 플러그인은 마켓플레이스 루트의 .claude-plugin/marketplace.json에 등록한다. version은 여기서만 선언한다.

{
 "name": "yarang-plugins",
 "plugins": [
 {
 "name": "blog-writer",
 "description": "SEO 최적화 블로그 글을 구조적으로 작성하는 스킬 플러그인",
 "version": "1.1.0",
 "keywords": ["blog", "seo", "writing", "content"],
 "source": {
 "source": "relative",
 "path": "./plugins/blog-writer"
 }
 },
 {
 "name": "domain-checker",
 "description": "도메인 가용성 확인",
 "keywords": ["domain", "rdap", "whois"],
 "source": {
 "source": "github",
 "repo": "yarang/skill-domain-checker",
 "ref": "v1.2.0"
 }
 }
 ]
}

외부 레포 플러그인은 source.source를 "github"으로 설정하고 repo와 ref(태그/브랜치)를 지정한다.

로컬 테스트 → 배포 워크플로

flowchart LR
 A[플러그인 작성] --> B[로컬 테스트]
 B --> C{동작 확인}
 C -- 실패 --> A
 C -- 성공 --> D[marketplace.json 등록]
 D --> E[GitHub push]
 E --> F[팀원 설치]

# 1. 로컬 테스트 (설치 없이 즉시 확인)
claude --plugin-dir ./plugins/blog-writer

# 2. 마켓플레이스 카탈로그 새로고침
claude plugin marketplace update

# 3. 개인 설치 (user scope, 기본값)
claude plugin install blog-writer@yarang-plugins

# 4. 팀 공유 설치 (project scope — .claude/settings.json에 기록)
claude plugin install blog-writer@yarang-plugins --scope project

자주 하는 실수 체크리스트

항목	올바른 방법
스킬 파일 이름	`SKILL.md` (대문자 고정)
커맨드 파일 이름	`<verb>-<noun>.md` (예: `create-post.md`)
에이전트 파일 이름	`<role>.md` (예: `editor.md`)
version 위치	내부 플러그인 → `marketplace.json`만 / 외부 플러그인 → `plugin.json`만
hooks 위치	`hooks/hooks.json` (plugin.json에 넣지 않음)
경로 탈출	`../` 사용 금지

결론

Claude Code 플러그인은 선언적 마크다운으로 Claude의 동작을 패키징하는 강력한 시스템이다. plugin.json으로 메타데이터를 정의하고, SKILL.md로 전문성을 주입하고, commands/로 단축키를 만들고, hooks/hooks.json으로 자동화 트리거를 걸면 — 팀 전체가 동일한 워크플로를 공유할 수 있다.

지금 바로 시작하려면:

plugins/<name>/ 디렉토리를 만들고
plugin.json과 SKILL.md를 작성한 뒤
claude --plugin-dir ./plugins/<name>으로 로컬 테스트를 돌려보자.

플러그인 하나가 팀의 반복 작업 수십 개를 자동화한다.

References

Claude Code Plugin System Docs
yarang/yarang-plugins — CLAUDE.md, docs/PLUGIN_SPEC.md
Claude Code v2.1 Release Notes

[Discord Decision MCP] 아키텍처 설계문서

Mon, 02 Mar 2026 21:36:30 +0900

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

1. 프로젝트 개요

1.1 목적

Claude Code가 tmux Teammate 모드로 자율 작업 중, 사용자 결정이 필요한 시점에 Discord를 통해 질문하고 응답을 받아 작업을 재개하는 MCP (Model Context Protocol) 서버입니다.

1.2 핵심 특징

특징	설명
프로젝트당 Bot 1개	각 프로젝트는 독립된 Discord Bot 사용
무한 대기 기본값	Timeout 없이 사용자 응답 대기 (Claude가 독단 진행 금지)
상태 영속화	프로세스 재시작 후에도 대기 상태 복원
한국어 친화적	한글 선택지, Yes/No 응답 지원
MCP 기반 통신	모든 Discord 통신은 MCP Tool을 통해 이루어짐

1.3 버전 정보

버전: 1.0.0
Python 요구사항: >= 3.11
MCP 프레임워크: FastMCP >= 0.1.0

2. 디렉토리 구조

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 설정 예시

3. 주요 모듈 설명

3.1 서버 진입점 (`server.py`)

역할: FastMCP 서버 생성 및 MCP Tool 등록

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

3.2 설정 관리 (`config.py`)

역할: 환경변수에서 설정값 로드

환경변수	설명	기본값
`DISCORD_BOT_TOKEN`	Discord Bot Token (“Bot " 접두사 포함)	필수
`DISCORD_CHANNEL_ID`	기본 질문 채널 ID	필수
`PROJECT_NAME`	question_id 생성에 사용	“project”
`PENDING_DIR`	상태 파일 저장 경로	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling 간격 (초)	5

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

역할: Discord REST API 호출 (httpx 기반)

주요 메서드:

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)

특징:

Rate limit 자동 처리 (429 응답 시 재시도)
싱글턴 패턴 (get_client())

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

역할: Discord Gateway WebSocket 연결 (수신 전용)

특징:

MESSAGE_CREATE 이벤트 실시간 수신
Polling 방식의 지연을 5초 → 즉시로 단축
Gateway 없이도 시스템 정상 동작 (Polling fallback)
자동 재연결 (Exponential backoff)

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

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

역할: 결정 요청의 전체 생명주기 조율

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

흐름:

중복 질문 확인
Thread 생성 (또는 기존 Thread 재사용)
상태 파일 생성 (~/.claude/pending_decisions/{question_id}.json)
Poller 실행하여 응답 대기
SIGHUP 시그널 핸들러로 disconnected 상태 표시

3.4.2 DecisionPoller (`poller.py`)

역할: Discord 채널을 polling하여 응답 대기

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

특징:

기본값: 무한 대기 (timeout_seconds=None)
tmux pane에 실시간 대기 상태 표시 (ANSI escape)
모호한 응답 시 최대 2회 재질문

3.4.3 응답 파서 (`parser.py`)

역할: 사용자 Discord 응답 파싱

지원 패턴:

선택지 매칭: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
긍정/부정: “yes”, “네”, “예”, “no”, “아니요”
자연어: 15자 이상 또는 한글 3자 이상

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

3.4.4 상태 저장소 (`state.py`)

역할: 결정 요청 상태를 JSON 파일로 영속화

상태 파일 위치: ~/.claude/pending_decisions/{question_id}.json

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

3.5 MCP Tools (`tools/`)

Tool	블로킹	설명
`discord_ask_decision`	✅	사용자 결정 요청
`discord_notify`	❌	진행 상황 알림
`discord_report_progress`	❌	작업 완료 리포트
`discord_check_pending`	❌	미해결 질문 확인
`discord_read_inbox`	❌	Inbox 메시지 조회
`discord_clear_inbox`	❌	Inbox 메시지 삭제

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

역할: Discord 채널을 감시하여 새 메시지를 inbox 파일에 기록

실행 방법:

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

특징:

지정된 채널(들)을 주기적으로 polling
새로운 사용자 메시지 감지 시 inbox에 기록
tmux pane에 상태 표시

3.6.2 InboxStore (`inbox.py`)

역할: Discord 메시지를 저장하는 JSON 파일 기반 저장소

Inbox 파일 위치: ~/.claude/discord_inbox.json

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() # 읽은 메시지 삭제

4. 데이터 흐름도

4.1 결정 요청 흐름

┌─────────────────┐
│ 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 │
 │ 반환 │
 └─────────────────┘

4.2 감시 데몬 흐름

┌─────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────┘

4.3 세션 복원 흐름

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

5. MCP 도구 목록

5.1 discord_ask_decision

설명: 사용자 결정이 필요할 때 Discord Thread에 질문 전송 후 응답 대기 (블로킹)

파라미터:

이름	타입	필수	설명
`question`	string	✅	질문 내용
`context`	string	✅	현재 작업 상황
`options`	string[]	❌	선택지 목록 (빈 배열이면 자유 응답)
`timeout_seconds`	float	❌	대기 Timeout (null이면 무한 대기)
`thread_id`	string	❌	기존 Thread ID (null이면 새 Thread 생성)

반환값:

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

5.2 discord_notify

설명: 진행 상황을 Discord에 알림 (논블로킹)

파라미터:

이름	타입	필수	설명
`message`	string	✅	알림 메시지
`level`	string	❌	info/warning/success/error (기본값: info)
`thread_id`	string	❌	전송할 Thread ID (null이면 기본 채널)

5.3 discord_report_progress

설명: 작업 완료 또는 단계 완료 시 결과 리포트 (논블로킹)

파라미터:

이름	타입	필수	설명
`title`	string	✅	리포트 제목
`summary`	string	✅	작업 결과 요약
`details`	string[]	❌	세부 항목 목록
`thread_id`	string	❌	전송할 Thread ID

5.4 discord_check_pending

설명: 세션 시작 시 미해결 질문 확인 (논블로킹)

파라미터: 없음

반환값:

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

5.5 discord_read_inbox

설명: Inbox에 저장된 메시지 조회 (논블로킹)

파라미터:

이름	타입	기본값	설명
`unread_only`	boolean	true	읽지 않은 메시지만 반환
`mark_read`	boolean	false	조회한 메시지를 읽음으로 표시

5.6 discord_clear_inbox

설명: Inbox 메시지 삭제 (논블로킹)

파라미터:

이름	타입	기본값	설명
`read_only`	boolean	true	읽은 메시지만 삭제

6. 의존성 정보

6.1 핵심 의존성

패키지	버전	용도
`fastmcp`	>= 0.1.0	MCP 서버 프레임워크
`httpx`	>= 0.27.0	비동기 HTTP 클라이언트
`websockets`	>= 12.0	WebSocket 클라이언트
`python-dotenv`	>= 1.0.0	환경변수 로드
`pydantic`	>= 2.0.0	데이터 모델 검증
`anyio`	>= 4.0.0	비동기 실행

6.2 개발 의존성

패키지	용도
`pytest`	테스트 프레임워크
`pytest-asyncio`	비동기 테스트 지원
`pytest-mock`	Mock 지원
`respx`	httpx mocking

6.3 CLI 명령어

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

7. 상태 파일 형식

7.1 결정 상태 파일

위치: ~/.claude/pending_decisions/{question_id}.json

{
 "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
}

7.2 Inbox 파일

위치: ~/.claude/discord_inbox.json

{
 "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
 }
 ]
}

8. 아키텍처 원칙

8.1 설계 원칙

싱글톤 패턴: DiscordClient, StateStore, InboxStore는 모듈 레벨 싱글턴
상태 영속화: 모든 결정 요청 상태는 파일로 영속화
무한 대기 기본값: Claude가 독단적으로 진행하지 않도록 timeout 기본값은 None
재질문 제한: 모호한 응답은 최대 2회까지만 재질문
Rate Limit 처리: Discord API 429 응답 시 자동 대기 후 재시도

8.2 에러 handling

상황	처리 방법
Discord API 429	자동 대기 후 재시도 (최대 5회)
WebSocket 연결 끊김	Exponential backoff로 재연결
응답 파싱 실패	최대 2회 재질문 후 중단
Timeout 발생	작업 중단 알림 후 aborted 상태
세션 끊김 (SIGHUP)	disconnected 상태로 저장

문서 버전: 1.0.0 마지막 수정: 2026-03-02

영어 버전: English Version

[Discord MCP] Gateway 아키텍처 설계

Sun, 01 Mar 2026 01:13:00 +0900

Claude Code 팀에서 Discord를 통한 사용자 소통을 위해 Discord Gateway Service를 설계했다. 이 글에서는 주요 아키텍처 결정 사항과 user_comm Agent 설계를 정리한다.

1. 전체 아키텍처

구성 요소

계층	구성요소	역할
Discord	Bot, Channel, Thread	사용자 인터페이스
Gateway	WebSocket, REST API, SSE	메시지 라우팅
MCP	gcp-mcp, oci-mcp, db-mcp	도구 실행
user_comm	Discord Agent	사용자 소통 담당

메시지 흐름

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_comm Agent는 Claude Code 팀의 멤버로서 Discord 채널을 통해 사용자와 소통하고 다른 agent들과 협업합니다.

기능	설명
입력 수신	Discord 메시지를 받아 적절한 agent에게 전달
의견 요청	다른 agent의 요청으로 사용자 의견 질의
알림/보고	시스템 상태, 경고, 리포트 전송
팀 통신	다른 agent와 메시지 송수신

내부 구조

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

메시지 타입

class MessageType(Enum):
 TASK_REQUEST = "task_request" # 작업 요청
 NOTIFICATION = "notification" # 알림
 OPINION_REQUEST = "opinion_request" # 의견 요청
 OPINION_RESPONSE = "opinion_response" # 의견 응답
 STATUS_REPORT = "status_report" # 상태 보고
 ERROR = "error" # 에러

주요 기능 동작

입력 수신 (Discord → Agent)

사용자: "@gcp-monitor 서버 상태 확인"
 → DiscordBot.on_message
 → UserCommAgent._parse_command (target: gcp-monitor)
 → TeamCommunicator.send_to_agent
 → Discord: "gcp-monitor에게 요청을 전달했습니다."

의견 요청 (Agent → Discord)

gcp-monitor: "디스크 정리할까요?" → user_comm
 → DiscordBot.ask_opinion (버튼 또는 답장 대기)
 → 사용자 응답
 → TeamCommunicator.send_to_agent (응답 전달)

알림/보고 (Agent → Discord)

oci-monitor: "디스크 92% 경고" → user_comm
 → DiscordBot.send_message (Embed 형식)

3. Redis 없이 동작하는 가벼운 아키텍처

왜 Redis를 제거했나?

항목	Redis 사용	In-Memory 사용
Thread Lock	Redis SET NX	Python dict
이벤트 분배	Redis Streams	SSE 직접
상태 저장	Redis Cache	메모리 캐시

결론: 단일 인스턴스 환경에서는 In-Memory로 충분

Gateway 구조

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]

구성요소 상세

모듈	역할	특징
Discord Bot	WebSocket 연결	자동 재연결
Thread Lock	동시성 제어	5분 타임아웃
Message Cache	메시지 보관	최대 1000개
SSE Manager	실시간 전송	모든 MCP에 브로드캐스트

4. MCP 선택 방식: 4단계 하이브리드

선택 우선순위

순위	방식	예시	설명
1	슬래시 커맨드	`/gcp status`	가장 명시적
2	@멘션	`@gcp-monitor status`	자연스러운 대화
3	키워드 감지	`gcp 서버 상태`	키워드 자동 인식
4	채널별 지정	#gcp-모니터링	채널 기본 MCP

Fallback 동작 순서

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]

슬래시 커맨드 목록

커맨드	MCP	설명
`/gcp status [server]`	gcp-mcp	GCP 서버 상태
`/gcp list`	gcp-mcp	GCP 인스턴스 목록
`/oci status [server]`	oci-mcp	OCI 서버 상태
`/oci list`	oci-mcp	OCI 인스턴스 목록
`/db query <sql>`	db-mcp	DB 쿼리 실행
`/db list`	db-mcp	DB 목록
`/alert check`	alert-mcp	알림 확인

5. Thread Lock 규칙

락 동작 방식

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

Method	Endpoint	설명
`POST`	`/api/threads/{id}/acquire`	락 획득
`POST`	`/api/threads/{id}/release`	락 해제
`GET`	`/api/threads/{id}/lock`	락 상태 확인

요청/응답 예시

락 획득 요청

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

락 획득 응답

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

6. MCP 도구 (8개)

도구 목록

도구	설명	주요 파라미터
`discord_send_message`	메시지 전송	channel_id, content
`discord_get_messages`	메시지 조회	channel_id, limit
`discord_wait_for_message`	메시지 대기	channel_id, timeout
`discord_create_thread`	스레드 생성	channel_id, message_id
`discord_list_threads`	스레드 목록	channel_id
`discord_archive_thread`	스레드 아카이브	thread_id
`discord_acquire_thread`	락 획득	thread_id, agent_name
`discord_release_thread`	락 해제	thread_id, agent_name

도구 관계도

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

사용 예시

# 메시지 전송
discord_send_message(
 channel_id="123456789",
 content="서버 상태: 정상"
)

# 스레드 생성
discord_create_thread(
 channel_id="123456789",
 message_id="987654321",
 name="상태 확인"
)

# 락 획득
discord_acquire_thread(
 thread_id="111222333",
 agent_name="gcp-mcp",
 timeout=300
)

7. 파일 구조

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

디렉토리 설명

경로	설명
`gateway/`	Gateway Service (FastAPI)
`user_comm/`	사용자 소통 Agent
`discord_mcp/`	MCP Server (8개 도구)
`mcp_shared/`	공유 MCP 도구
`docs/`	문서

8. 실행 방법

로컬 실행

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

# user_comm Agent 시작 (독립 모드)
python main.py --standalone

# user_comm Agent 시작 (팀 모드)
python main.py --team server-monitor

# 헬스체크
curl http://localhost:8081/health

# 응답
{"status": "healthy", "discord_connected": true}

Claude Code MCP 설정

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

9. 로드맵

Phase 1: 완료

FastAPI Gateway Service
Discord WebSocket 연결
Thread Lock (In-Memory)
SSE 브로드캐스트
MCP Server (8개 도구)

Phase 2: 진행 예정

user_comm Agent 구현
슬래시 커맨드 구현
채널별 기본 MCP 설정
키워드 자동 감지
라우팅 설정 파일

Phase 3: 선택 사항

API 인증 (API Key)
Rate Limiting
메시지 영속성 (SQLite)

결론

가벼운 아키텍처로 시작해서 필요시 확장하는 전략을 선택했다.

항목	현재	향후
상태 저장	In-Memory	SQLite (필요시)
분산 락	미사용	Redis (다중 인스턴스 시)
인증	없음	API Key (필요시)
사용자 소통	Gateway 직접	user_comm Agent

단일 인스턴스에서는 현재 구조로 충분하며, 트래픽이 늘어나면 점진적으로 확장할 계획이다. user_comm Agent를 통해 사용자와의 소통을 체계화하고, 팀 내 다른 agent들과의 협업을 효율화한다.

영어 버전: English Version

[Claude Code] 팀 에이전트 통신 아키텍처

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code 팀 에이전트 간 통신 아키텍처 설계

개요

Claude Code에서 여러 AI 에이전트가 협업할 때 효율적인 통신 방식이 필요합니다. 이 글에서는 Discord와 연동된 서버 모니터링 팀을 구축하며 설계한 통신 아키텍처를 공유합니다.

문제 정의

Claude Code에는 두 가지 유형의 에이전트가 있습니다:

Python 프로세스 (Daemon)
- Discord Gateway, user_comm_daemon 등
- 항상 실행 중, 파일 시스템 접근 가능
LLM Agent (Task로 생성)
- gcp-monitor, oci-monitor, alert-manager 등
- SendMessage 도구 사용, Claude Code 네이티브 통신

이 두 유형 간의 통신이 필요했습니다.

고려한 방식들

1. 파일 기반 메시지 큐 (기존)

장점: 구현 단순, 의존성 없음
단점: 지연 (~1초), 파일 관리 필요

2. WebSocket

장점: 실시간 양방향 통신
단점: 서버/클라이언트 구현 필요

3. gRPC

장점: 강력한 타입 체크, 스트리밍
단점: proto 파일 관리, 높은 복잡도

4. SQLite 메시지 허브 (채택)

장점: 빠름 (~10ms), 트랜잭션, 추가 의존성 없음
단점: 단일 머신에서만 동작

최종 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (직접 접근) │ │ (직접 접근) │ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub 구조

메시지 테이블

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

에이전트 상태 테이블

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

통신 방식

LLM Agent ↔ LLM Agent

SendMessage 사용 (Claude Code 네이티브)
자동 관리, idle notification 제공

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python은 직접 SQLite 접근
LLM Agent는 MCP Tool로 접근

MCP Server 구현

LLM Agent를 위한 MCP 도구들:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

메시지 플로우 예시

1. Discord 사용자: "안녕"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord 채널: "안녕하세요! 👋"

성능 비교

방식	지연 시간	안정성	복잡도
파일 기반	~1000ms	보통	낮음
WebSocket	~5ms	높음	중간
SQLite	~10ms	높음	낮음

결론

SQLite Message Hub + MCP Server 조합이 Claude Code 팀 에이전트 통신에 가장 적합했습니다:

낮은 지연: 파일 기반보다 100배 빠름
안정성: 트랜잭션으로 데이터 무결성 보장
단순함: 추가 의존성 없이 Python 내장 sqlite3 사용
유연성: Python과 LLM Agent 모두 동일한 데이터 소스 사용

코드

핵심 컴포넌트:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord 연동 게이트웨이
user_comm_daemon.py: 메시지 처리 데몬

영어 버전: English Version

Claude-Code on Yarang's Tech Lair

블로그 AI 자동 댓글 시스템 구축기 (1/3) — 아키텍처와 구현

개요

시스템 아키텍처

전체 데이터 흐름

구성 요소

giscus 설정

GitHub Webhook 구성

Flask 워커 구현

프로젝트 구조

핵심 의존성

웹훅 엔드포인트

무한 루프 방지

Claude Code CLI 호출

GitHub GraphQL API 통합

입력 Sanitization

감사 로그

마무리

Claude Code Discord MCP Plugin - asdf bun 경로 문제 해결

문제 상황

원인

해결 방법

asdf로 설치한 bun 절대 경로 찾기

설정 적용

핵심 정리

참고 자료

Claude Code 플러그인 개발 완전 가이드 — plugin.json부터 배포까지

Claude Code 플러그인 개발 완전 가이드 — plugin.json부터 배포까지

플러그인이란? — Claude Code 확장의 4가지 구성 요소

1단계: 디렉토리 구조 만들기

2단계: plugin.json 작성 — 메타데이터의 핵심

3단계: SKILL.md 작성 — Claude의 전문성 주입

4단계: agents/ — 전문가 서브에이전트 정의

5단계: commands/ — 슬래시 커맨드 등록

6단계: hooks/hooks.json — 자동 트리거 설정

7단계: marketplace.json에 플러그인 등록

로컬 테스트 → 배포 워크플로

자주 하는 실수 체크리스트

결론

References

[Discord Decision MCP] 아키텍처 설계문서

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

1. 프로젝트 개요

1.1 목적

1.2 핵심 특징

1.3 버전 정보

2. 디렉토리 구조

3. 주요 모듈 설명

3.1 서버 진입점 (server.py)

3.2 설정 관리 (config.py)

3.3 Discord API 클라이언트 (bot/)

3.3.1 REST API 클라이언트 (client.py)

3.3.2 WebSocket 게이트웨이 (gateway.py)

3.4 결정 요청 관리 (decision/)

3.4.1 DecisionManager (manager.py)

3.4.2 DecisionPoller (poller.py)

3.4.3 응답 파서 (parser.py)

3.4.4 상태 저장소 (state.py)

3.5 MCP Tools (tools/)

3.6 감시 데몬 (daemon/)

3.6.1 DiscordWatcher (watcher.py)

3.6.2 InboxStore (inbox.py)

4. 데이터 흐름도

4.1 결정 요청 흐름

4.2 감시 데몬 흐름

4.3 세션 복원 흐름

5. MCP 도구 목록

5.1 discord_ask_decision

5.2 discord_notify

5.3 discord_report_progress

5.4 discord_check_pending

5.5 discord_read_inbox

5.6 discord_clear_inbox

6. 의존성 정보

6.1 핵심 의존성

6.2 개발 의존성

6.3 CLI 명령어

7. 상태 파일 형식

7.1 결정 상태 파일

7.2 Inbox 파일

3.1 서버 진입점 (`server.py`)

3.2 설정 관리 (`config.py`)

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

3.4.2 DecisionPoller (`poller.py`)

3.4.3 응답 파서 (`parser.py`)

3.4.4 상태 저장소 (`state.py`)

3.5 MCP Tools (`tools/`)

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

3.6.2 InboxStore (`inbox.py`)