使用说明

总计-无折扣-Bot-MCP

Totally-Not-a-Discord-Bot（Totally-Not-a-Bot）是一个代理循环+MCP服务器，用于代理AI在不和谐服务器中进行交互，特别关注审核和安全性。

我开始这个项目是因为我想熟悉开发MCP。我能够与影响整个项目的某些架构选择、逻辑和其他决定作斗争。我建立了许多关于MCP和代理AI的心理模型，如果将来我必须开发另一个MCP，它会走得更快，而且是一个更有效的过程。

项目地图

docs/
|--tdd/tdd.md
|--todo.md
scripts/
|--tests.py
src/
|--bot/
|   |--internals/
|   |--tools/
|   |--app.py
|   |--discord_bot.py
|   |--exceptions.py
|   |--models.py
|--mcp/
|   |--server.py
|--rag/
|   |--agent.py
|   |--main.py
|--.env.example
|--.ruff.toml
|--pixi.lock
|--pixi.toml
|--README.md

先决条件和环境设置

在本地运行 完全不是机器人，确保您的系统上安装了以下先决条件：

python：版本 3.12 或更高（配置在 pixi.toml).
皮克西A. 现代包管理器.
Discord机器人A. Discord机器人启用了必要的权限（请参阅快速开始下面的指南）。

本地存储库设置

通过复制示例文件来设置.env：
```
cp .env.example .env
```
初始化环境并安装依赖项：
```
pixi install
```

快速启动和配置

获取Discord Bot

您需要设置自己的Discord应用程序，以便MCP访问：

去 Discord开发者门户
创建新应用程序或使用现有应用程序
如果您还没有创建机器人，请转到“机器人”部分并创建一个机器人->需要机器人、管理员和应用程序id权限
复制机器人令牌并将其设置为 DISCORD_BOT_TOKEN 在你的 .env 文件
要获取服务器id，请右键单击服务器图标，将鼠标悬停在“复制服务器信息”上，然后复制服务器id
将其设置为 DISCORD_BOT_GUILD 在你的 .env 文件
确保您已启用所有意图->机器人选项卡

启动应用程序

一旦你 .env 该文件包含您的机器人令牌和公会id，您可以使用Pixi启动应用程序。您可以使用以下可用命令选择运行MCP服务器或自主机器人：

1.独立MCP服务器

通过标准输入/输出公开机器人的工具(stdio)对于没有机器人自主行动的外部AI客户端（如Claude Desktop）：

pixi run mcp

2.独立自主机器人

要在不暴露MCP服务器的情况下，使用其本地LangChain循环自主管理服务器来运行机器人：

pixi run bot

建筑学

完全不是机器人 采用多线程异步架构，旨在将您的AI代理连接到Discord机器人。代码库分为三个不同的支柱：

graph TD
    A[Discord API] <-->|Discord Bot Connection| B[bot.discord_bot]
    B <-->|Services Layer| C[bot.internals.services]
    C <-->|Tool Execution| D[bot.tools]
    D <-->|Native Agent Loop| E[rag.agent]
    D <-->|FastMCP Server| F[mcp.server]
    F <-->|stdio Transport| G[External MCP Client]

核心机器人(src/bot/)：管理模型定义、异常映射，并初始化Discord客户端。服务层在Discord内部执行操作，工具层提供标准化的函数包装器。
RAG代理(src/rag/)：包含本地LangChain代理循环(agent.py)它通过直接调用来有机地处理Discord聊天 bot.tools Python函数。
MCP服务器(src/mcp/)：使用FastMCP实现声明性工具注入机制，包装本机 bot.tools 通过标准输入/输出公开它们的函数(stdio)对于外部AI代理。

MCP集成指南

连接 完全不是机器人 在您首选的AI代理客户端（例如，Claude Desktop、Cursor等）上，将下面的配置块添加到您的MCP配置文件中。尽管如此，我能想到的这个MCP的最佳用途是将其连接到一个有自己反馈回路的代理。

Claude桌面配置

将此添加到您的 claude_desktop_config.json （位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "totally-not-a-bot": {
      "command": "pixi",
      "args": [
        "run",
        "mcp"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "YOUR_DISCORD_BOT_TOKEN",
        "DISCORD_BOT_GUILD": "YOUR_DISCORD_BOT_GUILD"
      }
    }
  }
}

确保更换 YOUR_DISCORD_BOT_TOKEN 和 YOUR_DISCORD_BOT_GUILD 使用实际的id或在活动系统环境中设置它们。

当前工具

完全不是机器人 向代理模型公开了多种Discord API工具，按功能类别组织：

类别	工具名称	描述	关键输入
消息	`get_recent_messages`	从通道（默认值20）获取最近的消息，可选择按时间戳过滤	`channel_id`, `limit`, `timestamp`
	`get_pinned_messages`	获取特定频道中的所有固定消息	`channel_id`
	`get_thread_from_message`	获取从特定消息开始的所有线程	`channel_id`, `message_id`
	`send_message`	发送短信，可选择作为对另一条消息的回复	`channel_id`, `content`, `reply_to_message_id`
	`edit_message`	编辑现有短信	`channel_id`, `message_id`, `new_content`
	`delete_message`	删除现有邮件	`channel_id`, `message_id`
	`send_embed`	发送嵌入消息	`channel_id`, `embed`, `reply_to_message_id`
	`edit_embed`	编辑现有嵌入消息	`channel_id`, `message_id`, `new_embed`
	`pin_message`	在通道中固定特定消息	`channel_id`, `message_id`, `reason`
	`unpin_message`	打开频道中的特定消息	`channel_id`, `message_id`, `reason`
	`add_reaction`	在消息中添加表情符号反应	`channel_id`, `message_id`, `emoji`
	`remove_reaction`	从消息中删除表情符号反应	`channel_id`, `message_id`, `emoji`
频道	`get_channel_info`	获取特定频道的元数据	`channel_id`
	`get_all_channels_info`	列出公会中所有频道的元数据和详细信息	-
	`create_channel`	创建新的文本、语音或舞台频道	`name`, `type`, `category_id`, `position`
	`edit_channel`	更新现有频道的设置（名称、主题、类型等）	`channel_id`, `name`, `topic`, `nsfw`, `slowmode_delay`
	`delete_channel`	删除频道	`channel_id`
	`move_channel`	将频道移动到目标类别	`channel_id`, `category_id`
	`set_channel_position`	调整通道的位置/顺序	`channel_id`, `position`
	`bulk_create_channels`	同时创建多个通道	`channels` （列表）
	`bulk_edit_channels`	同时更新多个频道	`channels` （列表）
	`bulk_delete_channels`	同时删除多个频道	`channel_ids` （列表）
分类	`get_all_categories_info`	获取所有类别的详细信息和通道映射	-
	`create_category`	创建新类别	`name`, `position`
	`edit_category`	重命名或更新类别	`category_id`, `name`
	`delete_category`	删除类别	`category_id`
	`move_category`	调整类别排序位置	`category_id`, `position`
	`bulk_create_categories`	同时创建多个类别	`categories` （列表）
	`bulk_edit_categories`	同时更新多个类别	`categories` （列表）
	`bulk_delete_categories`	同时删除多个类别	`category_ids` （列表）
用户	`get_user_info`	解析用户的详细配置文件、角色和服务器加入详细信息	`user_id`
	`send_direct_message`	向用户发送私人消息	`user_id`, `content`
	`send_direct_message_with_embed`	发送带有丰富嵌入的私人消息	`user_id`, `embed`
角色	`get_all_roles`	列出服务器中配置的所有角色的详细信息	-
	`get_role_by_id`	检索特定角色的元数据	`role_id`
	`assign_role_to_user`	为服务器成员分配角色	`user_id`, `role_id`
	`remove_role_from_user`	从服务器成员中删除角色	`user_id`, `role_id`
	`create_role`	创建具有颜色/权限的新自定义角色	`name`, `color`, `hoist`, `mentionable`
	`edit_role`	修改现有角色的配置	`role_id`, `name`, `color`, `hoist`, `mentionable`
	`delete_role`	从服务器中删除角色	`role_id`
简介	`set_bot_status`	更新机器人的活动状态（在线、空闲、dnd、离线）	`status`
	`set_bot_activity`	更新机器人的活动表示（播放、流媒体等）	`activity_type`, `name`, `url`
执行	`mute_user`	将服务器中的用户（文本和语音）静音，可选地持续一段时间	`user_id`, `duration_minutes`
	`unmute_user`	在服务器中取消用户的静音	`user_id`
	`kick_user`	以可选原因将用户从服务器上踢出	`user_id`, `reason`
	`ban_user`	以可选原因禁止用户访问服务器	`user_id`, `reason`
	`unban_user`	取消用户与服务器的绑定	`user_id`
	`move_user`	将用户移动到指定的语音频道	`user_id`, `target_channel_id`
	`disconnect_user`	断开用户与语音通道的连接	`user_id`

更多的来了！这个项目仍在积极开发中，我还有很多东西要实施和学习！

开发指南

如果您想贡献功能、改进现有API或编写自己的MCP工具，请遵循以下指南。最重要的是，我真的鼓励任何人做出自己的贡献，看看会非常有趣，我很乐意提供帮助。

添加新的MCP工具

所有工具都是通过声明驱动的 FastMCP，这意味着您的Python签名和文档字符串直接生成代理使用的模式：

实施该工具：在中打开或创建相应的工具模块 src/bot/tools/ （例如。， enforcement_tools.py).定义一个异步函数，使用 typing.Annotated 描述每个参数：

from typing import Annotated

async def example_tool(
    user_id: Annotated[int, "The target Discord user ID"],
    reason: Annotated[str | None, "The reason for this action"] = None
) -> str:
    """
    Brief description of what the tool does.
    
    Args:
        user_id (int): The target Discord user ID
        reason (str, optional): The reason for this action
    """
    # Your implementation logic using client services
    return "Success details"

注册工具：打开[src/mcp/server.py](file:///Users/archzak/Desktop/totally-not-a-bot/src/mcp/server.py)，导入您的函数，并将其添加到MCP实例中：
```
from bot.tools.enforcement_tools import example_tool

mcp.add_tool(example_tool)
```
服务层：确保在服务层内编写实际的逻辑，如果需要，可以制作一个dto，用于将Pydantic模型返回给AI。

Pixi开发任务

我用 皮克西 用于依赖性管理和可重复的开发任务。以下CLI命令已预先配置：

命令	操作	详细信息
`pixi install`	安装依赖项	初始化虚拟环境并同步所有库。
`pixi run mcp`	启动MCP服务器	启动Discord客户端并打开stdio MCP服务器（禁用本机代理）。
`pixi run bot`	启动Bot	使用本地LangChain代理（禁用MCP）启动自主Discord客户端。
`pixi run format`	自动格式化和Lint	运行 `ruff` 自动格式化导入顺序和语法样式。
`pixi run testscript`	运行测试脚本	执行 `scripts/tests.py` 以验证服务器功能。
`pixi add <pkg>`	添加依赖关系	安装库并将其版本锁定在 `pixi.toml` / `pixi.lock`.

贡献

请随时为 完全不是机器人！由于这个项目仍在积极开发中，并且是一次学习之旅，请记住这一点（我也是一名大学生）。我总是乐于接受建议、功能、改进和潜在的错误修复。

我会尽可能为问题添加模板并拉取请求，但现在我只想说，我想保持PR较小，专注于一个更改。此外，如果您要添加新的MCP工具，请确保更新上面的工具表以包含新工具。

在提交任何代码之前，请运行格式化任务以保持存储库整洁。无论如何，该分支都无法合并：

pixi run format

使用说明

总计-无折扣-Bot-MCP

项目地图

先决条件和环境设置

本地存储库设置

快速启动和配置

获取Discord Bot

启动应用程序

1.独立MCP服务器

2.独立自主机器人

建筑学

MCP集成指南

Claude桌面配置

当前工具

开发指南

添加新的MCP工具

Pixi开发任务

贡献

相关 MCP

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Claude Code开发工具包

区块链交互服务器

语言服务器协议模型上下文协议