tlgrm (Celestial Tech)

Tlgrm：电报桌面重新布线

Tlgrm

Telegram Desktop的自定义分支，让您完全控制您的数据。导出受隐私限制的频道，存档已删除帐户中的消息，并通过内置的 主控程序 服务器——来自脚本、本地机器人、人工智能助手或任何使用JSON-RPC的工具。

为什么Tlgrm胜过股票电报桌面

用例

数据保存和导出

具有转发限制的出口渠道 --许多新闻频道、付费频道和企业集团都禁用了内容保存功能。Stock Telegram在客户端级别强制执行此操作——您不能复制文本、转发消息或导出，即使是通过外卖。Tlgrm从不适用这些客户端限制的本地同步数据库中读取。您可以在应用程序中看到内容，现在您也可以将其导出。完整历史记录，所有媒体，HTML或JSON格式。

恢复中断的出口 --您正在导出一个包含5000条消息和800个文件附件的频道。三个小时后，你的笔记本电脑进入睡眠状态，网络中断，或者应用程序崩溃。有了股票电报，你就可以重新开始。Tlgrm扫描磁盘上的导出目录，查找现有的HTML文件，统计已写入的邮件数量，并从停止的位置恢复。如果文件下载在传输过程中中断，它会检测到截断的文件（128KB对齐，缺少PDF EOF标记），并仅重新下载这些文件。

将已删除帐户的邮件存档 --与你聊天多年的人删除了他们的Telegram帐户。没有任何警告，他们发给你的每一条信息都会消失。Tlgrm可以扫描您的整个聊天列表以查找已删除的帐户，通过分析消息模式（您如何称呼他们、问候模式、他们消息中的电子邮件签名）来检测此人是谁，并将每条消息（文本、照片、视频、语音消息、文档）转发到存档组。存档组将根据检测到的人的姓名及其对等ID自动命名。

捕捉消失的消息 --带有自动删除计时器的频道和聊天会导致消息按计划消失。Tlgrm可以在计时器到期之前拦截并保留此内容。

自动化和脚本

构建本地机器人和工具 --IPC插座位于 /tmp/tdesktop_mcp.sock 接受来自任何本地进程的JSON-RPC连接。无需Telegram Bot API令牌，无读取速率限制，无机器人程序注册。您以自己的帐户操作，可以完全访问您的数据。示例：

• 一个Python脚本，每晚通过cron导出频道列表
• 监视特定聊天并发送警报的监视守护进程
• 一个汇总各组消息统计信息的仪表板
• 一个逐步归档重要聊天记录的备份工具

与AI助手集成 --MCP服务器发出 模型上下文协议，因此任何兼容MCP的工具都可以将您的Telegram用作数据源。Claude Desktop可以通过stdio直接连接(--mcp 旗）。本地LLM、自定义代理或任何实现MCP客户端规范的工具都可以通过IPC套接字连接。人工智能是一个可能的客户端——接口是通用的。

自动化账户管理 --编写您的隐私设置脚本：在旅行前收紧权限，审核所有设备的活动会话，批量管理您的阻止列表，设置自动删除时段。按计划运行它或从工作流中触发它。

安全和隐私

审核活动会话 --列出登录到您帐户的每个设备，包括IP地址、设备名称、应用程序版本和上次活动时间戳。识别你不认识的会话。使用单个命令终止任何会话。无需浏览设置菜单。

以编程方式管理隐私 --阅读您当前所有类别的隐私配置（最后一次看到、个人资料照片、电话号码、转发的消息、生日、个人简介），并更改其中任何一项。为不同的环境设置不同的规则——只联系、亲密朋友或没有人。

监控和控制 --检查聊天记录中的自动删除时段，查看被阻止的用户，验证您的安全设置是否符合您的期望。可编写脚本用于定期审计。

   

______________________________________________________________________

目录

• 概述
• 建筑
• 演出
• 快速开始
• 详细的构建说明（macOS）
• 代码修改参考
• MCP工具和功能
• 开发工作流程
• 故障排除
• 项目结构
• 文档

______________________________________________________________________

概述

核心能力

• 导出任何频道 包括受隐私限制的股票电报阻止保存、复制和转发
• 恢复中断的出口 --自动检测磁盘上以前的导出，并从精确位置继续
• 存档已删除的帐户消息 --在消息消失之前进行扫描、检测和保存，并自动恢复名称
• 捕捉消失的消息 在自毁定时器到期之前
• 330+编程工具 可通过IPC套接字或stdio通过JSON-RPC访问
• 直接数据库读取 -比Bot API快20-100倍，网络开销为零
• 与任何客户合作 --shell脚本、Python机器人、AI助手（Claude、本地LLM）、cron作业、自定义工具
• Python MCP服务器 --可选配语义搜索、意图分类、主题提取和对话摘要（Apple Silicon GPU加速）

______________________________________________________________________

建筑

                ┌──────────────────────────────────────┐
                │  Scripts / Bots / AI / Any MCP Client │
                └──────────────────┬───────────────────┘
                                   │ JSON-RPC 2.0
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
      ┌─────▼─────┐        ┌──────▼──────┐       ┌───────▼───────┐
      │  --mcp    │        │ IPC Bridge  │       │ Python MCP    │
      │  (stdio)  │        │ (Unix sock) │       │ (AI/ML layer) │
      └─────┬─────┘        └──────┬──────┘       └───────┬───────┘
            │                     │                      │ IPC
            │                     │               ┌──────▼──────┐
            │                     │               │ Semantic     │
            │                     │               │ search, NLP  │
            │                     │               │ Apple Silicon│
      ┌─────▼─────────────────────▼─────┐         └──────┬──────┘
      │       C++ MCP Server (330+)     │◄───────────────┘
      │  ┌─────────┐  ┌───────────────┐ │
      │  │Messaging│  │Export & Archive│ │
      │  │Analytics│  │Privacy/Security│ │
      │  └─────────┘  └───────────────┘ │
      └───────────────┬─────────────────┘
                      │ Direct Access
      ┌───────────────▼───────────────────┐
      │        Telegram Desktop           │
      │  • Local DB  • MTProto API        │
      │  • Session   • Media Files        │
      └───────────────────────────────────┘

运作原理

1. 嵌入式C++MCP服务器 在Telegram Desktop进程内运行，可直接访问所有数据
2. IPC网桥 (/tmp/tdesktop_mcp.sock)--始终打开，任何本地进程都可以连接和调用工具
3. Python MCP服务器 （可选）——通过IPC连接到C++服务器，添加语义搜索、意图分类、主题提取、对话摘要，并采用Apple Silicon GPU加速
4. 标准运输 (--mcp flag）--适用于Claude Desktop或其他使用stdin/stdout的MCP客户端
5. 本地阅读 直接访问数据库（无网络，无速率限制）
6. 写入和导出 通过tdesktop的现有连接使用MTProto API

演出

______________________________________________________________________

快速开始

先决条件

• macOS：文图拉（13.0+）或索诺玛（14.0+）
• 硬件：苹果硅（M1/M2/M3）或英特尔Mac
• Xcode：14.0+使用命令行工具
• 磁盘空间：50GB+免费
• 电报API证书：从 my.telegram.org

快速通道（如果已经建成）

cd ~/xCode/tlgrm

# Run Telegram with MCP
./tdesktop/out/Release/Telegram.app/Contents/MacOS/Telegram --mcp

# Configure Claude Desktop
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "telegram": {
      "command": "/Applications/Telegram.app/Contents/MacOS/Telegram",
      "args": ["--mcp"]
    }
  }
}

有关首次设置，请参阅 详细的构建说明 在......下面

______________________________________________________________________

详细的构建说明（macOS）

本节提供了在macOS上构建带有MCP集成的Telegram Desktop的全面、分步说明。

系统要求

预期构建时间

看 BUILD_BENCMARKS.md 进行详细的时序分析。

步骤1：安装依赖项

# Install Xcode (if not already installed)
xcode-select --install

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install build dependencies
brew install git cmake python3 automake autoconf libtool pkg-config ninja wget meson nasm

# Verify installations
which git cmake python3 automake autoconf libtool wget meson nasm

步骤2：获取Telegram API凭据

1. 首选 my.telegram.org
2. 使用您的电话号码登录
3. 引导到 API开发工具
4. 创建新应用程序：

- 应用程序标题： Telegram Desktop MCP （或任何名称） - 简称： tdesktop-mcp - 平台：桌面

1. 保存您的 api_id 和 api_hash

用于测试 （不建议用于生产）：

• API_ID（\_ID）： 2040
• API_HASH（语言）： b18441a1ff607e10a989891a5462e627

步骤3：克隆存储库

# Navigate to your projects directory
cd ~/xCode/tlgrm

# The repository is already cloned
# If starting fresh, you would clone from your git remote

步骤4：建立依赖关系（40-70分钟）

此步骤构建28个第三方库，包括Qt6、FFmpeg、OpenSSL等。

cd ~/xCode/tlgrm/tdesktop/Telegram

# Run preparation script in silent mode (non-interactive)
./build/prepare/mac.sh silent

这有什么作用：

• 下载并编译所有依赖项
• 创建 Libraries/ 带有内置库的目录
• 这是一个 一次性操作 （除非依赖关系发生变化）

进度跟踪：

# In another terminal, monitor progress:
tail -f ../build.log

# Or use the provided monitor script:
../monitor_build.sh

此步骤中的常见问题：

步骤5：配置构建

cd ~/xCode/tlgrm/tdesktop/Telegram

# Configure with your API credentials
./configure.sh \
  -D TDESKTOP_API_ID=YOUR_API_ID \
  -D TDESKTOP_API_HASH=YOUR_API_HASH

# This generates Xcode project in ../out/

这有什么作用：

• 运行CMake生成Xcode项目
• 配置macOS的构建设置
• 嵌入您的API凭据
• 创建 tdesktop/out/Telegram.xcodeproj

步骤6：构建Telegram桌面（10-20分钟）

您有两个选择：使用Xcode GUI或命令行构建。

选项A：使用Xcode构建（建议首次构建）

cd ~/xCode/tlgrm/tdesktop/out
open Telegram.xcodeproj

# In Xcode:
# 1. Select "Telegram" scheme (top toolbar)
# 2. Select "My Mac" as destination
# 3. Edit Scheme → Build Configuration → Release
# 4. Product → Build (Cmd+B)

监控进度：

• Xcode在工具栏中显示构建进度
• 查看详细日志：查看→ 导航仪→ 报告

选项B：从命令行构建

cd ~/xCode/tlgrm/tdesktop/out

# Build Release configuration with 24 parallel jobs
cmake --build . --config Release -j 24

# For systems with limited RAM (8GB):
cmake --build . --config Release -j 4

这编译了什么：

• 所有tdesktop源文件（约2000个文件）
• MCP集成代码（4个文件）
• Qt UI组件
• MTProto协议实现
• 媒体编解码器和处理

步骤7：验证构建

cd ~/xCode/tlgrm/tdesktop/out/Release

# Check that the app was created
ls -lh Telegram.app/Contents/MacOS/Telegram

# Should show: ~150-200MB executable

# Test launch (basic mode)
./Telegram.app/Contents/MacOS/Telegram --version

# Test MCP mode
./Telegram.app/Contents/MacOS/Telegram --mcp
# Press Ctrl+C after you see "MCP: Server started successfully"

步骤8：可选-安装到应用程序

# Copy to Applications folder
cp -r ~/xCode/tlgrm/tdesktop/out/Release/Telegram.app /Applications/

# Or create a symlink
ln -s ~/xCode/tlgrm/tdesktop/out/Release/Telegram.app /Applications/Telegram-MCP.app

步骤9：配置Claude桌面

创建或编辑Claude Desktop配置：

# Create config directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Edit config file (use your preferred editor)
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "telegram": {
      "command": "/Applications/Telegram.app/Contents/MacOS/Telegram",
      "args": ["--mcp"]
    }
  }
}

如果您使用了其他路径：

{
  "mcpServers": {
    "telegram": {
      "command": "/Users/YOUR_USERNAME/xCode/tlgrm/tdesktop/out/Release/Telegram.app/Contents/MacOS/Telegram",
      "args": ["--mcp"]
    }
  }
}

步骤10：使用Claude Desktop进行测试

# Restart Claude Desktop
killall Claude 2>/dev/null
open -a Claude

# In Claude, try:
# "List my Telegram chats"
# "Read the last 10 messages from [chat name]"

构建优化提示

适用于8GB RAM系统

# Use fewer parallel jobs
cmake --build . --config Release -j 4

# Close all other applications
# Disable Time Machine during build
tmutil disable

# Monitor memory pressure
# Activity Monitor → Memory tab

为了更快的构建

# Build on SSD (verify):
df -h ~/xCode/tlgrm
# Should show local SSD, not network/external drive

# Disable Spotlight indexing (temporarily):
sudo mdutil -i off /

# Use Release configuration (not Debug):
# Debug builds are 2-3x slower and 3-4x larger

对于增量构建

# After making changes to MCP code only:
cd ~/xCode/tlgrm/tdesktop/out
cmake --build . --config Release
# Only recompiles changed files: 2-5 minutes

# After making changes to dependencies:
cd ~/xCode/tlgrm/tdesktop/Telegram
./build/prepare/mac.sh silent
# Rebuilds only changed dependencies: 10-30 minutes

清理构建工件

# Clean Xcode build (keeps dependencies)
cd ~/xCode/tlgrm/tdesktop
rm -rf out/

# Clean dependencies (forces full rebuild)
rm -rf Libraries/

# Clean everything
cd ~/xCode/tlgrm
rm -rf tdesktop/out tdesktop/Libraries

______________________________________________________________________

代码修改参考

本节记录 每一个变化 在Telegram Desktop上添加MCP支持，以及 为什么 每一次改变都是必要的。

变更概述

修改的文件： 3个核心tdesktop文件 添加的文件： 4个新的MCP实施文件 线路更改： 修改了约80行，增加了约600行

修改过的文件

1. tdesktop/Telegram/CMakeLists.txt

地点： 第1207-1214行 补丁： 0001-add-mcp-cmake-configuration.patch

更改：

@@ -1207,6 +1207,10 @@ PRIVATE
     main/session/send_as_peers.h
     main/session/session_show.cpp
     main/session/session_show.h
+    mcp/mcp_bridge.cpp
+    mcp/mcp_bridge.h
+    mcp/mcp_server.cpp
+    mcp/mcp_server.h
     media/audio/media_audio.cpp

为什么会发生这种变化：

• CMake需要了解新的源文件才能编译它们
• 增添 PRIVATE 来源确保它们被编译成Telegram的主要目标
• 按字母顺序插入 main/session/ 以及之前 media/
• 链接器查找MCP符号所必需的

影响： 否则，MCP文件将无法编译，链接也将失败。

______________________________________________________________________

2. tdesktop/Telegram/SourceFiles/core/application.h

地点： 第109-112、245-247、474行 补丁： 0002-add-mcp-application-integration.patch

变更1：远期申报（第109-112行）

+namespace MCP {
+class Server;
+} // namespace MCP
+
 namespace Core {

为什么会发生这种变化：

• 转发声明避免包含完整 mcp_server.h 头球
• 减少编译依赖性（更快的构建）
• 其他组件（窗口、主界面等）遵循tdesktop的模式
• 允许使用 MCP::Server* 没有完整的类型定义

______________________________________________________________________

变更2：公共访问器（第245-250行）

+	// MCP Server component.
+	[[nodiscard]] MCP::Server *mcpServer() const {
+		return _mcpServer.get();
+	}
+
 	// Main::Session component.

为什么会发生这种变化：

• 提供从其他组件对MCP服务器的只读访问
• [[nodiscard]] 确保调用者检查指针是否为空
• 匹配模式 maybePrimarySession() 上面的访问者
• 需要与MCP服务器交互的功能的未来证明
• 可用于呼叫 setSession() 当会话准备就绪时

______________________________________________________________________

变更3：私人会员（第474行）

 	const std::unique_ptr _tray;

+	std::unique_ptr _mcpServer;
+
 	std::unique_ptr _floatPlayers;

为什么会发生这种变化：

• unique_ptr 确保适当的清理（RAII）
• MCP服务器寿命与应用程序寿命挂钩
• 应用程序被销毁时自动删除
• 默认情况下为空，仅在以下情况下初始化 --mcp 旗帜存在
• 定位在 _tray 和 _floatPlayers （按字母顺序排列）

影响： 没有这个，我们就无法存储MCP服务器实例。

______________________________________________________________________

3. tdesktop/Telegram/SourceFiles/core/application.cpp

地点： 第85、217-219、423-435行 补丁： 0002-add-mcp-application-integration.patch

变更1：包括标题（第85行）

 #include "window/window_controller.h"
+#include "mcp/mcp_server.h"
 #include "boxes/abstract_box.h"

为什么会发生这种变化：

• 需要使用 MCP::Server 类
• 放置在窗口包括之后，方框之前（遵循现有组织）
• 仅包含在.cpp文件中，不包含标头（减少依赖关系）

______________________________________________________________________

变更2：销毁器清理（第217-219行）

 Application::~Application() {
+	// Stop MCP server before other cleanup
+	_mcpServer = nullptr;
+
 	if (_saveSettingsTimer && _saveSettingsTimer->isActive()) {

为什么会发生这种变化：

• 正确停机至关重要：MCP服务器必须在其他组件之前停止
• 设置 unique_ptr 到 nullptr 调用MCP:：服务器析构函数
• MCP服务器析构函数停止stdio轮询，关闭连接，释放资源
• 订单事项：如果我们在会话清理后停止MCP，它可能会尝试访问释放的内存
• 注释解释了未来维护人员的订购要求

______________________________________________________________________

变更3：初始化（第423-435行）

+	// Start MCP server if --mcp flag is present
+	const auto args = QCoreApplication::arguments();
+	if (args.contains(u"--mcp"_q)) {
+		_mcpServer = std::make_unique();
+		if (_mcpServer->start(MCP::TransportType::Stdio)) {
+			DEBUG_LOG(("MCP: Server started successfully"));
+		} else {
+			LOG(("MCP Error: Failed to start server"));
+			_mcpServer = nullptr;
+		}
+	}
+
 	processCreatedWindow(_lastActivePrimaryWindow);

为什么会发生这种变化：

• 选择加入行为：仅在以下情况下开始 --mcp 旗帜存在
• u"--mcp"_q 使用Qt的字符串文字语法（tdesktop样式要求）
• 使用创建服务器实例 make_unique （例外安全）
• 呼叫 start() 其中：

- 初始化功能（工具、资源、提示） - 设置stdio传输（stdin/stdout上的QTextStream） - 为传入请求启动轮询定时器

• 错误处理：如果启动失败，则记录错误并删除服务器
• DEBUG_LOG 仅登录调试版本（生产保持静默）
• 放置在域/窗口设置之后，窗口处理之前

为什么这个位置在 run():

• 此时应用程序已完全初始化
• 窗口系统已准备就绪
• 太早：Qt事件循环未就绪
• 太晚：窗口已处理，可能会错过早期的MCP请求

______________________________________________________________________

添加文件

1. tdesktop/Telegram/SourceFiles/mcp/mcp_server.h （200行）

目的： MCP服务器类定义和协议结构

关键部件：

namespace MCP {

// Protocol types
enum class TransportType {
    Stdio,    // stdin/stdout (Claude Desktop)
    HTTP,     // Future: HTTP with SSE
    WebSocket // Future: WebSocket transport
};

// MCP primitives
struct Tool { QString name; QString description; QJsonObject inputSchema; };
struct Resource { QString uri; QString name; QString description; QString mimeType; };
struct Prompt { QString name; QString description; QJsonArray arguments; };

class Server : public QObject {
    Q_OBJECT
public:
    explicit Server(QObject *parent = nullptr);
    bool start(TransportType transport = TransportType::Stdio);
    void stop();

private:
    // Protocol handlers
    QJsonObject handleRequest(const QJsonObject &request);
    QJsonObject handleInitialize(const QJsonObject &params);
    QJsonObject handleListTools(const QJsonObject &params);
    QJsonObject handleCallTool(const QJsonObject &params);
    // ... more handlers

    // Tool implementations
    QJsonObject toolListChats(const QJsonObject &args);
    QJsonObject toolReadMessages(const QJsonObject &args);
    // ... more tools

    // Data members
    QVector _tools;
    QVector _resources;
    QVector
 _prompts;
    ServerInfo _serverInfo;
    TransportType _transportType;
    QTextStream *_stdin = nullptr;
    QTextStream *_stdout = nullptr;
};

} // namespace MCP

设计决策：

1. 为什么从QObject继承：

- 启用Qt信号/插槽（用于未来功能） - 与Qt事件循环集成 - tdesktop代码库中的标准模式 - QTimer所需（用于stdio轮询）

1. 为什么要分离工具/资源/提示结构：

- MCP协议将这些定义为不同的实体类型 - 允许单独注册和列出 - 比通用“MCPEntity”基类更干净

1. 为什么选择QJsonObject用于模式：

- MCP使用JSON模式作为工具参数 - QJsonObject提供原生JSON操作 - 避免基于字符串的JSON构造 - 编译时类型安全

1. 为什么选择QVector存储：

- tdesktop始终使用Qt容器 - QVector支持缓存（连续内存） - 工具/资源数量少（\start(100);

return true; }

return false; // HTTP/WebSocket not implemented yet }

**为什么是轮询而不是信号：**

- Qt不提供 `readyRead()` stdin信号
- QSocketNotifier是特定于平台且复杂的
- 100ms轮询的开销可以忽略不计（\atEnd()) return;

    QString line = _stdin->readLine();
    if (line.isEmpty()) return;

    QJsonDocument doc = QJsonDocument::fromJson(line.toUtf8());
    if (!doc.isObject()) {
        sendError(-32700, "Parse error");
        return;
    }

    QJsonObject response = handleRequest(doc.object());
    sendResponse(response);
}

为什么使用基于线路的协议：

• JSON-RPC请求是单行（标准）
• 解析简单，无需消息框架
• 每一行都是一个完整的请求
• 符合Claude Desktop的期望

______________________________________________________________________

D.工具实施

QJsonObject Server::toolListChats(const QJsonObject &args) {
    // Currently returns stub data
    QJsonArray chats;

    // TODO: Access real data via:
    // auto &owner = _session->data();
    // for (const auto &dialog : owner.chatsListFor(Data::Folder::kAll)->all()) {
    //     ...
    // }

    chats.append(QJsonObject{
        {"id", "-1001234567890"},
        {"title", "Example Chat"},
        {"type", "supergroup"},
        {"message_count", 42}
    });

    return QJsonObject{
        {"chats", chats},
        {"source", "local_database"},
        {"note", "Stub data - connect to session for real data"}
    };
}

为什么当前使用存根数据：

• MCP集成无需tdesktop数据连接即可工作
• 允许独立测试MCP协议
• 连接到真实数据需要会话引用
• 记录在TODO评论中，以供未来实施

______________________________________________________________________

E.QJsonObject构造模式

错误（无法使用tdesktop的Qt配置进行编译）：

return QJsonObject{
    {"content", QJsonArray{
        QJsonObject{{"type", "text"}, {"text", "data"}}
    }}
};

正确（分步施工）：

QJsonObject contentItem;
contentItem["type"] = "text";
contentItem["text"] = "data";

QJsonArray contentArray;
contentArray.append(contentItem);

QJsonObject response;
response["content"] = contentArray;
return response;

为什么需要这种模式：

• tdesktop使用Qt进行自定义配置
• 此版本不支持嵌套初始化器列表
• 编译器错误：“没有用于初始化'QJsonObject'的匹配构造函数”
• 逐步施工总是有效的
• 稍微更冗长，但更兼容

______________________________________________________________________

3. tdesktop/Telegram/SourceFiles/mcp/mcp_bridge.h （89行）

目的： 用于外部过程通信的IPC桥（可选功能）

关键部件：

namespace MCP {

class Bridge : public QObject {
    Q_OBJECT
public:
    explicit Bridge(QObject *parent = nullptr);
    bool start(const QString &socketPath = "/tmp/tdesktop_mcp.sock");
    void stop();

private Q_SLOTS:  // NOTE: Q_SLOTS, not "slots"
    void onNewConnection();
    void onReadyRead();
    void onDisconnected();

private:
    QLocalServer *_server = nullptr;
    QList _clients;
};

} // namespace MCP

关键修复：Qt关键字

错误：

private slots:  // Error: unknown type name 'slots'
    void onNewConnection();

对的：

private Q_SLOTS:  // Uses Q_SLOTS macro
    void onNewConnection();

为什么这一变化是必要的：

• tdesktop与 -DQT_NO_KEYWORDS 旗帜
• 这将禁用Qt slots, signals, emit 宏
• 防止全局命名空间中的宏污染
• 必须使用 Q_SLOTS, Q_SIGNALS, Q_EMIT 相反
• 没有此修复程序：编译错误

IPC桥存在的原因：

• 允许外部Python进程连接到tdesktop
• Unix域套接字(/tmp/tdesktop_mcp.sock)
• 当前未使用（直接C++MCP更快）
• 对未来有用：单独的MCP服务器进程
• 允许在不重建tdesktop的情况下更新MCP服务器

______________________________________________________________________

4. tdesktop/Telegram/SourceFiles/mcp/mcp_bridge.cpp （245行）

目的： 使用QLocalServer实现IPC网桥

主要特点：

• 创建Unix域套接字服务器
• 处理多个并发客户端连接
• 套接字上的JSON-RPC（与stdio协议相同）
• 优雅的连接处理和清理

为什么选择QLocalServer：

• Unix域套接字很快（本地IPC）
• 比TCP更安全（无网络暴露）
• Qt提供跨平台抽象
• 与Qt事件循环集成

目前未使用 因为：

• 直接C++MCP更简单、更快
• 无需单独处理
• 为未来的灵活性而保留

______________________________________________________________________

变更摘要

总计： 添加/更改了约1168条线路，以实现MCP的完全集成

最小工作集成： ~634条线路（不含IPC网桥）

______________________________________________________________________

为什么这些变化有效

1. 影响最小：仅修改了3个核心文件（CMake+应用程序）
2. 隔离代码：所有MCP逻辑单独 mcp/ 目录
3. 选择加入功能：仅在以下情况下激活 --mcp 使用标志
4. 干净关闭：正确的RAII unique_ptr
5. 无依赖关系：MCP代码不依赖于tdesktop内部（目前）
6. 面向未来：需要时易于连接到真实数据

______________________________________________________________________

跨更新进行维护

当Telegram Desktop发布新版本时：

1. 检查CMakeLists.txt：主要目标源列表是否发生了变化？

- 解决方案：使用新的行号重新生成补丁

1. 检查应用程序.h/cpp：初始化顺序是否更改？

- 解决方案：调整MCP初始化代码的位置

1. 重新应用补丁:

   git apply tdesktop/patches/0001-*.patch
   git apply tdesktop/patches/0002-*.patch

1. 如果冲突：手动合并和重新生成补丁

看 建筑.md 了解系统架构的详细信息。

______________________________________________________________________

MCP工具和功能

可用工具（330+）

C++MCP服务器公开了330多个工具，并集成了真正的Telegram API：

导出功能: export_chat 支持HTML和JSON格式，自动检测并恢复中断的导出，重用现有目录，通过准确的消息计数跟踪进度，适用于频道、群组和私人聊天。

Claude使用示例

You: "Export the WSJ channel to HTML"
Claude: Uses export_chat(chat_id=562951444505165, format="html")
→ Auto-detects previous export, resumes from message #416, shows progress panel

You: "List all chats with deleted accounts"
Claude: Uses list_deleted_accounts()
→ Scans all chats, returns deleted account peers with message previews

You: "Archive messages from deleted account 768828198"
Claude: Uses archive_deleted_accounts(peer_id=768828198)
→ Forwards all messages to an archive group, detects peer name

______________________________________________________________________

开发工作流程

添加新的MCP工具

推荐方法： 先用Python做原型，然后用C++实现。

1.Python原型

cd ~/xCode/tlgrm/python-bridge

# Edit mcp_server.py

@mcp.tool()
def get_chat_statistics(chat_id: str) -> dict:
    """
    Get statistics for a specific chat.

    Args:
        chat_id: Telegram chat ID

    Returns:
        Statistics including message count, member count, etc.
    """
    # Prototype implementation
    return {
        "chat_id": chat_id,
        "total_messages": 1234,
        "active_members": 42,
        "created_date": "2024-01-01"
    }

# Test
python main.py

2.使用Claude Desktop进行测试

更新Claude配置以使用Python服务器：

{
  "mcpServers": {
    "telegram": {
      "command": "python",
      "args": ["/Users/YOUR_USER/xCode/tlgrm/python-bridge/main.py"]
    }
  }
}

与Claude一起测试新工具。

3.用C实现++

Python原型工作后：

// In tdesktop/Telegram/SourceFiles/mcp/mcp_server.h
private:
    QJsonObject toolGetChatStatistics(const QJsonObject &args);

// In mcp_server.cpp - registerTools()
_tools.append(Tool{
    "get_chat_statistics",
    "Get statistics for a specific chat",
    QJsonObject{
        {"type", "object"},
        {"properties", QJsonObject{
            {"chat_id", QJsonObject{
                {"type", "string"},
                {"description", "Telegram chat ID"}
            }}
        }},
        {"required", QJsonArray{"chat_id"}}
    }
});

// In mcp_server.cpp - handleCallTool()
} else if (name == "get_chat_statistics") {
    result = toolGetChatStatistics(arguments);
}

// In mcp_server.cpp - implementation
QJsonObject Server::toolGetChatStatistics(const QJsonObject &args) {
    QString chatId = args["chat_id"].toString();

    // TODO: Access real tdesktop data
    QJsonObject stats;
    stats["chat_id"] = chatId;
    stats["total_messages"] = 1234;
    stats["active_members"] = 42;
    stats["created_date"] = "2024-01-01";

    return stats;
}

4.重建和测试

cd ~/xCode/tlgrm/tdesktop/out
cmake --build . --config Release

# Update Claude config back to C++ server
# Test with Claude Desktop

增量构建工作流

# 1. Make changes to MCP code
nano ~/xCode/tlgrm/tdesktop/Telegram/SourceFiles/mcp/mcp_server.cpp

# 2. Rebuild (only recompiles changed files)
cd ~/xCode/tlgrm/tdesktop/out
cmake --build . --config Release
# Time: 2-5 minutes

# 3. Test
./Release/Telegram.app/Contents/MacOS/Telegram --mcp

连接到真实电报数据

当前状态： 工具返回存根数据

下一步： 连接到tdesktop的会话数据

如何实施：

// In application.cpp - after session is created
if (_mcpServer && maybePrimarySession()) {
    _mcpServer->setSession(maybePrimarySession());
}

// In mcp_server.h
private:
    Main::Session *_session = nullptr;
public:
    void setSession(Main::Session *session);

// In mcp_server.cpp - toolListChats()
QJsonObject Server::toolListChats(const QJsonObject &args) {
    if (!_session) {
        return QJsonObject{{"error", "No active session"}};
    }

    QJsonArray chats;
    auto &owner = _session->data();

    for (const auto &dialog : owner.chatsListFor(Data::Folder::kAll)->all()) {
        auto peer = dialog->peer();

        QJsonObject chat;
        chat["id"] = QString::number(peer->id.value);
        chat["title"] = peer->name();
        chat["type"] = peer->isUser() ? "user" :
                      (peer->isChat() ? "group" : "channel");

        chats.append(chat);
    }

    return QJsonObject{{"chats", chats}};
}

看 docs/BUILD_GUIDE.md 获取详细的构建指南。

______________________________________________________________________

故障排除

构建问题

缺少的依赖

症状：

configure: error: You must have aclocal/autoconf/automake installed

解决方案：

brew install automake autoconf libtool

______________________________________________________________________

症状：

wget: command not found

解决方案：

brew install wget

______________________________________________________________________

症状：

meson: command not found

解决方案：

brew install meson

______________________________________________________________________

Qt关键字错误

症状：

error: expected ':'
error: unknown type name 'slots'

地点： mcp_bridge.h:36

解决方案： 已在补丁中修复。如果你看到这个：

1. 验证是否应用了补丁
2. 使用 Q_SLOTS 而不是 slots

// CORRECT:
private Q_SLOTS:
    void onNewConnection();

______________________________________________________________________

QJsonObject构造函数错误

症状：

error: no matching constructor for initialization of 'QJsonObject'

地点： mcp_server.cpp （不同地点）

解决方案： 采用分步施工：

// WRONG:
return QJsonObject{{"key", QJsonArray{QJsonObject{{"nested", "value"}}}}};

// CORRECT:
QJsonObject nested;
nested["nested"] = "value";

QJsonArray array;
array.append(nested);

QJsonObject result;
result["key"] = array;
return result;

______________________________________________________________________

在Qt/FFmpeg上构建马厩

症状： 构建在Qt6或FFmpeg编译时显示为冻结状态

原因： 8GB RAM系统的内存压力

解决方案：

# Close other applications
# Monitor in Activity Monitor

# Use fewer parallel jobs
cd tdesktop/out
cmake --build . --config Release -j 4

# Check memory pressure
memory_pressure

______________________________________________________________________

运行时问题

MCP服务器无法启动

症状： 与一起运行时无输出 --mcp 旗帜

诊断：

# Check logs
log show --predicate 'process == "Telegram"' --last 5m | grep MCP

# Should see:
# "MCP: Server started successfully"

# Or in Console.app:
# Filter by "Telegram" process
# Search for "MCP"

常见原因：

1. 不使用 --mcp 旗帜
2. 内部版本不包括MCP文件（请检查CMakeLists.txt）
3. 启动时崩溃（检查日志）

______________________________________________________________________

工具返回空数据

预期： 这是当前行为（存根数据）

症状： list_chats() 返回示例数据，而不是真实聊天

原因： MCP实现尚未连接到tdesktop会话

状态： 看 实施总结

______________________________________________________________________

克劳德桌面无法连接

症状： 克劳德没有展示Telegram工具

诊断：

# 1. Verify config file exists
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 2. Check JSON is valid
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 3. Verify path is correct
ls -l /Applications/Telegram.app/Contents/MacOS/Telegram

# 4. Test Telegram manually
/Applications/Telegram.app/Contents/MacOS/Telegram --mcp
# Should stay running, not exit immediately

# 5. Restart Claude completely
killall Claude
open -a Claude

常见问题：

• 配置中的JSON语法错误
• Telegram二进制文件的路径错误
• Telegram在启动时崩溃
• Claude Desktop需要重新启动

______________________________________________________________________

性能问题

症状： 在M1 Pro上构建需要2个小时以上+

诊断：

# Check disk speed
diskutil info / | grep "Solid State"
# Should show: Solid State: Yes

# Check memory pressure
vm_stat | grep Pages
# High "Pages swapped out" = RAM pressure

# Check CPU throttling
pmset -g thermlog

解决：

1. 释放RAM： 关闭其他应用程序
2. 使用SSD： 不要在外部HDD上构建
3. 关闭时光机： tmutil disable
4. 减少并行作业： -j 4 而不是 -j 24
5. 检查冷却： 确保通风良好

______________________________________________________________________

更新到新的Telegram版本

当Telegram Desktop发布新版本（例如6.4）时：

cd ~/xCode/tlgrm/tdesktop

# 1. Fetch upstream changes
git remote add upstream https://github.com/telegramdesktop/tdesktop.git
git fetch upstream

# 2. Checkout new version
git checkout upstream/dev  # or tags/v6.4

# 3. Try applying patches
git apply --check ../patches/0001-add-mcp-cmake-configuration.patch
git apply --check ../patches/0002-add-mcp-application-integration.patch

# 4a. If patches apply cleanly:
cd ..
./apply-patches.sh

# 4b. If conflicts occur:
git apply --reject ../patches/0001-*.patch
# Fix conflicts in *.rej files
# Regenerate patches:
git diff HEAD Telegram/CMakeLists.txt > patches/0001-add-mcp-cmake-configuration.patch

# 5. Rebuild
cd Telegram
./build/prepare/mac.sh silent
./configure.sh -D TDESKTOP_API_ID=... -D TDESKTOP_API_HASH=...
cd ../out
cmake --build . --config Release

______________________________________________________________________

项目结构

~/xCode/tlgrm/
├── .git/                           # Git repository
├── .gitignore                      # Comprehensive ignore rules
├── .env                            # Environment variables (API credentials)
│
├── tdesktop/                       # Modified Telegram Desktop
│   ├── .git/                       # tdesktop's git (submodule)
│   ├── Telegram/
│   │   ├── CMakeLists.txt          # Modified: +4 lines (MCP sources)
│   │   ├── SourceFiles/
│   │   │   ├── core/
│   │   │   │   ├── application.h   # Modified: +14 lines
│   │   │   │   └── application.cpp # Modified: +16 lines
│   │   │   └── mcp/                # NEW: MCP implementation
│   │   │       ├── mcp_server.h    # MCP protocol (200 lines)
│   │   │       ├── mcp_server.cpp  # MCP implementation (600 lines)
│   │   │       ├── mcp_bridge.h    # IPC bridge (89 lines)
│   │   │       └── mcp_bridge.cpp  # IPC implementation (245 lines)
│   │   └── build/
│   │       └── prepare/
│   │           └── mac.sh          # Dependency builder
│   ├── patches/                    # Patch files for updates
│   │   ├── 0001-add-mcp-cmake-configuration.patch
│   │   ├── 0002-add-mcp-application-integration.patch
│   │   └── mcp_source_files/       # MCP sources (for patching)
│   ├── out/                        # Build output (ignored by git)
│   │   ├── Telegram.xcodeproj      # Generated Xcode project
│   │   └── Release/
│   │       └── Telegram.app        # Built application
│   └── Libraries/                  # Built dependencies (ignored)
│
├── python-bridge/                  # Python MCP fallback
│   ├── README.md                   # Python implementation docs
│   ├── requirements.txt            # Python dependencies
│   ├── config.toml                 # Configuration
│   ├── config.dev.toml             # Development config
│   ├── config.prod.toml            # Production config
│   ├── main.py                     # Entry point
│   ├── mcp_server.py               # FastMCP server
│   ├── tdesktop_bridge.py          # IPC client for C++ server
│   ├── telegram_client.py          # Telegram Bot API wrapper
│   ├── config.py                   # Config loader
│   └── cache.py                    # Message caching
│
├── docs/                           # Documentation
│   ├── ARCHITECTURE_DECISION.md    # Why C++ over Python
│   ├── IMPLEMENTATION_SUMMARY.md   # Complete implementation overview
│   └── BUILD_GUIDE.md              # Build instructions & troubleshooting
│
├── Libraries/                      # Build dependencies (ignored)
│   ├── qt_6.2.12/                 # Qt framework
│   ├── ffmpeg/                    # Media processing
│   ├── openssl3/                  # Cryptography
│   └── ... (28 total dependencies)
│
├── ThirdParty/                     # External tools (ignored)
│   └── depot_tools/               # Chromium build tools
│
├── README.md                       # This file
├── docs/CLAUDE_NOTES.md            # AI assistant context
├── BUILD_BENCHMARKS.md             # Build performance data
├── apply-patches.sh                # Patch application script
└── test_mcp.py                     # MCP testing script

密钥目录

______________________________________________________________________

文档

主要文件

• README.md （此文件）-完整指南
• docs/CLAUDE_NOTES.md -AI助手的技术背景
• BUILD_BENCMARKS.md -构建性能分析

详细文件

• docs/ARCHITECTURE_DECISION.md

- 为什么C++胜过Python（性能分析） - 基准和比较 - 设计原理

• docs/BUILD_GUIDE.md

- 完整的构建参考和故障排除 - CMake配置和选项 - 常见问题和解决方案

• docs/IMPLEMENTATION_SUMMARY.md

- 完整实施状态 - 统计和指标 - 技术栈 - 即将到来的里程碑

• python桥/README.md

- Python MCP服务器文档 - IPC客户端使用情况 - 独立模式与桥接模式

外部文档

• MCP规范 -MCP官方文件
• 电报桌面版 -基地项目
• Qt文档 -Qt框架
• 电报API -电报协议

______________________________________________________________________

路线图

第一阶段：核心功能✅ 完成

• \[x\] tdesktop中嵌入的C++MCP服务器
• \[x\] JSON-RPC 2.0协议的实现
• \[x\] 标准传输（适用于Claude Desktop）
• \[x\] IPC桥接传输（用于外部工具的Unix套接字）
• \[x\] 330+工具注册
• \[x\] 更新补丁系统

第二阶段：数据集成✅ 完成

• \[x\] 将MCP服务器连接到tdesktop会话
• \[x\] 从本地数据库检索真实消息
• \[x\] 通过MTProto发送真实消息
• \[x\] 来自tdesktop数据结构的用户/聊天/频道信息
• \[x\] 隐私、安全和配置文件设置
• \[x\] 邮件搜索（本地数据库）
• \[x\] 54多种工具与真正的API集成

第3阶段：导出和归档✅ 完成

• \[x\] 逐步导出系统（绕过外卖环节）
• \[x\] HTML和JSON导出格式
• \[x\] 自动恢复中断的导出
• \[x\] 已删除帐户检测和存档
• \[x\] 恢复时截断文件清理
• \[x\] 通过准确的消息计数进行进度跟踪
• \[x\] 主题导出支持

第四阶段：高级功能📋 计划的

• \[\]语音转录（Whisper.cpp集成）
• \[\]语义搜索（FAISS矢量索引）
• \[\]HTTP传输支持
• \[\]实时通知（SSE）
• \[\]剩余的130多个存根工具实现

______________________________________________________________________

安全

当前安全模型

• 无网络曝光：可通过stdio（Claude Desktop）和本地Unix套接字访问MCP服务器(/tmp/tdesktop_mcp.sock)
• 不要求进行验证：信任调用过程
• 会话隔离：每个Telegram会话都是单独的
• tdata加密：使用本地密钥加密的会话数据（无macOS Keychain）
• 数据隐私：所有数据都保持本地（没有外部API调用）

未来的安全增强（如果添加了HTTP传输）

• 用于HTTP连接的API密钥身份验证
• 限制利率以防止滥用
• 范围限制（限制可访问的聊天）
• 所有MCP操作的审计日志记录
• 网络传输的TLS加密

最佳实践

1. 保持Telegram更新：定期应用安全补丁
2. 验证克劳德桌面：仅连接到官方Claude Desktop应用程序
3. 审核日志：通过系统日志监控MCP使用情况
4. 保护API凭据：从不承诺 .env 文件到公共存储库
5. 使用白名单 （Python桥）：必要时限制聊天访问

______________________________________________________________________

贡献

开发设置

# Fork the repository (after pushing to GitHub)
git clone https://github.com/YOUR_USERNAME/telegram-mcp.git
cd telegram-mcp

# Create feature branch
git checkout -b feature/my-feature

# Make changes, test, commit
git add .
git commit -m "Add feature X"

# Push and create pull request
git push origin feature/my-feature

贡献领域

1. 数据集成 -将MCP工具连接到真实的tdesktop会话
2. 新工具 -其他MCP工具（反应、民意调查等）
3. 演出 -优化消息检索和缓存
4. 测试 -单元测试、集成测试
5. 文档 -改进指南，添加示例
6. 语音AI -集成Whisper.cpp进行转录
7. 语义搜索 -实现FAISS矢量搜索
8. 媒体处理 -OCR、图像分析

代码风格

• C：遵循tdesktop风格（Qt惯例）
• python：使用黑色格式化程序遵循PEP 8
• 评论：记录为什么，而不是什么
• 提交消息：常规承诺格式

______________________________________________________________________

许可证

该项目延伸 电报桌面版，根据 GPLv3.

所有MCP集成代码也根据 GPLv3.

看 法律 获取完整的许可证信息。

______________________________________________________________________

致谢

• Telegram桌面团队 -优秀的开源客户端
• Anthropic -MCP规范和Claude
• FastMCP -Python MCP框架
• Qt项目 -跨平台UI框架
• MCP社区 -灵感与支持

______________________________________________________________________

支持与联系

获取帮助

• 构建问题：参见 故障排除 以上章节
• MCP协议: 模型上下文协议.io
• tdesktop: Telegram桌面文档

报告问题

在报告问题时，请包括：

1. 系统信息：macOS版本、硬件、Xcode版本
2. 生成日志：构建输出的相关部分
3. 错误消息：完整的错误文本
4. 重现步骤：详细的复制步骤
5. 预期与实际你的期望与实际情况

______________________________________________________________________

项目状态

版本: 6.9.5 基础：电报桌面6.5.1 最后更新: 2026-04-02 平台：macOS（苹果硅） MCP工具：330+注册（54+完全实施）

生成状态: ✅ 编译成功 MCP协议: ✅ 完全工作（stdio+IPC） 数据集成: ✅ 真实电报API 专家系统: ✅ 逐步出口并恢复 已删除帐户存档: ✅ 完全工作