Discord Agent

Автономный ИИ-агент, который живёт внутри Discord. Упомяните его, задайте вопрос на обычном языке — и он изучит сервер, спланирует многошаговые действия, выполнит их через инструменты 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-совместимый endpoint.

• Изоляция между гильдиями — каждый запрос, запись кэша и памяти привязаны к гильдии.

• Инструментальный слой в стиле 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.*.

• Интеллект прав доступа — объясняет, почему участник может или не может действовать.

• Защитные барьеры — классификация рисков, настраиваемые уровни подтверждения, режим dry-run/plan, идемпотентные операции ensure_*, авторизация, независимая от LLM.

• Устойчивость к prompt-инъекциям — весь контент 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

Production-сборка:

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.

Готовый образ публикуется в GitHub Container Registry с помощью Docker workflow при каждом пуше в main и каждом теге:

docker pull ghcr.io/NacreousDawn596/DiscordMCP:main

CI workflow запускает проверку типов, тестовый набор и production-сборку при каждом пуше и 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-вызовы выполняются от имени самого бота (контекст администратора), в рамках того, что бот реально может делать. Деструктивная модерация (ban/kick/purge) по-прежнему требует ENABLE_MODERATION=true. По MCP нет интерактивного канала подтверждения, поэтому действия выполняются немедленно.

Шаг 1 — Сборка (или запуск через tsx)

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

Шаг 2 — Настройка opencode

Добавьте запись mcp в конфигурацию opencode. Это может быть конфиг проекта (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 больше значения по умолчанию 5s — сервер входит в Discord от имени бота перед ответом, что может занять несколько секунд.

Dev (без сборки): используйте "command": ["npx", "tsx", "src/mcp/entry.ts"].

Шаг 3 — Перезапустите opencode

Перезапустите opencode, чтобы он подхватил новый MCP-сервер. Проверить подключение можно через /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

Модульные тесты покрывают изоляцию гильдий, авторизацию, расчёт прав, классификацию рисков, изоляцию памяти, валидацию инструментов, валидацию планов и защиту от prompt-инъекций.

Безопасность

У бота неизменяемые границы: он никогда не раскрывает свой токен, не обходит права Discord, не пересекает границы гильдий, не позволяет содержимому сообщений переопределять политику, не авторизует привилегированные действия для неавторизованных пользователей и не сообщает об успехе без проверки состояния. См. docs/SECURITY.md.

Лицензия

MIT