# 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`](openspec/changes/project-roadmap) và tài liệu nền trong [`docs/`](docs/00-tong-quan.md).

- **Stack:** TypeScript + [discord.js](https://discord.js.org) + [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) (transport stdio).
- **Runtime & package manager:** [Bun](https://bun.sh) ≥ 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

```bash
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

```bash
bun install
```

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

```bash
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):

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

## 5. Chạy

```bash
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:

```bash
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

```bash
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):

```json
{
  "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)
```