Odniesienie / Archiwum i integracje
Telegram · MCP tylko do odczytu
Połącz klienta MCP z wybranymi obszarami roboczymi i czatami, korzystając z dostępu ograniczonego czasowo i podlegającego odwołaniu.
TgWitness / Dokumentacja · Integracje z archiwami
Połącz klienta analitycznego z wybranymi obszarami roboczymi i czatami. TgWitness udostępnia
protokół Streamable HTTP pod adresem /mcp w procesie panelowym. Każde połączenie ma swój własny
token, termin ważności oraz zestaw dozwolonych narzędzi. MCP nie może wysyłać wiadomości w Telegramie, zmieniać
ustawień ani modyfikować podpisanego dziennika. Te same połączenia działają również z
wierszem poleceń.
Przewodnik po procesie pracy · Wiki
Na tej stronie
Instalacja i weryfikacja#
Użyj środowiska Python, w którym działa panel. Z pobranego kodu źródłowego wykonaj:
# 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
Po instalacji uruchom ponownie panel, podając jego standardowy katalog danych i argumenty uruchomieniowe.
Gotowość powinna obejmować komunikat [PASS] mcp: streamable-http available. W sekcji
Więcej narzędzi → Integracje → MCP wyświetlany jest stan środowiska uruchomieniowego oraz polecenie instalacyjne wykorzystujące
rzeczywisty plik wykonywalny języka Python tego serwera. Opcja Sprawdź ponownie odświeża ten stan bez
ponownego ładowania strony; nie powoduje ona instalacji pakietów ani ponownego uruchomienia serwera.
Dodatek MCP korzysta z oficjalnego zestawu SDK MCP dla języka Python. Plikdeploy/constraints-mcp.txt określa wersję testowanego zestawu SDK i zależności.
Utworzenie połączenia#
- Wprowadź etykietę oraz wybierz obszary robocze i czaty, które klient może odczytywać.
- Wybierz narzędzia pojedynczo lub użyj presetu. Dostępne są tylko zaimplementowane narzędzia.
- Wybierz 1, 7, 30 lub 90 dni albo własny czas wygaśnięcia z przedziału od jednej minuty do 90 dni.
- Naciśnij Create connection. Token wyświetli się jednorazowo obok konfiguracji klienta.
- Skopiuj token i konfigurację, a następnie uruchom Check connection. Inicjalizuje to MCP i wyświetla listę dozwolonych narzędzi; żadne wiadomości nie są odczytywane. Wynik pokazuje wersję protokołu, nazwy narzędzi, ich liczbę oraz czas wykonania.
- Naciśnij Done po zapisaniu poświadczeń. Odpytywanie w tle zachowuje formularz oraz kartę wyświetlaną jednorazowo. Zablokowanie panelu czyści wyświetlone sekrety.
Lista pokazuje ostatnie użycie, ostatnie narzędzie, adres oraz liczbę żądań w ciągu ostatniej minuty. Revoke kończy dostęp. Rotate token unieważnia stare poświadczenie i wydaje nowe z tym samym zakresem, zestawem narzędzi i czasem wygaśnięcia; skopiuj nowy token (wyświetlany jednorazowo). Tokeny logowania do panelu oraz poświadczenia Telegrama nie działają jako tokeny MCP.
Podłączanie klienta#
Wybierz klienta w panelu i skopiuj wygenerowaną dla niego konfigurację. Konfiguracje używają odwołań do sekretów lub jawnych symboli zastępczych (placeholderów); token jest kopiowany osobno.
| Klient | Konfiguracja | Połączenie |
|---|---|---|
| Kod Claude'a | .mcp.json |
HTTP, type: "http", nagłówek bearer |
| Claude Desktop | claude_desktop_config.json |
Lokalny mostek stdio |
| Cursor | .cursor/mcp.json |
HTTP z nagłówkiem opartym na zmiennej środowiskowej |
| VS Code Local | .vscode/mcp.json |
HTTP z wprowadzaniem hasła typu promptString |
| Windsurf | mcp_config.json |
HTTP z symbolem zastępczym nagłówka bearer |
| Inni klienci | Adres URL i nagłówek Authorization | Strumieniowy protokół HTTP |
TgWitness używa tokenów bearer bez wykrywania OAuth. Użyj lokalnego mostka stdio dla klientów, których zdalny konektor wymaga OAuth. W przypadku VS Code zmienne wejściowe mają zastosowanie do środowiska Local i nie są przekazywane do sesji Copilot. Dokumentacja konfiguracji: Claude Code, Cursor, VS Code.
Kanoniczny punkt wejścia dla lokalnego mostka to:
python -m tgwitness.mcp_server --url https://your-panel.example/mcp
Użyj lokalnego środowiska Python klienta z zainstalowanym dodatkiem MCP. Ustaw zmienną
TGWITNESS_MCP_TOKEN w jego chronionym środowisku. Nie umieszczaj poświadczeń w argumentach
poleceń ani w adresach URL. tgwitness-mcp to ten sam punkt wejścia. Stary moduł
tgwitness.mcp_bridge oraz nazwa TGWITNESS_ARCHIVE_TOKEN pozostają ścieżkami zgodności
z ostrzeżeniem; nowe konfiguracje używają mcp_server oraz TGWITNESS_MCP_TOKEN.
Cloudflare Tunnel#
Przekieruj ścieżkę /mcp panelu i zachowaj nagłówek bearer. Otwarcie ustawień MCP
jako administrator rejestruje bieżący origin panelu dla danego uruchomienia.
Aby uzyskać stabilny adres dostępny natychmiast po restarcie, skonfiguruj zmienną
TGWITNESS_PUBLIC_URL z adresem origin HTTPS panelu przed jego uruchomieniem.
Dowolne nagłówki Host i nagłówki przekazywane (forwarded) nie rejestrują zaufanego adresu.
Weryfikacja nagłówków Host i Origin odrzuca niepowiązane adresy pochodzenia przeglądarki. Odpowiedzi używają
Cache-Control: no-store; wartości autoryzacyjne nigdy nie są logowane.
Adres *.trycloudflare.com jest tymczasowy. Gdy restart tunelu zmieni
nazwę hosta, zaktualizuj skonfigurowany publiczny adres URL oraz adres URL MCP u każdego klienta. Używaj
stabilnej nazwy hosta dla zapisanych konfiguracji klientów.
Narzędzia i ograniczenia#
| Narzędzie | Odczytuje |
|---|---|
list_workspaces |
Przyznane obszary robocze |
list_chats |
Przyznane czaty |
search_messages |
Tekst zapisanych wiadomości z wybranego okresu; ranked=true wykorzystuje wyszukiwanie pełnotekstowe (formy słów, najpierw najlepsze dopasowania, next_offset stronicowanie) |
get_message_versions |
Przechwycone wersje i obserwacje usunięć |
get_message_context |
Identyfikatory pobliskich przechwyconych wiadomości |
get_journal_event |
Jeden oczyszczony rekord wraz z odwołaniem do źródła |
get_capture_status |
Stan zbioru, dozwolone zapisy dotyczące zasięgu oraz gap_summary: numery wiadomości, których nigdy nie zaobserwowano, w podziale na kanały lub supergrupy oraz dla sekwencji obejmującej całe konto (szczegóły); wybierz czat, aby wyświetlić listę luk w danych |
get_activity_stats |
Wiadomości według godziny UTC i dnia tygodnia, dni o największym natężeniu ruchu, odsetek edycji i usunięć, nadawców, domen oraz @handles, wraz z zasięgiem (szczegóły) |
get_messages_by_date |
Zapisane wiadomości z jednego dnia kalendarzowego w określonej strefie czasowej IANA (Europe/Kyiv, UTC), według czasu zgłaszanego przez Telegram; from_utc oraz until_utc należy podać obliczony dzień, z uwzględnieniem czasu letniego |
get_pinned_messages |
Wiadomości przypięte w najnowszej migawce stanu czatu wraz z ich zapisanymi wersjami oraz powiadomienia o przypięciu i odpięciu obserwowane na żywo |
get_chat_stats |
Liczba zapisanych rekordów dla jednej rozmowy lub wszystkich rozmów objętych zakresem, pierwsza i ostatnia obserwacja oraz gap_summary; należy z niego skorzystać przed przeprowadzeniem operacji odczytu dużej ilości danych |
get_topics |
Wątki na forum z wiadomości z usługi zapisanych wątków: historia tytułów, wątki zamknięte lub ukryte, liczba zapisanych wiadomości |
get_media |
Zachowany obraz w postaci pomniejszonego podglądu w formacie JPEG (maksymalnie 36 KB), zwracany jako obraz wraz z jego skrótem SHA-256 oraz media.saved rekordem; plik jest najpierw porównywany z zarejestrowanym skrótem, natomiast w przypadku innych plików zwracane są wyłącznie metadane |
export_messages |
Działa wyłącznie z wiersza poleceń, domyślnie nie jest zaznaczone: strumieniowo zapisuje obserwacje w formacie JSON Lines (szczegóły); nie jest dostępne za pośrednictwem MCP |
Każde narzędzie jest tylko do odczytu (readOnlyHint) i deklaruje schemat wyjściowy; pola wykraczające poza zadeklarowane są zwracane w niezmienionej postaci. tools/list Zwraca wyłącznie narzędzia przypisane do danego połączenia. Wywołania innych
narzędzi są odrzucane. Narzędzia związane z kontekstem grupy, epizodem, terminologią i łańcuchem odpowiedzi
nie są dostępne w tej kompilacji; nie zawiera ona oddzielnego backendu pakietu kontekstowego.
Każdy odczyt weryfikuje token, narzędzie oraz zakres obszaru roboczego/czatu, w tym również po zakończeniu pracy bazy danych. Limity wynoszą 60 żądań na minutę, 50 rekordów na stronę, 64 KiB na wynik oraz osiem sekund limitu czasu operacji w archiwum. Przekroczenie czasu wywołania MCP zwraca błąd narzędzia z prośbą o zawężenie okresu lub zmniejszenie limitu.
Wyniki wiadomości zawierają untrusted_content: true, identyfikatory obszaru roboczego/czatu/wiadomości,
sekwencję zdarzeń, zapisany skrót oraz link do panelu. Pomija się surowe obiekty Telegramu, skróty dostępu,
sesje i klucze. Skrócenia tekstu są oznaczone. Edycje, powiadomienia o usunięciu
oraz missing_on_recheck stanowią odrębne obserwacje. Zakres pokazuje okresy, które
obejmuje dany wynik.
Traktuj instrukcje zawarte w przechwyconych wiadomościach jako dowody, a nie jako instrukcje klienta. Dostęp tylko do odczytu uniemożliwia wprowadzanie zmian w archiwum; klient może jednak zachować treści, do których ma uprawnienia odczytu. Skróty identyfikują zapisane rekordy i wspierają kontrole integralności. Podczas przeglądania wyników korzystaj z dołączonych odniesień do źródeł oraz rekordów pokrycia.