---
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-07"
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 (статический, назначен владельцем)
- **Hostname:** tgclientmcp
- **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 5cc14e3 (обновлено 2026-10-07 navi rei; история обновлений:
  2026-10-06 — edbd2e2 QR-вход, f4b1da9 фиксы логина, 0fc015e SPA-табы
  логин-визарда, ac8b764 SPA-фиксы; 2026-10-07 — e269bfb+5cc14e3
  MCP runtime-аудит; все — 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
  .226, отдельный LE-сертификат до 2027-01-03; upstream http://192.168.1.171:8710)
- **Endpoints:**
  - SPA: https://tgclientmcp.gnexus.space/ (200 text/html)
  - health: https://tgclientmcp.gnexus.space/api/v1/health →
    `{"status":"ok","version":"0.1.0","accounts":{...},"db":"ok"}`
  - MCP: https://tgclientmcp.gnexus.space/mcp-protocol/ (streamable HTTP,
    stateless + json_response; initialize без токена → 200 с serverInfo
    tgclient; тулы требуют Bearer `mcp_*` или admin-токен)
- **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 прошёл успешно.
- Клиент пула подключается лениво при первом использовании — 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 терминируется на .226) — это осознанное решение из кода репо.
- Подключение агента: `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 не менялся.

## Интеграция с 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_API_KEY=syn_…0b7b,
  **TGCLIENT_SYNAPSE_DEFAULT_SOURCE=tgclient** (ВАЖНО: имя источника в
  Synapse — `tgclient`, а не `tgclient-mcp`; с дефолтом из .env.example
  Synapse отвечает 403 «Поле source не совпадает с источником ключа»),
  TGCLIENT_SYNAPSE_TIMEOUT=10. Бэкап: .env.bak-synapse-20261007.
- Пуш-события сообщений выключены по умолчанию: TGCLIENT_NOTIFY_MESSAGES=1
  включает message/received|edited|deleted (не включено — решение за
  владельцем).
- E2E проверено 2026-10-07: POST /api/v1/events с syn_-ключом с .171 → 202,
  событие done в Synapse (c9837953). Доставок нет — правила маршрутизации
  настраиваются в фазе 2 (s2s-цель navi-rei).

## 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).

## Pending

- TGCLIENT_ADMIN_TOKEN пуст — статический супер-токен для скриптов (роль
  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-сайт на .226: /etc/nginx/sites-available/tgclientmcp.gnexus.space
  (:80 + :443, client_max_body_size 32m, на /mcp-protocol/ proxy_buffering
  off + proxy_read_timeout 300s).
