TgWitness / Dokumentacja

Co zostało przetestowane →

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

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#

  1. Wprowadź etykietę oraz wybierz obszary robocze i czaty, które klient może odczytywać.
  2. Wybierz narzędzia pojedynczo lub użyj presetu. Dostępne są tylko zaimplementowane narzędzia.
  3. Wybierz 1, 7, 30 lub 90 dni albo własny czas wygaśnięcia z przedziału od jednej minuty do 90 dni.
  4. Naciśnij Create connection. Token wyświetli się jednorazowo obok konfiguracji klienta.
  5. 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.
  6. 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.