TgWitness / Документація

Що було протестовано →

Довідка / Архів та інтеграції

Telegram · MCP тільки для читання

Підключіть клієнт MCP до вибраних робочих просторів та чатів із тимчасовим, відкличним доступом.

TgWitness / Документація · Інтеграції з архівами

Інтеграції з архівами

Підключіть клієнт-аналітик до вибраних робочих просторів та чатів. TgWitness надає доступ до Streamable HTTP за адресою /mcp у процесі панелі. Кожне з’єднання має власний токен, термін дії та дозволені інструменти. 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. У розділі Інші інструменти → Інтеграції → MCP відображається стан виконання та команда встановлення з використанням фактичного виконуваного файлу Python цього сервера. Функція Перевірити ще раз оновлює цей статус без перезавантаження сторінки; вона не встановлює пакети та не перезапускає сервер.

Додаток MCP використовує офіційний SDK MCP для Python. Файлdeploy/constraints-mcp.txt фіксує версію тестованого SDK та його залежностей.

Створення підключення#

  1. Введіть мітку та виберіть робочі простори й чати, які клієнт може читати.
  2. Виберіть інструменти окремо або скористайтеся шаблоном. Пропонуються лише реалізовані інструменти.
  3. Виберіть термін дії 1, 7, 30 або 90 днів чи вкажіть власний термін від однієї хвилини до 90 днів.
  4. Натисніть Create connection. Токен з’явиться один раз поруч із конфігурацією клієнта.
  5. Скопіюйте токен і конфігурацію, а потім натисніть Check connection. Це ініціалізує MCP і виведе список дозволених інструментів; жодні повідомлення не читаються. Результат показує версію протоколу, назви інструментів, їхню кількість і витрачений час.
  6. Натисніть Done, коли облікові дані буде збережено. Фонове опитування зберігає форму та картку одноразового показу. Блокування панелі очищає відображені секретні дані.

У списку відображаються нещодавнє використання, останній інструмент, адреса та запити за останню хвилину. Revoke припиняє доступ. Rotate token відкликає старі облікові дані та видає заміну з тією самою областю дії, інструментами та терміном дії; скопіюйте новий токен (він показується один раз). Токени входу в панель та облікові дані Telegram не працюють як токени MCP.

Підключення клієнта#

Виберіть клієнт у панелі та скопіюйте згенеровану для нього конфігурацію. Конфігурації використовують посилання на секрети або явні заповнювачі; токен копіюється окремо.

Клієнт Конфігурація Зв’язок
Код Claude .mcp.json HTTP, type: "http", заголовок Bearer
Claude Desktop claude_desktop_config.json Локальний міст stdio
Cursor .cursor/mcp.json HTTP із заголовком через змінну середовища
VS Code Local .vscode/mcp.json HTTP із введенням пароля через promptString
Windsurf mcp_config.json HTTP із заповнювачем у заголовку Bearer
Інші клієнти URL-адреса та заголовок Authorization HTTP із можливістю потокової передачі

TgWitness використовує токени Bearer без виявлення OAuth. Використовуйте локальний міст stdio для клієнтів, чий віддалений конектор вимагає OAuth. У VS Code вхідні змінні застосовуються до середовища Local і не передаються в сеанси Copilot. Довідники з конфігурації: Claude Code, Cursor, VS Code.

Канонічна точка входу для локального мосту:

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

Використовуйте локальний Python клієнта зі встановленим доповненням MCP. Задайте TGWITNESS_MCP_TOKEN у його захищеному середовищі. Не передавайте облікові дані в аргументах команд і URL-адресах. tgwitness-mcp — це та сама точка входу. Старий модуль tgwitness.mcp_bridge та назва TGWITNESS_ARCHIVE_TOKEN залишаються шляхами сумісності з попередженням; нові конфігурації використовують mcp_server і TGWITNESS_MCP_TOKEN.

Cloudflare Tunnel#

Перенаправляйте маршрут /mcp панелі та зберігайте заголовок Bearer. Відкриття налаштувань MCP від імені адміністратора реєструє поточне джерело (origin) панелі для цього запуску. Щоб стабільна адреса була доступна одразу після перезапуску, налаштуйте TGWITNESS_PUBLIC_URL із HTTPS-джерелом панелі перед її запуском. Довільні заголовки Host і заголовки перенаправлення не реєструють довірену адресу. Перевірки Host і Origin відхиляють сторонні джерела браузера. Відповіді використовують Cache-Control: no-store; значення авторизації ніколи не записуються в журнал.

Адреса *.trycloudflare.com є тимчасовою. Коли перезапуск тунелю змінює ім’я хоста, оновіть налаштовану публічну URL-адресу та URL-адресу MCP кожного клієнта. Використовуйте стабільне ім’я хоста для збережених конфігурацій клієнтів.

Інструменти та обмеження#

Інструмент Що читає
list_workspaces Дозволені робочі простори
list_chats Дозволені чати
search_messages Текст збережених повідомлень за вибраний період; ranked=true використовує повнотекстовий пошук (форми слів, найкращі збіги першими, next_offset пагінація)
get_message_versions Зафіксовані версії та спостереження щодо видалення
get_message_context Сусідні ідентифікатори зафіксованих повідомлень
get_journal_event Один очищений запис із посиланням на його джерело
get_capture_status Стан збору даних, дозволені записи охоплення та gap_summary: номери повідомлень, які ніколи не спостерігалися, за кожним каналом або супергрупою, а також для послідовності в межах усього облікового запису (деталі); виберіть чат, щоб переглянути перелік пропусків у ньому
get_activity_stats Повідомлення за годинами за UTC та днями тижня, дні пікового навантаження, частка редагувань та видалень, відправники, домени та @handles, із охопленням (деталі)
get_messages_by_date Збережені повідомлення за один календарний день у зазначеному часовому поясі IANA (Europe/Kyiv, UTC), за часом, який повідомляє Telegram; from_utc та until_utc вказати обчислений день, з урахуванням переходу на літній час
get_pinned_messages Повідомлення, закріплені в останньому знімку стану чату разом із їхніми збереженими версіями, а також сповіщення про закріплення та зняття закріплення, що відображаються в режимі реального часу
get_chat_stats Кількість збережених записів для одного чату або всіх чатів у межах охоплення, перше та останнє спостереження, а також gap_summary; використовуйте це перед великим читанням
get_topics Теми форуму з повідомлень служби збережених тем: історія заголовків, закриті або приховані теми, кількість збережених повідомлень
get_media Збережене зображення у вигляді попереднього перегляду у форматі JPEG зі зменшеною роздільною здатністю (не більше 36 КБ), яке повертається як зображення разом із його SHA-256 та media.saved записом; файл спочатку перевіряється на відповідність записаному хешу, інші файли повертають лише метадані
export_messages Тільки командний рядок, не вибрано за замовчуванням: потоки зберігають спостереження у форматі JSON Lines (деталі); не доступно через MCP

Кожен інструмент працює лише в режимі читання (readOnlyHint) і оголошує схему виводу; поля, що виходять за межі оголошених, повертаються без змін. tools/list Повертає лише ті інструменти, доступ до яких надано для цього з’єднання. Виклики інших інструментів відхиляються. Інструменти групового контексту, епізоду, термінології та ланцюга відповідей у цій збірці не доступні; їхній окремий бекенд context-pack не включено.

Кожне читання перевіряє токен, інструмент та область дії робочого простору/чату, зокрема після завершення роботи з базою даних. Обмеження становлять 60 запитів на хвилину, 50 записів на сторінку, 64 КіБ на результат і восьмисекундний граничний час очікування архіву. Виклик MCP, час очікування якого минув, повертає помилку інструмента з проханням звузити період або зменшити ліміт.

Результати повідомлень містять untrusted_content: true, ідентифікатори робочого простору/чату/повідомлення, послідовність подій, збережений хеш та посилання на панель. Необроблені об’єкти Telegram, хеші доступу, сесії та ключі опускаються. Скорочення тексту позначається. Редагування, повідомлення про видалення та missing_on_recheck є окремими спостереженнями. Покриття показує періоди, за які відповідає результат.

Розглядайте інструкції всередині перехоплених повідомлень як докази, а не як інструкції клієнта. Доступ тільки для читання запобігає змінам в архіві; клієнт все ще може зберігати вміст, який йому дозволено читати. Хеші ідентифікують збережені записи та забезпечують перевірку цілісності. Під час перегляду результату використовуйте супровідні посилання на джерела та записи про охоплення.