Odniesienie / Archiwum i integracje

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.

Podłącz klienta analitycznego do wybranych obszarów roboczych i czatów. TgWitness obsługuje Streamable HTTP pod ścieżką /mcp w procesie panelu. Każde połączenie ma własny token, termin ważności oraz dozwolone narzędzia. MCP nie może wysyłać wiadomości na Telegramie, zmieniać ustawień ani modyfikować podpisanego dziennika.

Przewodnik po procesie pracy · Wiki

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 ze standardowym katalogiem danych i argumentami startowymi. Sprawdzenie gotowości powinno zawierać [PASS] mcp: streamable-http available. Sekcja Integrations → MCP pokazuje status środowiska uruchomieniowego oraz polecenie instalacyjne używające rzeczywistego pliku wykonywalnego Pythona na tym serwerze. Przycisk Re-check odświeża ten status bez przeładowywania strony; nie instaluje pakietów ani nie restartuje serwera.

Dodatek MCP wykorzystuje oficjalny pakiet MCP Python SDK. Plik deploy/constraints-mcp.txt przypina przetestowane wersje SDK i zależności. Funkcje te wymagają aktualnego kodu źródłowego; przenośna wersja poglądowa 0.7.0 powstała przed ich wprowadzeniem.

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
Claude Code	`.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	Streamable 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`	Zapisany tekst wiadomości w wybranym okresie
`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 gromadzenia danych i dozwolone rekordy pokrycia

Wywołanie tools/list zwraca wyłącznie narzędzia przyznane dla danego połączenia. Wywołania innych narzędzi są odrzucane. Narzędzia dotyczące kontekstu grupowego, epizodów, terminologii oraz łańcuchów odpowiedzi nie są dostępne w tej kompilacji; ich oddzielny backend pakietów kontekstowych nie jest dołączony.

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, numer sekwencyjny zdarzenia, zapisany skrót (hash) oraz link do panelu. Surowe obiekty Telegrama, skróty dostępu (access hashes), sesje i klucze są pomijane. Obcięcie tekstu jest oznaczane. Edycje, powiadomienia o usunięciu oraz missing_on_recheck to odrębne obserwacje. Brakujące rekordy nie dowodzą, że zdarzenie nigdy nie miało miejsca.

Traktuj instrukcje zawarte w przechwyconych wiadomościach jako materiał dowodowy, a nigdy jako polecenia dla klienta. Dostęp tylko do odczytu uniemożliwia wprowadzanie zmian w archiwum; klient nadal może jednak zachować treści, do których odczytu ma uprawnienia. Skróty identyfikują zapisane rekordy i wspierają weryfikację integralności; nie dowodzą one autorstwa na Telegramie ani kompletności przechwycenia.