# MCP только для чтения

Canonical page: https://phishdestroy.github.io/TgWitness/ru/docs/reference/mcp/

Подключите клиент MCP к выбранным рабочим пространствам и чатам с ограниченным по времени и отзывным доступом.

Подключайте клиент аналитика к выбранным рабочим пространствам и чатам. TgWitness обслуживает **Streamable HTTP по пути `/mcp` в процессе панели**. У каждого подключения свой токен, срок действия и разрешенные инструменты. MCP не может отправлять сообщения в Telegram, менять настройки или изменять подписанный журнал.

[Руководство по рабочему процессу](https://phishdestroy.github.io/TgWitness/docs/archive/) · [Вики](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

## Установка и проверка

Используйте окружение 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](https://github.com/modelcontextprotocol/python-sdk). Файл `deploy/constraints-mcp.txt` фиксирует протестированные версии SDK и зависимостей. Эти функции требуют актуального исходного кода; портативная предварительная сборка 0.7.0 была выпущена до их появления.

## Выпуск подключения

1. Введите метку и выберите рабочие пространства и чаты, которые клиент может читать.
2. Выберите инструменты по отдельности или используйте пресет. Предлагаются только реализованные инструменты.
3. Выберите 1, 7, 30 или 90 дней либо укажите собственный срок действия от одной минуты до 90 дней.
4. Нажмите **Создать подключение**. Токен отобразится один раз рядом с конфигурацией клиента.
5. Скопируйте токен и конфигурацию, затем запустите **Проверить подключение**. Это инициализирует MCP и выводит список разрешенных инструментов; **сообщения при этом не читаются**. В результате отображаются версия протокола, имена инструментов, их количество и затраченное время.
6. Нажмите **Готово**, когда учетные данные будут сохранены. Фоновый опрос не сбрасывает форму и карточку однократного показа. Блокировка панели очищает отображаемые секреты.

В списке отображаются недавнее использование, последний инструмент, адрес и количество запросов за последнюю минуту. **Отозвать** прекращает доступ. **Ротация токена** отзывает старые учетные данные и выпускает замену с теми же областью доступа, инструментами и сроком действия; скопируйте новый токен при единственном показе. Токены входа в панель и учетные данные 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](https://code.claude.com/docs/en/mcp), [Cursor](https://prod.cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

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

```
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 или полноту фиксации.