Merge branch 'upstream/main' into feat/transport-selection-50 and remove CLAUDE.md

Author: omid-io

.env.example

@@ -7,9 +7,11 @@ TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
 # TELEGRAM_EVENT_FEED_FILE=/path/to/incoming_feed.jsonl
 
 # --- Single account (backward-compatible) ---
-# Option 1: File-based session (a .session file will be created)
+# Recommended for long-running servers: persists Telegram update state locally.
 TELEGRAM_SESSION_NAME=telegram_session
-# Option 2: String-based session
+# Portable setup/migration source: does not persist Telegram update state.
+# If both variables are set, TELEGRAM_SESSION_STRING takes precedence, so remove
+# or comment it out after running `uv run telegram-mcp-migrate-session`.
 # TELEGRAM_SESSION_STRING=1231231232erfdfdffd
 
 # --- Multiple accounts ---

.github/workflows/docker-build.yml

@@ -9,7 +9,7 @@ on:
 
 jobs:
   docker_build:
-    name: Build Docker Image
+    name: Build Docker Image (Multistage)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -21,8 +21,26 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Build Docker image
-        run: docker build --file Dockerfile --tag telegram-mcp:ci .
+      - name: Build production target
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: production
+          tags: telegram-mcp:latest,telegram-mcp:ci
+          load: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Build and test development target
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: development
+          tags: telegram-mcp:dev
+          load: true
+          cache-from: type=gha
 
   docker_compose:
     name: Build & Validate Docker Compose
@@ -37,7 +55,6 @@ jobs:
           echo "TELEGRAM_API_ID=DUMMY_ID" > .env
           echo "TELEGRAM_API_HASH=DUMMY_HASH" >> .env
           echo "TELEGRAM_SESSION_STRING=DUMMY_SESSION" >> .env
-          # Add other required variables with dummy values if needed
 
       - name: Validate Compose file syntax
         run: docker compose config

CLAUDE.md

@@ -1,48 +1,65 @@
-# Use an official Python runtime as a parent image (Alpine-based for minimal vulnerabilities)
-FROM python:3.13-alpine
+# =============================================================================
+# Base stage: official minimal Alpine Python runtime
+# =============================================================================
+FROM python:3.13-alpine AS base
 
-# Set the working directory in the container
 WORKDIR /app
 
-# Prevent Python from writing pyc files to disc
-ENV PYTHONDONTWRITEBYTECODE=1
-# Ensure Python output is sent straight to terminal (useful for logs)
-ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
 
-# Install system dependencies if needed (e.g., for certain Python packages)
-# RUN apt-get update && apt-get install -y --no-install-recommends some-package && rm -rf /var/lib/apt/lists/*
+# =============================================================================
+# Builder stage: build wheels / dependencies
+# =============================================================================
+FROM base AS builder
 
-# Copy dependency definition files
-# If using Poetry:
-# COPY pyproject.toml poetry.lock* ./
-# RUN pip install --no-cache-dir poetry
-# RUN poetry config virtualenvs.create false && poetry install --no-dev --no-interaction --no-ansi
-# If using pip with requirements.txt:
 COPY requirements.txt ./
-RUN pip install --no-cache-dir --upgrade pip
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir --prefix=/install -r requirements.txt
 
-# Copy the rest of the application code
+# =============================================================================
+# Development / Test stage: includes dev tooling from pyproject.toml
+# =============================================================================
+FROM base AS development
+
+# Copy installed production packages
+COPY --from=builder /install /usr/local
+
+# Copy dev dependencies and install test/lint tools
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir black flake8 pytest pytest-asyncio pytest-cov
+
+# Copy application source and tests
 COPY main.py sanitize.py ./
 COPY telegram_mcp ./telegram_mcp
-# COPY session_string_generator.py . # Optional: if needed within the container, otherwise can be run outside
+COPY tests ./tests
 
-# Create a non-root user and switch to it
-RUN adduser --disabled-password --gecos "" appuser && chown -R appuser:appuser /app
-USER appuser
+CMD ["pytest", "--cov", "--cov-report=term-missing"]
+
+# =============================================================================
+# Production stage: slim runtime container with non-root appuser
+# =============================================================================
+FROM base AS production
+
+# Copy only installed dependencies from builder
+COPY --from=builder /install /usr/local
 
-# Define environment variables needed by the application
-# These should be provided at runtime, not hardcoded (especially secrets)
-ENV TELEGRAM_API_ID=""
-ENV TELEGRAM_API_HASH=""
-# Specify one of the following at runtime:
-# Default session filename
-ENV TELEGRAM_SESSION_NAME="telegram_mcp_session"
-# Or provide the session string directly
-ENV TELEGRAM_SESSION_STRING=""
+# Copy application source code
+COPY main.py sanitize.py ./
+COPY telegram_mcp ./telegram_mcp
+
+# Create non-root user and setup directories
+RUN adduser --disabled-password --gecos "" appuser && \
+    mkdir -p /app/data/transcripts && \
+    chown -R appuser:appuser /app
+
+USER appuser
 
-# Expose any ports if the application were a web server (not needed for stdio MCP)
-# EXPOSE 8000
+# Runtime environment variables (to be supplied at run/container start)
+ENV TELEGRAM_API_ID="" \
+    TELEGRAM_API_HASH="" \
+    TELEGRAM_SESSION_NAME="telegram_mcp_session" \
+    TELEGRAM_SESSION_STRING=""
 
-# Define the command to run the application
 CMD ["python", "main.py"]

Dockerfile

@@ -25,6 +25,7 @@ Message sent successfully:
 
 ## Contents
 
+- [Skills & Practical Workflows](skills/README.md)
 - [What It Can Do](#what-it-can-do)
 - [Requirements](#requirements)
 - [Quick Start](#quick-start)
@@ -40,6 +41,15 @@ Message sent successfully:
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
+## Skills & Workflows
+
+Looking for ready-to-use workflows, prompt examples, or integration recipes?
+Explore the [**Skills Documentation**](skills/README.md) for step-by-step guides on:
+- [Summarizing unread messages safely](skills/examples/summarize-latest-unread.md)
+- [Drafting replies without sending](skills/examples/draft-replies-without-sending.md)
+- [Triaging action items & urgent requests](skills/examples/triage-and-action-items.md)
+- [Searching chat history and expanding context](skills/examples/search-chat-and-summarize-context.md)
+
 ## What It Can Do
 
 The server currently includes 80+ MCP tools grouped into these areas:
@@ -159,7 +169,10 @@ uv sync
 uv run session_string_generator.py
 ```
 
-Follow the prompts. Save the generated session string securely.
+Follow the prompts. Save the generated session string securely. A session
+string is convenient for initial setup and portable deployments; for a
+long-running server, migrate it to a persistent file session after configuring
+your environment (see below).
 
 For scripted setup or operational runbooks, choose the login method explicitly:
 
@@ -189,6 +202,43 @@ TELEGRAM_API_HASH=your_api_hash_here
 TELEGRAM_SESSION_STRING=your_session_string_here
 ```
 
+### Recommended: Persistent Session for Long-Running Servers
+
+`StringSession` stores the Telegram authorization key, but not Telethon's update
+state. After a restart, a busy account can therefore receive a large backlog of
+updates. A local SQLite session persists the update cursor and entity cache, so
+subsequent reconnects receive only the missed delta.
+
+Stop all running telegram-mcp processes, then migrate the string configured in
+`.env`:
+
+```bash
+uv run telegram-mcp-migrate-session
+```
+
+The command verifies the new session with Telegram and prints the exact setting
+to use. Update `.env` as instructed, for example:
+
+```env
+# Remove or comment this out; it takes precedence when both are present.
+# TELEGRAM_SESSION_STRING=your_session_string_here
+TELEGRAM_SESSION_NAME=/absolute/path/to/telegram_mcp_session
+```
+
+The resulting `.session` file contains account credentials. Keep it private and
+do not commit it. The repository's `.gitignore` already excludes session files.
+
+For a labeled account, use `--account` with the same label:
+
+```bash
+uv run telegram-mcp-migrate-session --account work
+```
+
+This reads `TELEGRAM_SESSION_STRING_WORK` and writes the corresponding
+`TELEGRAM_SESSION_NAME_WORK` instruction. Use `--target PATH` to choose another
+destination. Do not run the migration while another process is using the source
+session.
+
 By default, all Telegram MCP tools are exposed. If you want to prevent MCP
 clients from sending messages or performing chat/account mutations, set
 `TELEGRAM_EXPOSED_TOOLS=read-only` to expose only tools annotated with
@@ -374,8 +424,10 @@ Telegram throttles and may flag accounts that open many parallel sessions.
 
 Every tool call also has a server-side ceiling of 55 seconds, configured with
 `TELEGRAM_TOOL_TIMEOUT_SECONDS`. A timed-out Telegram request returns an explicit
-MCP error instead of leaving the client waiting indefinitely. Set the value to
-`0` only for a deliberately unbounded operator session.
+MCP error instead of leaving the client waiting indefinitely. The error says
+that completion is unknown: a write may already have succeeded, so check the
+destination before retrying. Set the value to `0` only for a deliberately
+unbounded operator session.
 
 Register the shared server with clients:
 
@@ -539,12 +591,13 @@ bypassing the proxy.
 
 ## File Path Security
 
-File-path tools are disabled until allowed roots are configured. This affects tools such as `send_file`, `download_media`, `upload_file`, `send_voice`, `send_sticker`, `set_profile_photo`, and `edit_chat_photo`.
+File-path and media tools (`send_file`, `download_media`, `upload_file`, `send_voice`, `send_sticker`, `set_profile_photo`, `edit_chat_photo`, and `send_album`) are registered and supported, but remain strictly disabled by default until allowed roots are configured (safe-by-default to prevent unauthorized file access).
 
 Allowed roots can come from:
 
-- Server CLI arguments, used as a fallback.
-- MCP client Roots, when supported by the client.
+- **Environment Variable (`TELEGRAM_ALLOWED_ROOTS`):** Semicolon- (`;`) or comma- (`,`) separated paths (also supports colon `:` on POSIX systems). Ideal for Docker, headless daemon setups, and MCP clients that pass settings via environment.
+- **Server CLI arguments:** Positional folder paths passed to `main.py`, used as a server-side fallback.
+- **MCP client Roots:** Configured directly in supported MCP clients (`roots/list`).
 
 Security behavior:
 
@@ -567,13 +620,20 @@ Security behavior:
   and `upload_file` have no extension limit by default; see
   `TELEGRAM_FILE_EXTENSIONS` above to add one.
 
-Run with allowed roots:
+Run with allowed roots via environment variable:
+
+```bash
+# Semicolon- or comma-separated roots
+TELEGRAM_ALLOWED_ROOTS="/data/telegram,/tmp/telegram-mcp" uv run main.py
+```
+
+Or run with allowed roots via CLI positional arguments:
 
 ```bash
 uv run main.py /data/telegram /tmp/telegram-mcp
 ```
 
-From an MCP client configuration, pass the same roots after `main.py`:
+From an MCP client configuration, you can pass roots via `env` or as arguments after `main.py`:
 
 ```json
 {
@@ -751,7 +811,7 @@ Telegram messages, display names, chat titles, and button labels are untrusted c
   Then set `TELEGRAM_SESSION_STRING` in `.env`. The MCP server does not perform
   interactive phone-code login over stdio.
 - **Invalid API credentials:** verify `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` at [my.telegram.org/apps](https://my.telegram.org/apps).
-- **Database is locked:** prefer string sessions, or make sure no other process is using the same file session.
+- **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).
 - **File tools are disabled:** pass allowed roots or configure MCP Roots in your client.
 - **Path rejected:** ensure the path is inside an allowed root and does not use traversal or wildcard patterns.

README.md

@@ -5,6 +5,7 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+      target: production
     container_name: telegram-mcp
     # Load environment variables from a .env file in the same directory
     env_file: