telebotstudio-mcp

<div align="center"> # TeleBot Studio MCP **让您的 AI 基于官方文档。让它管理您的机器人。** [](https://python.org) [](LICENSE) [](https://modelcontextprotocol.io) [](https://github.com/jlowin/fastmcp) []() 一个生产就绪的 MCP 服务器，包含两个引擎： 1. **文档搜索** — 跨官方 TeleBot Studio 文档的 BM25 排名搜索。零嵌入。零外部 API。离线工作。 2. **机器人管理** — 完整的 REST API 集成。从任何 MCP 兼容的 AI 客户端创建、配置和控制您的 TeleBot Studio 机器人。 [快速开始](#快速开始) · [获取 API 凭证](#获取您的telebotstudio-api-凭证) · [工具](#mcp-工具-26) · [架构](#架构) · [部署](#部署) · [安全](#安全与隐私) </div> --- ## 为什么存在 LLM 会编造 API 细节。当您询问 LLM 关于 TeleBot Studio 时，它会根据过时的训练数据进行猜测 — 错误的函数签名、发明的参数、过时的模式。这是 **文档漂移**：AI 说的内容与文档实际指定的内容之间的差距。 TeleBot Studio MCP 通过两种方式缩小了这一差距： - **文档工具** 让您的 AI 基于官方文档。如果答案不在语料库中，服务器返回空值 — 没有虚拟函数，没有发明的 API。 - **API 工具** 让您的 AI 执行操作 — 创建机器人、编写命令、启动和停止它们 — 通过官方 TeleBot Studio REST API v2。 结果：一个既了解平台又能对其采取行动的 AI 助手。 --- ## 功能 | | 您获得的内容 | |:---|:---| | **文档** | BM25 全文搜索、标题感知分块、单字 + 二字词标记化、5 种作用域搜索模式、LRU 缓存、100% 离线 | | **机器人管理** | 创建 / 删除 / 更新机器人、创建 / 更新 / 删除 / 列出命令、启动 / 停止 / 重启机器人 | | **代理管道** | 计划器 → 验证器 → 预览 → 执行器，用于诸如完整机器人部署等多步骤操作 | | **批量操作** | 批量创建或删除命令，并带有每步成功/失败报告 | | **安全性** | 执行前预览、会话作用域凭证（从不持久化）、令牌掩蔽 | | **服务器** | FastMCP、STDIO + HTTP/可流式 HTTP 传输、`/health` 端点、线程安全会话、重试和退避 | --- ## 快速开始 ### 先决条件 - Python 3.9+ - pip - 一个 [TeleBot Studio](https://telebotstudio.com) 账户（用于 API 工具 — 文档工具无需账户） ### 安装 ```bash git clone https://github.com/harshi79/telebotstudio-mcp.git cd telebotstudio-mcp python -m venv venv source venv/bin/activate # Windows: .\venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` ### 验证索引 ```bash python build_index.py --validate ``` 这会从 `docs/` 目录构建 BM25 索引，并检查所有分块是否有问题。您应该会看到类似的内容： ``` ✓ 所有 730 个分块都已成功验证。 ``` ### 运行服务器 ```bash # STDIO 模式（Claude Desktop、Cursor、Windsurf 等） python server.py # HTTP 模式（远程客户端、Web 仪表板、Render 部署） python server.py --transport http ``` ### 连接到您的 AI 客户端 对于 **Claude Desktop**，请在您的配置中添加以下内容： ```json { "mcpServers": { "telebotstudio": { "command": "python", "args": ["/absolute/path/to/telebotstudio-mcp/server.py"] } } } ``` 对于 **Cursor**、**Windsurf**、**Cline** 或 **Continue** — 将命令设置为 `python`，参数设置为 `server.py` 的绝对路径，并选择 STDIO 传输。 ### 使用 API 工具 服务器运行并连接后，按以下顺序调用工具： 1. `tbs_set_api_key` — 使用您的 TeleBot Studio API 密钥进行身份验证 2. `tbs_set_bot_id` — 选择要操作的机器人（或让 `tbs_create_bot` 自动设置） 3. 调用任何管理工具 — `tbs_create_command`、`tbs_start_bot`、`tbs_deploy_bot` 等。 还没有 API 密钥？请参见下一节。 --- ## 获取您的 TeleBot Studio API 凭证 机器人管理工具需要两条信息：一个 **API 密钥** 和一个 **机器人 ID**。以下是获取两者的方法。 ### 1. 创建一个 TeleBot Studio 账户 如果您还没有，请在以下网址注册： **[telebotstudio.com](https://telebotstudio.com)** 需要一个账户，因为 API 工具会代表您与 TeleBot Studio REST API 通信。您的 API 密钥会验证每个请求。 ### 2. 获取您的 API 密钥 登录后： 1. 打开左上角的菜单（**☰**） 2. 进入 **设置** 3. 滚动到 **API 访问** 4. 复制您的 API 密钥  几点需要注意： - 您的 API 密钥是 **机密的**。永远不要将其提交到 git 中，永远不要公开分享，永远不要在源代码中硬编码。 - 它仅在运行时需要。此 MCP 服务器仅 **存储在内存中** — 它从不写入磁盘，从不以明文记录，从不持久保存。 - 如果您的密钥被泄露，您可以从同一个设置页面重新生成它。 ### 3. 创建您的机器人 如果您还没有 TeleBot Studio 上的机器人： 1. 使用 Telegram 上的 **@BotFather** 创建一个 Telegram 机器人 2. 复制 BotFather 给您的 **机器人令牌** 3. 打开 TeleBot Studio 并使用该令牌创建一个新机器人 或者，您可以直接通过 MCP 工具 `tbs_create_bot` 传递机器人令牌来创建机器人。 ### 4. 获取您的机器人 ID 创建机器人后： 1. 打开左上角的菜单（**☰**） 2. 进入 **我的机器人** 3. 选择您的机器人 4. 打开 **机器人设置** 5. 复制 **机器人 ID**  机器人 ID 几乎所有 REST API 操作都是必需的 — 列出命令、创建命令、启动和停止机器人等。一旦您拥有它，请将其传递给 `tbs_set_bot_id`，这样服务器就会在您的会话中记住它。 --- ## MCP 工具（26 个） ### 文档搜索（8 个） | 工具 | 它能做什么 | |:---|:---| | `search_docs(query, top_k)` | 主要搜索。对所有分块进行全文 BM25 搜索。 | | `get_page(name)` | 通过文件名检索整个文档页面。 | | `list_pages()` | 列出所有可用的文档页面。 | | `search_examples(query, top_k)` | 代码示例和代码片段的范围搜索。 | | `search_api(query, top_k)` | API 参考和端点的范围搜索。 | | `search_library(query, top_k)` | 库和依赖项信息的范围搜索。 | | `search_functions(query, top_k)` | 函数定义和签名的范围搜索。 | | `search_errors(query, top_k)` | 错误和故障排除的范围搜索。 | ### 凭证（3 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_set_api_key(api_key)` | 设置您的 API 密钥（仅存储在内存中，从不持久化）。 | | `tbs_set_bot_id(bot_id)` | 为会话设置活动的机器人 ID。 | | `tbs_credential_status()` | 检查凭证是否已设置（密钥被掩盖）。 | ### 机器人管理（3 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_create_bot(bot_token)` | 使用 Telegram 机器人令牌创建新机器人。自动设置机器人 ID。 | | `tbs_delete_bot(bot_id, confirm)` | 软删除机器人。设置 `confirm=true` 以执行；默认为仅预览。 | | `tbs_update_bot_token(bot_id, new_token, confirm)` | 更新机器人的令牌（触发重启）。支持预览。 | ### 命令管理（5 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_create_command(command, code, bot_id)` | 在机器人上创建新命令。 | | `tbs_get_command(command_name, bot_id)` | 按名称获取命令详细信息。 | | `tbs_update_command(command_name, code, bot_id, confirm)` | 更新命令的代码。支持预览。 | | `tbs_delete_command(command_name, bot_id, confirm)` | 删除命令。支持预览。 | | `tbs_list_commands(bot_id)` | 列出机器人的所有命令。 | ### 机器人控制（3 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_start_bot(bot_id)` | 启动机器人（设置 webhook）。 | | `tbs_stop_bot(bot_id)` | 停止机器人（删除 webhook）。 | | `tbs_restart_bot(bot_id)` | 重启机器人（停止 + 启动）。 | ### 代理工具（2 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_deploy_bot(bot_token, commands_json, confirm)` | 完整部署：创建机器人 → 添加命令 → 启动。 | | `tbs_setup_commands(commands_json, bot_id, confirm)` | 在现有机器人上批量创建命令。 | ### 批量工具（2 个） | 工具 | 它能做什么 | |:---|:---| | `tbs_batch_create_commands(commands_json, bot_id, confirm)` | 顺序创建多个命令。 | | `tbs_batch_delete_commands(command_names_json, bot_id, confirm)` | 顺序删除多个命令。支持预览。 | --- ## 架构 ### 双引擎设计 ``` ┌─────────────────────────────────────────────────────┐ │ FastMCP 服务器 │ │ │ │ ┌──────────────────┐ ┌──────────────────────────┐ │ │ │ 文档引擎（BM25） │ │ 机器人管理引擎（REST API v2） │ │ │ │ │ │ │ │ │ │ 8 个搜索工具 │ │ 计划器 → 验证器 │ │ │ │ 100% 离线 │ │ → 预览 → 执行器 │ │ │ │ 内存索引 │ │ 18 个 API 工具 │ │ │ └──────────────────┘ └──────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ 会话管理器（线程安全，仅限内存） │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ │ │ STDIO / HTTP HTTPS → api.telebotstudio.com ``` ### 代理管道 代理工具（`tbs_deploy_bot`、`tbs_setup_commands`、批量操作）将复杂目标分解为可执行的计划： ``` 用户目标 → 规划器（分解为步骤） → 验证器（检查凭证、参数） → 预览（显示将发生什么，掩盖机密） → [confirm=true] → 执行器（顺序运行步骤） → 批量结果（每步成功/失败） ``` 每个步骤独立运行。如果步骤 3/5 失败，则步骤 4 和 5 仍会执行。结果报告准确执行了什么和未执行什么，以便您始终了解机器人的状态。 ### 预览和确认 破坏性操作 — 删除机器人、删除命令、更新机器人令牌 — 需要 `confirm=true`。当 `confirm` 为 false 或省略时，工具会返回 **预览**：对将要发生的操作的描述，而不执行任何操作。 此两步模式存在是因为 AI 助手可能会误解用户意图。用户说“删除测试机器人”不应意外删除生产机器人。预览让用户在不可逆操作之前进行验证。 --- ## 项目结构 ``` telebotstudio-mcp/ ├── server.py 入口点 — FastMCP 服务器、文档工具、/health ├── loader.py Markdown 加载器和标题感知分块 ├── search.py BM25 索引构建器和搜索引擎 ├── build_index.py CLI 诊断工具 ├── api/ │ ├── __init__.py 公共 API 导出 │ ├── auth.py 输入验证（API 密钥、机器人令牌、命令名称） │ ├── client.py 带有重试、超时和错误映射的 HTTP 客户端 │ ├── errors.py 类型异常层次结构 │ ├── models.py 请求/响应数据类 │ ├── session.py 线程安全凭证管理器 │ ├── bots.py 机器人管理包装器 │ ├── commands.py 命令管理包装器 │ └── bot_control.py 启动 / 停止 / 重启包装器 ├── agent/ │ ├── __init__.py 代理层导出 │ ├── planner.py 将目标分解为执行计划 │ ├── validator.py 验证计划与会话状态 │ ├── preview.py 生成人类可读的计划预览 │ └── executor.py 执行计划，带有速率限制感知 ├── tools/ │ ├── __init__.py │ └── api_tools.py 18 个 MCP 工具定义 ├── docs/ 官方 TeleBot Studio 文档（.md） ├── Dockerfile 容器定义 ├── .dockerignore Docker 构建排除 ├── requirements.txt Python 依赖项 ├── LICENSE MIT 许可证 └── README.md 本文件 ``` --- ## 配置 ### 传输模式 **STDIO** — 默认，用于本地 AI 客户端： ```bash python server.py ``` **HTTP / streamable-http** — 用于远程客户端和部署： ```bash python server.py --transport http --host 0.0.0.0 --port 9000 ``` ### 环境变量 | 变量 | 默认值 | 用途 | |:---|:---|:---| | `TBS_DOCS_DIR` | `docs` | 覆盖文档目录 | | `HOST` | `0.0.0.0` | HTTP 模式的默认主机 | | `PORT` | `8000` | HTTP 模式的默认端口（Render 自动设置此环境变量） | --- ## 部署 ### docker ```bash docker build -t telebotstudio-mcp . docker run -p 8000:8000 telebotstudio-mcp ``` MCP 端点位于 `http://localhost:8000/mcp`，健康检查位于 `http://localhost:8000/health`。 Dockerfile 不会硬编码端口 — 它读取 `PORT` 环境变量，因此您可以覆盖它： ```bash docker run -p 9000:9000 -e PORT=9000 telebotstudio-mcp ``` ### render.com 1. 在 Render 上创建一个新的 **Web 服务** 2. 连接您的 GitHub 仓库 3. 构建命令：`pip install -r requirements.txt` 4. 启动命令：`python server.py --transport http` 5. Render 自动分配 `PORT` 环境变量 — 服务器会获取它 ### 健康检查 `GET /health` 返回 `{"status": "ok"}`。此端点位于 MCP 协议之外，无需身份验证。适用于 UptimeRobot、Render 健康检查或任何正常运行监控器。 --- ## 安全与隐私 - **无遥测** — 零分析、跟踪或电话回家 - **仅内存凭证** — API 密钥和机器人令牌仅存储在内存中。永远不会持久化到磁盘中，永远不会以明文记录 - **令牌掩蔽** — 机器人令牌和 API 密钥在所有日志消息和预览响应中被掩蔽（例如 `tbs_1...xyz`） - **执行前预览** — 删除和更新操作需要显式 `confirm=true`。默认为仅预览 - **输入验证** — 在 API 调用之前验证所有输入（令牌格式、机器人 ID 格式、命令名称长度、代码长度） - **线程安全会话** — 凭证管理器使用线程本地存储和锁以确保 HTTP 传输安全 - **离线文档** — 文档搜索无需网络连接。API 工具需要互联网访问 `api.telebotstudio.com` --- ## 设计决策 <details> <summary>为什么选择 BM25 而不是向量嵌入？</summary> 对于技术文档库，用户搜索确切的函数名、错误代码和类属性。BM25 在此规模上在准确的词典匹配方面在数学上优于语义嵌入 — 零成本、零延迟、零外部依赖。 </details> <details> <summary>为什么选择会话范围的凭证而不是持久化配置？</summary> 将 API 密钥存储在配置文件中是一种安全风险 — 它们可能会提交到 git、日志中泄露或被其他进程访问。会话范围的仅内存凭证在重启时丢失，这是故意的：它强制重新身份验证并防止过时的凭证持续存在。</details> <details> <summary>为什么选择破坏操作的预览和确认？</summary> AI 助手可能会误解用户意图。用户说“删除测试机器人”不应意外删除生产机器人。两步预览 → 确认模式让用户在不可逆操作之前进行验证。</details> <details> <summary>为什么选择同步 HTTP 客户端而不是异步？</summary> FastMCP 工具处理程序可以是同步或异步的。我们使用同步 `httpx.Client` 以简化和可靠性为目的。重试等待逻辑是异步感知（使用 `run_in_executor`）以避免在 HTTP 传输下阻塞事件循环。</details> ## 常见问题 <details> <summary>文档搜索是否支持离线使用？</summary> 支持。一旦安装完成，BM25索引和文档就完全是本地的。API工具需要互联网连接才能访问`api.telebotstudio.com`，但文档工具无需任何网络连接即可工作。 </details> <details> <summary>我可以在Render或Railway上部署吗？</summary> 支持。运行`python server.py --transport http`，服务器会自动读取`PORT`环境变量。 </details> <details> <summary>我的API密钥是否安全？</summary> 您的API密钥仅存储在服务器内存中 - 绝不会写入磁盘，绝不会以明文形式记录。它通过HTTPS传输到`api.telebotstudio.com`，并在服务器重启时丢失。 对于多用户HTTP部署，请注意FastMCP的可流式HTTP传输目前不提供每个客户端的会话标识符。所有HTTP客户端共享一个全局凭证存储。这对于单用户部署来说是没问题的，但不适用于多租户环境。 </details> <details> <summary>如果批量操作部分失败，会发生什么？</summary> 执行器独立运行每个步骤。如果第3步失败，第4步和第5步仍会执行。`BatchResult`报告每一步的成功/失败，以便您可以确切地看到发生了什么以及哪些步骤需要重试。 </details> <details> <summary>支持哪些API端点？</summary> 支持TeleBot Studio REST API v2的所有11个端点： | 方法 | 端点 | 目的 | |:---|:---|:---| | POST | `/v2/create-bot` | 创建新机器人 | | DELETE | `/v2/bots/{botid}` | 删除机器人 | | POST | `/v2/bots/{botid}/update-bot-token` | 更新机器人的令牌 | | POST | `/v2/bots/{botid}/commands` | 创建命令 | | POST | `/v2/bots/{botid}/command/by-name` | 按名称获取命令 | | POST | `/v2/bots/{botid}/command/by-name/update` | 更新命令 | | POST | `/v2/bots/{botid}/command/by-name/delete` | 删除命令 | | GET | `/v2/bots/{botid}/commands/list` | 列出所有命令 | | POST | `/v2/bots/{botid}/start` | 启动机器人 | | POST | `/v2/bots/{botid}/stop` | 停止机器人 | | POST | `/v2/bots/{botid}/restart` | 重启机器人 | </details> --- ## 开发 ### 添加新的API端点 架构设计为可扩展： 1. 在`api/models.py`中添加请求/响应模型 2. 在相应的管理器（`api/bots.py`、`api/commands.py`或`api/bot_control.py`）中添加方法 3. 在`tools/api_tools.py`中添加工具函数，并带有`@mcp.tool`装饰器 4. 如果是破坏性操作，请添加带有预览支持的`confirm`参数 5. 如果是多步骤操作，请在`agent/planner.py`中添加计划器方法 ### 添加文档 1. 将`.md`文件放入`docs/`目录中 2. 重启服务器 - BM25索引会自动重建 ### 编码风格 PEP 8，带有类型提示。每个文件中都包含`from __future__ import annotations`。尽可能保持函数纯粹。 --- ## 路线图 ### 当前（v0.2.0） - [x] 8个文档搜索工具（BM25） - [x] 18个机器人管理API工具 - [x] 会话范围的凭证管理器 - [x] 代理管道（计划器 → 验证器 → 预览 → 执行器） - [x] 破坏性操作的预览和确认 - [x] 带有每步错误报告的批量操作 - [x] 线程安全的凭证存储 - [x] 异步感知重试逻辑 - [x] Docker + Render部署 - [x] `/health`端点 ### 下一步 - [ ] API调用的连接池 - [ ] FastMCP会话中间件，用于客户端凭证隔离 - [ ] 搜索的精确短语匹配增强 - [ ] 标题层次结构增强（H1 > H3） ### 未来 - [ ] GitHub Actions CI/CD管道 - [ ] Pytest单元测试和集成测试套件 - [ ] 抽象为通用文档MCP框架 --- ## 更新日志 ### v0.2.0 - 18个TeleBot Studio API管理工具 - 会话范围的线程安全的凭证管理器 - 带有计划器 → 验证器 → 预览 → 执行器的代理管道 - 破坏性操作的预览和确认 - 批量命令创建/删除 - 带有指数退火的异步感知重试 - 日志和响应中的令牌掩蔽 ### v0.1.0 - 8个文档搜索工具 - 带有单词和二元组标记化的BM25排名 - LRU缓存，输入验证，路径遍历预防 - STDIO和HTTP/streamable-http传输 - Docker支持，`/health`端点 --- ## 贡献 1. Fork仓库 2. 创建一个功能分支（`git checkout -b feature/amazing-feature`） 3. 确保您的代码通过基本检查 4. 编写清晰，描述性的提交消息 5. 对`main`分支打开拉取请求 --- ## 鸣谢 - **[FastMCP](https://github.com/jlowin/fastmcp)** — 用于构建MCP服务器的Python框架 - **[rank-bm25](https://github.com/dorianbrown/rank_bm25)** — 纯Python BM25实现 - **[TeleBot Studio](https://telebotstudio.com)** — 平台和文档 - **[Model Context Protocol](https://modelcontextprotocol.io)** — Anthropic的AI工具集成标准 --- <div align="center"> MIT License — 请参阅 [LICENSE](LICENSE) 一步一步让AI回归现实 </div>