Telegram Human In The Loop

🤖💬 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）
• 使用本地对话框脱机工作
• 优雅的退化——永远不会阻挡人工智能

______________________________________________________________________

🧩 兼容平台

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

______________________________________________________________________

🛠 可用工具

______________________________________________________________________

🔧 原理

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

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

图像流

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

环境变量

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

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

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

______________________________________________________________________

📸 图像功能详解

从Telegram接收图像

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

1. 服务器下载照片的最高分辨率版本
2. 跑 光学字符识别 （光学字符识别）提取图像中的任何文本
3. 退货 混合MCP含量: TextContent （元数据+OCR文本）+ ImageContent （实际图像）
4. 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)

捕获策略：

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

屏幕截图返回如下：

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

______________________________________________________________________

🎤 语音消息支持（Whispr）

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

运作原理

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

设置--零配置

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

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

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

命令

消息页脚

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

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

模型

环境变量

模型在本地缓存在 ~/.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上工作。

______________________________________________________________________

🌐 环境变量引用

______________________________________________________________________

📝 许可证

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

______________________________________________________________________

🙏 积分