mcp-server-telegram-bot 0.2.0__tar.gz

mcp_server_telegram_bot-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

mcp_server_telegram_bot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirmaxamat
+
+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.

mcp_server_telegram_bot-0.2.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: mcp-server-telegram-bot
+Version: 0.2.0
+Summary: MCP server that lets AI agents send Telegram messages and files via a bot
+Project-URL: Homepage, https://github.com/mirmakhamat/mcp-server-telegram-bot
+Project-URL: Issues, https://github.com/mirmakhamat/mcp-server-telegram-bot/issues
+Author: Mirmaxamat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot,claude,mcp,telegram
+Requires-Python: >=3.10
+Requires-Dist: fpdf2>=2.8.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.2
+Description-Content-Type: text/markdown
+
+# mcp-server-telegram-bot
+
+MCP server that lets AI agents send Telegram messages and files through your own bot.
+The token is read from the environment and never reaches the agent.
+
+## Setup
+1. Create a bot with @BotFather and copy its token.
+2. Send `/start` to your bot from the chat that should receive messages.
+3. Install and register (replace the placeholders):
+
+```
+claude mcp add telegram \
+  -e TELEGRAM_BOT_TOKEN=<token> \
+  -e ALLOWED_CHAT_IDS=<chat_id> \
+  -- uvx mcp-server-telegram-bot
+```
+
+Use `--scope user` so it works in every folder. When running from a checkout use `uv run --project <dir>` (not `--directory`), otherwise the server cannot see the session directory.
+
+Don't know your chat id? Register with a temporary `ALLOWED_CHAT_IDS=0`, ask the agent to run `get_updates`, then re-register with the real id.
+
+## Environment
+| Variable | Meaning |
+|---|---|
+| `TELEGRAM_BOT_TOKEN` | Bot token (required) |
+| `ALLOWED_CHAT_IDS` | Comma-separated chats, each `id` or `name=id` (e.g. `me=111,ali=222`); first is default (required) |
+| `ALLOWED_DIRS` | Extra directories whose files are sent without asking (optional) |
+| `ACCESS_MODE` | `ask` (default): files outside the allowed roots need your confirmation. `strict`: they are refused |
+| `DENY_PATHS` | Extra files/dirs that are never sent (optional) |
+
+## Typical use
+- "Send `report.pdf` to me when you finish" -> `send_document(path)` to the default chat.
+- "Send the result to Ali" -> `send_message(text, chat_id="ali")`.
+- A person can only receive messages after they open the bot and press Start. Telegram blocks the bot otherwise.
+
+## Tools
+`send_message(text, chat_id?)`, `send_document(path, caption?, chat_id?)`, `send_photo(path, caption?, chat_id?)`, `send_generated(name, content, format, caption?, chat_id?)`, `get_updates(limit?)`
+Access management: `list_access()`, `add_chat(chat_id, name?)`, `add_dir(path)`, `remove_chat(chat)`, `remove_dir(path)`
+
+## File access
+1. **Never sent**, whatever env or the agent says: `.ssh`, `.gnupg`, `.aws`, `.kube`, `.docker`, `~/.claude*`, browser profiles, keyrings, `/etc`, `/proc`, `/sys`; `.env*`, `.netrc`, `.pgpass`, `.git-credentials`, `.git/config`, `id_*` keys, `*.pem`, `*.key`, `*.p12`, `*.kdbx`, shell history. Paths are resolved with `realpath`, so symlinks and `..` do not help. Add your own with `DENY_PATHS`.
+2. **Sent directly:** files inside the directory the session was started in (not if that is `/` or your home), and inside `ALLOWED_DIRS`.
+3. **Everything else:** you are asked to confirm each time (`ACCESS_MODE=ask`), or it is refused (`strict`).
+
+`send_generated` builds the file from text the agent provides (pdf, md, txt, csv, json) and reads nothing from disk, so it needs no folder access: "send me a PDF of everything you did".
+
+Every send is logged (time, chat, path or file name, never contents) to `~/.local/state/telegram-mcp/sent.log`.
+
+Limits: the deny list cannot know every secret. A password inside an ordinary file in the session directory will be sent if the agent is told to send it. Files go to Telegram's servers. Max 50 MB. Use one bot per user.
+
+## Changing access from the agent
+- `add_chat` / `add_dir` ask the user to confirm (MCP elicitation). If the client cannot ask, the call is refused.
+- `/` and the home directory cannot be added. Protected dirs stay blocked.
+- Additions are saved in `~/.config/mcp-server-telegram-bot/state.json` (override with `TELEGRAM_MCP_STATE`).
+- `remove_*` only removes runtime additions. Env entries are changed in the environment.
+
+## Development
+```
+uv sync && uv run pytest
+```

mcp_server_telegram_bot-0.2.0/README.md

@@ -0,0 +1,60 @@
+# mcp-server-telegram-bot
+
+MCP server that lets AI agents send Telegram messages and files through your own bot.
+The token is read from the environment and never reaches the agent.
+
+## Setup
+1. Create a bot with @BotFather and copy its token.
+2. Send `/start` to your bot from the chat that should receive messages.
+3. Install and register (replace the placeholders):
+
+```
+claude mcp add telegram \
+  -e TELEGRAM_BOT_TOKEN=<token> \
+  -e ALLOWED_CHAT_IDS=<chat_id> \
+  -- uvx mcp-server-telegram-bot
+```
+
+Use `--scope user` so it works in every folder. When running from a checkout use `uv run --project <dir>` (not `--directory`), otherwise the server cannot see the session directory.
+
+Don't know your chat id? Register with a temporary `ALLOWED_CHAT_IDS=0`, ask the agent to run `get_updates`, then re-register with the real id.
+
+## Environment
+| Variable | Meaning |
+|---|---|
+| `TELEGRAM_BOT_TOKEN` | Bot token (required) |
+| `ALLOWED_CHAT_IDS` | Comma-separated chats, each `id` or `name=id` (e.g. `me=111,ali=222`); first is default (required) |
+| `ALLOWED_DIRS` | Extra directories whose files are sent without asking (optional) |
+| `ACCESS_MODE` | `ask` (default): files outside the allowed roots need your confirmation. `strict`: they are refused |
+| `DENY_PATHS` | Extra files/dirs that are never sent (optional) |
+
+## Typical use
+- "Send `report.pdf` to me when you finish" -> `send_document(path)` to the default chat.
+- "Send the result to Ali" -> `send_message(text, chat_id="ali")`.
+- A person can only receive messages after they open the bot and press Start. Telegram blocks the bot otherwise.
+
+## Tools
+`send_message(text, chat_id?)`, `send_document(path, caption?, chat_id?)`, `send_photo(path, caption?, chat_id?)`, `send_generated(name, content, format, caption?, chat_id?)`, `get_updates(limit?)`
+Access management: `list_access()`, `add_chat(chat_id, name?)`, `add_dir(path)`, `remove_chat(chat)`, `remove_dir(path)`
+
+## File access
+1. **Never sent**, whatever env or the agent says: `.ssh`, `.gnupg`, `.aws`, `.kube`, `.docker`, `~/.claude*`, browser profiles, keyrings, `/etc`, `/proc`, `/sys`; `.env*`, `.netrc`, `.pgpass`, `.git-credentials`, `.git/config`, `id_*` keys, `*.pem`, `*.key`, `*.p12`, `*.kdbx`, shell history. Paths are resolved with `realpath`, so symlinks and `..` do not help. Add your own with `DENY_PATHS`.
+2. **Sent directly:** files inside the directory the session was started in (not if that is `/` or your home), and inside `ALLOWED_DIRS`.
+3. **Everything else:** you are asked to confirm each time (`ACCESS_MODE=ask`), or it is refused (`strict`).
+
+`send_generated` builds the file from text the agent provides (pdf, md, txt, csv, json) and reads nothing from disk, so it needs no folder access: "send me a PDF of everything you did".
+
+Every send is logged (time, chat, path or file name, never contents) to `~/.local/state/telegram-mcp/sent.log`.
+
+Limits: the deny list cannot know every secret. A password inside an ordinary file in the session directory will be sent if the agent is told to send it. Files go to Telegram's servers. Max 50 MB. Use one bot per user.
+
+## Changing access from the agent
+- `add_chat` / `add_dir` ask the user to confirm (MCP elicitation). If the client cannot ask, the call is refused.
+- `/` and the home directory cannot be added. Protected dirs stay blocked.
+- Additions are saved in `~/.config/mcp-server-telegram-bot/state.json` (override with `TELEGRAM_MCP_STATE`).
+- `remove_*` only removes runtime additions. Env entries are changed in the environment.
+
+## Development
+```
+uv sync && uv run pytest
+```

mcp_server_telegram_bot-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mcp-server-telegram-bot"
+version = "0.2.0"
+description = "MCP server that lets AI agents send Telegram messages and files via a bot"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mirmaxamat" }]
+keywords = ["mcp", "telegram", "bot", "claude"]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.2,<2",
+    "httpx>=0.27",
+    "fpdf2>=2.8.9",
+]
+
+[project.scripts]
+mcp-server-telegram-bot = "telegram_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/mirmakhamat/mcp-server-telegram-bot"
+Issues = "https://github.com/mirmakhamat/mcp-server-telegram-bot/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/telegram_mcp"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["CLAUDE.md", ".env*", "uv.lock"]
+include = ["src", "tests", "README.md", "pyproject.toml", ".env.example"]

mcp_server_telegram_bot-0.2.0/src/telegram_mcp/fonts/LICENSE-DejaVu

@@ -0,0 +1,187 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org.
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+TeX Gyre DJV Math
+-----------------
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+
+Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
+(on behalf of TeX users groups) are in public domain.
+
+Letters imported from Euler Fraktur from AMSfonts are (c) American
+Mathematical Society (see below).
+Bitstream Vera Fonts Copyright
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
+is a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license (“Fonts”) and associated
+documentation
+files (the “Font Software”), to reproduce and distribute the Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute,
+and/or sell copies of the Font Software, and to permit persons  to whom
+the Font Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be
+included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional
+glyphs or characters may be added to the Fonts, only if the fonts are
+renamed
+to names not containing either the words “Bitstream” or the word “Vera”.
+
+This License becomes null and void to the extent applicable to Fonts or
+Font Software
+that has been modified and is distributed under the “Bitstream Vera”
+names.
+
+The Font Software may be sold as part of a larger software package but
+no copy
+of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
+SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
+ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
+INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+Except as contained in this notice, the names of GNOME, the GNOME
+Foundation,
+and Bitstream Inc., shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Font Software without prior written
+authorization from the GNOME Foundation or Bitstream Inc., respectively.
+For further information, contact: fonts at gnome dot org.
+
+AMSFonts (v. 2.2) copyright
+
+The PostScript Type 1 implementation of the AMSFonts produced by and
+previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
+available for general use. This has been accomplished through the
+cooperation
+of a consortium of scientific publishers with Blue Sky Research and Y&Y.
+Members of this consortium include:
+
+Elsevier Science IBM Corporation Society for Industrial and Applied
+Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
+
+In order to assure the authenticity of these fonts, copyright will be
+held by
+the American Mathematical Society. This is not meant to restrict in any way
+the legitimate use of the fonts, such as (but not limited to) electronic
+distribution of documents containing these fonts, inclusion of these fonts
+into other public domain or commercial font collections or computer
+applications, use of the outline data to create derivative fonts and/or
+faces, etc. However, the AMS does require that the AMS copyright notice be
+removed from any derivative versions of the fonts which have been altered in
+any way. In addition, to ensure the fidelity of TeX documents using Computer
+Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+has requested that any alterations which yield different font metrics be
+given a different name.
+
+$Id$

mcp_server_telegram_bot-0.2.0/src/telegram_mcp/pdf.py

@@ -0,0 +1,36 @@
+import os
+
+from fpdf import FPDF
+
+FONTS = os.path.join(os.path.dirname(__file__), "fonts")
+MAX_CHARS = 500_000
+
+
+def render(content: str, title: str | None = None) -> bytes:
+    """Plain text to PDF. '# ' and '## ' lines are headings, '- ' lines are bullets."""
+    if len(content) > MAX_CHARS:
+        raise ValueError(f"content is longer than {MAX_CHARS} characters")
+    pdf = FPDF()
+    pdf.add_font("dv", "", os.path.join(FONTS, "DejaVuSans.ttf"))
+    pdf.add_font("dv", "B", os.path.join(FONTS, "DejaVuSans-Bold.ttf"))
+    pdf.add_page()
+    def line(text, size, style="", indent=0):
+        pdf.set_font("dv", style, size)
+        pdf.set_x(pdf.l_margin + indent)
+        pdf.multi_cell(0, size * 0.55, text, new_x="LMARGIN", new_y="NEXT")
+
+    if title:
+        line(title, 18, "B")
+        pdf.ln(3)
+    for raw in content.splitlines():
+        if raw.startswith("## "):
+            line(raw[3:], 13, "B")
+        elif raw.startswith("# "):
+            line(raw[2:], 16, "B")
+        elif raw.startswith(("- ", "* ")):
+            line("• " + raw[2:], 11, indent=4)
+        elif raw.strip():
+            line(raw, 11)
+        else:
+            pdf.ln(3)
+    return bytes(pdf.output())

mcp_server_telegram_bot-0.2.0/src/telegram_mcp/security.py

@@ -0,0 +1,174 @@
+import fnmatch
+import json
+import os
+from dataclasses import dataclass, field, replace
+
+MAX_BYTES = 50 * 1024 * 1024  # Bot API upload limit
+# Never sendable, whatever env or the user says.
+BLOCKED_DIRS = {".ssh", ".gnupg", ".aws", ".kube", ".docker", ".password-store"}
+BLOCKED_HOME = (
+    ".config/gcloud", ".config/telegram-mcp", ".local/state/telegram-mcp", ".local/share/keyrings",
+    ".claude", ".mozilla", ".config/google-chrome", ".config/chromium", ".config/BraveSoftware",
+)
+BLOCKED_ABS = ("/etc", "/proc", "/sys", "/dev", "/boot", "/root")
+BLOCKED_NAMES = (
+    ".env*", ".netrc", ".pgpass", ".git-credentials", "id_rsa*", "id_ed25519*", "id_ecdsa*", "id_dsa*",
+    "*.pem", "*.key", "*.p12", "*.pfx", "*.kdbx", ".bash_history", ".zsh_history", ".claude.json",
+    "credentials", "credentials.json",
+)
+
+
+class ConfigError(Exception):
+    pass
+
+
+class DeniedError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    token: str
+    chat_ids: tuple[str, ...]
+    dirs: tuple[str, ...]
+    names: dict = field(default_factory=dict)  # lowercase name -> chat id
+    session_dir: str = ""  # auto-allowed; empty when the session runs in / or home
+    mode: str = "ask"  # ask = confirm files outside allowed roots, strict = refuse them
+    deny: tuple[str, ...] = ()  # extra user-defined blocked paths
+
+
+def parse_chat(entry: str) -> tuple[str | None, str]:
+    """'ali=123' -> ('ali', '123'); '123' -> (None, '123')."""
+    name, sep, cid = entry.rpartition("=")
+    return (name.strip() or None, cid.strip()) if sep else (None, entry.strip())
+
+
+def _chats(entries) -> tuple[tuple[str, ...], dict]:
+    ids, names = [], {}
+    for e in entries:
+        name, cid = parse_chat(e)
+        if cid not in ids:
+            ids.append(cid)
+        if name:
+            names[name.lower()] = cid
+    return tuple(ids), names
+
+
+def _split(value: str) -> tuple[str, ...]:
+    return tuple(p.strip() for p in value.split(",") if p.strip())
+
+
+def load_config(env=os.environ, cwd: str | None = None) -> Config:
+    token = env.get("TELEGRAM_BOT_TOKEN", "").strip()
+    chat_ids, names = _chats(_split(env.get("ALLOWED_CHAT_IDS", "")))
+    if not token:
+        raise ConfigError("TELEGRAM_BOT_TOKEN is not set")
+    if not chat_ids:
+        raise ConfigError("ALLOWED_CHAT_IDS is not set")
+    dirs = tuple(os.path.realpath(os.path.expanduser(d)) for d in _split(env.get("ALLOWED_DIRS", "")))
+    mode = env.get("ACCESS_MODE", "ask").strip().lower()
+    if mode not in ("ask", "strict"):
+        raise ConfigError("ACCESS_MODE must be 'ask' or 'strict'")
+    session = os.path.realpath(cwd or os.getcwd())
+    if session in (os.sep, os.path.realpath(os.path.expanduser("~"))):
+        session = ""
+    deny = tuple(os.path.realpath(os.path.expanduser(d)) for d in _split(env.get("DENY_PATHS", "")))
+    return Config(token, chat_ids, dirs, names, session, mode, deny)
+
+
+def resolve_chat(cfg: Config, chat_id: str | int | None) -> str:
+    if chat_id is None or str(chat_id) == "":
+        return cfg.chat_ids[0]
+    key = str(chat_id).strip()
+    key = cfg.names.get(key.lower(), key)
+    if key not in cfg.chat_ids:
+        raise DeniedError("chat is not in ALLOWED_CHAT_IDS")
+    return key
+
+
+def _under(real: str, root: str) -> bool:
+    return os.path.commonpath([real, root]) == root
+
+
+def is_blocked(cfg: Config, real: str) -> bool:
+    home = os.path.realpath(os.path.expanduser("~"))
+    parts = real.split(os.sep)
+    if BLOCKED_DIRS & set(parts):
+        return True
+    if any(_under(real, os.path.join(home, h)) for h in BLOCKED_HOME):
+        return True
+    if any(_under(real, a) for a in BLOCKED_ABS) or any(_under(real, d) for d in cfg.deny):
+        return True
+    if any(fnmatch.fnmatch(parts[-1], n) for n in BLOCKED_NAMES):
+        return True
+    return ".git" in parts[:-1] and parts[-1] == "config"
+
+
+def check_path(cfg: Config, path: str) -> str:
+    """Return the real path, or raise if it is protected, missing or too large."""
+    real = os.path.realpath(os.path.expanduser(path))
+    if is_blocked(cfg, real):
+        raise DeniedError("path points to a protected file")
+    if not os.path.isfile(real):
+        raise DeniedError("not a regular file")
+    if os.path.getsize(real) > MAX_BYTES:
+        raise DeniedError("file is larger than 50 MB")
+    return real
+
+
+def is_inside(cfg: Config, real: str) -> bool:
+    """True when the file may be sent without asking: ALLOWED_DIRS or the session directory."""
+    roots = cfg.dirs + ((cfg.session_dir,) if cfg.session_dir else ())
+    return any(_under(real, r) for r in roots)
+
+
+# Runtime additions (added via tools) live in a state file; env values stay the base.
+def state_path() -> str:
+    return os.path.expanduser(os.environ.get("TELEGRAM_MCP_STATE", "~/.config/telegram-mcp/state.json"))
+
+
+def load_extra(path: str) -> dict:
+    try:
+        with open(path) as f:
+            d = json.load(f)
+        return {"chats": list(d.get("chats", [])), "dirs": list(d.get("dirs", []))}
+    except (OSError, ValueError):
+        return {"chats": [], "dirs": []}
+
+
+def save_extra(path: str, extra: dict) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(extra, f)
+
+
+def merge(base: Config, extra: dict) -> Config:
+    ids, names = _chats(extra["chats"])
+    chats = base.chat_ids + tuple(c for c in ids if c not in base.chat_ids)
+    dirs = base.dirs + tuple(d for d in extra["dirs"] if d not in base.dirs)
+    return replace(base, chat_ids=chats, dirs=dirs, names={**names, **base.names})
+
+
+def validate_chat(chat_id: str) -> str:
+    c = str(chat_id).strip()
+    if not c.lstrip("-").isdigit():
+        raise DeniedError("chat_id must be a numeric id")
+    return c
+
+
+def validate_name(name: str) -> str:
+    n = name.strip()
+    if not n.replace("_", "").replace("-", "").isalnum():
+        raise DeniedError("name may contain only letters, digits, _ and -")
+    return n
+
+
+def validate_dir(cfg: Config, path: str) -> str:
+    real = os.path.realpath(os.path.expanduser(path))
+    if real == os.sep or real == os.path.realpath(os.path.expanduser("~")):
+        raise DeniedError("directory is too broad (root or home)")
+    if is_blocked(cfg, real):
+        raise DeniedError("directory is protected")
+    if not os.path.isdir(real):
+        raise DeniedError("not a directory")
+    return real

mcp_server_telegram_bot-0.2.0/src/telegram_mcp/server.py

@@ -0,0 +1,190 @@
+import os
+import re
+import sys
+from datetime import datetime
+
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import BaseModel
+
+from . import pdf, security, telegram
+
+FORMATS = ("pdf", "md", "txt", "csv", "json")
+mcp = FastMCP("telegram")
+_base: security.Config | None = None
+
+
+def base() -> security.Config:
+    global _base
+    if _base is None:
+        _base = security.load_config()
+    return _base
+
+
+def cfg() -> security.Config:
+    return security.merge(base(), security.load_extra(security.state_path()))
+
+
+@mcp.tool()
+async def send_message(text: str, chat_id: str | None = None) -> str:
+    """Send a text message. chat_id is an allowed id or name (see list_access); omitted = default chat."""
+    c = cfg()
+    r = await telegram.call(c.token, "sendMessage", {"chat_id": security.resolve_chat(c, chat_id), "text": text})
+    return f"sent, message_id={r['message_id']}"
+
+
+def _log(chat: str, what: str) -> None:
+    """Append-only record of what was sent where. Never stores file contents."""
+    path = os.path.expanduser(os.environ.get("TELEGRAM_MCP_LOG", "~/.local/state/telegram-mcp/sent.log"))
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a") as f:
+            f.write(f"{datetime.now().isoformat(timespec='seconds')}\tchat={chat}\t{what}\n")
+    except OSError:
+        pass  # logging must never block a send
+
+
+async def _send_file(ctx: Context, method: str, field: str, path: str, caption: str | None, chat_id: str | None) -> str:
+    c = cfg()
+    chat = security.resolve_chat(c, chat_id)
+    real = security.check_path(c, path)
+    if not security.is_inside(c, real):
+        if c.mode == "strict":
+            raise security.DeniedError("file is outside the session directory and ALLOWED_DIRS (ACCESS_MODE=strict)")
+        await _approve(ctx, f"send {real} to chat {chat}")
+    data = {"chat_id": chat, **({"caption": caption} if caption else {})}
+    with open(real, "rb") as f:
+        r = await telegram.call(c.token, method, data, {field: f})
+    _log(chat, f"file={real}")
+    return f"sent, message_id={r['message_id']}"
+
+
+@mcp.tool()
+async def send_document(ctx: Context, path: str, caption: str | None = None, chat_id: str | None = None) -> str:
+    """Send an existing file. Files in the session directory send directly; elsewhere the user is asked. Secrets (.ssh, .env, keys) are always refused."""
+    return await _send_file(ctx, "sendDocument", "document", path, caption, chat_id)
+
+
+@mcp.tool()
+async def send_photo(ctx: Context, path: str, caption: str | None = None, chat_id: str | None = None) -> str:
+    """Send an existing image as a photo. Same access rules as send_document."""
+    return await _send_file(ctx, "sendPhoto", "photo", path, caption, chat_id)
+
+
+@mcp.tool()
+async def send_generated(
+    name: str, content: str, format: str = "pdf", caption: str | None = None, chat_id: str | None = None
+) -> str:
+    """Create a file from text and send it; reads nothing from disk. format: pdf, md, txt, csv, json.
+    For a pdf, '# ' / '## ' lines are headings and '- ' lines are bullets. Use it for reports, summaries, logs, tables."""
+    if format not in FORMATS:
+        raise ValueError(f"format must be one of: {', '.join(FORMATS)}")
+    c = cfg()
+    chat = security.resolve_chat(c, chat_id)
+    stem = re.sub(r"[^\w.-]+", "_", os.path.splitext(os.path.basename(name))[0]).strip("._") or "file"
+    filename = f"{stem}.{format}"
+    body = pdf.render(content, title=name if format == "pdf" else None) if format == "pdf" else content.encode()
+    if len(body) > security.MAX_BYTES:
+        raise security.DeniedError("file is larger than 50 MB")
+    data = {"chat_id": chat, **({"caption": caption} if caption else {})}
+    r = await telegram.call(c.token, "sendDocument", data, {"document": (filename, body)})
+    _log(chat, f"generated={filename} bytes={len(body)}")
+    return f"sent {filename}, message_id={r['message_id']}"
+
+
+@mcp.tool()
+async def get_updates(limit: int = 10) -> list[dict]:
+    """List recent messages sent to the bot (shows chat ids; helps first-time setup)."""
+    r = await telegram.call(cfg().token, "getUpdates", {"limit": limit})
+    return [
+        {"chat_id": m["chat"]["id"], "from": m.get("from", {}).get("first_name"), "text": (m.get("text") or "")[:200]}
+        for u in r
+        if (m := u.get("message"))
+    ]
+
+
+class Confirm(BaseModel):
+    confirm: bool = False
+
+
+async def _approve(ctx: Context, what: str) -> None:
+    """Widening access needs a human yes. Fails closed if the client cannot ask."""
+    try:
+        r = await ctx.elicit(f"Allow mcp-server-telegram-bot to {what}?", Confirm)
+    except Exception:
+        raise security.DeniedError("client cannot ask for confirmation; set it in the environment instead") from None
+    if r.action != "accept" or not r.data.confirm:
+        raise security.DeniedError("not approved")
+
+
+def _edit(kind: str, value: str, add: bool) -> str:
+    path = security.state_path()
+    extra = security.load_extra(path)
+    items = extra[kind]
+    if add and value not in items:
+        items.append(value)
+    elif not add:
+        if value not in items:
+            raise security.DeniedError("not a runtime-added entry (env entries are changed in the environment)")
+        items.remove(value)
+    security.save_extra(path, extra)
+    return value
+
+
+@mcp.tool()
+def list_access() -> dict:
+    """Show allowed chats (id and name) and directories. Use names as chat_id when sending."""
+    extra = security.load_extra(security.state_path())
+    c = cfg()
+    by_id = {v: k for k, v in c.names.items()}
+    return {
+        "chats": [{"id": i, "name": by_id.get(i)} for i in c.chat_ids],
+        "dirs": list(c.dirs),
+        "added_at_runtime": extra,
+    }
+
+
+@mcp.tool()
+async def add_chat(chat_id: str, ctx: Context, name: str | None = None) -> str:
+    """Allow another chat id, optionally with a name (e.g. "ali") usable as chat_id later. Asks the user to confirm."""
+    cid = security.validate_chat(chat_id)
+    entry = f"{security.validate_name(name)}={cid}" if name else cid
+    await _approve(ctx, f"send messages to chat {entry}")
+    _edit("chats", entry, True)
+    return f"added chat {entry}"
+
+
+@mcp.tool()
+async def add_dir(path: str, ctx: Context) -> str:
+    """Allow files from another directory (asks the user to confirm)."""
+    real = security.validate_dir(cfg(), path)
+    await _approve(ctx, f"send files from {real}")
+    return f"added dir {_edit('dirs', real, True)}"
+
+
+@mcp.tool()
+def remove_chat(chat: str) -> str:
+    """Remove a chat (id or name) that was added at runtime."""
+    for e in security.load_extra(security.state_path())["chats"]:
+        name, cid = security.parse_chat(e)
+        if chat.strip() in (cid, name):
+            _edit("chats", e, False)
+            return f"removed chat {e}"
+    raise security.DeniedError("not a runtime-added entry (env entries are changed in the environment)")
+
+
+@mcp.tool()
+def remove_dir(path: str) -> str:
+    """Remove a directory that was added at runtime."""
+    return f"removed dir {_edit('dirs', security.validate_dir(cfg(), path), False)}"
+
+
+def main() -> None:
+    try:
+        base()
+    except security.ConfigError as e:
+        sys.exit(f"mcp-server-telegram-bot: {e}")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_server_telegram_bot-0.2.0/src/telegram_mcp/telegram.py

@@ -0,0 +1,27 @@
+import logging
+
+import httpx
+
+# httpx logs full request URLs at INFO, and the URL contains the bot token
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+
+class TelegramError(Exception):
+    pass
+
+
+async def call(token: str, method: str, data=None, files=None, client: httpx.AsyncClient | None = None) -> dict:
+    """Call a Bot API method. Errors never include the URL, so the token cannot leak."""
+    own = client is None
+    client = client or httpx.AsyncClient(timeout=60)
+    try:
+        r = await client.post(f"https://api.telegram.org/bot{token}/{method}", data=data, files=files)
+        body = r.json()
+    except (httpx.HTTPError, ValueError) as e:
+        raise TelegramError(f"request failed: {type(e).__name__}") from None
+    finally:
+        if own:
+            await client.aclose()
+    if not body.get("ok"):
+        raise TelegramError(f"Telegram error {body.get('error_code')}: {body.get('description')}")
+    return body["result"]

mcp_server_telegram_bot-0.2.0/tests/test_security.py

@@ -0,0 +1,286 @@
+import asyncio
+import os
+
+import httpx
+import pytest
+
+from telegram_mcp import security, telegram
+
+TOKEN = "123456:secret-token"
+
+
+def cfg(tmp_path, chats=("1", "2")):
+    return security.load_config(
+        {"TELEGRAM_BOT_TOKEN": TOKEN, "ALLOWED_CHAT_IDS": ",".join(chats), "ALLOWED_DIRS": str(tmp_path)}
+    )
+
+
+def test_missing_env():
+    with pytest.raises(security.ConfigError):
+        security.load_config({"ALLOWED_CHAT_IDS": "1"})
+    with pytest.raises(security.ConfigError):
+        security.load_config({"TELEGRAM_BOT_TOKEN": "x"})
+
+
+def test_chat(tmp_path):
+    c = cfg(tmp_path)
+    assert security.resolve_chat(c, None) == "1"
+    assert security.resolve_chat(c, 2) == "2"
+    with pytest.raises(security.DeniedError):
+        security.resolve_chat(c, "999")
+
+
+def test_path_ok_and_traversal(tmp_path):
+    c = cfg(tmp_path)
+    f = tmp_path / "a.txt"
+    f.write_text("hi")
+    real = security.check_path(c, str(f))
+    assert real == str(f.resolve()) and security.is_inside(c, real)
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    out = security.check_path(c, str(sub / ".." / "a.txt"))
+    assert security.is_inside(c, out)
+    outside = tmp_path.parent / "elsewhere.txt"
+    outside.write_text("x")
+    assert not security.is_inside(c, security.check_path(c, str(sub / ".." / ".." / "elsewhere.txt")))
+
+
+def test_symlink_escape(tmp_path):
+    allowed = tmp_path / "ok"
+    allowed.mkdir()
+    secret = tmp_path / "secret.txt"
+    secret.write_text("x")
+    link = allowed / "link.txt"
+    os.symlink(secret, link)
+    c = cfg(allowed)
+    assert not security.is_inside(c, security.check_path(c, str(link)))  # resolves outside, so it must ask
+
+
+def test_symlink_to_protected_is_refused(tmp_path):
+    key = tmp_path / ".ssh"
+    key.mkdir()
+    (key / "id").write_text("x")
+    link = tmp_path / "innocent.txt"
+    os.symlink(key / "id", link)
+    with pytest.raises(security.DeniedError):
+        security.check_path(cfg(tmp_path), str(link))
+
+
+def test_protected_and_size(tmp_path, monkeypatch):
+    c = cfg(tmp_path)
+    (tmp_path / ".env").write_text("x")
+    (tmp_path / ".ssh").mkdir()
+    (tmp_path / ".ssh" / "id").write_text("x")
+    for p in (tmp_path / ".env", tmp_path / ".ssh" / "id"):
+        with pytest.raises(security.DeniedError):
+            security.check_path(c, str(p))
+    big = tmp_path / "big.bin"
+    big.write_text("x")
+    monkeypatch.setattr(security, "MAX_BYTES", 0)
+    with pytest.raises(security.DeniedError):
+        security.check_path(c, str(big))
+
+
+def test_session_dir_auto_allowed(tmp_path):
+    work = tmp_path / "work"
+    work.mkdir()
+    f = work / "r.txt"
+    f.write_text("x")
+    env = {"TELEGRAM_BOT_TOKEN": "x", "ALLOWED_CHAT_IDS": "1"}
+    c = security.load_config(env, cwd=str(work))
+    assert security.is_inside(c, security.check_path(c, str(f)))
+    other = tmp_path / "other.txt"
+    other.write_text("x")
+    assert not security.is_inside(c, security.check_path(c, str(other)))
+
+
+def test_home_or_root_session_is_not_auto_allowed(monkeypatch, tmp_path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    env = {"TELEGRAM_BOT_TOKEN": "x", "ALLOWED_CHAT_IDS": "1"}
+    assert security.load_config(env, cwd=str(tmp_path)).session_dir == ""
+    assert security.load_config(env, cwd="/").session_dir == ""
+
+
+def test_blocked_paths(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    c = security.load_config(
+        {"TELEGRAM_BOT_TOKEN": "x", "ALLOWED_CHAT_IDS": "1", "DENY_PATHS": str(tmp_path / "mine")}, cwd=str(tmp_path / "w")
+    )
+    for rel in (".claude/x.json", ".config/gcloud/k", ".git/config", "a/id_rsa", "a/b.pem", "a/.env.local", "mine/f", ".aws/credentials"):
+        p = tmp_path / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text("x")
+        with pytest.raises(security.DeniedError):
+            security.check_path(c, str(p))
+    with pytest.raises(security.DeniedError):
+        security.check_path(c, "/etc/hostname")
+    ok = tmp_path / "w" / "notes.md"
+    ok.parent.mkdir()
+    ok.write_text("x")
+    assert security.check_path(c, str(ok))
+
+
+def test_bad_access_mode():
+    with pytest.raises(security.ConfigError):
+        security.load_config({"TELEGRAM_BOT_TOKEN": "x", "ALLOWED_CHAT_IDS": "1", "ACCESS_MODE": "open"})
+
+
+def test_error_hides_token():
+    def boom(request):
+        raise httpx.ConnectError("fail " + str(request.url))
+
+    async def run():
+        async with httpx.AsyncClient(transport=httpx.MockTransport(boom)) as cl:
+            await telegram.call(TOKEN, "sendMessage", client=cl)
+
+    with pytest.raises(telegram.TelegramError) as e:
+        asyncio.run(run())
+    assert "secret-token" not in str(e.value)
+
+
+def test_httpx_logger_silenced():
+    import logging
+
+    assert logging.getLogger("httpx").getEffectiveLevel() >= logging.WARNING
+
+
+def test_extra_merge_and_validation(tmp_path, monkeypatch):
+    monkeypatch.setenv("TELEGRAM_MCP_STATE", str(tmp_path / "s" / "state.json"))
+    from telegram_mcp import server
+
+    server._base = cfg(tmp_path)
+    d = tmp_path / "more"
+    d.mkdir()
+    assert server._edit("chats", "7", True) == "7"
+    assert server._edit("dirs", str(d), True) == str(d)
+    c = server.cfg()
+    assert "7" in c.chat_ids and str(d) in c.dirs
+    server._edit("chats", "7", False)
+    assert "7" not in server.cfg().chat_ids
+    with pytest.raises(security.DeniedError):
+        server._edit("chats", "1", False)  # env entry cannot be removed
+    for bad in ("/", os.path.expanduser("~"), str(tmp_path / "nope")):
+        with pytest.raises(security.DeniedError):
+            security.validate_dir(server.cfg(), bad)
+    with pytest.raises(security.DeniedError):
+        security.validate_chat("abc")
+
+
+def test_approve_fails_closed():
+    from types import SimpleNamespace as NS
+
+    from telegram_mcp import server
+
+    class Ctx:
+        def __init__(self, r=None, exc=None):
+            self.r, self.exc = r, exc
+
+        async def elicit(self, *a):
+            if self.exc:
+                raise self.exc
+            return self.r
+
+    ok = NS(action="accept", data=NS(confirm=True))
+    asyncio.run(server._approve(Ctx(ok), "x"))
+    for ctx in (Ctx(NS(action="decline", data=None)), Ctx(NS(action="accept", data=NS(confirm=False))), Ctx(exc=RuntimeError())):
+        with pytest.raises(security.DeniedError):
+            asyncio.run(server._approve(ctx, "x"))
+
+
+def test_chat_names(tmp_path, monkeypatch):
+    monkeypatch.setenv("TELEGRAM_MCP_STATE", str(tmp_path / "state.json"))
+    from telegram_mcp import server
+
+    server._base = security.load_config(
+        {"TELEGRAM_BOT_TOKEN": TOKEN, "ALLOWED_CHAT_IDS": "me=1,2", "ALLOWED_DIRS": ""}
+    )
+    server._edit("chats", "ali=77", True)
+    c = server.cfg()
+    assert security.resolve_chat(c, "Ali") == "77"
+    assert security.resolve_chat(c, "me") == "1"
+    assert security.resolve_chat(c, None) == "1"
+    assert server.remove_chat("ali") == "removed chat ali=77"
+    with pytest.raises(security.DeniedError):
+        security.resolve_chat(server.cfg(), "ali")
+    with pytest.raises(security.DeniedError):
+        server.remove_chat("me")
+    with pytest.raises(security.DeniedError):
+        security.validate_name("a b=c")
+
+
+def test_pdf_render_unicode_and_limits():
+    from telegram_mcp import pdf
+
+    out = pdf.render("# Sarlavha\nOʻzbekcha: gʻoya, ўзбек, қ\n- band\n" + "x" * 500, title="Hisobot")
+    assert out.startswith(b"%PDF")
+    with pytest.raises(ValueError):
+        pdf.render("x" * (pdf.MAX_CHARS + 1))
+
+
+def test_send_generated(tmp_path, monkeypatch):
+    from telegram_mcp import server
+
+    monkeypatch.setenv("TELEGRAM_MCP_STATE", str(tmp_path / "s.json"))
+    monkeypatch.setenv("TELEGRAM_MCP_LOG", str(tmp_path / "sent.log"))
+    server._base = cfg(tmp_path)
+    seen = {}
+
+    async def fake(token, method, data=None, files=None, client=None):
+        seen.update(method=method, data=data, files=files)
+        return {"message_id": 5}
+
+    monkeypatch.setattr(server.telegram, "call", fake)
+    r = asyncio.run(server.send_generated("../../My Report!", "# Hi", "md", chat_id="2"))
+    assert r == "sent My_Report.md, message_id=5"
+    assert seen["data"]["chat_id"] == "2" and seen["files"]["document"][0] == "My_Report.md"
+    asyncio.run(server.send_generated("r", "# Hi", "pdf"))
+    assert seen["files"]["document"][1].startswith(b"%PDF")
+    with pytest.raises(ValueError):
+        asyncio.run(server.send_generated("r", "x", "exe"))
+    with pytest.raises(security.DeniedError):
+        asyncio.run(server.send_generated("r", "x", "md", chat_id="999"))
+    assert "generated=My_Report.md" in (tmp_path / "sent.log").read_text()
+
+
+def test_send_file_tiers(tmp_path, monkeypatch):
+    from types import SimpleNamespace as NS
+
+    from telegram_mcp import server
+
+    monkeypatch.setenv("TELEGRAM_MCP_STATE", str(tmp_path / "s.json"))
+    monkeypatch.setenv("TELEGRAM_MCP_LOG", str(tmp_path / "sent.log"))
+    work = tmp_path / "work"
+    work.mkdir()
+    (work / "in.txt").write_text("x")
+    (tmp_path / "out.txt").write_text("x")
+    sent = []
+
+    async def fake(token, method, data=None, files=None, client=None):
+        sent.append(method)
+        return {"message_id": 1}
+
+    monkeypatch.setattr(server.telegram, "call", fake)
+
+    class Ctx:
+        def __init__(self, yes):
+            self.yes, self.asked = yes, 0
+
+        async def elicit(self, *a):
+            self.asked += 1
+            return NS(action="accept", data=NS(confirm=self.yes))
+
+    def run(mode, path, ctx):
+        env = {"TELEGRAM_BOT_TOKEN": TOKEN, "ALLOWED_CHAT_IDS": "1", "ACCESS_MODE": mode}
+        server._base = security.load_config(env, cwd=str(work))
+        return asyncio.run(server.send_document(ctx, str(path)))
+
+    c = Ctx(True)
+    run("ask", work / "in.txt", c)
+    assert c.asked == 0  # inside session dir: no prompt
+    run("ask", tmp_path / "out.txt", c)
+    assert c.asked == 1  # outside: asked, approved
+    with pytest.raises(security.DeniedError):
+        run("ask", tmp_path / "out.txt", Ctx(False))
+    with pytest.raises(security.DeniedError):
+        run("strict", tmp_path / "out.txt", Ctx(True))
+    assert len(sent) == 2