fix: report MTProto schema drift instead of a generic error code

When the server sends an object whose constructor the installed Telethon
schema does not know, Telethon raises TypeNotFoundError. Today that is
swallowed by log_and_format_error and surfaces as

    An error occurred (code: CHAT-ERR-418). Check mcp_errors.log for details.

which is indistinguishable from "no such user/chat".

That confusion is expensive, because schema drift does not fail cleanly:
an unknown constructor desynchronises the whole read buffer, so only some
calls break while their neighbours keep working. In our case list_chats,
get_common_chats, resolve_username and get_full_user were failing while
get_chats, search_contacts, list_messages and send_message were fine —
which reads exactly like "that user does not exist". The reported
constructor id is often garbage from the desynchronised stream and appears
in no schema at all, so searching for it leads nowhere too.

This names the condition, states that the data did arrive and only parsing
failed, and points at the fix. Every other error keeps the existing format.

Tested: both branches covered; the new test was run against a sabotaged
implementation first and fails there, so it can actually catch a regression.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: artgas1

telegram_mcp/runtime.py

@@ -732,9 +732,31 @@ def log_and_format_error(
     if user_message:
         return user_message
 
+    # MTProto schema drift must not hide behind the generic code. Telethon releases lag
+    # behind production Telegram, and when the server sends an object whose constructor
+    # the installed schema does not know, the read buffer desynchronises: some tools fail
+    # while their neighbours keep working. Reported as a generic error, that pattern is
+    # indistinguishable from "no such user/chat" and sends debugging the wrong way.
+    if _is_schema_drift(error):
+        return (
+            f"MTProto schema mismatch: the installed Telethon does not know an object the "
+            f"server sent ({error}). This is NOT a missing user or chat — the data arrived, "
+            f"parsing it failed. Upgrade Telethon; if it is already the latest release, its "
+            f"schema is behind the current layer (code: {error_code})."
+        )
+
     return f"An error occurred (code: {error_code}). Check mcp_errors.log for details."
 
 
+def _is_schema_drift(error: Exception) -> bool:
+    """True for TypeNotFoundError — the installed TL schema is older than what the server sends."""
+    try:
+        from telethon.errors.common import TypeNotFoundError
+    except Exception:  # telethon missing or moved — not this helper's problem
+        return False
+    return isinstance(error, TypeNotFoundError)
+
+
 def validate_id(*param_names_to_validate):
     """
     Decorator to validate chat_id and user_id parameters, including lists of IDs.

tests/test_schema_drift.py

@@ -0,0 +1,21 @@
+"""Schema drift must be reported as such, not as a generic error code.
+
+A `TypeNotFoundError` means the installed TL schema is older than what the server
+sends. Hidden behind the generic message, it reads like "no such user/chat" and
+costs hours of debugging in the wrong direction.
+"""
+
+from telegram_mcp.runtime import log_and_format_error
+from telethon.errors.common import TypeNotFoundError
+
+
+def test_schema_drift_is_named_and_actionable():
+    msg = log_and_format_error("list_chats", TypeNotFoundError(0xD58A08C6, b"\x00"))
+    assert "MTProto schema mismatch" in msg
+    assert "NOT a missing user or chat" in msg
+
+
+def test_ordinary_error_keeps_the_generic_format():
+    msg = log_and_format_error("get_chat", ValueError("boom"))
+    assert "code:" in msg
+    assert "MTProto schema mismatch" not in msg