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. 必要な特権ゲートウェイインテントを有効にします:

   • 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 を参照してください。

ビルド済みイメージは、main へのプッシュとタグのたびに Docker ワークフロー によって GitHub Container Registry に公開されます:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

CI ワークフロー は、プッシュと PR のたびに型チェック、テストスイート、本番ビルドを実行します。

設定

完全なリストは .env.example を参照してください。主な設定:

OpenCode に接続する (MCP)

はい — discord.* ツールスイートは、opencode(または Claude Code、Cursor などの任意の MCP クライアント)に、stdio 経由の本格的な Model Context Protocol サーバーとして公開できます。接続すると、次のようなプロンプトから 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 呼び出しはボット自体として(管理者コンテキストで)実行され、ボットが実際に実行できる範囲にスコープされます。破壊的なモデレーション(ban/kick/purge)には引き続き 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
    }
  }
}

cwd をプロジェクトディレクトリに設定すると、サーバーが .env(DISCORD_BOT_TOKEN と、オプションで MCP_DEFAULT_GUILD_ID を含む)を読み込みます。

オプション 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 が設定されている場合(またはボットがちょうど 1 つのギルドにしか参加していない場合)、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