内容
# Discord 服务器构建工具 MCP
用于 AI 编码代理的安全、自托管 Discord 服务器构建工具。该项目不再运行 Discord AI 机器人或调用 OpenAI、Claude、Gemini、Groq 或 OpenRouter。代理创建或编辑 JSON/YAML 蓝图；该工具验证它们，显示预览/差异，写入备份，并在明确确认后应用更改。
## 该工具的作用
- 在调用 Discord API 之前验证 Discord 服务器蓝图。
- 将创建/更新/删除操作作为干燥运行进行预览。
- 在确认后应用角色、类别、通道和权限覆盖。
- 在每次应用之前写入备份，并支持从备份中回滚。
- 除非明确允许，否则阻止管理员角色和特权权限。
- 除非蓝图和命令行都明确允许，否则阻止删除。
- 公开 CLI 和可选的 MCP 服务器，供 Codex、Claude Code 或其他代理使用。
## 安装
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
创建 Discord 机器人，将其邀请到目标服务器，并授予仅限于您计划运行的操作所需的权限。对于实时预览、导出、备份和应用，请设置：
```bash
set DISCORD_BOT_TOKEN=您的Discord机器人令牌
```
永远不要提交 `.env` 文件或真实令牌。`.gitignore` 默认情况下排除它们。
## 蓝图工作流程
1. 请求代理在 `examples/` 或另一个本地文件中创建或编辑蓝图。
2. 在本地验证它。
3. 预览针对空状态、备份文件或实时公会的操作计划。
4. 手动审查差异。
5. 仅在确认字符串完全匹配时应用。
```bash
python -m discord_builder validate examples/community-blueprint.yaml
python -m discord_builder preview examples/community-blueprint.yaml
python -m discord_builder preview examples/community-blueprint.yaml --guild-id 123456789012345678
python -m discord_builder apply examples/community-blueprint.yaml --guild-id 123456789012345678 --confirm APPLY:123456789012345678
```
删除始终需要两次确认：
```bash
python -m discord_builder apply blueprint.yaml --guild-id 123456789012345678 --allow-delete --confirm APPLY:123456789012345678
```
管理员和特权权限也需要确认：
```bash
python -m discord_builder apply team-blueprint.json --guild-id 123456789012345678 --allow-privileged --confirm APPLY:123456789012345678
```
## 命令
```bash
python -m discord_builder validate <蓝图文件>
python -m discord_builder preview <蓝图文件> [--state backup.json] [--guild-id 公会ID] [--json]
python -m discord_builder export --guild-id 公会ID --out current.json
python -m discord_builder backup --guild-id 公会ID --out-dir backups
python -m discord_builder apply <蓝图文件> --guild-id 公会ID --confirm APPLY:公会ID
python -m discord_builder rollback <备份文件> --guild-id 公会ID --allow-delete --confirm ROLLBACK:公会ID
python -m discord_builder mcp-server
```
## 蓝图格式
蓝图是 JSON 或 YAML 对象：
```yaml
version: 1
safety:
delete_unknown_channels: false
delete_unknown_roles: false
allow_admin_roles: false
allow_privileged_permissions: false
roles:
- name: 成员
color: "#57F287"
permissions: [view_channel, send_messages, read_message_history]
categories:
- name: 社区
overwrites:
- target: "@everyone"
allow: [view_channel]
deny: []
channels:
- name: general
type: text
topic: 主要聊天
```
支持的频道类型有 `text`、`voice`、`forum` 和 `stage`。文本和论坛频道名称必须为小写，只能包含字母、数字、连字符或下划线。
## 安全模型
该工具假设 AI 代理可能会出错。因此：
- `preview` 是只读的，是正常的代理规划步骤。
- `apply` 需要 `--confirm APPLY:<guild-id>`。
- `rollback` 需要 `--confirm ROLLBACK:<guild-id>` 和 `--allow-delete`。
- 除非蓝图设置 `delete_unknown_*: true` 且命令包含 `--allow-delete`，否则永远不会删除未知频道/角色。
- 除非蓝图设置 `allow_admin_roles: true` 且命令包含 `--allow-admin`，否则拒绝 `administrator`。
- 管理/审核权限（例如 `manage_roles`、`manage_channels`、`ban_members`、`kick_members`、`manage_messages` 和 `mention_everyone`）需要 `allow_privileged_permissions: true` 和 `--allow-privileged`。
- 在每次应用之前写入备份。
## MCP 使用
通过 stdio 运行 MCP 服务器：
```bash
python -m discord_builder mcp-server
```
MCP 配置示例：
```json
{
"mcpServers": {
"discord-server-builder": {
"command": "python",
"args": ["-m", "discord_builder", "mcp-server"],
"env": {
"DISCORD_BOT_TOKEN": "您的Discord机器人令牌",
"DISCORD_BUILDER_ENABLE_APPLY": "0"
}
}
}
}
```
除非 `DISCORD_BUILDER_ENABLE_APPLY=1`，否则禁用 MCP 应用。即使如此，MCP 工具也需要确切的确认字符串 `APPLY:<guild-id>`。
推荐的代理指令：
> 仅创建或更新蓝图文件。始终先运行验证和预览。除非人类审查了差异并提供了确切的确认字符串，否则不要调用应用。
## 备份和回滚
创建备份：
```bash
python -m discord_builder backup --guild-id 123456789012345678
```
从备份回滚：
```bash
python -m discord_builder rollback backups/123456789012345678-20260608T120000Z.json --guild-id 123456789012345678 --allow-delete --confirm ROLLBACK:123456789012345678
```
回滚将备份应用于所需状态，可以删除备份后创建的资源，因此它始终需要 `--allow-delete`。
## 开发
运行本地检查：
```bash
python -m unittest discover -s tests
python -m compileall discord_builder tests
```
