使用说明

🤖💬 Telegram人在环MCP服务器

让你的AI通过Telegram与你对话。 此MCP服务器使任何AI编码助手都可以暂停、向您提问并等待您的回复——就在您的Telegram聊天中。现在与 富文本格式, 图像支持, 本地文件浏览, 窗口截图, 光学字符识别，以及 语音信息转录.

📌 这是什么？

当人工智能代理处理你的代码时，它有时需要问你一个问题——“我应该给这个取什么名字？”“你更喜欢哪种方法？”“这是正确的文件吗？”

此服务器拦截这些问题，并 将它们发送到您的Telegram。您在手机（或桌面电报）上回复，AI会继续处理您的答案。

没有浏览器选项卡。无终端切换。只是电报。

✨ 主要特点

💬 双向文本通信

AI向您的Telegram聊天发送提示
您用文本回复——AI收到文本并继续工作
支持多行输入、选择、确认和信息消息
富文本格式 --AI消息通过以下方式呈现大胆, 斜体, inline code，以及 code blocks 在电报（Markdown→ 具有自动纯文本回退功能的HTML转换）
自动拆分 对于长消息，超过4096个字符的消息会自动在段落/换行符/空格边界处用部分指示符分块(📄 1/3、2/3等）

📸 图像支持（Telegram→ AI)

发送照片 从您的手机/桌面直接到AI
图像作为MCP转发 ImageContent --人工智能可以“看到”你发送的内容
包含 OCR提取 --照片中的文本会自动提取
非常适合：分享错误截图、UI模型、图表、手写笔记

🗂️ 本地图像浏览（AI→ AI)

AI可以 读取任何图像文件 从本地文件系统
浏览文件夹以一次发现和预览多个图像
自动 调整大小 用于大图像（可配置最大尺寸）
可选的 OCR文本提取 来自本地图像
支持PNG、JPEG、GIF、BMP、WebP、TIFF、SVG
可通过以下方式切换 HITL_IMAGE_TOOLS_ENABLED 环境变量

🖥️ 窗口截图（AI→ 电报）

AI可以按标题捕获任何窗口的屏幕截图
Win32打印窗口API --甚至适用于最小化或遮挡的窗口
自动 OCR文本提取 从捕获的屏幕截图
结果以图像+元数据（尺寸、OCR文本、置信度）的形式返回

🎤 语音信息转录（Whispr）

发送 语音信息 在Telegram中，它们会自动转录为文本
使用本地Whisper模型（Whispr模块）保护隐私
转录的文本作为常规文本响应发送给AI
编辑跟踪：显示原始转录和应用的任何编辑

🔄 后备系统

如果未配置Telegram，所有工具将回退到 本机GUI弹出窗口 （tkinter）
使用本地对话框脱机工作
优雅的退化——永远不会阻挡人工智能

🧩 兼容平台

平台	状态	配置位置
VS代码（GitHub复制代理模式）	✅ 完全测试	用户 `mcp.json` 或工作空间 `.vscode/mcp.json`
VS代码（副驾驶聊天）	✅ 作品	与上述相同
克劳德代码（CLI）	✅ 兼容	`~/.claude/mcp.json`
克劳德桌面版	✅ 兼容	请参阅下面的配置示例
光标	✅ 兼容	`.cursor/mcp.json` 在工作空间中
风帆冲浪（Codeium）	✅ 兼容	`~/.codeium/windsurf/mcp_config.json`
克莱恩	✅ 兼容	通过临床MCP设置UI
任何MCP stdio客户端	✅ 兼容	通行证 `python hitl_mcp_server.py` 作为命令

服务器使用标准 MCP 标准 运输——它与 任何客户 支持MCP。

🛠 可用工具

工具	说明
`get_multiline_input`	向Telegram发送提示，等待用户的回复。支持文本, 照片（返回为ImageContent+OCR），以及语音信息（Whispr转录）。主要沟通工具。
`get_user_input`	简单的文本/数字输入对话框
`get_user_choice`	多选选择对话框
`get_image`	从本地文件系统读取单个映像文件。根据需要调整大小，可选OCR。返回图像+元数据。
`list_images`	浏览文件夹中的图像。最多返回N个包含缩略图和元数据的图像。支持排序、过滤、递归扫描。
`get_window_screenshot`	按标题捕获任何窗口的屏幕截图。使用Win32打印窗口（最小化工作）。返回图像+OCR元数据。仅限Windows。
`show_confirmation_dialog`	是/否确认对话框
`show_info_message`	向用户显示信息
`toggle_whispr`	启用/禁用语音消息转录模块
`health_check`	检查服务器状态、Telegram连接、可用功能

🔧 原理

┌──────────────┐     MCP stdio      ┌───────────────┐    Telegram API    ┌───────────┐
│  AI Agent    │ ◄────────────────► │  HITL Server  │ ◄────────────────► │ You       │
│ (Copilot,    │   tool calls +     │  (Python)     │   send message     │ Telegram  │
│  Claude...)  │   results          │               │   wait for reply   │           │
└──────────────┘                    └───────────────┘                    └───────────┘

AI呼叫 get_multiline_input （或其他工具）
服务器将提示发送到您的 电报聊天 通过Bot API
您在手机/桌面上阅读了消息回复（文字、照片或语音）
服务器捕获您的回复并将其返回给AI
人工智能继续使用您的输入

图像流

You (Telegram)                    HITL Server                     AI Agent
     │                                │                               │
     │── Send photo ──────────────────►│                               │
     │                                │── Download image               │
     │                                │── Run OCR extraction           │
     │                                │── Return ImageContent ────────►│
     │                                │   + OCR text metadata          │
     │                                │                               │── AI "sees" the image

窗口截图流程

AI Agent                          HITL Server                     AI Agent
     │                                │                               │
     │── get_window_screenshot ──────►│                               │
     │   (window_title="Settings")   │── Find window by title        │
     │                                │── Win32 PrintWindow capture   │
     │                                │── Run OCR on screenshot       │
     │                                │── Return image + metadata ───►│
     │                                │                               │── AI processes screenshot

退路： 如果未配置Telegram，所有工具都将回退到本机 GUI弹出窗口 （tkinter）。

🚀 快速开始

先决条件

Python 3.10+
Telegram Bot令牌（通过创建 @植物学家)
您的Telegram聊天ID

安装

git clone https://github.com/theohero/telegram-human-in-the-loop.git
cd telegram-human-in-the-loop
git checkout main
pip install fastmcp pydantic

可选依赖 （完整功能集）：

pip install pygetwindow pyautogui Pillow numpy rapidocr-onnxruntime

套餐	必需
`pygetwindow`	窗口截图
`pyautogui`	回退截图方法
`Pillow`	图像处理
`numpy`	OCR支持
`rapidocr-onnxruntime`	从图像中提取OCR文本

环境变量

变量	必填	描述
`TELEGRAM_BOT_TOKEN`	是	您的Telegram Bot API令牌
`TELEGRAM_CHAT_ID`	是	您的个人Telegram聊天ID
`HITL_TELEGRAM_TIMEOUT_SECONDS`	否	等待答复超时（默认值：3600）

VS代码配置（GitHub副本）

添加到您的 .vscode/mcp.json 或用户 mcp.json:

{
  "servers": {
    "hitl-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["path/to/hitl_mcp_server.py"],
      "env": {
        "HITL_TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "HITL_TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

Claude桌面配置

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "hitl-mcp-server": {
      "command": "python",
      "args": ["path/to/hitl_mcp_server.py"],
      "env": {
        "HITL_TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "HITL_TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

克劳德代码（CLI）

{
  "mcpServers": {
    "hitl-mcp-server": {
      "command": "python",
      "args": ["path/to/hitl_mcp_server.py"],
      "env": {
        "HITL_TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "HITL_TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}

🔍 查找您的聊天ID

打开Telegram并搜索 @用户信息机器人
向它发送任何消息——它会回复您的聊天ID
复制号码（例如。， 123456789)

备选方案： 打开 https://web.telegram.org，转到任何聊天室，查看URL——后面的数字 # 是您的聊天ID。

📸 图像功能详解

从Telegram接收图像

当您在Telegram中发送照片作为对AI提示的回复时：

服务器下载照片的最高分辨率版本
跑 光学字符识别 （光学字符识别）提取图像中的任何文本
退货 混合MCP含量: TextContent （元数据+OCR文本）+ ImageContent （实际图像）
AI接收图像和任何提取的文本

响应元数据包括：

{
  "success": true,
  "user_input": "caption or OCR text",
  "has_image": true,
  "image_width": 1920,
  "image_height": 1080,
  "image_file_size": 245000,
  "image_mime_type": "image/jpeg",
  "ocr_enabled": true,
  "ocr_text": "extracted text from the image",
  "ocr_lines": ["line 1", "line 2"],
  "ocr_avg_confidence": 0.95
}

窗口截图

这 get_window_screenshot 工具按标题捕获任何窗口：

# AI calls this tool with:
get_window_screenshot(window_title_contains="Settings", max_size=1400)

捕获策略：

主要：Win32 PrintWindow API --即使对于最小化或遮挡的窗口也有效（仅限windows）
后撤：皮乌古伊地区占领 --要求窗口可见

屏幕截图返回如下：

TextContent 带有元数据（标题、尺寸、OCR文本）
ImageContent 与实际截图图像

🎤 语音消息支持（Whispr）

服务器包括一个可选 Whisper 本地语音转文本模块更快的耳语（基于CTranslate2的Whisper）。

运作原理

您在Telegram中发送语音信息
Whisper下载音频并使用Whisper模型在本地转录
转录的文本作为常规文本响应发送给AI
元数据包括原始转录和任何编辑

设置--零配置

Whispr会在您首次启用时自动安装所有内容：

来自Telegram： 轻按 /whispr_on 在任何消息页脚中（显示在每条AI消息的底部）
来自AI： 这 toggle_whispr MCP工具自动安装依赖项并下载模型

不 pip install，无需模型下载，无需终端——只需点击即可。

命令

命令	描述
`/whispr_on`	启用语音转录（必要时自动安装）
`/whispr_off`	禁用语音转录
`/whispr status`	显示当前Whispr状态和设置
`/whispr model <name>`	更改型号： `tiny`, `base`, `small`, `medium`, `large-v3`
`/whispr lang <code>`	设置语言： `en`, `ru`, `de`, `fr`, `auto`

消息页脚

每条AI消息底部都包含一个Whispr状态页脚：

🎙 Whispr: OFF · /whispr_on     ← tap to enable
🎙 Whispr: ON  · /whispr_off    ← tap to disable

模型

型号	尺寸	速度	精度	最适合
`tiny`	约75 MB	最快	基本	快速笔记、短语
`base`	~150 MB	快速	良好	通用（默认）
`small`	约500 MB	中等	更好	消息更长
`medium`	约1.5 GB	较慢	较高	详细转录
`large-v3`	约3 GB	最慢	最好	最高精度

环境变量

变量	默认值	描述
`HITL_WHISPR_ENABLED`	`false`	在服务器启动时启用Whispr
`HITL_WHISPR_MODEL`	`base`	要使用的Whisper型号
`HITL_WHISPR_LANGUAGE`	（auto）	语言代码，或为空以进行自动检测

模型在本地缓存在 ~/.hitl-mcp/whispr_models/.

❓ 常见问题解答

Q：是否有消息长度限制？ A：没有实际限制。超过4096个字符（Telegram的限制）的消息会自动拆分为多条带有部分指示符的消息。回复键盘仅连接到最后一个块。

Q：我需要所有可选的依赖项吗？ A：不需要。核心功能（通过Telegram进行文字聊天）只需要 fastmcp 和 pydantic。仅安装所需功能的可选软件包。

Q：我可以禁用图像文件浏览工具吗？ A：是的。集 HITL_IMAGE_TOOLS_ENABLED=false 在您的环境或MCP配置中。这 get_image 和 list_images 工具将不会被注册。

Q：没有Telegram，它还能工作吗？ A：是的！当Telegram未配置时，所有工具都会回退到本机GUI弹出对话框（tkinter）。

Q： AI能看到我的照片吗？ A：只有你明确发送作为对人工智能提示的回复的照片。服务器不会以任何其他方式访问您的Telegram。

Q： OCR是否始终启用？ A：如果满足以下条件，OCR将自动运行 rapidocr-onnxruntime, numpy，以及 Pillow 已安装。如果未安装，图像仍会被转发，但不会进行OCR文本提取。

Q：它在macOS/Linux上工作吗？ A：文本通信和图像支持无处不在。窗口截图(get_window_screenshot)目前使用Win32 API，仅在Windows上工作。

🌐 环境变量引用

变量	默认值	描述
`TELEGRAM_BOT_TOKEN`	-	Telegram Bot API令牌（来自@BotFather）
`TELEGRAM_CHAT_ID`	--	您的Telegram聊天ID
`HITL_TELEGRAM_TIMEOUT_SECONDS`	`3600`	等待回复的时间（秒）
`HITL_IMAGE_TOOLS_ENABLED`	`true`	启用/禁用 `get_image` 和 `list_images` 工具
`HITL_OCR_ENABLED`	`true`	启用/禁用从图像中提取OCR文本
`HITL_WHISPR_ENABLED`	`false`	在服务器启动时启用语音转录
`HITL_WHISPR_MODEL`	`base`	Whisper型号尺寸(`tiny`/`base`/`small`/`medium`/`large-v3`)
`HITL_WHISPR_LANGUAGE`	（自动）	用于转录的语言代码(`en`, `ru`, `de`等等）
`FASTMCP_LOG_LEVEL`	`INFO`	日志记录级别

📝 许可证

MIT许可证。看许可证了解详情。

🙏 积分

建于 FastMCP 和那个电报机器人API.

使用说明

🤖💬 Telegram人在环MCP服务器

📌 这是什么？

✨ 主要特点

💬 双向文本通信

📸 图像支持（Telegram→ AI)

🗂️ 本地图像浏览（AI→ AI)

🖥️ 窗口截图（AI→ 电报）

🎤 语音信息转录（Whispr）

🔄 后备系统

🧩 兼容平台

🛠 可用工具

🔧 原理

图像流

窗口截图流程

🚀 快速开始

先决条件

安装

环境变量

VS代码配置（GitHub副本）

Claude桌面配置

克劳德代码（CLI）

🔍 查找您的聊天ID

📸 图像功能详解

从Telegram接收图像

窗口截图

🎤 语音消息支持（Whispr）

运作原理

设置--零配置

命令

消息页脚

模型

环境变量

❓ 常见问题解答

🌐 环境变量引用

📝 许可证

🙏 积分

相关 MCP

Playwright浏览器自动化服务器

Gemini API文档搜索服务

React开发协议服务

文件上下文服务器

图标搜索工具

TypeScript重构工具