diff --git a/10-systems/hosts/tgclientmcp.md b/10-systems/hosts/tgclientmcp.md new file mode 100644 index 0000000..367c8d0 --- /dev/null +++ b/10-systems/hosts/tgclientmcp.md @@ -0,0 +1,93 @@ +--- +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-05" +review_interval: "90d" +source_of_truth: "ssh-host-and-owner-confirmed" +--- + +# VPS tgclientmcp (tgclient-mcp) + +## Overview + +Home LAN VPS (KVM/QEMU guest, MAC 52:54:00:xx — из того же libvirt-пула, что и +остальные VM). Выделен владельцем 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) + +- **Repo:** /home/ubuntu/tgclient-mcp + (https://git.gnexus.space/git/root/tgclient-mcp.git), branch `master`, + HEAD 4b5e242 +- **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 +- **Endpoints:** + - SPA: http://192.168.1.171:8710/ (200 text/html) + - health: http://192.168.1.171:8710/api/v1/health → + `{"status":"ok","version":"0.1.0","accounts":{...},"db":"ok"}` + - MCP: http://192.168.1.171:8710/mcp-protocol/ (streamable HTTP; GET без + MCP-заголовков → 406 — норма) +- **Config:** /home/ubuntu/tgclient-mcp/.env (chmod 600, из .env.example). + На момент деплоя НЕ заполнены (сервис работает, но добавление Telegram- + аккаунтов недоступно): TGCLIENT_API_ID/_API_HASH (my.telegram.org), + TGCLIENT_ADMIN_TOKEN, TGCLIENT_AUTH_* (SSO), TGCLIENT_SYNAPSE_*. + GOTCHA: `TGCLIENT_API_ID=` пустая строка ломает pydantic int — строку + закомментировали; при заполнении вписать число и раскомментировать. +- **Креды:** gnexus-creds secret "tgclient-mcp host SSH (192.168.1.171)". + +## Deploy fixes (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 ./`. + В git НЕ закоммичено — при `git pull` поверх может затереться; при + обновлении проверить строку COPY. +2. **backend/app/tg/manager.py:** `NameError: TelegramClient` — класс + используется в аннотациях, но не импортирован. Исправлено: + `from telethon import TelegramClient, errors`. В git НЕ закоммичено — + та же оговорка. + +Оба фикса стоит отправить в репозиторий (или дождаться апстрима). + +## SSO / MCP-ключи (pending) + +- SSO gnexus-auth не настроен (TGCLIENT_AUTH_CLIENT_ID пуст) — сервис + работает в открытом режиме: все акки уходят локальному служебному юзеру. +- Персональные MCP-ключи `mcp_*` выпускаются на странице «MCP-ключи» SPA + (plaintext показывается один раз). Статический TGCLIENT_ADMIN_TOKEN — + супер-бэкдор для скриптов (роль superadmin), пока пуст. +- Подключение агента: `claude mcp add --transport http tgclient + http://192.168.1.171:8710/mcp-protocol/ --header "Authorization: Bearer mcp_..."` + +## 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 && + docker compose up -d --build` (docker через sudo; сборка ~1 мин). +- Публичный URL (https://tgclient.gnexus.space через nginx на .226) — не + настроен, по согласованию с владельцем.