diff --git a/10-systems/applications/tgclient-mcp.md b/10-systems/applications/tgclient-mcp.md new file mode 100644 index 0000000..ae8702b --- /dev/null +++ b/10-systems/applications/tgclient-mcp.md @@ -0,0 +1,47 @@ +--- +owner: gmikcon +status: active +last_reviewed: 2026-11-14 +review_interval: 30d +confidence: high +source_of_truth: ssh-host-and-live-verified +--- + +# tgclient-mcp + +Multi-account Telegram user-client (Telethon) with an MCP server and a SPA admin panel. Lets Navi agents read and act on the owner's Telegram accounts through MCP tools instead of raw scripts. + +## Access + +- MCP endpoint: `https://tgclientmcp.gnexus.space/mcp` (streamable HTTP, `Authorization: Bearer mcp_*`; `/mcp-protocol/` is a legacy alias). +- SPA admin: `https://tgclientmcp.gnexus.space` (SSO via gnexus-auth). +- Health: `GET /api/v1/health`. +- Accounts: id 1 = sukhodolskiy (78389352, owner's main), id 2 = Navi (8781031814, dedicated agent account). +- Secrets: gnexus-creds secret «tgclient-mcp host SSH (192.168.1.171)»; MCP tokens are issued in the SPA admin (≤10 per user). +- NOTE (2026-11-14): the service is reachable via `tgclientmcp.gnexus.space`, but this hostname is absent from the domains inventory and from internal-nginx-proxy `proxy_mappings` — registration gap to close. + +## Infrastructure path + +`Internet -> external-vps -> OpenVPN tunnel -> internal-proxy-vps -> tgclientmcp VM (192.168.1.171:8710)` + +## Deployment + +- Host: `tgclientmcp` VM (see hosts inventory), LAN 192.168.1.171, SSH `ubuntu` (fleet password, also sudo via `sudo -S`). +- Repo on host: `/home/ubuntu/tgclient-mcp` (branch master); docker compose single service `tgclient`, container `tgclient-tgclient-1`, port 8710→8000, volume `data:/data` (SQLite WAL `tgclient.db`; accounts.session_data holds StringSession per account). +- Update: `cd /home/ubuntu/tgclient-mcp && sudo docker compose up -d --build`. +- Local fixes on host from 2026-10-05 (deployed, NOT committed upstream): `backend/Dockerfile` COPY of `frontend/package-lock.json`; `backend/app/tg/manager.py` missing `TelegramClient` import. Beware `git pull` overwriting them. + +## Media handling — big files + +- MCP tool `download_media` returns `data_base64` in the tool response and is capped by `TGCLIENT_MEDIA_MAX_BYTES` (default 20 MiB) — unsuitable for files >20 MB. +- Workaround used 2026-11-14 (624 MB .blend): run a script inside the container (Telethon + StringSession read from `/data/tgclient.db`) → `async for chunk in client.iter_download(...)` → write to `/data/` → `docker cp` to host `/tmp` → `sshpass scp` to the navi host; verify md5 on both ends. Full recipe: navi skill `tg-big-file-download`. +- Follow-ups tracked in gntodo project `tgclient-mcp` (id 29): task #543 — server-side MCP tools `download_media_to_disk` / `upload_file_from_disk`; task #544 — navi-side wrapper `tg_fetch_file`. + +## Gotchas + +- `client.get_messages(ids=[...])` returns a LIST — index `[0]`. +- `iter_download` inside `async def` must be consumed with `async for` (plain `for` raises RuntimeError). +- sudo on the host only via `echo '' | sudo -S`. +- Empty `TGCLIENT_API_ID=` breaks pydantic int parsing (keep the line commented out if unset). +- `ssh_exec` action=scp with a named connection currently fails («connect() got multiple values for argument 'host'») — use `sshpass` scp from a local terminal instead. +- Compose service name is `tgclient` (not `backend`) — `docker compose exec tgclient ...`. diff --git a/40-inventory/projects.yml b/40-inventory/projects.yml index a44a292..7428ed1 100644 --- a/40-inventory/projects.yml +++ b/40-inventory/projects.yml @@ -1,109 +1,130 @@ -# Software projects, repositories, external documentation, and deployment links. --- - id: gnexus-book name: Gnexus Book status: active type: documentation-system - description: Knowledge base and maintenance API for personal digital and server infrastructure. + description: Knowledge base and maintenance API for personal digital and server + infrastructure. repositories: - - name: gnexus-book - path: /home/gmikcon/Projects/gnexus-book - role: canonical-documentation-repository + - name: gnexus-book + path: /home/gmikcon/Projects/gnexus-book + role: canonical-documentation-repository documentation: - - label: Project implementation plan - path: ../00-overview/mvp-implementation-plan.md - role: planning - - label: Documentation rules - path: ../90-maintenance/documentation-rules.md - role: maintenance-policy + - label: Project implementation plan + path: ../00-overview/mvp-implementation-plan.md + role: planning + - label: Documentation rules + path: ../90-maintenance/documentation-rules.md + role: maintenance-policy related_services: [] related_hosts: - - internal-proxy-vps - - external-vps + - internal-proxy-vps + - external-vps related_domains: - - gnexus-space + - gnexus-space docs: ../10-systems/applications/gnexus-book.md last_reviewed: 2026-05-10 source_of_truth: repository - - id: gnexus-ui-kit name: Gnexus UI Kit status: active type: ui-library description: Official Gnexus UI kit and visual style foundation. repositories: - - name: gnexus-ui-kit - url: https://git.gnexus.space/root/gnexus-ui-kit - path: /home/gmikcon/Projects/gnexus-ui-kit - role: source-repository + - name: gnexus-ui-kit + url: https://git.gnexus.space/root/gnexus-ui-kit + path: /home/gmikcon/Projects/gnexus-ui-kit + role: source-repository documentation: - - label: UI kit docs - path: /home/gmikcon/Projects/gnexus-ui-kit/docs/index.md - role: upstream-docs + - label: UI kit docs + path: /home/gmikcon/Projects/gnexus-ui-kit/docs/index.md + role: upstream-docs related_services: [] related_hosts: [] related_domains: - - git-gnexus-space + - git-gnexus-space docs: ../10-systems/applications/gnexus-ui-kit.md last_reviewed: 2026-05-10 source_of_truth: owner-confirmed-and-local-repository - - id: smart-home-server-project name: Smart Home Server status: active type: smart-home-platform - description: Custom smart-home platform with PHP backend, web client, ESP device firmware, and ControlScripts automation layer. + description: Custom smart-home platform with PHP backend, web client, ESP device + firmware, and ControlScripts automation layer. repositories: - - name: smart-home-server - url: https://git.gnexus.space/git/root/smart-home-server.git - path: /home/shome/smart-home-server - role: deployed-source-repository - host: smart-home-server - branch: master - last_observed_commit: 4ef1bfa - last_observed_commit_summary: Fix resilient device state - working_tree_status: dirty - dirty_files: - - server/ControlScripts/Common.php - - server/ControlScripts/Scopes/LightHubScope.php - - webclient/config.php + - name: smart-home-server + url: https://git.gnexus.space/git/root/smart-home-server.git + path: /home/shome/smart-home-server + role: deployed-source-repository + host: smart-home-server + branch: master + last_observed_commit: 4ef1bfa + last_observed_commit_summary: Fix resilient device state + working_tree_status: dirty + dirty_files: + - server/ControlScripts/Common.php + - server/ControlScripts/Scopes/LightHubScope.php + - webclient/config.php documentation: - - label: Architecture - path: /home/shome/smart-home-server/docs/architecture.md - role: upstream-docs - - label: Device API spec - path: /home/shome/smart-home-server/docs/device-spec.md - role: upstream-docs - - label: Server API spec - path: /home/shome/smart-home-server/docs/server-spec.md - role: upstream-docs + - label: Architecture + path: /home/shome/smart-home-server/docs/architecture.md + role: upstream-docs + - label: Device API spec + path: /home/shome/smart-home-server/docs/device-spec.md + role: upstream-docs + - label: Server API spec + path: /home/shome/smart-home-server/docs/server-spec.md + role: upstream-docs related_services: - - smart-home-platform + - smart-home-platform related_hosts: - - smart-home-server + - smart-home-server related_domains: [] docs: ../10-systems/automations/smart-home-overview.md last_reviewed: 2026-05-10 source_of_truth: ssh-host-and-repository - - id: gitbucket-repository-catalog name: GitBucket Repository Catalog status: active type: repository-catalog - description: Catalog of repositories visible to the root account on the GitBucket instance at git.gnexus.space. + description: Catalog of repositories visible to the root account on the GitBucket + instance at git.gnexus.space. source_service: gitbucket repository_count_observed: 65 repository_owner: root documentation: - - label: GitBucket overview and repository catalog - path: ../10-systems/applications/gitbucket.md - role: repository-catalog + - label: GitBucket overview and repository catalog + path: ../10-systems/applications/gitbucket.md + role: repository-catalog related_services: - - gitbucket + - gitbucket related_hosts: - - gitbucket + - gitbucket related_domains: - - git-gnexus-space + - git-gnexus-space docs: ../10-systems/applications/gitbucket.md last_reviewed: 2026-05-10 source_of_truth: gitbucket-api +- id: tgclient-mcp + description: Multi-account Telegram user-client (Telethon) + MCP server + SPA admin. + Lets Navi agents read and act on the owner's Telegram accounts via MCP tools. + Deployed on tgclientmcp VM 192.168.1.171, port 8710. + docs: ../10-systems/applications/tgclient-mcp.md + documentation: + - label: Application doc + path: ../10-systems/applications/tgclient-mcp.md + role: upstream-docs + last_reviewed: '2026-11-14' + name: tgclient-mcp + related_hosts: + - tgclientmcp + related_services: + - tgclient-mcp + repositories: + - name: tgclient-mcp + path: /home/ubuntu/tgclient-mcp + role: deployed-source-repository + url: https://git.gnexus.space/root/tgclient-mcp + status: active + type: telegram-mcp-client diff --git a/40-inventory/services.yml b/40-inventory/services.yml index 5394cc1..cd0a7f8 100644 --- a/40-inventory/services.yml +++ b/40-inventory/services.yml @@ -242,14 +242,19 @@ web SPA) in /srv/gntodo on gntasks host. SSO via gnexus-auth (OAuth + signed webhook), per-user MCP tokens (Settings → MCP tokens), multi-tenant since ac8aefb (ТЗ 0.34). MCP endpoint https://tasks.gnexus.space/mcp/ (streamable HTTP, Bearer per-user - token).' + token). Browser extension (MV3, ТЗ 0.42+): ZIP built inside web image (frontend/Dockerfile + multi-stage), served at https://tasks.gnexus.space/extension/gntodo-extension.zip, + instruction page /extension. Deploy: cd /srv/gntodo && sudo docker compose up + -d --build (repo owned by root, sudo -S with owner password). Daily automated + backups since 2026-10-09: /usr/local/bin/gntodo-backup.sh (pg_dump + attachments + volume tar), root cron 30 3 * * * (UTC), rotation keeps newest 10, log /var/log/gntodo-backup.log.' docs: ../10-systems/hosts/gntasks.md domains: - tasks-gnexus-space health_endpoint: /api/health host: gntasks internal_upstream: http://192.168.1.179:8135 - last_reviewed: '2026-09-22' + last_reviewed: '2026-10-09' name: GNexus Tasks (gntodo) ports: - 8135 @@ -260,3 +265,28 @@ tls: terminates on internal-proxy-vps (.226), separate Let's Encrypt certificate CN=tasks.gnexus.space (expires 2026-12-20) type: web-app +- id: tgclient-mcp + active_services: + - tgclient-mcp-docker-compose + criticality: medium + description: 'tgclient-mcp: multi-account Telegram user-client (Telethon) + MCP + server (/mcp, streamable HTTP, Bearer mcp_*) + SPA admin (SSO). Docker compose + single service tgclient, port 8710->8000, volume data:/data (SQLite WAL). Accounts: + id 1 sukhodolskiy, id 2 Navi. Big files: download_media returns base64 and is + capped at 20 MiB; disk-side download is a manual container-script workaround until + gntodo #543/#544 are implemented.' + docs: ../10-systems/applications/tgclient-mcp.md + domains: + - tgclientmcp-gnexus-space + health_endpoint: /api/v1/health + host: tgclientmcp + internal_upstream: http://192.168.1.171:8710 + last_reviewed: '2026-11-14' + name: tgclient-mcp + owner: gmikcon + ports: + - 8710 + purpose: MCP interface to the owner's Telegram accounts for Navi agents + source_of_truth: ssh-host-and-live-verified + status: active + type: telegram-client-mcp