agent-log-viewer 1.0.0 → 1.0.1

package/vendor/telegram-mcp/telegram_mcp/install_guard.py

@@ -0,0 +1,209 @@
+"""Installation provenance checks for the Telegram MCP server.
+
+The PyPI distribution name ``telegram-mcp`` is currently occupied by an
+unrelated project. This guard can only protect executions that reach this
+repository's code; it cannot run when a user launches the third-party package.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+DISTRIBUTION_NAME = "telegram-mcp"
+
+
+class UnsafeInstallationError(RuntimeError):
+    """Raised when installed package metadata points at the wrong project."""
+
+
+@dataclass(frozen=True)
+class DistributionIdentity:
+    """Small, testable view of Python package metadata."""
+
+    name: str
+    version: str
+    authors: tuple[str, ...] = ()
+    maintainers: tuple[str, ...] = ()
+    urls: tuple[str, ...] = ()
+    summary: str = ""
+    direct_url: str = ""
+    source_root: Path | None = None
+
+    @classmethod
+    def from_distribution(cls, dist: metadata.Distribution) -> "DistributionIdentity":
+        package_metadata = dist.metadata
+        urls = tuple(package_metadata.get_all("Project-URL") or ())
+        homepage = package_metadata.get("Home-page")
+        if homepage:
+            urls += (homepage,)
+
+        authors = tuple(
+            value
+            for value in (
+                package_metadata.get("Author"),
+                package_metadata.get("Author-email"),
+            )
+            if value
+        )
+        maintainers = tuple(
+            value
+            for value in (
+                package_metadata.get("Maintainer"),
+                package_metadata.get("Maintainer-email"),
+            )
+            if value
+        )
+
+        read_text = getattr(dist, "read_text", None)
+        direct_url = read_text("direct_url.json") if callable(read_text) else ""
+
+        return cls(
+            name=package_metadata.get("Name") or getattr(dist, "name", DISTRIBUTION_NAME),
+            version=package_metadata.get("Version") or dist.version,
+            authors=authors,
+            maintainers=maintainers,
+            urls=urls,
+            summary=package_metadata.get("Summary", ""),
+            direct_url=direct_url or "",
+            source_root=_distribution_source_root(dist),
+        )
+
+
+def _project_root_declares_distribution_name(path: Path) -> bool:
+    pyproject_path = path / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return False
+
+    try:
+        pyproject_text = pyproject_path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+
+    return f'name = "{DISTRIBUTION_NAME}"' in pyproject_text
+
+
+def _resolve_path(path: Path) -> Path:
+    try:
+        return path.resolve()
+    except OSError:
+        return path
+
+
+def _candidate_is_project_root(path: Path) -> bool:
+    return _project_root_declares_distribution_name(_resolve_path(path))
+
+
+def _distribution_source_root(dist: metadata.Distribution) -> Path | None:
+    """Return an editable/source-checkout root for installer metadata.
+
+    ``uv sync`` installs the project editably. In that mode ``importlib.metadata``
+    can resolve the active distribution to ``telegram_mcp.egg-info`` in the
+    checkout, while the PEP 610 ``direct_url.json`` file lives in the
+    environment's ``.dist-info`` directory. Treating the adjacent project root as
+    source provenance keeps the PyPI-collision guard strict for normal installs
+    without blocking cloned checkouts.
+    """
+
+    dist_path = getattr(dist, "_path", None)
+    if dist_path is not None:
+        metadata_path = Path(dist_path)
+        if metadata_path.name.endswith(".egg-info"):
+            candidate = metadata_path.parent
+            if _candidate_is_project_root(candidate):
+                return _resolve_path(candidate)
+
+    files = getattr(dist, "files", None)
+    locate_file = getattr(dist, "locate_file", None)
+    if not files or not callable(locate_file):
+        return None
+
+    for package_file in files:
+        if Path(str(package_file)) != Path("pyproject.toml"):
+            continue
+
+        candidate = Path(locate_file(package_file)).parent
+        if _candidate_is_project_root(candidate):
+            return _resolve_path(candidate)
+
+    return None
+
+
+def _direct_url_json(direct_url: str) -> dict:
+    if not direct_url:
+        return {}
+
+    try:
+        direct_url_data = json.loads(direct_url)
+    except json.JSONDecodeError:
+        return {}
+
+    return direct_url_data if isinstance(direct_url_data, dict) else {}
+
+
+def _direct_url_is_explicit_source_install(direct_url: str) -> bool:
+    direct_url_data = _direct_url_json(direct_url)
+    if not direct_url_data:
+        return False
+
+    raw_url = str(direct_url_data.get("url", "")).strip()
+    if not raw_url:
+        return False
+
+    parsed_url = urlparse(raw_url)
+
+    if parsed_url.scheme == "file":
+        source_path = Path(unquote(parsed_url.path)).resolve()
+        return _project_root_declares_distribution_name(source_path)
+
+    vcs_info = direct_url_data.get("vcs_info")
+    return isinstance(vcs_info, dict) and bool(vcs_info.get("vcs"))
+
+
+def _looks_like_explicit_source_install(identity: DistributionIdentity) -> bool:
+    return (
+        _direct_url_is_explicit_source_install(identity.direct_url)
+        or identity.source_root is not None
+    )
+
+
+def _format_unsafe_installation_message(identity: DistributionIdentity) -> str:
+    authors = ", ".join(identity.authors) or "unknown"
+    maintainers = ", ".join(identity.maintainers) or "unknown"
+    urls = "; ".join(identity.urls) or "unknown"
+
+    return (
+        "Refusing to start: the installed 'telegram-mcp' distribution was not "
+        "installed from an explicit source checkout.\n"
+        f"Detected distribution: name={identity.name!r}, version={identity.version!r}, "
+        f"authors={authors!r}, maintainers={maintainers!r}, urls={urls!r}.\n"
+        "The 'telegram-mcp' name on PyPI is currently owned by a different project. "
+        "This guard requires a source checkout or installer-recorded direct "
+        "git/file URL. Run this server from a cloned checkout or install a "
+        "trusted repository explicitly with: "
+        'pip install "git+https://github.com/chigwell/telegram-mcp.git"'
+    )
+
+
+def assert_safe_distribution(distribution_name: str = DISTRIBUTION_NAME) -> None:
+    """Abort when the installed distribution metadata is not this project.
+
+    Source checkouts that have not been installed as a distribution are allowed:
+    ``uv --directory /path/to/telegram-mcp run main.py`` can run from source
+    without package metadata. If metadata for ``telegram-mcp`` is present, it
+    must come from an explicit git or file install recorded by the installer.
+    """
+
+    try:
+        dist = metadata.distribution(distribution_name)
+    except metadata.PackageNotFoundError:
+        return
+
+    identity = DistributionIdentity.from_distribution(dist)
+    if _looks_like_explicit_source_install(identity):
+        return
+
+    raise UnsafeInstallationError(_format_unsafe_installation_message(identity))

package/vendor/telegram-mcp/telegram_mcp/runner.py

@@ -0,0 +1,198 @@
+"""Application entrypoints for the Telegram MCP server."""
+
+from telegram_mcp.install_guard import UnsafeInstallationError, assert_safe_distribution
+
+try:
+    assert_safe_distribution()
+except UnsafeInstallationError as exc:
+    raise SystemExit(str(exc)) from None
+
+from telethon.errors import AuthKeyDuplicatedError
+
+from telegram_mcp import runtime as _runtime
+from telegram_mcp.runtime import *
+from telegram_mcp.singleton import (
+    DEFAULT_GRACE_SECONDS,
+    SessionLock,
+    SessionLockError,
+    session_identity,
+)
+import telegram_mcp.tools  # noqa: F401 - registers MCP tools via decorators
+
+# Populated as each account's session lock is acquired; released in _main's
+# finally block so a lock is never held past this process's lifetime.
+_session_locks: dict[str, SessionLock] = {}
+
+
+def _lock_grace_seconds() -> float:
+    raw = os.getenv("TELEGRAM_LOCK_GRACE_SECONDS")
+    if not raw:
+        return DEFAULT_GRACE_SECONDS
+    try:
+        return float(raw)
+    except ValueError:
+        return DEFAULT_GRACE_SECONDS
+
+
+async def _connect_authorized_client(label, client) -> None:
+    # First, prevent our own duplicate-spawn case outright: an exclusive
+    # per-session lock means a second instance of this server never even
+    # attempts to connect while another instance already holds the same
+    # session (see telegram_mcp/singleton.py for why and how).
+    lock = SessionLock(label, session_identity(client))
+    await asyncio.to_thread(lock.acquire, grace_seconds=_lock_grace_seconds())
+    _session_locks[label] = lock
+
+    # Once we hold the lock, still tolerate a transient AuthKeyDuplicatedError
+    # from Telegram itself (e.g. the same session briefly seen from two IPs
+    # during a VPN reconnect) with a bounded retry, since that's not caused by
+    # a second instance of this server and a blip shouldn't take the server
+    # down. Give each concurrent client its own session (TELEGRAM_SESSION_STRINGS
+    # pool or TELEGRAM_SESSION_STRING_<LABEL>) to avoid the collision entirely.
+    max_attempts = 4
+    for attempt in range(1, max_attempts + 1):
+        try:
+            await client.connect()
+            break
+        except AuthKeyDuplicatedError:
+            if attempt >= max_attempts:
+                raise
+            delay = min(2**attempt, 15)
+            print(
+                f"AuthKeyDuplicatedError connecting '{label}' (attempt "
+                f"{attempt}/{max_attempts}): session in use from another IP. "
+                f"Retrying in {delay}s. If this persists, give each concurrent "
+                "client its own session via TELEGRAM_SESSION_STRINGS or "
+                "TELEGRAM_SESSION_STRING_<LABEL>.",
+                file=sys.stderr,
+            )
+            try:
+                await client.disconnect()
+            except Exception:
+                pass
+            await asyncio.sleep(delay)
+
+    if await client.is_user_authorized():
+        return
+
+    raise RuntimeError(
+        f"Telegram client '{label}' is not authorized. Interactive phone login "
+        "is disabled for the MCP server because it runs over stdio. Generate a "
+        "session string with `uv run session_string_generator.py`, then set "
+        "TELEGRAM_SESSION_STRING or TELEGRAM_SESSION_STRING_<LABEL> in .env. "
+        "For existing file sessions, run the login outside the MCP server first."
+    )
+
+
+def _configure_transport_security() -> None:
+    """Wire MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS into FastMCP's DNS-rebinding
+    protection, e.g. when the server sits behind a reverse proxy on a public
+    domain instead of only being reached via 127.0.0.1/localhost.
+    """
+    raw_hosts = os.getenv("MCP_ALLOWED_HOSTS", "")
+    allowed_hosts = [h.strip() for h in raw_hosts.split(",") if h.strip()]
+    if not allowed_hosts:
+        return
+
+    from mcp.server.transport_security import TransportSecuritySettings
+
+    raw_origins = os.getenv("MCP_ALLOWED_ORIGINS", "")
+    allowed_origins = [o.strip() for o in raw_origins.split(",") if o.strip()]
+
+    mcp.settings.transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=allowed_hosts,
+        allowed_origins=allowed_origins,
+    )
+
+
+async def _serve(transport: str) -> None:
+    """Run the MCP server on the selected transport.
+
+    HTTP transports let one long-lived process hold a single shared Telegram
+    connection while multiple local MCP clients connect over HTTP, instead of
+    each client spawning its own Telethon session (which Telegram
+    throttles/flags). "http" is streamable HTTP — the current MCP transport
+    that Claude Code (`--transport http`) and Codex (`--url`) speak natively;
+    "sse" is kept for clients that only support the legacy SSE transport.
+    """
+    if transport in ("http", "sse"):
+        mcp.settings.host = os.getenv("MCP_HOST", "127.0.0.1")
+        mcp.settings.port = int(os.getenv("MCP_PORT", "8765"))
+        _configure_transport_security()
+        if transport == "http":
+            await mcp.run_streamable_http_async()
+        else:
+            await mcp.run_sse_async()
+    else:
+        # Use the asynchronous entrypoint instead of mcp.run()
+        await mcp.run_stdio_async()
+
+
+async def _main() -> None:
+    try:
+        labels = ", ".join(clients.keys())
+        print(f"Starting {len(clients)} Telegram client(s) ({labels})...", file=sys.stderr)
+        await asyncio.gather(
+            *(_connect_authorized_client(label, cl) for label, cl in clients.items())
+        )
+
+        # Warm entity caches — StringSession has no persistent cache,
+        # so fetch all dialogs once per client to populate them.
+        # Runs in background: blocking startup on this (e.g. under a
+        # GetDialogsRequest flood wait) makes MCP clients time out, and
+        # resolve_entity() re-warms the cache on miss anyway.
+        print("Warming entity caches (background)...", file=sys.stderr)
+
+        async def _warm_caches() -> None:
+            try:
+                await asyncio.gather(*(cl.get_dialogs() for cl in clients.values()))
+                print("Entity caches warmed.", file=sys.stderr)
+            except Exception as warm_exc:
+                print(f"Entity cache warm failed: {warm_exc}", file=sys.stderr)
+
+        warm_task = asyncio.create_task(_warm_caches())
+
+        transport = os.getenv("MCP_TRANSPORT", "stdio").lower()
+        print(
+            f"Telegram client(s) started ({labels}). Running MCP server ({transport})...",
+            file=sys.stderr,
+        )
+        await _serve(transport)
+    except Exception as e:
+        print(f"Error starting client: {e}", file=sys.stderr)
+        if isinstance(e, sqlite3.OperationalError) and "database is locked" in str(e):
+            print(
+                "Database lock detected. Please ensure no other instances are running.",
+                file=sys.stderr,
+            )
+        elif isinstance(e, SessionLockError):
+            print(
+                "Another instance of this MCP server already holds this Telegram "
+                "session (e.g. the client restarted the connector without the old "
+                "process exiting yet). This instance is exiting instead of "
+                "connecting a second time, which would risk Telegram invalidating "
+                "the session for both. Retry once the other instance is gone.",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+    finally:
+        try:
+            await asyncio.gather(
+                *(cl.disconnect() for cl in clients.values()), return_exceptions=True
+            )
+        except Exception:
+            pass
+        for lock in _session_locks.values():
+            lock.release()
+        _session_locks.clear()
+
+
+def main() -> None:
+    _configure_allowed_roots_from_cli(sys.argv[1:])
+    _runtime._apply_exposed_tools_mode()
+    asyncio.run(_main())
+
+
+if __name__ == "__main__":
+    main()