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	Chức năng
get_server_overview	Tên, số thành viên, features, verification level, đếm role/category/channel
list_roles	Danh sách role: tên, màu, position, hoist, quyền — theo phân cấp
list_channels	Category + kênh con, loại kênh, quan hệ cha–con
get_channel_permissions	Permission overwrite của một kênh (role/member, allow/deny)
ping	Trạng thái kết nối bot

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

Nhóm	Tool
Role	create_role, edit_role, delete_role, reorder_role, assign_role, remove_role
Category/Channel	create_category, create_channel, edit_channel, move_channel, delete_channel, sync_channel_to_category
Permission	set_channel_permission, remove_channel_permission

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")

Tool	Chức năng
list_blueprints	Liệt kê blueprint (6 loại: game, education, community, crypto, creator, business)
get_blueprint	Chi tiết một blueprint theo id
get_discovery_questions	Bộ câu hỏi khám phá nhu cầu (trước khi dựng)
recommend_blueprint	Đề xuất blueprint từ mục đích (+ quy mô/nhóm) kèm lý do; mơ hồ thì trả câu hỏi
propose_changes	So blueprint với hiện trạng guild → kế hoạch (không ghi)
apply_blueprint	Dựng phần còn thiếu (categories→channels→roles→overwrites), idempotent, có dryRun

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)

Tool	Chức năng
enable_community	Bật Community (cần rules + public-updates channel) — bước 1 trước Onboarding
get_onboarding	Đọc cấu hình Onboarding hiện tại (read-only)
configure_onboarding	Cấu hình Onboarding (default channels + prompts→role/kênh); kiểm ràng buộc ≥7/≥5 & Community trước
audit_permissions	Quét rủi ro: Administrator, kênh staff bị lộ, announcement mở, role bot thấp (có severity)
view_as	Kênh một role/member thấy được / không thấy được
generate_handoff	Xuất tài liệu bàn giao Markdown (cây role + sơ đồ kênh + bot/bảo mật từ blueprint)

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)