agent-log-viewer 1.0.0 → 1.0.1

package/vendor/telegram-mcp/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telegram-mcp"
+version = "2.0.1"
+description = "Telegram integration for Claude via the Model Context Protocol"
+readme = "README.md"
+authors = [
+    {name = "chigwell"},
+    {name = "l1v0n1"}
+]
+license = {text = "Apache-2.0"}
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12"
+]
+requires-python = ">=3.10"
+dependencies = [
+    "dotenv>=0.9.9",
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.8.0,<2",
+    "python-dotenv>=1.1.0",
+    "python-json-logger>=3.3.0",
+    "qrcode>=8.2",
+    "telethon>=1.44.0",
+]
+
+[project.optional-dependencies]
+# Required only when TELEGRAM_PROXY_TYPE is set to socks5/socks4/http.
+proxy = [
+    "python-socks>=2.4.3",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/chigwell/telegram-mcp"
+"Bug Tracker" = "https://github.com/chigwell/telegram-mcp/issues"
+
+[tool.setuptools]
+py-modules = ["main", "sanitize", "session_string_generator"]
+packages = ["telegram_mcp", "telegram_mcp.tools"]
+
+[project.scripts]
+telegram-mcp = "main:main"
+telegram-mcp-generate-session = "session_string_generator:main"
+
+[tool.black]
+line-length = 99
+target-version = ['py311']
+
+[tool.flake8]
+ignore = ["E203", "E501", "W503"]
+max-line-length = 99
+max-complexity = 10
+exclude = [
+    ".git",
+    "__pycache__",
+    ".venv",
+    "build",
+    "dist",
+    "docs/source/conf.py",
+]
+
+[dependency-groups]
+dev = [
+    "black>=25.9.0",
+    "flake8>=7.3.0",
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.coverage.run]
+branch = true
+# Unit coverage focuses on deterministic local logic. The Telegram tool modules
+# are live API adapters and should get separate mocked or integration coverage.
+source = [
+    "main",
+    "sanitize",
+    "telegram_mcp.runtime",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 80

package/vendor/telegram-mcp/requirements.txt

@@ -0,0 +1,7 @@
+dotenv>=0.9.9
+httpx>=0.28.1
+mcp[cli]>=1.8.0,<2
+python-dotenv>=1.1.0
+python-json-logger>=3.3.0
+qrcode>=8.2
+telethon>=1.44.0

package/vendor/telegram-mcp/sanitize.py

@@ -0,0 +1,143 @@
+"""
+Sanitization utilities for telegram-mcp.
+
+All user-controlled content (message text, display names, chat titles,
+button labels, etc.) returned in MCP tool results MUST be sanitized
+before inclusion. This prevents prompt injection attacks where malicious
+Telegram content could manipulate the LLM consuming these tool results.
+
+Defence strategy:
+1. Structural boundary — tool results use JSON, so user content sits
+   inside JSON string values and cannot be confused with field names
+   or tool-level instructions.
+2. Content sanitization (this module) — strips control characters,
+   zero-width characters, and truncates excessively long content as
+   defence-in-depth inside JSON values.
+"""
+
+import json
+import re
+import unicodedata
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+# Zero-width and invisible Unicode characters that can be used to hide content
+_INVISIBLE_CHARS = re.compile(
+    "["
+    "\u200b"  # zero width space
+    "\u200c"  # zero width non-joiner
+    "\u200d"  # zero width joiner
+    "\u200e"  # left-to-right mark
+    "\u200f"  # right-to-left mark
+    "\u2028"  # line separator
+    "\u2029"  # paragraph separator
+    "\u202a-\u202e"  # bidi embedding/override
+    "\u2060"  # word joiner
+    "\u2061-\u2064"  # invisible operators
+    "\ufeff"  # zero width no-break space / BOM
+    "\ufff9-\ufffb"  # interlinear annotations
+    "]"
+)
+
+# Three or more consecutive newlines → collapse to two
+_EXCESSIVE_NEWLINES = re.compile(r"\n{3,}")
+
+
+def sanitize_user_content(text: Optional[str], max_length: int = 4096) -> str:
+    """Sanitize user-controlled text content before returning in tool results.
+
+    - Returns "[empty]" for None / empty input
+    - Strips Unicode control characters (Cc, Cf) except newline and tab
+    - Strips zero-width / invisible characters
+    - Collapses excessive consecutive newlines (>2) to 2
+    - Truncates to max_length with a marker
+
+    This does NOT attempt keyword-based injection detection (too brittle).
+    The real defence is the structural JSON boundary in tool results.
+    """
+    if not text:
+        return "[empty]"
+
+    # Strip control characters except \n (0x0a) and \t (0x09)
+    cleaned = []
+    for ch in text:
+        cat = unicodedata.category(ch)
+        if cat in ("Cc", "Cf"):
+            if ch in ("\n", "\t"):
+                cleaned.append(ch)
+            # else: drop the character
+        else:
+            cleaned.append(ch)
+    result = "".join(cleaned)
+
+    # Strip invisible / zero-width characters
+    result = _INVISIBLE_CHARS.sub("", result)
+
+    # Collapse excessive newlines
+    result = _EXCESSIVE_NEWLINES.sub("\n\n", result)
+
+    # Strip leading/trailing whitespace
+    result = result.strip()
+
+    if not result:
+        return "[empty]"
+
+    # Truncate
+    if len(result) > max_length:
+        result = result[:max_length] + "... [truncated]"
+
+    return result
+
+
+def sanitize_name(text: Optional[str], max_length: int = 256) -> str:
+    """Sanitize a display name (username, chat title, sender name).
+
+    Names should be single-line, so newlines are stripped entirely
+    in addition to the standard sanitization.
+    """
+    result = sanitize_user_content(text, max_length=max_length)
+    # Names must be single-line
+    result = result.replace("\n", " ").replace("\r", " ")
+    # Collapse multiple spaces that might result from newline replacement
+    result = re.sub(r" {2,}", " ", result).strip()
+    return result
+
+
+def sanitize_dict(data: Any) -> Any:
+    """Recursively sanitize all string values in a nested dict/list structure.
+
+    Use this for raw Telegram API responses (e.g. to_dict()) where
+    user-controlled content can appear at any nesting depth.
+    """
+    if isinstance(data, dict):
+        return {k: sanitize_dict(v) for k, v in data.items()}
+    if isinstance(data, list):
+        return [sanitize_dict(item) for item in data]
+    if isinstance(data, str):
+        return sanitize_user_content(data, max_length=4096)
+    return data
+
+
+def _json_default(obj: Any) -> Any:
+    """JSON serializer for objects not serializable by default json code."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+def format_tool_result(
+    records: List[Dict[str, Any]],
+    metadata: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Format tool output as a JSON string.
+
+    All tool functions that return user-controlled content should use
+    this formatter. The JSON structure provides an unambiguous boundary
+    between trusted field names and untrusted user-generated values.
+    """
+    payload: Dict[str, Any] = {"results": records}
+    if metadata:
+        payload.update(metadata)
+    return json.dumps(payload, ensure_ascii=False, default=_json_default)

package/vendor/telegram-mcp/session_string_generator.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+Telegram Session String Generator
+
+This script generates a session string that can be used for Telegram authentication
+with the Telegram MCP server. The session string allows for portable authentication
+without storing session files.
+
+Usage:
+    python session_string_generator.py
+    python session_string_generator.py --qr
+
+Requirements:
+    - telethon
+    - python-dotenv
+
+Note on ID Formats:
+When using the MCP server, please be aware that all `chat_id` and `user_id`
+parameters support integer IDs, string representations of IDs (e.g., "123456"),
+and usernames (e.g., "@mychannel").
+"""
+
+import argparse
+import asyncio
+import getpass
+import io
+import os
+import sys
+from datetime import datetime, timezone
+
+from dotenv import load_dotenv
+from telethon import errors
+from telethon.sessions import StringSession
+from telethon.sync import TelegramClient
+from telegram_mcp.client_identity import client_identity_kwargs
+from telegram_mcp.install_guard import UnsafeInstallationError, assert_safe_distribution
+
+# How many times the QR code is regenerated after expiry before giving up.
+_QR_MAX_REFRESHES = 10
+
+load_dotenv()
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generate a Telegram session string for telegram-mcp."
+    )
+    login_group = parser.add_mutually_exclusive_group()
+    login_group.add_argument(
+        "--qr",
+        action="store_true",
+        help="Use Telegram QR login without prompting for a login method.",
+    )
+    login_group.add_argument(
+        "--phone",
+        action="store_true",
+        help="Use phone number + verification code login without prompting for a login method.",
+    )
+    return parser.parse_args()
+
+
+def _check_installation() -> None:
+    try:
+        assert_safe_distribution()
+    except UnsafeInstallationError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+
+
+def _render_qr(qr) -> None:
+    import qrcode
+
+    print("\n----- QR Code Login -----\n")
+
+    qr_obj = qrcode.QRCode(border=1)
+    qr_obj.add_data(qr.url)
+    qr_obj.make(fit=True)
+    f = io.StringIO()
+    qr_obj.print_ascii(out=f, invert=True)
+    print(f.getvalue())
+
+    print("Scan the QR code above with your Telegram app:")
+    print("  Open Telegram > Settings > Devices > Link Desktop Device\n")
+    print(f"Or open this link on a device where you're logged in:\n  {qr.url}\n")
+    print(f"Expires at: {qr.expires.strftime('%H:%M:%S')}")
+    print("Waiting for you to scan...")
+
+
+def _seconds_until_expiry(qr) -> float:
+    """Seconds left before this QR token expires, with a small safety margin."""
+    expires = qr.expires
+    if expires.tzinfo is None:
+        expires = expires.replace(tzinfo=timezone.utc)
+    remaining = (expires - datetime.now(timezone.utc)).total_seconds()
+    return max(1.0, remaining - 1.0)
+
+
+def _qr_login(client: TelegramClient) -> None:
+    qr = client.qr_login()
+    _render_qr(qr)
+
+    for _ in range(_QR_MAX_REFRESHES):
+        try:
+            client.loop.run_until_complete(qr.wait(timeout=_seconds_until_expiry(qr)))
+            return
+        except asyncio.TimeoutError:
+            client.loop.run_until_complete(qr.recreate())
+            print("\nQR code expired, here is a fresh one.")
+            _render_qr(qr)
+        except errors.SessionPasswordNeededError:
+            while True:
+                pw = getpass.getpass(
+                    "\nTwo-factor authentication enabled. Please enter your password: "
+                )
+                try:
+                    client.sign_in(password=pw)
+                    return
+                except errors.PasswordHashInvalidError:
+                    print("Invalid password, please try again.")
+
+    print("\nQR code expired too many times. Please run the generator again.")
+    client.disconnect()
+    sys.exit(1)
+
+
+def _phone_login(client: TelegramClient) -> None:
+    phone = input("Please enter your phone (or bot token): ")
+
+    try:
+        client.send_code_request(phone)
+    except errors.FloodWaitError as e:
+        print(f"\nFlood wait error; you must wait {e.seconds} seconds before trying again.")
+        client.disconnect()
+        sys.exit(1)
+    except errors.PhoneNumberInvalidError:
+        print("\nThe phone number is invalid.")
+        client.disconnect()
+        sys.exit(1)
+    except Exception as e:
+        print(f"\nError sending code: {e}")
+        client.disconnect()
+        sys.exit(1)
+
+    code = input("\nPlease enter the code you received: ")
+    try:
+        client.sign_in(phone, code)
+    except errors.SessionPasswordNeededError:
+        pw = getpass.getpass("Two-factor authentication enabled. Please enter your password: ")
+        client.sign_in(password=pw)
+
+
+def main() -> None:
+    args = _parse_args()
+    _check_installation()
+
+    API_ID = os.getenv("TELEGRAM_API_ID")
+    API_HASH = os.getenv("TELEGRAM_API_HASH")
+
+    if not API_ID or not API_HASH:
+        print("Error: TELEGRAM_API_ID and TELEGRAM_API_HASH must be set in .env file")
+        print("Create an .env file with your credentials from https://my.telegram.org/apps")
+        sys.exit(1)
+
+    try:
+        API_ID = int(API_ID)
+    except ValueError:
+        print("Error: TELEGRAM_API_ID must be an integer")
+        sys.exit(1)
+
+    print("\n----- Telegram Session String Generator -----\n")
+    print("This script will generate a session string for your Telegram account.")
+    print("The generated session string can be added to your .env file.")
+    print(
+        "\nYour credentials will NOT be stored on any server and are only used for local authentication.\n"
+    )
+
+    try:
+        label = (
+            input("Account label (optional, e.g. 'work', 'personal'; leave empty for default): ")
+            .strip()
+            .lower()
+        )
+    except EOFError:
+        # Non-interactive stdin (piped/scripted runs): fall back to the default label.
+        label = ""
+
+    if args.qr:
+        method = "1"
+    elif args.phone:
+        method = "2"
+    else:
+        print("\nChoose login method:")
+        print("  1) QR code login (recommended -- scan from your Telegram app)")
+        print("  2) Phone number + verification code")
+        method = input("\nEnter 1 or 2 [default: 1]: ").strip() or "1"
+
+    try:
+        client = TelegramClient(StringSession(), API_ID, API_HASH, **client_identity_kwargs())
+        client.connect()
+
+        if not client.is_user_authorized():
+            if method == "1":
+                _qr_login(client)
+            else:
+                _phone_login(client)
+
+        session_string = StringSession.save(client.session)
+
+        if label:
+            env_var = f"TELEGRAM_SESSION_STRING_{label.upper()}"
+        else:
+            env_var = "TELEGRAM_SESSION_STRING"
+
+        print("\nAuthentication successful!")
+        print("\n----- Your Session String -----")
+        print(f"\n{session_string}\n")
+        print("Add this to your .env file as:")
+        print(f"{env_var}={session_string}")
+        print("\nIMPORTANT: Keep this string private and never share it with anyone!")
+
+        try:
+            choice = input(
+                "\nWould you like to automatically update your .env file with this session string? (y/N): "
+            )
+        except EOFError:
+            choice = "n"
+        if choice.lower() == "y":
+            try:
+                with open(".env", "r") as file:
+                    env_contents = file.readlines()
+
+                session_string_line_found = False
+                for i, line in enumerate(env_contents):
+                    if line.startswith(f"{env_var}="):
+                        env_contents[i] = f"{env_var}={session_string}\n"
+                        session_string_line_found = True
+                        break
+
+                if not session_string_line_found:
+                    env_contents.append(f"{env_var}={session_string}\n")
+
+                with open(".env", "w") as file:
+                    file.writelines(env_contents)
+
+                print("\n.env file updated successfully!")
+            except Exception as e:
+                print(f"\nError updating .env file: {e}")
+                print("Please manually add the session string to your .env file.")
+
+        client.disconnect()
+
+    except Exception as e:
+        print(f"\nError: {e}")
+        print("Failed to generate session string. Please try again.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,15 @@
+"""Telegram MCP server package."""
+
+
+def __getattr__(name: str):
+    if name == "mcp":
+        from telegram_mcp.install_guard import assert_safe_distribution
+
+        assert_safe_distribution()
+        from telegram_mcp.runtime import mcp
+
+        return mcp
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["mcp"]

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

@@ -0,0 +1,31 @@
+"""Resolve the Telethon device identity used when connecting to Telegram.
+
+These values are what Telegram shows in Settings > Devices (active sessions).
+When they are not provided, Telethon falls back to the host platform (for
+example ``arm64``), and because the values are re-sent on every connection,
+a long-running server would otherwise overwrite the name chosen during login
+on each reconnect. Making them configurable keeps a stable, recognisable name.
+"""
+
+import os
+
+# Maps the Telethon constructor keyword to the environment variable that sets it.
+_DEVICE_ENV = {
+    "device_model": "TELEGRAM_DEVICE_MODEL",
+    "system_version": "TELEGRAM_SYSTEM_VERSION",
+    "app_version": "TELEGRAM_APP_VERSION",
+}
+
+
+def client_identity_kwargs() -> dict:
+    """Return TelegramClient device kwargs derived from the environment.
+
+    Only variables that are set to a non-empty value are included, so unset
+    ones keep Telethon's own defaults.
+    """
+    kwargs = {}
+    for kwarg, env_var in _DEVICE_ENV.items():
+        value = os.environ.get(env_var)
+        if value:
+            kwargs[kwarg] = value
+    return kwargs