docs: tighten account-check and reconnect wording

Author: vsem-azamat

.env.example

@@ -51,10 +51,7 @@ TELEGRAM_SESSION_NAME=telegram_session
 # TELEGRAM_APP_VERSION=1.0
 
 # --- Expected account check (optional) ---
-# Refuse to start if the session is logged in to a different Telegram account
-# than expected (compared with get_me().username, case-insensitive, '@'
-# optional). Per-account values use the same _<LABEL> suffix as the session
-# variables and override the unsuffixed one. Unset = no check.
+# Refuse to start if the session belongs to another account. _<LABEL> overrides.
 # TELEGRAM_EXPECTED_USERNAME=my_username
 # TELEGRAM_EXPECTED_USERNAME_WORK=my_work_username
 

README.md

@@ -570,30 +570,7 @@ every connect), so set them in the same place as your other credentials.
 
 ## Expected Account Check
 
-Optionally pin each session to the Telegram account it is supposed to belong to.
-When set, the server calls `get_me()` right after connecting and compares the
-account's username (case-insensitive, leading `@` optional, active collectible
-usernames included) with the configured value. On a mismatch, or if the account
-has no username, it disconnects and refuses to start, so a swapped or
-mislabelled session string cannot silently act as the wrong person:
-
-```env
-TELEGRAM_EXPECTED_USERNAME=my_username
-```
-
-In multi-account setups use the same `_<LABEL>` suffix as the session variables;
-a suffixed value overrides the unsuffixed one for that account:
-
-```env
-TELEGRAM_SESSION_STRING_WORK=session_string_for_work
-TELEGRAM_SESSION_STRING_PERSONAL=session_string_for_personal
-TELEGRAM_EXPECTED_USERNAME_WORK=my_work_username
-TELEGRAM_EXPECTED_USERNAME_PERSONAL=my_personal_username
-```
-
-An unsuffixed `TELEGRAM_EXPECTED_USERNAME` applies to every account that has no
-suffixed value. When neither is set (the default) no check is made and no extra
-request is sent.
+Set `TELEGRAM_EXPECTED_USERNAME` (or `TELEGRAM_EXPECTED_USERNAME_<LABEL>` per account) and the server refuses to start when the session belongs to a different account. The comparison is case-insensitive and ignores a leading `@`. Unset means no check.
 
 ## Proxy Support
 
@@ -867,10 +844,8 @@ Telegram messages, display names, chat titles, and button labels are untrusted c
   the MCP server when you can scan from an existing Telegram app, or
   `uv run session_string_generator.py --phone` when you need phone-code login.
   Then set `TELEGRAM_SESSION_STRING` in `.env`. The MCP server does not perform
-  interactive phone-code login over stdio. This also applies when a session is
-  terminated (for example from **Settings > Devices** on another device) while the
-  server is running: the next reconnect fails with "not authorized after reconnect"
-  instead of prompting for a phone number. Re-authorize as above and restart the server.
+  interactive phone-code login over stdio, including after a reconnect: a session
+  terminated while the server runs fails with "not authorized after reconnect".
 - **Invalid API credentials:** verify `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` at [my.telegram.org/apps](https://my.telegram.org/apps).
 - **Database is locked:** make sure no other process is using the same file session.
 - **`AuthKeyDuplicatedError` / "Another telegram-mcp process is already connected with this session":** two processes tried to connect the same Telegram session at once (e.g. an MCP client restarted the connector before the old process exited), which Telegram rejects and can invalidate the session for both. The server now takes an exclusive lock per session before connecting; a second concurrent launch waits briefly (default 20s, override with `TELEGRAM_LOCK_GRACE_SECONDS`) for the first to release it and otherwise exits without ever calling `connect()`, instead of racing into a duplicate connection. Retry once only one instance is running — the refusal names the PID holding the lock. If several instances on this host are meant to share one session (all reaching Telegram from the same IP), set `TELEGRAM_SESSION_LOCK=shared`; see [Sharing one session from one host](#sharing-one-session-from-one-host).

telegram_mcp/runner.py

@@ -68,31 +68,21 @@ def _normalize_username(value) -> str:
 
 
 def _expected_username(label: str) -> str:
-    """``TELEGRAM_EXPECTED_USERNAME[_<LABEL>]``: the account a session must belong to.
-
-    The per-account ``_<LABEL>`` variable overrides the unsuffixed one, like the
-    ``TELEGRAM_PROXY_*`` variables. Returns ``""`` (no check) when neither is set.
-    """
+    """TELEGRAM_EXPECTED_USERNAME_<LABEL>, else TELEGRAM_EXPECTED_USERNAME; "" if unset."""
     raw = os.getenv(f"TELEGRAM_EXPECTED_USERNAME_{label.upper()}") or os.getenv(
         "TELEGRAM_EXPECTED_USERNAME"
     )
     return _normalize_username(raw)
 
 
 async def _verify_expected_username(label: str, client) -> None:
-    """Refuse to serve a session that is logged in to a different account.
-
-    Guards against a swapped or mislabelled session string (e.g. the personal
-    account's session configured under the work label), which would otherwise
-    let MCP clients read and send messages as the wrong person.
-    """
+    """Refuse to serve a session logged in to a different account."""
     expected = _expected_username(label)
     if not expected:
         return
 
     me = await client.get_me()
     usernames = {_normalize_username(getattr(me, "username", None))}
-    # Accounts with collectible usernames list the extra ones in `usernames`.
     for entry in getattr(me, "usernames", None) or []:
         if getattr(entry, "active", False):
             usernames.add(_normalize_username(getattr(entry, "username", None)))
@@ -107,9 +97,7 @@ async def _verify_expected_username(label: str, client) -> None:
         pass
     raise RuntimeError(
         f"Telegram client '{label}' is logged in to a different account than "
-        f"TELEGRAM_EXPECTED_USERNAME_{label.upper()} / TELEGRAM_EXPECTED_USERNAME "
-        "expects. Refusing to start; check which session string or session file is "
-        "configured for this account."
+        f"TELEGRAM_EXPECTED_USERNAME_{label.upper()} / TELEGRAM_EXPECTED_USERNAME expects."
     )
 
 

telegram_mcp/runtime.py

@@ -813,23 +813,15 @@ async def _force_reconnect(cl: TelegramClient):
             f"Reconnecting to Telegram timed out after {_RECONNECT_TIMEOUT:.0f}s."
         ) from exc
     if not await cl.is_user_authorized():
-        # The session was revoked or logged out while the server was running.
-        # Never fall back to cl.start(): its phone/code prompts call input()
-        # synchronously, which blocks the event loop (asyncio.wait_for cannot
-        # cancel it) and, over the stdio transport, reads MCP protocol frames
-        # as a phone number. Startup already refuses interactive login for the
-        # same reason (see runner._connect_authorized_client).
+        # cl.start() would prompt via blocking input(): it stalls the event loop
+        # and, over stdio, reads protocol frames as a phone number.
         try:
             await cl.disconnect()
         except Exception:
             pass
         raise RuntimeError(
-            "Telegram session is not authorized after reconnect (it may have been "
-            "terminated from another device or logged out). Interactive login is "
-            "disabled inside the MCP server. Re-authorize outside the server with "
-            "`uv run session_string_generator.py`, update TELEGRAM_SESSION_STRING "
-            "or TELEGRAM_SESSION_STRING_<LABEL> (or log the file session in again), "
-            "then restart the server."
+            "Telegram session is not authorized after reconnect. Re-authorize it "
+            "outside the server (session_string_generator.py) and restart."
         )
     _last_conn_verified[id(cl)] = time.time()
     reconnect_logger.warning("Forced reconnect successful")

tests/test_runtime.py

@@ -575,7 +575,7 @@ async def test_ensure_connected_surfaces_revoked_session(monkeypatch):
     client = _ConnectivityClient(connected=False, authorized=False)
     monkeypatch.setattr(runtime, "_last_conn_verified", {})
 
-    with pytest.raises(RuntimeError, match="Interactive login is disabled"):
+    with pytest.raises(RuntimeError, match="not authorized after reconnect"):
         await runtime.ensure_connected(client)
 
     assert "start" not in client.calls