telegram-context-mcp 0.2.0__py3-none-any.whl

telegram_context_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: telegram-context-mcp
+Version: 0.2.0
+Summary: Local, read-only Telegram MCP server with folder-aware retrieval
+Project-URL: Documentation, https://github.com/egor-fedorov/telegram-mcp/blob/main/README.md
+Project-URL: Repository, https://github.com/egor-fedorov/telegram-mcp
+Project-URL: Issues, https://github.com/egor-fedorov/telegram-mcp/issues
+Project-URL: Roadmap, https://github.com/egor-fedorov/telegram-mcp/blob/main/ROADMAP.md
+Project-URL: Changelog, https://github.com/egor-fedorov/telegram-mcp/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Requires-Dist: anyio<5,>=4.15.1
+Requires-Dist: httpx2<3,>=2.5
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: portalocker<5,>=4.4.1
+Requires-Dist: pydantic<3,>=2.14.1
+Requires-Dist: pywin32>=311; sys_platform == 'win32'
+Requires-Dist: starlette<2,>=1.6
+Requires-Dist: telethon<2,>=1.45
+Requires-Dist: uvicorn<1,>=0.52.4
+Description-Content-Type: text/markdown
+
+# Telegram Context MCP
+
+[![CI](https://github.com/egor-fedorov/telegram-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/egor-fedorov/telegram-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/egor-fedorov/telegram-mcp/blob/main/LICENSE)
+
+Read Telegram through your own account from an MCP client. Find permitted conversations,
+search and read original posts, navigate topics and replies, and inspect albums, reactions,
+and polls. Connect several local clients to one session-owning process, or run standalone STDIO.
+
+Supports Windows, macOS, and Linux with Python 3.12–3.15. The server uses Telethon and
+preserves original text, dates, links, entities, and available metadata. It does not send
+messages, join channels, mark messages read, or download attachment bytes.
+
+## Install and log in
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run:
+
+```sh
+uv tool install --python 3.12 telegram-context-mcp==0.2.0
+telegram-mcp --version
+telegram-mcp login
+telegram-mcp configure
+telegram-mcp status
+```
+
+These examples target release 0.2.0; check [PyPI](https://pypi.org/project/telegram-context-mcp/)
+for published versions. Use the [source setup](#run-from-source) for unreleased revisions.
+
+Obtain `api_id` and `api_hash` from [my.telegram.org](https://my.telegram.org), then
+enter them in the local login prompt with your phone number, login code, and any 2FA
+password. Do not send login codes or credentials to the model.
+
+`configure` lets you choose folders/chats and separately enable all-chat access,
+explicit public-channel reads, or public-channel discovery. Enter keeps the current
+value. By default, no message sources are permitted. `status` should report
+`authorized: true` after login. Use `catalog` to find folder and chat IDs locally.
+
+The package name is **`telegram-context-mcp`**; the executable is **`telegram-mcp`**.
+You can also run a pinned version without installing a persistent command:
+
+```sh
+uvx --python 3.12 --from telegram-context-mcp==0.2.0 telegram-mcp --version
+```
+
+## Connect your clients
+
+Start one server in a terminal and leave it running:
+
+```sh
+telegram-mcp serve --transport http
+```
+
+It listens only on `http://127.0.0.1:8765/mcp`. Configure each MCP client to launch
+`telegram-mcp connect` over STDIO. This small proxy reads the local token and connects
+to the existing server; it does not start a server or silently fall back to another
+Telegram session. Closing a client leaves the shared server running.
+
+[Client examples](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/clients.md)
+cover Codex, Claude Desktop, Claude Code, Cursor, and VS Code, including a pinned `uvx`
+command and executable paths for Windows.
+
+For one client, standalone STDIO is still available: configure that client to launch
+`telegram-mcp serve`. Use either mode for a given session. Stop the session-owning
+process before running local `login`, `configure`, `catalog`, or `status`; use the
+`get_status` MCP tool while the server is running.
+
+All shared clients use the same Telegram account, read permissions, and cursor store.
+The HTTP bearer token is created in the local user profile and read by `connect`;
+do not paste it into client configuration. This is a local, single-user integration.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `get_status` | Authorization, connection, permitted sources |
+| `list_folders` | Folders, IDs, order, inclusion/exclusion rules |
+| `list_chats` | Chats filtered by name, type, or folders |
+| `get_chat` | Description and linked discussion group |
+| `search_public_channels` | Find public broadcast channels by query; metadata only |
+| `get_similar_channels` | Find similar public channels for one specified public source; metadata only |
+| `search_messages` | Keyword search by chats, folders, dates, sender, or content type |
+| `get_history` | Chat or forum-topic history over a time range, in either order |
+| `list_topics` | Forum topics with navigation references, optional title query, and pagination |
+| `get_pinned_messages` | Chat-wide or forum-topic pinned messages, newest first |
+| `get_messages` | Messages by links/IDs with authors, dates, attachments, counters, reactions, and polls |
+| `get_album` | Members of a selected album within a bounded neighborhood of one message |
+| `get_context` | Messages before/after an anchor and a chain of parent replies |
+| `get_thread` | Comments on a channel post or replies in a group thread |
+
+
+## First tasks
+
+- Ask the client to list the folders you permitted and read a selected conversation
+  over a timezone-qualified date range.
+- Enable discovery to find candidate public channels, select a source, then read its
+  posts with a separate read permission.
+- Follow `next_cursor` with the original filters until it is absent. An empty page
+  can still have a cursor. Respect `retry_after_seconds` after a temporary failure.
+- Use `get_messages` with `next_text_offset` to finish long text. Album completeness
+  is explicitly unknown; each member remains a separate source message.
+
+[Usage and response contracts](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/usage.md)
+explain filters, cursor recovery, topics, public-channel discovery, and message metadata.
+Message text is data for the calling agent, not an instruction source.
+
+## Configuration and troubleshooting
+
+Configuration, Telegram sessions, and the HTTP token live outside the repository in
+platform-specific user directories. The login command prints the configuration path.
+Use `telegram-mcp --config /absolute/private/config.toml COMMAND` to select another file;
+pass the same file to the shared server and each proxy.
+
+On POSIX, private files use restrictive permissions. On Windows, protect them with
+user-profile filesystem ACLs; Unix `0600` is not an ACL guarantee. A Telegram session
+contains account access credentials, and the underlying account can do more than the
+server's read-only tools allow.
+
+- [Configuration and permissions](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/configuration.md)
+- [Troubleshooting](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/troubleshooting.md)
+- [Example TOML](https://github.com/egor-fedorov/telegram-mcp/blob/main/config.example.toml)
+- [Security reporting](https://github.com/egor-fedorov/telegram-mcp/blob/main/SECURITY.md)
+
+## Run from source
+
+```sh
+git clone https://github.com/egor-fedorov/telegram-mcp.git
+cd telegram-mcp
+uv sync --locked --python 3.12
+uv run --locked telegram-mcp login
+uv run --locked telegram-mcp configure
+uv run --locked telegram-mcp serve --transport http
+```
+
+For client commands, use the checkout's `.venv/bin/telegram-mcp` on POSIX or
+`.venv\Scripts\telegram-mcp.exe` on Windows, with `connect` as the argument.
+Use an absolute executable path so clients do not depend on their working directory.
+
+## Development
+
+Run `make check` for formatting, lint, types, architecture checks, and offline tests.
+[Contributing](https://github.com/egor-fedorov/telegram-mcp/blob/main/CONTRIBUTING.md)
+includes equivalent commands for Windows without Make. Changes use focused pull requests
+and squash merges after CI. See the
+[roadmap](https://github.com/egor-fedorov/telegram-mcp/blob/main/ROADMAP.md),
+[architecture](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/architecture.md),
+[changelog](https://github.com/egor-fedorov/telegram-mcp/blob/main/CHANGELOG.md), and
+[release procedure](https://github.com/egor-fedorov/telegram-mcp/blob/main/docs/releasing.md).
+
+The code is [MIT licensed](https://github.com/egor-fedorov/telegram-mcp/blob/main/LICENSE).
+This does not grant rights to Telegram content. Secret chats are unsupported; attachment
+downloads, sending, administration, and persistent archives are separate future work.
+Use source material you are entitled to share with your chosen model and follow
+[Telegram's content terms](https://telegram.org/tos/content-licensing).

telegram_context_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+telegram_mcp/__init__.py,sha256=LShGvu63tXwxgYmoJpfYFl-uPFp_kjrA3X4vp2AuU3w,55
+telegram_mcp/bootstrap.py,sha256=7Sn-4lhpLmrnPBgFoDDMgUj4C1cBLG08Z5pbRlAWpV4,1616
+telegram_mcp/cli.py,sha256=HfgvjR-uRtY9_M_tf7XckSNmKIoNIp4p-uUM5XxVsqU,135
+telegram_mcp/adapters/__init__.py,sha256=qWfFGpBNefKGiF907eZrtsF5yiW_A3UjZa4Ax-yPy_o,62
+telegram_mcp/adapters/bridge.py,sha256=1gAJWlxrv_1WyMIcw3_9v3fpKc69ml-PYq1U3yUSPe8,2918
+telegram_mcp/adapters/cli.py,sha256=nt1_F03YdmR49VT0p3WGyVwoqHPBV-uC323co0yx148,8536
+telegram_mcp/adapters/clock.py,sha256=YVsCji7YxX2AIHPTLd08GEiW2lsWDUHmsPKB_-GM0Dg,277
+telegram_mcp/adapters/config.py,sha256=hdFkaO1MGsEeft-rqDu81Ehy9m00gKoP_Eh1G3l5Ezs,6984
+telegram_mcp/adapters/cursors.py,sha256=vjKoRZLS_sJ3wxrQXn0zZ8xeZzCDCVLpPXHvEVThtoY,2123
+telegram_mcp/adapters/http_token.py,sha256=EGSNiNqbTPJGXNyr4eQWTfqUn7ICwVs-qxDAR9GoDQM,2603
+telegram_mcp/adapters/mcp.py,sha256=uINuPOScQrN3y5KVmD4VP-o2o25vds7RV8fW6Bg8unE,17061
+telegram_mcp/adapters/session.py,sha256=WB0m-FpEf-Kh2N9lzSM3h6bOwkEdCh10DHrm-A33VMY,1793
+telegram_mcp/adapters/tool_gate.py,sha256=FPAJ7lJfzYjc-eWIqf5dQr5QGZ12Koxo8jXmAUauNNc,774
+telegram_mcp/adapters/transport.py,sha256=ULckM2Aknh-IPp-RgXyE_uobMzmi9oIXln-j_1s1cZk,3712
+telegram_mcp/adapters/version.py,sha256=RcTAIvbXUCC_vGF3IW2XCFVoHZYzbq_qwi_9bY4n3dg,188
+telegram_mcp/adapters/telegram/__init__.py,sha256=wclc3gq9hG6wuzD-mpw1L34iu95GtN0bxepehHQFFpg,243
+telegram_mcp/adapters/telegram/auth.py,sha256=PXScKRl1sG04GJoqFMLSAby35drL40QhGSWj3borTso,1599
+telegram_mcp/adapters/telegram/backend.py,sha256=XwCgNxpRYcL4DRS46B5cIvmphYqN8aeOUspZIFlYp54,4172
+telegram_mcp/adapters/telegram/chats.py,sha256=O9RCRLJYx4NDi8DN-RQ2gbAbMVtee1ZZLQ6zPgnp8uw,7595
+telegram_mcp/adapters/telegram/discovery.py,sha256=AEC0uwE0r8ACrELo4JDvYmkC0gIDd4Ao6tf2YMVQnhE,2356
+telegram_mcp/adapters/telegram/forums.py,sha256=HbXGiHuQi2_nilWjy_lmbPf-B8kuQIqCW_R9qRiGBpk,5290
+telegram_mcp/adapters/telegram/mapping.py,sha256=ZaLjPV5Uu8UoA3G8dROoNhD6BMPWTr1JWOX_wV568zs,11139
+telegram_mcp/adapters/telegram/messages.py,sha256=rXmDOACQrnkJJkbb-i4cnn_qFalU0Ry43awmOmQKde8,18129
+telegram_mcp/adapters/telegram/metadata.py,sha256=C_IhP1HTbQARI1bXad4GkXcCofLHGtpBCpW2Ki8lwYw,5504
+telegram_mcp/adapters/telegram/runtime.py,sha256=By4_rlez1-YReUGEOenrItfN_R_v35SK1Lc-daJd3sA,5579
+telegram_mcp/application/__init__.py,sha256=4fPU_l5oJ3gplKsmc0c-gmcnIqQFWY93u2eMRfWCawk,53
+telegram_mcp/application/access.py,sha256=aiEIDrSh_CCQ4X8WIkUooSGU7A5IY1ZSu7fMhtzaWw4,2276
+telegram_mcp/application/catalog.py,sha256=WnHDgMCIrzjG9cMCVya8zVElLdXltF2G89qzKBRdjpU,2880
+telegram_mcp/application/common.py,sha256=hm41HSWvkOJ-Bz5_02OMFShRTcS_eego5x4vAqgHTQs,632
+telegram_mcp/application/discovery.py,sha256=fbz-BVaCpAjVOddhKNqV2Ko8woFewBXTS4U_sZk52tc,2058
+telegram_mcp/application/message_pager.py,sha256=Q6RgAE9FszpF5VlxvOJfTUReZquP0NV8ybNgbmeiffU,5276
+telegram_mcp/application/messages.py,sha256=nvFm3vyQmGSaF_z5jfcrjsNNLwr4YYDtQOaT9uqHt5w,8828
+telegram_mcp/application/ports.py,sha256=0YGWyxHdsllk4kWa0BZ-uV2UcOgHzfE8Y5kxAdf3gGQ,3574
+telegram_mcp/application/queries.py,sha256=ST_YkuiN0kQgl9w8ayWjOtY-VixrOqR0eiBlWdxyZSI,4194
+telegram_mcp/application/query_preparation.py,sha256=fdNY6YgfqLPW1yVqdyI7l_wNHr3MwET2KL2nVvFpOR0,6190
+telegram_mcp/application/requests.py,sha256=9s-nerhRksF_9ywx26keQPfewO19jipvbuSE7eTrs1w,1128
+telegram_mcp/application/retry.py,sha256=qqHEfAs4avsPQ6bitI9V188qV1TjHG-kzNtBT2a3Y6o,975
+telegram_mcp/application/service.py,sha256=JY3HxSR4XoOmxy3xnR_i2s0rMW_Xv1aDa_SYJxTldaE,6652
+telegram_mcp/application/topics.py,sha256=YcP2lZTDPOsGA6lTx_YqSr97vCfM9ydEIBJmYEb0OZk,5860
+telegram_mcp/domain/__init__.py,sha256=idV106eVVaA2lz2aFmouoa4xiIbJP0h4-yEGQULq6Jo,39
+telegram_mcp/domain/folders.py,sha256=FTbpcpVWH7Sg1nAWEu8Y4l1pqz3qtj69wJimTVE8uNw,3404
+telegram_mcp/domain/models.py,sha256=2drZwa0NRcXxUSW04xVQ2n1jQ0Z-CKWK_cCAbQu9b00,9286
+telegram_mcp/domain/policy.py,sha256=7rIC7Wenh8OfwpipZEyD-CPl7vyfmWGGjoyBAV0WII4,361
+telegram_mcp/domain/text.py,sha256=TGQuEgMJq8qFW6Ju7QGEthiJVZrbA-mF7G7QWi5dleM,515
+telegram_context_mcp-0.2.0.dist-info/METADATA,sha256=DZN4vtGVFAGwJpFgeODKBchgwTz0tT0ErA8t3s_ylxY,9514
+telegram_context_mcp-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+telegram_context_mcp-0.2.0.dist-info/entry_points.txt,sha256=AnkjeB4Oeu6bjL2mNoM3G8alvMfPhcn4fY54jIQm8g4,55
+telegram_context_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=Sb4YOw89QCIIIGM_KRImBZYJdnVqBsmWsxBhz5V3XEw,1070
+telegram_context_mcp-0.2.0.dist-info/RECORD,,

telegram_context_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

telegram_context_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+telegram-mcp = telegram_mcp.cli:main

telegram_context_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egor Fyodorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telegram_mcp/__init__.py

@@ -0,0 +1 @@
+"""Folder-aware, read-only Telegram context server."""

telegram_mcp/adapters/__init__.py

@@ -0,0 +1 @@
+"""External transport, persistence, and Telegram adapters."""

telegram_mcp/adapters/bridge.py

@@ -0,0 +1,77 @@
+"""Expose the shared loopback server to clients that launch STDIO subprocesses."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import httpx2
+from mcp.client import Client
+from mcp.client.streamable_http import streamable_http_client
+from mcp.server.lowlevel import Server
+from mcp.server.stdio import stdio_server
+from mcp.shared.exceptions import MCPError
+from mcp_types import CallToolRequestParams, CallToolResult, PaginatedRequestParams, TextContent
+
+from telegram_mcp.adapters.config import Settings
+from telegram_mcp.adapters.http_token import load_token
+from telegram_mcp.adapters.transport import endpoint
+from telegram_mcp.domain.models import ToolError
+
+
+def unavailable() -> ToolError:
+    return ToolError(
+        "SHARED_SERVER_UNAVAILABLE",
+        "Cannot connect to the shared Telegram server. Start 'serve --transport http' "
+        "and use the same http_port and http_token_path for connect. If it is already running, "
+        "check that both commands use the same token file.",
+    )
+
+
+def create_bridge(upstream: Client) -> Server:
+    async def list_tools(_context, params: PaginatedRequestParams | None):
+        return await upstream.list_tools(cursor=params.cursor if params is not None else None)
+
+    async def call_tool(_context, params: CallToolRequestParams) -> CallToolResult:
+        try:
+            return await upstream.call_tool(params.name, params.arguments, meta=params.meta)
+        except MCPError:
+            raise
+        except Exception:
+            return CallToolResult(
+                content=[TextContent(type="text", text=unavailable().issue().model_dump_json())],
+                is_error=True,
+            )
+
+    info = upstream.server_info
+    return Server(
+        info.name if info is not None else "Telegram Context",
+        version=info.version if info is not None else "",
+        instructions=upstream.instructions,
+        on_list_tools=list_tools,
+        on_call_tool=call_tool,
+    )
+
+
+@asynccontextmanager
+async def shared_client(settings: Settings) -> AsyncIterator[Client]:
+    token = load_token(settings.http_token_path)
+    try:
+        async with httpx2.AsyncClient(
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=httpx2.Timeout(30, read=300),
+            trust_env=False,
+        ) as http:
+            async with Client(
+                streamable_http_client(endpoint(settings), http_client=http), cache=None
+            ) as upstream:
+                yield upstream
+    except ToolError:
+        raise
+    except Exception:
+        raise unavailable() from None
+
+
+async def connect(settings: Settings) -> None:
+    async with shared_client(settings) as upstream:
+        proxy = create_bridge(upstream)
+        async with stdio_server() as (read_stream, write_stream):
+            await proxy.run(read_stream, write_stream, proxy.create_initialization_options())

telegram_mcp/adapters/cli.py

@@ -0,0 +1,215 @@
+"""Local commands for login, selecting scope, diagnosis and serving MCP."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import json
+import logging
+import sys
+from collections.abc import Awaitable, Callable, Coroutine
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import SecretStr, ValidationError
+
+from telegram_mcp.adapters.config import (
+    Settings,
+    config_path,
+    load_settings,
+    save_settings,
+    validate_settings,
+    validation_error,
+)
+from telegram_mcp.adapters.mcp import create_server
+from telegram_mcp.adapters.version import get_version
+from telegram_mcp.application.ports import Backend
+from telegram_mcp.application.service import Service
+from telegram_mcp.domain.models import ToolError
+
+
+async def login(
+    settings: Settings, path: Path, authenticate: Callable[..., Awaitable[None]]
+) -> None:
+    if not sys.stdin.isatty():
+        raise ToolError(
+            "INTERACTIVE_LOGIN_REQUIRED", "Run login yourself in an interactive terminal."
+        )
+    settings = settings.model_copy(deep=True)
+    if settings.api_id is None:
+        value = (await asyncio.to_thread(input, "Telegram api_id (my.telegram.org): ")).strip()
+        try:
+            settings.api_id = int(value)
+        except ValueError:
+            raise ToolError("INVALID_ARGUMENT", "api_id: enter a positive integer.") from None
+    if settings.api_hash is None:
+        settings.api_hash = SecretStr(getpass.getpass("Telegram api_hash: ").strip())
+    settings = validate_settings(settings, "Login input")
+    await authenticate(
+        settings,
+        phone=lambda: input("Phone number: "),
+        code=lambda: getpass.getpass("Telegram login code: "),
+        password=lambda: getpass.getpass("Telegram 2FA password: "),
+    )
+    save_settings(settings, path)
+    print(f"Session saved. Configuration: {path}")
+    print("Next: telegram-mcp configure — choose the folders/chats the server may read.")
+
+
+async def prompt_boolean(prompt: str, current: bool) -> bool:
+    current_label = "yes" if current else "no"
+    while True:
+        value = await asyncio.to_thread(input, f"{prompt} [y/n] (Enter: keep {current_label}): ")
+        value = value.strip().lower()
+        if not value:
+            return current
+        if value in {"y", "yes", "n", "no"}:
+            return value in {"y", "yes"}
+        print("Enter y or n, or press Enter to keep the current setting.")
+
+
+async def configure(
+    settings: Settings, path: Path, backend_factory: Callable[[Settings], Backend]
+) -> None:
+    if not sys.stdin.isatty():
+        raise ToolError(
+            "INTERACTIVE_CONFIGURATION_REQUIRED", "Run configure in an interactive terminal."
+        )
+    updated = settings.model_copy(deep=True)
+    backend = backend_factory(settings)
+    try:
+        _, folders = await backend.catalog()
+        for folder in folders:
+            print(f"{folder.id}: {folder.title}")
+        value = (
+            await asyncio.to_thread(
+                input, "Allowed folder IDs, comma-separated (Enter: keep current): "
+            )
+        ).strip()
+        if value:
+            try:
+                chosen = [int(item.strip()) for item in value.split(",")]
+            except ValueError:
+                raise ToolError(
+                    "INVALID_ARGUMENT", "allowed_folder_ids: enter comma-separated integer IDs."
+                ) from None
+            if set(chosen) - {f.id for f in folders}:
+                raise ToolError("FOLDER_NOT_FOUND", "A selected folder does not exist.")
+            updated.allowed_folder_ids = chosen
+        value = (
+            await asyncio.to_thread(
+                input, "Additional chat IDs, comma-separated (Enter: keep current): "
+            )
+        ).strip()
+        if value:
+            try:
+                updated.allowed_chat_ids = [str(int(item.strip())) for item in value.split(",")]
+            except ValueError:
+                raise ToolError(
+                    "INVALID_ARGUMENT", "allowed_chat_ids: enter comma-separated integer IDs."
+                ) from None
+        updated.allow_public_channel_reads = await prompt_boolean(
+            "Allow explicitly requested public channels outside this scope?",
+            settings.allow_public_channel_reads,
+        )
+        updated.allow_public_channel_discovery = await prompt_boolean(
+            "Allow public-channel search and similar-channel metadata (no post reads)?",
+            settings.allow_public_channel_discovery,
+        )
+        updated.allow_all_chats = await prompt_boolean(
+            "Allow reading all account chats instead of limiting reads to selected sources?",
+            settings.allow_all_chats,
+        )
+        save_settings(validate_settings(updated, "Configuration input"), path)
+        print(f"Scope saved to {path}. Restart the MCP server to apply configuration changes.")
+    finally:
+        await backend.close()
+
+
+async def diagnose(
+    settings: Settings, dependencies: CliDependencies, catalog: bool = False
+) -> None:
+    backend = dependencies.backend_factory(settings)
+    try:
+        if catalog:
+            chats, folders = await backend.catalog()
+            output: object = {
+                "folders": [f.model_dump(mode="json") for f in folders],
+                "chats": [c.model_dump(mode="json") for c in chats],
+            }
+        else:
+            output = await dependencies.service_factory(backend, settings).get_status()
+        print(json.dumps(output, ensure_ascii=False, indent=2))
+    finally:
+        await backend.close()
+
+
+@dataclass(frozen=True)
+class CliDependencies:
+    backend_factory: Callable[[Settings], Backend]
+    service_factory: Callable[[Backend, Settings], Service]
+    authenticate: Callable[..., Awaitable[None]]
+    serve_http: Callable[[Service, Settings], None]
+    connect: Callable[[Settings], Coroutine[object, object, None]]
+
+
+def main(dependencies: CliDependencies) -> None:
+    parser = argparse.ArgumentParser(
+        prog="telegram-mcp", description="Local read-only Telegram MCP server"
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {get_version()}")
+    parser.add_argument("--config", type=Path, help="Configuration TOML path")
+    parser.add_argument(
+        "command", choices=["serve", "connect", "login", "configure", "status", "catalog"]
+    )
+    parser.add_argument(
+        "--transport", choices=["stdio", "http"], help="Transport for serve (default: stdio)"
+    )
+    args = parser.parse_args()
+    if args.transport is not None and args.command != "serve":
+        parser.error("--transport is supported only with serve")
+    logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
+    try:
+        path = (args.config or config_path()).expanduser()
+        settings = load_settings(path)
+        if args.command == "serve":
+            service = dependencies.service_factory(dependencies.backend_factory(settings), settings)
+            if args.transport == "http":
+                dependencies.serve_http(service, settings)
+            else:
+                create_server(service).run(transport="stdio")
+        elif args.command == "connect":
+            asyncio.run(dependencies.connect(settings))
+        elif args.command == "login":
+            asyncio.run(login(settings, path, dependencies.authenticate))
+        elif args.command == "configure":
+            asyncio.run(configure(settings, path, dependencies.backend_factory))
+        else:
+            asyncio.run(diagnose(settings, dependencies, args.command == "catalog"))
+    except ToolError as exc:
+        print(str(exc), file=sys.stderr)
+        if exc.code == "SESSION_IN_USE":
+            print(
+                "A running server owns this Telegram session. Use get_status through a connected "
+                "MCP app, or stop the server before running direct local commands.",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+    except ValidationError as exc:
+        print(str(validation_error(exc, "Local command")), file=sys.stderr)
+        sys.exit(1)
+    except OSError:
+        print(
+            "LOCAL_IO_ERROR: Local command failed to access a file or device. "
+            "Check paths and permissions.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except EOFError:
+        print(
+            "INPUT_CLOSED: Interactive input ended; configuration was not saved.", file=sys.stderr
+        )
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)

telegram_mcp/adapters/clock.py

@@ -0,0 +1,12 @@
+"""Wall and monotonic time for the application's injected clock port."""
+
+import time
+from datetime import UTC, datetime
+
+
+class SystemClock:
+    def utc_now(self) -> datetime:
+        return datetime.now(UTC)
+
+    def monotonic(self) -> float:
+        return time.monotonic()