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

Canonical page: https://phishdestroy.github.io/TgWitness/uk/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`. Розділ **Integrations → MCP** показує стан середовища виконання та команду встановлення з використанням фактичного виконуваного файлу Python цього сервера. Кнопка **Re-check** оновлює цей статус без перезавантаження сторінки; вона не встановлює пакунки та не перезапускає сервер.

Доповнення 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. Натисніть **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](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) панелі для цього запуску. Щоб стабільна адреса була доступна одразу після перезапуску, налаштуйте `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 чи повноту захоплення.