Veilleur

Veilleur — Discord MCP 服务

English version

Veilleur 是一个 MCP（Model Context Protocol）服务，可通过 AI 管理 Discord 服务。它在本地运行，并通过 Discord 机器人创建频道、修改角色、发送嵌入消息等。

它的理念是：你告诉 AI 想做什么，由 AI 准备好变更，然后由你确认后再应用。这样可以避免在不知道 AI 会做什么的情况下，就把服务器的控制权交给它。

这个项目是在 AI 的帮助下创建的。

工作原理

例如，你可以提出这样的要求：

创建一个“欢迎”分类，其中包含只读规则频道和“版主”角色。

AI 会向你展示计划执行的操作。如果你觉得没问题，电脑上会弹出一个窗口：勾选复选框并确认即可。随后，Veilleur 会保存服务器结构，并由 AI 执行变更。

如果对结果不满意，你可以要求回退。注意：这并不是完美的 Ctrl+Z。 已删除的频道可以重新创建，但其中的消息会丢失，而且频道会有新的 ID。详情请参阅备份。

它能做什么

• 创建、修改和删除频道、分类及角色；管理其权限。
• 添加或移除角色、搜索成员、修改昵称及管理超时。
• 发送消息和嵌入消息，或修改机器人发送的消息。
• 将多个操作分组、备份服务器结构并准备回退。

机器人需要相应的 Discord 权限，而且只能管理位于其角色下方的角色。Discord 服务器必须已经存在。

安装

1. 前提条件

• Windows、Python 3.11 和启动器 py。确认界面使用 Tkinter，通常随 Python 一同安装。
• 一个你有权邀请机器人的 Discord 服务器。
• 一个支持通过 stdio 使用 MCP 服务的 AI 客户端，例如 Codex。
• 互联网连接：程序在你的电脑上运行，但需要连接 Discord。

2. 创建机器人

1. 在 Discord 开发者门户创建一个应用。
2. 在 Bot 选项卡中生成令牌，并留待后续使用。不要在任何地方发布它。
3. 在 OAuth2 → URL Generator 中选择 bot 和所需权限，然后打开生成的链接以邀请机器人。
4. 在服务器的 Discord 设置中，将机器人的角色置于它需要管理的角色上方。
5. 在 Discord 中启用开发者模式，然后右键点击服务器 → 复制服务器 ID。

3. 配置 Veilleur

下载或克隆代码仓库，然后在其文件夹中打开 PowerShell：

Set-ExecutionPolicy -Scope Process Bypass
.\installer.ps1

安装程序会创建 Python 环境，并在 .env 和 config.json 不存在时创建这两个文件。

打开 .env，在 = 后填入你的令牌：

DISCORD_BOT_TOKEN=ton_token

在 config.json 中，将服务器 ID 填入引号之间：

{
  "guild_id": "123456789012345678"
}

这两个文件会被 Git 忽略。如果令牌泄露，请在 Discord 门户中重新生成。

4. 连接你的 AI 客户端

对于 Codex，请在项目目录中运行以下命令：

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
codex mcp add discord-local -- $pythonDiscord $serveurDiscord

重启 Codex，然后尝试说：“读取我的 Discord 服务器，并提出一种组织方式。”如果 discord-local 已使用这些路径完成配置，则无需再次添加。

对于 OpenCode v2，安装项目并填写 .env 和 config.json 后，请在仓库目录中运行以下命令：

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
opencode mcp add veilleur --global -- $pythonDiscord $serveurDiscord
opencode mcp list

此配置为全局配置：Veilleur 可在你的 OpenCode 项目中使用。如有需要，请重启 OpenCode。已使用 OpenCode v2.1.4 和测试配置验证连接。对于其他版本，请参阅 OpenCode 文档。

对于 Claude Code，填写 .env 和 config.json 后，请在仓库目录中运行：

$pythonDiscord = (Resolve-Path .\.venv\Scripts\python.exe).Path
$serveurDiscord = (Resolve-Path .\server.py).Path
claude mcp add --scope user --transport stdio veilleur -- $pythonDiscord $serveurDiscord
claude mcp list

此配置可用于你的 Claude Code 项目，与 Claude Desktop 聊天的配置相互独立。已使用 Claude Code 2.1.226 和测试配置验证连接。请参阅 Claude Code 文档。

对于其他兼容 stdio 的 MCP 客户端，请将 .venv\Scripts\python.exe 的绝对路径用作命令，并将 server.py 的绝对路径用作参数。具体配置取决于客户端。验证窗口必须能够在你的 Windows 会话中打开。

使用 pip 安装

Veilleur 可通过 PyPI 和 官方 MCP 注册表获取。在注册表中搜索 io.github.NoPaperSpray/veilleur。

在 Windows 上，你可以将软件包安装到专用环境中：

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install veilleur-discord-mcp

在 MCP 客户端中，将 .venv\Scripts\veilleur-discord-mcp.exe 的绝对路径用作命令，并在其本地配置中设置环境变量 DISCORD_BOT_TOKEN 和 DISCORD_GUILD_ID。请妥善保管 token：某些客户端会以明文存储此配置。

默认情况下，此安装会将计划和备份保存在 %LOCALAPPDATA%\Veilleur。你可以使用 VEILLEUR_HOME 选择其他目录。在仓库副本中，python -m pip install . 也会安装此软件包。旧命令 python server.py 仍会使用仓库目录中的 .env、config.json 和 data/：它的备份与已安装软件包的备份相互独立。

验证与备份

计划必须先在本地窗口中获得批准，才能执行。此许可仅对该特定计划有效，时长为 10 分钟，且只能执行一次。如果服务器或目标在此期间发生变化，则必须准备新计划。

执行前，Veilleur 会备份结构、角色、部分设置，以及直接受影响的成员或消息。文件存储在 data/ 中，可能包含私人信息。

备份内容取决于机器人能够看到的内容：无法访问的频道可能不会包含在内。依赖备份进行恢复前，请先检查机器人的权限。

恢复存在一些限制：重新创建的项目会获得新的 ID；已删除的消息、附件和反应无法恢复。外部链接、帖子串、邀请和集成不会自动修复。已删除角色的分配情况也不会为所有成员备份。

回滚同样需要经过预览，并可能覆盖备份之后所做的修改。如果发生错误或网络响应丢失，请先查看日志，再决定是否重试。

验证机制适用于 Veilleur 的 MCP 工具。它无法保护你的 token 免受能够访问你的文件或 Discord 账号的程序侵害。

故障排除

• 客户端看不到 Veilleur：检查 Python 和 server.py 的路径，然后重启客户端。
• 窗口未打开：向 AI 询问计划 ID，然后在项目目录中运行 .\.venv\Scripts\python.exe approve.py ID_DU_PLAN。
• 401 错误：检查 .env 中的 token。
• 403 错误：检查机器人的权限和角色位置。某些成员搜索和消息读取操作可能还需要在 Discord 门户中启用 intents。
• 机器人处于离线状态：这是正常的。Veilleur 使用 HTTP API，无需连接 Gateway。

也可以让 AI 运行 diagnostic：它会检查服务器级别的机器人连接和权限，但不会计算各个频道特有的例外情况。

更多详情请参阅完整手册和 AI 工具指南。

测试

测试可离线运行，不会使用你的 token：

.\.venv\Scripts\python.exe -m unittest discover -v

程序更新后，请重启 MCP 客户端，以便加载新版本。

贡献

发现 Bug 或有新想法？请创建 issue。要贡献代码，请参阅 CONTRIBUTING.md。本项目采用 MIT 许可证。