TgWitness / 文件說明
繁體中文
EnglishРусскийУкраїнськаEspañolPortuguês (Brasil)Türkçeالعربيةفارسیاردوहिन्दीBahasa IndonesiaTiếng Việt简体中文FrançaisDeutschItalianoO‘zbekcha한국어繁體中文Bahasa MelayuPolski日本語ไทยעבריתবাংলা

參考資料 / 存檔與整合功能

唯讀 MCP

將 MCP 客戶端連接到選定的工作區和聊天室，並賦予其具有有效期限且可撤銷的存取權限。

將分析師用戶端連線至選定的工作區與聊天室。TgWitness 在面板行程中的 /mcp 提供 Streamable HTTP 服務。每個連線都有獨立的權杖、到期時間與授權工具。MCP 無法傳送 Telegram 訊息、變更設定或修改已簽章的日誌。

工作流程指南 · 維基

安裝與檢查#

請使用執行面板的 Python 環境。從原始碼檢出目錄執行：

# Windows PowerShell
& .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
& .\.venv\Scripts\python.exe start.py --check
# Linux / macOS
.venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
.venv/bin/python start.py --check

安裝完成後，請使用慣用的資料目錄與啟動引數重新啟動面板。就緒狀態應包含 [PASS] mcp: streamable-http available。 Integrations → MCP 會顯示執行階段狀態，以及使用該伺服器實際 Python 執行檔的安裝指令。Re-check 會在不重新載入頁面的情況下重新整理此狀態；它不會安裝套件或重新啟動伺服器。

MCP 擴充套件使用官方的 MCP Python SDK。 deploy/constraints-mcp.txt 鎖定了經測試的 SDK 與相依套件版本。這些功能需要最新的原始碼；0.7.0 可攜式預覽版早於這些功能推出。

核發連線#

  1. 輸入標籤，並選擇允許用戶端讀取的工作區與聊天室。
  2. 逐一選擇工具或使用預設組合。系統僅提供已實作的工具。
  3. 選擇 1、7、30 或 90 天，或設定介於 1 分鐘至 90 天之間的自訂到期時間。
  4. 按下 Create connection。權杖會在用戶端設定旁顯示一次。
  5. 複製權杖與設定，接著執行 Check connection。這會初始化 MCP 並列出授權的工具；不會讀取任何訊息。結果會顯示通訊協定版本、工具名稱、數量與耗時。
  6. 儲存憑證後按下 Done。輪詢期間會保留表單與僅顯示一次的卡片。鎖定面板會清除畫面上顯示的機密資訊。

清單會顯示近期使用情況、最後使用的工具、位址以及過去一分鐘內的請求數。 Revoke 會終止存取權限。Rotate token 會撤銷舊憑證，並核發具有相同範圍、工具與到期時間的替代權杖；請單次複製該替代權杖。 面板登入權杖與 Telegram 憑證無法作為 MCP 權杖使用。

連接您的用戶端#

在面板中選擇用戶端並複製產生的設定。設定檔會使用機密參照或明確的預留位置；權杖需另外複製。

用戶端 設定 連結
Claude Code .mcp.json HTTP、type: "http"、Bearer 標頭
Claude Desktop claude_desktop_config.json 本機 stdio 橋接器
Cursor .cursor/mcp.json 使用環境變數標頭的 HTTP
VS Code Local .vscode/mcp.json 使用密碼 promptString 輸入的 HTTP
Windsurf mcp_config.json 使用 Bearer 標頭預留位置的 HTTP
其他用戶端 URL 與 Authorization 標頭 Streamable HTTP

TgWitness 使用 Bearer 權杖，不支援 OAuth 自動探索。若用戶端的遠端連接器要求使用 OAuth，請改用本機 stdio 橋接器。針對 VS Code，輸入變數僅適用於 Local 執行環境，不會轉發至 Copilot 工作階段。 設定參考文件：Claude Code、Cursor、VS Code。

本機橋接器的標準進入點為：

python -m tgwitness.mcp_server --url https://your-panel.example/mcp

請使用用戶端本機已安裝 MCP 擴充套件的 Python 環境。在其受保護的環境中設定 TGWITNESS_MCP_TOKEN。請勿將憑證寫入指令引數與 URL 中。tgwitness-mcp 是相同的進入點。舊的 tgwitness.mcp_bridge 模組與 TGWITNESS_ARCHIVE_TOKEN 名稱仍作為相容性路徑保留並會發出警告；新的設定請使用 mcp_server 與 TGWITNESS_MCP_TOKEN。

Cloudflare Tunnel#

轉發面板的 /mcp 路由並保留 Bearer 標頭。以管理員身分開啟 MCP 設定時，會為當次執行註冊面板目前的來源位址（Origin）。 若要在重新啟動後立即擁有穩定的可用位址，請在啟動面板前，將面板的 HTTPS 來源位址設定至 TGWITNESS_PUBLIC_URL。 任意的 Host 與轉發標頭不會註冊為受信任的位址。 Host 與 Origin 檢查會拒絕不相關的瀏覽器來源。回應會使用 Cache-Control: no-store；授權值絕不會被記錄至日誌中。

*.trycloudflare.com 位址是暫時性的。當通道重新啟動並變更主機名稱時，請更新已設定的公開 URL 以及各個用戶端的 MCP URL。針對需要儲存的用戶端設定，請使用穩定的主機名稱。

工具與權限邊界#

工具 讀取內容
list_workspaces 已授權的工作區
list_chats 已授權的聊天室
search_messages 指定期間內已儲存的訊息文字
get_message_versions 已擷取的版本與刪除觀測記錄
get_message_context 鄰近的已擷取訊息 ID
get_journal_event 單筆經過清理的記錄及其來源參照
get_capture_status 收集狀態與授權的涵蓋範圍記錄

tools/list 僅會回傳授予該連線的工具。對其他工具的呼叫將會被拒絕。此組建不提供群組脈絡、事件片段（episode）、術語及回覆鏈工具；系統未包含這些工具獨立的 context-pack 後端。

每次讀取都會檢查權杖、工具以及工作區／聊天室範圍，包含在資料庫作業完成之後的檢查。限制為每分鐘 60 次請求、每頁 50 筆記錄、每筆結果 64 KiB，以及 8 秒的封存查詢時限。逾時的 MCP 呼叫會回傳工具錯誤，要求縮小時間範圍或降低筆數上限。

訊息結果包含 untrusted_content: true、工作區／聊天室／訊息 ID、事件序號、已儲存的雜湊值以及面板連結。原始 Telegram 物件、存取雜湊（access hashes）、工作階段與金鑰均會被省略。文字截斷處會加以標記。編輯、刪除通知與 missing_on_recheck 為各自獨立的觀測結果。缺少記錄並不能證明某個事件從未發生。

請將擷取訊息內的指示視為證據，切勿將其作為用戶端指令執行。唯讀存取權限可防止封存內容遭竄改；但用戶端仍可保留其獲准讀取的內容。雜湊值用於識別已儲存的記錄並支援完整性檢查；它們無法證明 Telegram 的作者身分或擷取內容的完整性。