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

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

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

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

Підключіть аналітичний клієнт до вибраних робочих просторів і чатів. 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. Розділ Integrations → MCP показує стан середовища виконання та команду встановлення з використанням фактичного виконуваного файлу Python цього сервера. Кнопка Re-check оновлює цей статус без перезавантаження сторінки; вона не встановлює пакунки та не перезапускає сервер.

Доповнення MCP використовує офіційний MCP Python SDK. Файл deploy/constraints-mcp.txt фіксує протестовані версії SDK та залежностей. Ці функції потребують актуального вихідного коду; портативна попередня версія 0.7.0 вийшла раніше за них.

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

  1. Введіть мітку та виберіть робочі простори й чати, які клієнт може читати.
  2. Виберіть інструменти окремо або скористайтеся шаблоном. Пропонуються лише реалізовані інструменти.
  3. Виберіть термін дії 1, 7, 30 або 90 днів чи вкажіть власний термін від однієї хвилини до 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 HTTP із введенням пароля через promptString
Windsurf mcp_config.json HTTP із заповнювачем у заголовку Bearer
Інші клієнти URL-адреса та заголовок Authorization Streamable 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 Збережений текст повідомлень за вибраний період
get_message_versions Зафіксовані версії та спостереження щодо видалення
get_message_context Сусідні ідентифікатори зафіксованих повідомлень
get_journal_event Один очищений запис із посиланням на його джерело
get_capture_status Стан збору та дозволені записи про охоплення

tools/list повертає лише інструменти, надані цьому підключенню. Виклики інших інструментів відхиляються. Інструменти групового контексту, епізодів, термінології та ланцюжків відповідей не пропонуються в цій збірці; їхній окремий бекенд пакетів контексту не включено.

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

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

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