TgWitnessСправочник / Архив и интеграции
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.
Раздел Интеграции → MCP показывает статус выполнения и команду установки с использованием
фактического исполняемого файла Python этого сервера. Повторная проверка обновляет этот статус без
перезагрузки страницы; она не устанавливает пакеты и не перезапускает сервер.
Дополнение MCP использует официальный MCP Python SDK.
Файл deploy/constraints-mcp.txt фиксирует протестированные версии SDK и зависимостей. Эти функции
требуют актуального исходного кода; портативная предварительная сборка 0.7.0 была выпущена до их появления.
Выпуск подключения#
- Введите метку и выберите рабочие пространства и чаты, которые клиент может читать.
- Выберите инструменты по отдельности или используйте пресет. Предлагаются только реализованные инструменты.
- Выберите 1, 7, 30 или 90 дней либо укажите собственный срок действия от одной минуты до 90 дней.
- Нажмите Создать подключение. Токен отобразится один раз рядом с конфигурацией клиента.
- Скопируйте токен и конфигурацию, затем запустите Проверить подключение. Это инициализирует MCP и выводит список разрешенных инструментов; сообщения при этом не читаются. В результате отображаются версия протокола, имена инструментов, их количество и затраченное время.
- Нажмите Готово, когда учетные данные будут сохранены. Фоновый опрос не сбрасывает форму и карточку однократного показа. Блокировка панели очищает отображаемые секреты.
В списке отображаются недавнее использование, последний инструмент, адрес и количество запросов за последнюю минуту. Отозвать прекращает доступ. Ротация токена отзывает старые учетные данные и выпускает замену с теми же областью доступа, инструментами и сроком действия; скопируйте новый токен при единственном показе. Токены входа в панель и учетные данные 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) панели для текущего запуска.
Чтобы получить стабильный адрес, доступный сразу после перезапуска, укажите HTTPS-источник панели в
TGWITNESS_PUBLIC_URL перед ее запуском.
Произвольные заголовки 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 или полноту фиксации.