Discord Agent

Discord 안에서 작동하는 자율 AI 에이전트. 멘션하고 자연어로 요청하면, 서버를 검사하고 다단계 작업을 계획하며, Discord API 도구를 통해 실행하고, 결과를 검증한 다음, 실제 관리자처럼 보고합니다.

멀티 길드 설계: 모든 작업은 호출된 길드로 엄격히 범위가 제한되며, 서버 간 컨텍스트, 메모리, 권한이 섞일 가능성이 없습니다.

User:  @Agent create a Development category with frontend, backend, devops,
       and code-review channels, plus a Dev role that can access them.
Agent: Done. Created the Development category with 4 channels and the Dev role,
       and configured permissions. Everything verified.

기능

• 자율 계획 및 실행 — 사용자는 API 호출이 아닌 목표를 설명합니다.

• LLM 무관 — OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Ollama 또는 모든 OpenAI 호환 엔드포인트.

• 멀티 길드 격리 — 모든 쿼리, 캐시 항목, 메모리 레코드는 길드별로 네임스페이스가 지정됩니다.

• MCP 스타일 도구 레이어 — discord.guild.*, discord.channel.*, discord.role.*, discord.permission.*, discord.message.*, discord.member.*, discord.moderation.*, discord.thread.*, discord.forum.*, discord.search.*, discord.audit.*, discord.analytics.*, discord.memory.*, discord.automation.*, discord.schedule.*, discord.server.*, discord.bulk.*.

• 권한 인텔리전스 — 멤버가 작업을 수행할 수 있는지 이유를 설명합니다.

• 안전 게이트 — 위험 분류, 구성 가능한 확인 수준, 드라이런/계획 모드, 멱등 ensure_* 작업, LLM과 독립적인 권한 부여.

• 프롬프트 인젝션 저항 — 모든 Discord 콘텐츠는 신뢰할 수 없는 것으로 취급되며, 규칙과 길드 경계는 재정의될 수 없습니다.

• 길드 범위 메모리 — "기억해줘 …", "잊어줘 …", "뭐 기억하고 있어?".

• 이벤트 자동화 및 예약 작업 — 환영 메시지, 반응, 주간 요약.

• 감사 추적 — 길드별 구조화된 실행/작업 기록.

• CLI 진단 — agent doctor, agent status, agent guilds, agent capabilities, agent test.

Related MCP server: discord-mcp

빠른 시작

1. Discord 애플리케이션 만들기

1. https://discord.com/developers/applications로 이동하여 New Application을 만듭니다.

2. Bot에서 봇을 만들고 토큰을 복사합니다.

3. 필요한 Privileged Gateway Intents를 활성화합니다:

   • Server Members Intent

   • Message Content Intent

4. OAuth2 → URL Generator를 사용하여 bot 범위와 필요한 권한(예: Manage Channels, Manage Roles, Manage Messages)으로 봇을 초대합니다. 봇은 Discord 권한이 허용하는 작업만 수행합니다.

2. 구성

cp .env.example .env
# edit .env and set at minimum:
#   DISCORD_BOT_TOKEN=
#   LLM_PROVIDER=openai
#   LLM_API_KEY=
#   LLM_MODEL=gpt-4o-mini

3. 실행

Docker:

docker compose up --build

로컬 개발:

npm install
npm run dev

프로덕션 빌드:

npm run build
npm start

4. 사용

아무 채널에서 봇을 멘션하세요:

@Agent organize this server
@Agent create a private staff section
@Agent why can't John send messages in #general?
@Agent audit the server permissions
@Agent remember that release channels should always be read-only

실행 없이 계획만 보려면 요청 앞에 plan / preview / dry-run을 붙이고, 읽기 전용 분석은 audit / analyze를 붙이세요.

명령 및 진단

npm run cli -- doctor         # environment + configuration health check
npm run cli -- status         # configuration summary
npm run cli -- guilds         # list known guilds
npm run cli -- capabilities   # list all tools by namespace and risk
npm run cli -- config         # show resolved config (secrets redacted)
npm run cli -- test           # quick self-test

Docker

이 프로젝트는 멀티스테이지 Dockerfile(전체 툴체인 이미지에서 빌드, node 사용자로 슬림 이미지에서 실행)과 docker-compose.yml을 제공합니다.

# Build and run with docker compose
docker compose up --build -d

# Or build the image directly
docker build -t discord-agent .

# Run the self-test inside the built image
docker run --rm discord-agent node dist/cli/cli.js test

SQLite 데이터베이스는 agent-data 볼륨의 /app/data/agent.sqlite에 저장됩니다. docs/DEPLOYMENT.md를 참조하세요.

사전 빌드 이미지는 Docker 워크플로우에 의해 main 브랜치로의 모든 푸시와 모든 태그에 대해 GitHub Container Registry에 게시됩니다:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

CI 워크플로우는 모든 푸시와 PR에서 타입체크, 테스트 스위트, 프로덕션 빌드를 실행합니다.

구성

전체 목록은 .env.example을 참조하세요. 주요 설정:

OpenCode (MCP) 연결

네 — discord.* 도구 모음은 opencode(또는 모든 MCP 클라이언트: Claude Code, Cursor 등)에 실제 Model Context Protocol 서버로 stdio를 통해 노출될 수 있습니다. 연결하면 다음과 같은 프롬프트로 Discord 서버를 제어할 수 있습니다:

use the discord-agent tools to create a "Development" category with
#frontend, #backend and #devops in guild 123456789

작동 방식

MCP 서버(npm run mcp)는 동일한 Discord 봇을 부팅하고, 토큰으로 로그인한 다음, 127개의 모든 도구를 stdin/stdout으로 제공합니다. 각 도구는 선택적 guild_id를 받아 동일한 서버가 봇이 속한 모든 길드를 관리할 수 있습니다.

중요: MCP 호출은 봇 자체(관리자 컨텍스트)로 실행되며, 봇이 실제로 할 수 있는 작업으로 범위가 제한됩니다. 파괴적 중재(밴/킥/퍼지)는 여전히 ENABLE_MODERATION=true가 필요합니다. MCP에는 대화형 확인 채널이 없으므로 작업이 즉시 실행됩니다.

1단계 — 빌드 (또는 tsx로 실행)

npm install
npm run build        # produces dist/mcp/entry.js

2단계 — opencode 구성

opencode 구성에 mcp 항목을 추가하세요. 프로젝트 구성(opencode.json) 또는 전역 구성(~/.config/opencode/opencode.json)일 수 있습니다.

옵션 A — 프로젝트 .env 사용 (권장):

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discord-agent": {
      "type": "local",
      "command": ["node", "dist/mcp/entry.js"],
      "cwd": "/absolute/path/to/discord-agent",
      "enabled": true,
      "timeout": 30000
    }
  }
}

서버가 .env(DISCORD_BOT_TOKEN과 선택적으로 MCP_DEFAULT_GUILD_ID를 보유)를 로드하도록 cwd를 프로젝트 디렉터리로 설정하세요.

옵션 B — 토큰을 명시적으로 전달 (.env 불필요):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discord-agent": {
      "type": "local",
      "command": ["node", "dist/mcp/entry.js"],
      "cwd": "/absolute/path/to/discord-agent",
      "environment": {
        "DISCORD_BOT_TOKEN": "your-bot-token",
        "MCP_DEFAULT_GUILD_ID": "123456789"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

timeout을 기본 5초보다 높게 설정하세요 — 서버는 응답 전에 봇을 Discord에 로그인하며, 몇 초가 걸릴 수 있습니다.

개발 (빌드 없음): "command": ["npx", "tsx", "src/mcp/entry.ts"]를 사용하세요.

3단계 — opencode 재시작

새 MCP 서버를 인식하도록 opencode를 재시작하세요. /mcp로 연결을 확인할 수 있습니다 (또는 list the discord-agent tools라고 물어보세요).

4단계 — 사용

모든 도구는 discord_ 접두사가 붙습니다. 예:

create a #welcome channel in guild 123456789 using discord-agent
list the roles in guild 123456789
audit the permissions in guild 123456789

MCP_DEFAULT_GUILD_ID가 설정된 경우(또는 봇이 정확히 하나의 길드에 있는 경우) guild_id를 생략할 수 있습니다:

using discord-agent, create a Development category with #frontend and #backend

MCP 옵션

전체 도구 카탈로그는 docs/CONFIGURATION.md를, 실시간 목록은 npm run cli -- capabilities를 참조하세요.

아키텍처

Discord ── message/mention/interaction ──► Discord Agent
                                            ├── Context Manager
                                            ├── LLM / Agent Runtime (tool loop)
                                            ├── Memory (guild-scoped)
                                            ├── Planner + validation
                                            ├── Permission awareness
                                            ├── MCP Tool Layer
                                            └── Execution Engine ──► Discord API

자세한 내용은 docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/SECURITY.md, docs/DEPLOYMENT.md를 참조하세요. 바로 사용할 수 있는 예제 프롬프트와 공급자 구성은 examples/를 참조하세요.

테스트

npm test

단위 테스트는 길드 격리, 권한 부여, 권한 계산, 위험 분류, 메모리 격리, 도구 검증, 계획 검증, 프롬프트 인젝션 방어를 다룹니다.

보안

봇은 불변 경계를 가집니다: 토큰을 절대 노출하지 않고, Discord 권한을 절대 우회하지 않으며, 길드 경계를 절대 넘지 않고, 메시지 콘텐츠가 정책을 재정의하지 못하게 하며, 권한 없는 사용자의 특권 작업을 절대 승인하지 않고, 상태를 검증하지 않고 성공을 주장하지 않습니다. docs/SECURITY.md를 참조하세요.

라이선스

MIT