Discord MCP

MCP server để tùy chỉnh & khảo sát server Discord, hướng tới vai một chuyên gia setup Discord. Trọn vòng: P1 (nền tảng + tool đọc), P2 (tool ghi cấu trúc), P3 (blueprint + tư vấn), P4 (Community/Onboarding + audit + bàn giao), P5 (HTTP transport, đủ 6 blueprint, test). Xem lộ trình trong openspec/changes/project-roadmap và tài liệu nền trong docs/.

• Stack: TypeScript + discord.js + @modelcontextprotocol/sdk (transport stdio).

• Runtime & package manager: Bun ≥ 1.1 (chạy TypeScript trực tiếp, không cần build; tự nạp .env).

Tool hiện có (P1, read-only)

Tool ghi (P2, write — mọi tool có dryRun để xem trước)

An toàn ghi: mọi tool ghi nhận dryRun: true để trả về thay đổi dự kiến mà không thực thi; thao tác role bị chặn nếu role đích không thấp hơn role cao nhất của bot (lỗi role_hierarchy).

Tool blueprint & tư vấn (P3 — "bộ não")

4 tool đầu chạy không cần kết nối Discord (thao tác trên dữ liệu blueprint). apply_blueprint gọi lại lớp write P2 qua service dùng chung (src/discord/structureOps.ts).

Tool Community / Audit / Bàn giao (P4)

configure_onboarding kiểm ràng buộc trước khi gọi API (Community đã bật; ≥7 default channel, ≥5 cho @everyone gửi) và trả hướng dẫn thủ công nếu vi phạm. Các tool cấu hình có dryRun.

1. Tạo Discord application & bot

1. Vào Discord Developer Portal → New Application.

2. Tab Bot → Reset Token → copy token (giữ bí mật, đây là DISCORD_TOKEN).

3. Trong tab Bot, bật Privileged Gateway Intents:

   • Server Members Intent

   • Message Content Intent

   Bắt buộc, nếu không bot sẽ đăng nhập lỗi (server này khởi tạo client với các intent đó).

2. Mời bot vào server (toàn quyền)

Theo thiết kế P1, bot vận hành được cấp Administrator cho tốc độ phát triển. Tạo OAuth2 invite URL:

https://discord.com/api/oauth2/authorize?client_id=<APPLICATION_ID>&permissions=8&scope=bot%20applications.commands

• <APPLICATION_ID>: lấy ở tab General Information.

• permissions=8 = Administrator.

Mở URL, chọn server của bạn để thêm bot.

⚠️ Administrator là bề mặt rủi ro lớn nếu token lộ. Đây là lựa chọn có chủ đích cho giai đoạn dev; có thể siết quyền ở P4 (audit). Không commit token.

3. Cấu hình môi trường

cp .env.example .env

Điền vào .env:

DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD_ID=            # tùy chọn: guild mặc định để tool bỏ qua tham số guildId
LOG_LEVEL=info               # debug | info | warn | error

4. Cài đặt

bun install

Kiểm tra chất lượng:

bun run typecheck   # tsc --noEmit
bun run lint
bun run format:check

Build (tùy chọn — chỉ cần khi muốn một file bundle chạy bằng Node):

bun run build       # bun build → dist/index.js (target node)

5. Chạy

bun run dev         # chạy từ src, tự reload khi đổi file (--watch)
# hoặc
bun start           # chạy từ src (bun run src/index.ts)

Bun tự nạp .env ở thư mục hiện tại. Log đi ra stderr (stdout dành riêng cho giao thức MCP).

Transport HTTP (deploy dạng service)

Mặc định là stdio. Để chạy dưới dạng service HTTP:

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 bun start

Server phục vụ MCP streamable tại POST http://<host>:3000/mcp (stateless). Nếu chọn http mà thiếu/sai MCP_HTTP_PORT, server dừng với lỗi rõ. HTTP hiện không kèm auth — chỉ dùng nội bộ hoặc sau reverse proxy.

Test

bun test        # bộ test logic thuần (không cần Discord)

6. Cấu hình trong Claude Code

Thêm server vào cấu hình MCP của Claude Code (chạy thẳng source bằng Bun, không cần build):

{
  "mcpServers": {
    "discord": {
      "command": "bun",
      "args": ["run", "D:/personal/discord-mcp/src/index.ts"],
      "env": {
        "DISCORD_TOKEN": "your-bot-token-here",
        "DISCORD_GUILD_ID": ""
      }
    }
  }
}

Sau khi thêm, khởi động lại Claude Code; các tool get_server_overview, list_roles, list_channels, get_channel_permissions, ping sẽ khả dụng.

env truyền trực tiếp trong config vì cwd khi Claude Code khởi chạy có thể khác thư mục dự án (nên không chắc .env được nạp).

Cấu trúc mã

src/
  index.ts              # entrypoint: nạp config, chọn transport (stdio/http), kết nối Discord
  config/               # schema env (zod) + loader
  discord/              # client (singleton) + format + structureOps (service ghi dùng chung)
  server/               # bootstrap MCP server + stdio/http transport + helper thực thi tool
  blueprints/           # schema + 6 blueprint + recommend + discovery (P3/P5)
  tools/inspection/     # 5 tool read-only (P1)
  tools/structure/      # 14 tool ghi role/channel/permission (P2)
  tools/blueprint/      # 6 tool blueprint/tư vấn (P3)
  tools/community/      # enable_community + get/configure_onboarding (P4)
  tools/audit/          # audit_permissions + view_as (P4)
  tools/handoff/        # generate_handoff (P4)
  lib/                  # logger (stderr), lỗi có cấu trúc
tests/                  # bun test — logic thuần (blueprint, recommend, config, format)