用途
aiogram-mcp 是一个 MCP（Model Context Protocol）服务器中间件，用于把基于 aiogram 的 Telegram 机器人接入 AI 智能体。它让任何 aiogram 机器人变成 MCP 服务器，使 Claude Desktop 等 AI 客户端能够通过现有机器人发送消息、读取聊天历史、构建交互式菜单并实时响应事件，无需重写任何 handler。机器人在 Telegram 用户侧照常运行，MCP 服务器与其并行运行，向 AI 智能体开放同一机器人的工具与资源。
主要能力
- 约 30 个工具：覆盖消息发送（5）、交互式消息（3）、用户（3）、聊天（6）、富媒体（10）、事件（2）和广播（1，默认关闭/需显式启用）。
- 7 项资源：机器人信息、配置、聊天列表、消息历史、事件队列、文件元数据、审计日志，AI 智能体无需调用工具即可读取。
- 3 个提示词：内置审核、公告和用户报告工作流，为 AI 智能体提供结构化上下文。
- 结构化输出：每个工具返回带 outputSchema 的类型化 Pydantic 模型，便于程序化解析。
- 实时事件：机器人通过 MCP 通知向 AI 客户端推送 Telegram 事件，无需轮询；AI 智能体调用一次 subscribe_events 后即可接收符合过滤条件的推送。
- 交互式消息：AI 智能体可创建内联键盘菜单、处理按钮点击、编辑消息，实现菜单、确认和多步向导等完整交互界面。
- 安全与控制：内置令牌桶限流防止 Telegram 429 错误；支持权限级别（只读、消息、审核、完全管理）；记录每次工具调用的时间戳和参数，可通过 telegram://audit/log 资源访问。
- 安全限制项：allowed_chat_ids 限定 AI 可交互的聊天（默认全部聊天）；enable_broadcast 默认关闭广播工具；max_broadcast_recipients 限制单次广播的聊天数上限。
使用方式
要求 Python 3.10+ 和 aiogram 3.20+。在现有机器人中添加相应代码（约 5 行），并在 claude_desktop_config.json 中配置连接，即可让 Claude 发送消息、读取历史、创建按钮菜单并响应事件。若要捕获按钮点击，机器人需要注册 dp.callback_query.middleware(middleware)。
适用场景
为已有 aiogram Telegram 机器人增加 AI 智能体控制能力的场景，例如让 AI 代发消息、读取聊天历史、创建交互式菜单、订阅并响应实时事件、执行内容审核或广播任务，同时保持原有 handler 不变。
限制
具体安装命令、配置示例与各工具的详细参数在提供的资料中未完整给出，暂未提供；许可证为 MIT。
