Newer
Older
gnexus-book / 10-systems / hosts / tgclientmcp.md

title: "VPS tgclientmcp (tgclient-mcp)" type: host ip: "192.168.1.171" purpose: "tgclient-mcp — мульти-аккаунтный Telegram-клиент (Telethon) + MCP-сервер + SPA-админка в home LAN" owner: gmikcon status: active confidence: "90" last_reviewed: "2026-10-17" review_interval: "90d"

source_of_truth: "ssh-host-and-owner-confirmed"

VPS tgclientmcp (tgclient-mcp)

Overview

Home LAN VPS (KVM/QEMU guest). Выделен владельцем 2026-10-05 из свободного диапазона 192.168.1.170–180 (скан nmap: свободны были .171/.174/.180). Хостит tgclient-mcp — Telegram-клиент формата MCP для экосистемы Gnexus: мульти-аккаунтный MTProto юзер-клиент (Telethon), MCP-сервер для ИИ-агентов (/mcp-protocol/) и SPA-админка с персональными MCP-токенами.

Technical Details

  • IP: 192.168.1.171 (статический, netplan внутри гостя с 2026-10-17)
  • Hostname: tgclientmcp
  • MAC: 52:54:00:6d:8d:86 (virsh, bserv)
  • OS: Ubuntu 22.04.5 LTS
  • Platform: KVM guest, 1.9 GiB RAM, 15G root disk (47% занято на деплой)
  • User: ubuntu (SSH + sudo, пароль getroot88)
  • Firewall: ufw не активен
  • Docker: 29.1.3 (предустановлен), docker compose plugin 2.40.3 (пакет docker-compose-v2 установлен 2026-10-05 navi rei)

tgclient-mcp (deployed 2026-10-05, updated 2026-10-06 ×4, 2026-10-07)

  • Repo: /home/ubuntu/tgclient-mcp (https://git.gnexus.space/git/root/tgclient-mcp.git), branch master, HEAD df2492b (обновлено 2026-10-07 navi rei; история обновлений: 2026-10-06 — edbd2e2 QR-вход, f4b1da9 фиксы логина, 0fc015e SPA-табы логин-визарда, ac8b764 SPA-фиксы; 2026-10-07 — e269bfb+5cc14e3 MCP runtime-аудит, 004db72 фикс _touch, df2492b фильтр аккаунтов; все — git pull --ff-only + sudo docker compose up -d --build, health ok)
  • Stack: docker compose, один сервис tgclient (multi-stage build: SPA node:22-slim → backend python:3.12-slim + uvicorn), volume data:/data (SQLite aiosqlite WAL — единственное состояние)
  • Port: 8710 (host) → 8000 (container), 0.0.0.0
  • Public URL: https://tgclientmcp.gnexus.space (TLS на internal-proxy-vps .183, отдельный LE-сертификат до 2027-01-03; upstream http://192.168.1.171:8710)
  • Endpoints:
  • Config: /home/ubuntu/tgclient-mcp/.env (chmod 600, из .env.example).
    • Telegram API заполнены 2026-10-05 (владелец получил на my.telegram.org, физлицо, бесплатно; апка-регистрация старая — CONAssistantApp, ~8 лет, это нормально: api_id идентифицирует приложение, не аккаунт): TGCLIENT_API_ID=24357013, TGCLIENT_API_HASH — в .env и в gnexus-creds secret "tgclient-mcp Telegram API (api_id/api_hash)" (id d5d70390-a058-4399-add8-539d71c9e1de). Один набор на деплой.
    • SSO gnexus-auth настроен 2026-10-05 (креды выдал владелец): TGCLIENT_AUTH_BASE_URL=https://auth.gnexus.space, TGCLIENT_AUTH_CLIENT_ID=gnx_207OcTjCYgqSQJwuTO2V5ks0EB1GftA0, TGCLIENT_AUTH_REDIRECT_URI=https://tgclientmcp.gnexus.space/auth/callback, client_secret и webhook secret — в .env и в gnexus-creds secret "tgclient-mcp SSO gnexus-auth (OAuth client)" (id 935a3ff1-f9c5-4738-9da5-83fdafb5fd70). TGCLIENT_AUTH_ALLOWLIST пуст — пускается любой залогиненный gnexus-auth.
    • Synapse-репортер настроен 2026-10-07 (см. «Интеграция с Synapse»).
    • Всё ещё НЕ заполнен: TGCLIENT_ADMIN_TOKEN.
    • GOTCHA: TGCLIENT_API_ID= пустая строка ломает pydantic int — при ротации не оставлять строку пустой, комментировать или вписывать число.
  • Креды хоста: gnexus-creds secret "tgclient-mcp host SSH (192.168.1.171)" (id 70fb91b3-85f0-479c-9ecb-ba009299417f).

Аккаунты (2026-10-06)

  • Аккаунт владельца залогинен 2026-10-06 через QR-вход (edbd2e2): phone +380632912932, username sukhodolskiy, display_name «Eugene Suhodolskiy», status active, id 1 в БД. Первая попытка QR («произошла ошибка» на Android при скане) не прошла — вероятная причина: скан протухшего токена (TTL ~30 с) или гонка первой попытки; повторный QR-логин через свежий POST /accounts/logins/qr прошёл успешно.
  • Аккаунт Navi (id 2): phone +380939126548, display_name «Navi», tg_user_id 8781031814, status active — бот-аккаунт для агентских сценариев.
  • Клиент пула подключается лениво при первом использовании — health показывает connected: 0 до первой операции с аккаунтом, это норма (после логина владельца показывает connected: 1).

SSO flow (verified 2026-10-05)

  • GET /auth/login → 302 на https://auth.gnexus.space/oauth/authorize?response_type=code&client_id=…&redirect_uri=https%3A%2F%2Ftgclientmcp.gnexus.space%2Fauth%2Fcallback&state=…&code_challenge=…&code_challenge_method=S256&scope=openid+email+profile+roles+permissions&return_to=/ (PKCE S256; gnexus-auth показывает страницу Sign in — клиент принят).
  • GET /auth/callback?code&state — обмен кода (client_secret + PKCE verifier), сессия в cookie (secure, т.к. redirect_uri https), redirect на return_to. Фейковый state → 400 «Invalid or expired OAuth state».
  • POST /webhooks/gnexus-auth (+ вариант с trailing slash) — события gnexus-auth (HMAC-подпись через TGCLIENT_AUTH_WEBHOOK_SECRET); без подписи → 401 «invalid webhook signature».
  • Внутренние httpx-запросы к gnexus-auth идут с verify=False (сервис в LAN, TLS терминируется на internal-proxy) — это осознанное решение из кода репо.
  • Подключение агента: claude mcp add --transport http tgclient https://tgclientmcp.gnexus.space/mcp-protocol/ --header "Authorization: Bearer mcp_..."

Deploy fixes & features (2026-10-05, rei) — закоммичены в репо

  1. backend/Dockerfile: COPY frontend/package.json frontend/.npmrc ./ — не копировался package-lock.json, npm ci падал. Исправлено: COPY frontend/package.json frontend/package-lock.json frontend/.npmrc ./.
  2. backend/app/tg/manager.py: NameError: TelegramClient — класс используется в аннотациях, но не импортирован. Исправлено: from telethon import TelegramClient, errors.
  3. backend/app/mcp/server.py: FastMCP (mcp-sdk 1.30.0) при дефолтном host=127.0.0.1 автоматически включает DNS-rebinding защиту с allowed_hosts только 127.0.0.1/localhost/[::1] — любой запрос через домен получал 421 «Invalid Host header». Исправлено: в конструктор FastMCP добавлен transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False) (сервис за nginx с собственным гардом require_mcp — защита не нужна).
  4. backend/app/tg/login_flow.py: AttributeError: 'TelegramClientWithSession' object has no attribute 'session' — враппер логин-клиента не экспонировал .session, _finalize падал сразу после успешного sign_in (Telegram авторизацию засчитывал, сессия терялась, аккаунт не записывался в БД). Исправлено: добавлен @property session → self._client.session. Попутно добавлен диагностический лог [login] send_code_request ok: sent=… (тип доставки кода от Telegram — SentCodeTypeApp/SentCodeTypeSms/Call).
  5. Фича: автоотмена зависших логинов (запрос владельца: «если через 15 минут начала процесса входа сессия так и не была создана — отменить»). Фоновый sweeper login_sweeper_loop (main.py, интервал 30 с, таск в lifespan с graceful cancel) каждые 30 с вызывает login_flow.purge_stale_logins(): pending-логины старше TGCLIENT_LOGIN_STALE_MINUTES (config.py, default 15) минут от created_at отменяются как ручная DELETE — _cleanup (строка в БД + disconnect-логика, иначе зомби-коннект к Telegram), лог [login] auto-cancel stale login <id> (age > 15m, step=…). auth.purge_expired больше НЕ удаляет login_sessions — sweeper единственный владелец их очистки (GC по expires_at disconnect не делал). Верифицировано живым тестом: тестовая строка с created_at=now-20min вычищена sweeper'ом за 40 с, лог подтверждён.

Все пять изменений закоммичены в репо 2026-10-05: 77bded2 (деплой-фиксы + sweeper), 7d64d8a (отмена логина инвалидирует код у Telegram через auth.cancelCode, а не только чистит строку; sweeper отменяет так же; фронт — ошибка отмены не глотается: тост + модалка не закрывается на неудаче). Рабочая копия на хосте чистая, git pull --ff-only проходит без конфликтов (проверено всеми обновлениями 2026-10-06 и 2026-10-07).

Обновления 2026-10-06 (задеплоены navi rei)

День — edbd2e2, QR-вход:

  • Новый эндпоинт/MCP-тул account_login_qr_start + SPA «Вход по QR» — вход через QR-код (telethon qr_login), коды Telegram не используются — обходит PHONE_CODE_FLOOD.
  • Резидентный waiter qr.wait/recreate; 2FA — через обычный password-шаг; отмена/сгорание QR чистят waiter.

Вечер — f4b1da9, ревью логина (4 коммита):

  • b00ec83: cancelCode/qr.recreate под wait_for (5с/10с) — DELETE отмены на полумёртвом MTProto-коннекте висел вечно, кнопка «Отменить логин» выглядела мёртвой ровно тогда, когда код не приходил.
  • de74028: лимит 3 pending-логина считает только живые (expires_at>now) — истёкшие зомби-строки больше не лочат новый вход 409-ом на 15 минут.
  • 3323cc4: ревью логина — 3 фатальных бага + честные терминальные шаги.
  • f4b1da9: README — терминальные шаги логина (done/error) + раздел Тесты.
  • В репо появились тесты: backend/tests/test_login_flow.py (484 строки) + conftest.py; pyproject.toml дополнен.

Поздний вечер — 0fc015e, SPA: табы логин-визарда:

  • Входная часть логин-визарда — табы «SMS-код / QR» (LoginWizard.vue, i18n en/ru/uk). Только фронт, бэкенд не менялся.

Ночь — ac8b764, SPA-фиксы:

  • Фикс пустой иконки disconnect (AccountsPage.vue) + дублированный инпут имени ключа (McpKeysPage.vue), мелочь в AdminPage.vue. Только фронт.

Обновления 2026-10-07 (задеплоены navi rei)

e269bfb + 5cc14e3 — MCP runtime-аудит тулов:

  • e269bfb: boundary тулов ловит реальные классы «диалог не найден» (backend/app/mcp/tools.py).
  • 5cc14e3: runtime-аудит — None-offsets в messages_history и video=None в звонках (backend/app/mcp/tools.py, backend/app/tg/calls.py).
  • Новые тесты: backend/tests/test_mcp_tools.py (407 строк) + test_tool_boundary.py (64 строки). Только бэкенд, SPA не менялся.

004db72 — фикс AccountManager._touch (19:26):

  • get_client вызывал await self._touch(account_id), но метода в классе не было — warmup падал с AttributeError ДО регистрации слушателей (register_listeners), клиенты оставались закэшированными: отправка работала, а message/*-события не рождались. Исправлено: добавлен метод _touch (UPDATE accounts SET last_used_at = now). Живой тест после фикса — message/received дошёл до Synapse и Navi.

df2492b — фильтр аккаунтов TGCLIENT_NOTIFY_ACCOUNTS (19:37):

  • Запрос владельца: «чтоб только с аккаунта Navi сообщения приходили в Navi, зачем ей мои». Реализовано: config.py notify_accounts: str (csv id аккаунтов, пусто = все) + гейт _allowed() в events.py (_report_message и _on_deleted). .env: TGCLIENT_NOTIFY_ACCOUNTS=2 (бэкап .env.bak-notifyacc-20261007), .env.example дополнен.
  • Живой тест: сообщение с акка 1 → Navi (акк 2) → ровно одно событие message/received от account-2 (68a5c24f), от account-1 ничего — фильтр работает. Наблюдение: исходящее сообщение через MCP-тул (out=true) событие не порождает — NewMessage-хендлер ловит только входящие (out=false); для сценария «Navi реагирует на входящие» это корректно.

Интеграция с Synapse (2026-10-07, navi rei)

  • Репортер backend/app/synapse_report.py включён: 10 типов событий (account/logged_in|logged_out|auth_lost|login_failed, api/flood_wait, token/issued|revoked, message/received|edited|deleted), fire-and-forget, dedup по UTC-дню для account/api-событий, ttl 24ч (сообщения — 1ч).
  • Synapse: source tgclient (id 2) + 10 зарегистрированных типов + API-ключ (key id 2, hint 0b7b) — plaintext в gnexus-creds secret "tgclient-mcp Synapse reporter API key (syn_…)" (id 98284541-d320-4bc4-b691-09295d22dba3).
  • .env: TGCLIENT_SYNAPSE_URL=http://192.168.1.172:8013, TGCLIENT_SYNAPSE_APIKEY=syn…0b7b, TGCLIENT_SYNAPSE_DEFAULT_SOURCE=tgclient (ВАЖНО: имя источника в Synapse — tgclient, а не tgclient-mcp; с дефолтом из .env.example Synapse отвечает 403 «Поле source не совпадает с источником ключа»), TGCLIENT_SYNAPSE_TIMEOUT=10. Бэкап: .env.bak-synapse-20261007.
  • Пуш-события сообщений ВКЛЮЧЕНЫ 2026-10-07 19:22 (решение владельца — доставлять сообщения через Synapse): TGCLIENT_NOTIFY_MESSAGES=1 в .env (бэкап .env.bak-notify-20261007), контейнер пересоздан. Живой тест: сообщение с аккаунта Navi (id 2) владельцу (id 1) → message/received 8093aa27 в Synapse → delivery s2s navi-rei delivered (1 попытка) → synapse.delivery_accepted на Navi. Реальный трафик (message/edited из новостных каналов) тоже течёт. Слушатели вешаются при подключении клиента (manager.py, гейт notify_messages читается на get_client).
  • Фильтр аккаунтов (19:37): TGCLIENT_NOTIFY_ACCOUNTS=2 — в Synapse пушатся только сообщения аккаунта Navi (id 2); переписки аккаунта владельца (id 1, новостные каналы и личные чаты) не покидают tgclient. Пусто = все аккаунты (прошлое поведение).
  • E2E проверено 2026-10-07: POST /api/v1/events с syn_-ключом с .171 → 202, событие done в Synapse (c9837953).
  • Маршрутизация (фаза 2, 2026-10-07 19:02): правило 2 «tgclient → navi-rei (s2s)» (conditions: source=tgclient) → s2s-цель navi-rei (id 3, endpoint http://192.168.1.168:8099/webhooks/synapse, token_ref navi-rei). Доставки работают — проверено живыми событиями token/issued|revoked и message/received|edited.

MCP-токены (2026-10-07, navi rei)

Персональные MCP-ключи mcp_* — таблица mcp_tokens в tgclient.db, выпускаются на странице «MCP-ключи» SPA (plaintext показывается один раз), роль superadmin у владельца (user_id=1, goldmikki@gmail.com):

  • id 1 «Navi» (hint wBmQadiq) — активен, создан 2026-10-07 12:36 UTC.
  • id 2 «Navi started» (hint NvFzVdNS) — активен, создан 2026-10-07 13:51 UTC.
  • id 3 «synapse-e2e-test» (hint 8_E65tXn) — создан и отозван 2026-10-07 19:13 UTC (полный жизненный цикл за 200 мс, last_used_at NULL) — программный E2E-тест выпуска/отзыва токена. События token/issued + token/revoked ушли в Synapse и доставлены в s2s-цель navi-rei (правило 2); реакционная сессия navi rei отработала событие token/revoked (75374a28-8ba6-4b6f-859e-7fbaabc66298) — инцидента нет, оба рабочих ключа активны, аккаунты active/connected, health ok.

Telegram login notes (2026-10-05)

  • Свежесозданному api_id Telegram может молча не доставлять код (сервер отвечает SentCodeTypeApp «отправил», но в чат 777000 ничего не приходит) — антиабьюз-прогрев, лечится временем (~час). После прогрева код приходит в приложение (чат «Telegram»/777000), SMS не используется. Наблюдение 2026-10-05: 6 отправок подряд — доставилась 1; троттлинг на уровне api_id, завершение сессий аккаунта с телефона на него не влияет.
  • Повторный POST /logins на неистёкшую pending-сессию того же user+phone возвращает её БЕЗ повторной send_code (защита от флуда) — для реотправки сначала DELETE /accounts/logins/{id}.
  • Автоотмена (фича #5): pending-логин старше 15 мин от created_at вычищается sweeper'ом (30-секундный цикл). Критерий — created_at, НЕ expires_at: продление expires_at в БД вручную больше не спасает сессию от автоотмены. Для нового логина после автоотмены — свежий POST /accounts/logins (новая send_code).
  • QR-вход (2026-10-06, живой опыт): токен QR живёт ~30 с, waiter ротирует его через recreate; SPA перерисовывает QR при смене qr_url. Первая попытка скана дала «произошла ошибка» на Android — повторная через свежий QR прошла. При отмене код-логина наблюдался [login] cancel_code(...): TypeError — чистим локально (обработано грейсfully, но TypeError от auth.cancelCode стоит глянуть в репо).
  • Диагностическая сессия для API-вызовов без браузера: строка в таблице sessions (id hex, user_id='1', expires_at +1h) + заголовок Cookie: tgclient_session=<id> (имя cookie — SESSION_COOKIE в auth.py).

2026-10-17: блэкаут, возврат на .171 (navi rei)

  • Ночной блэкаут 2026-10-16/17: VM погашена владельцем, утром 2026-10-17 запущена заново. Netplan-статика на момент блэкаута ещё не была настроена (файл был cloud-init DHCP) — VM получила от pfSense временный адрес 192.168.1.24, старый .171 освободился.
  • Временный фикс (утро): TGCLIENT_SYNAPSE_URL=http://192.168.1.29:8013 (synapse тоже временно на .29), nginx-апстрим на internal-proxy (.183) → http://192.168.1.24:8710.
  • Возврат (решение владельца, день 2026-10-17): netplan-статика 192.168.1.171/24 (gateway 192.168.1.1, DNS 192.168.1.1 + 1.1.1.1), cloud-init network config disabled, 50-cloud-init.yaml удалён, создан 50-static.yaml; TGCLIENT_SYNAPSE_URL откатан на http://192.168.1.172:8013, контейнер пересоздан; nginx-апстрим на internal-proxy откатан на .171:8710. Проверено: health 200 (2/2 аккаунта connected), MCP tgclient connected.
  • Открытый пункт: Kea-резервация на pfSense (MAC 52:54:00:6d:8d:86 → .171) не требуется, пока в госте статика; при отказе от статики — добавить резервацию (нужен админ-доступ к pfSense).

Pending

  • TGCLIENT_ADMINTOKEN пуст — статический супер-токен для скриптов (роль superadmin) не задан; персональные MCP-ключи `mcp*` выпускаются на странице «MCP-ключи» SPA (plaintext показывается один раз).
  • Разобраться в TypeError от auth.cancelCode при отмене логина (лог [login] cancel_code(...): TypeError — чистим локально, 2026-10-06) — кандидат на фикс в репо.

Listening ports (TCP, verified 2026-10-05)

  • 22 — sshd
  • 8710 — tgclient docker (0.0.0.0)

Notes

  • Обновление сервиса: cd /home/ubuntu/tgclient-mcp && git pull --ff-only && sudo docker compose up -d --build (docker только через sudo — ubuntu не в docker-группе; сборка ~1 мин; после pull проверить, что локальных незакоммиченных изменений нет: git status --short).
  • nginx-сайт на internal-proxy (.183): /etc/nginx/sites-available/tgclientmcp.gnexus.space (:80 + :443, client_max_body_size 32m, на /mcp-protocol/ proxy_buffering off + proxy_read_timeout 300s).