Merge pull request #187 from antonkulaga/feature/send-media-topic-id

Add topic_id support to media send tools

Author: chigwell

telegram_mcp/tools/chats.py

@@ -235,8 +235,9 @@ async def list_topics(
     """
     Retrieve forum topics from a supergroup with the forum feature enabled.
 
-    Note for LLM: You can send a message to a selected topic via reply_to_message tool
-    by using Topic ID as the message_id parameter.
+    Note for LLM: Send into a topic by passing Topic ID as topic_id to send_file /
+    send_album / send_voice / send_sticker / send_gif, or as message_id to
+    reply_to_message for text.
 
     Args:
         chat_id: The ID of the forum-enabled chat (supergroup).

telegram_mcp/tools/media.py

@@ -10,6 +10,7 @@ async def send_file(
     chat_id: Union[int, str],
     file_path: Union[str, List[str]],
     caption: str = None,
+    topic_id: Optional[int] = None,
     ctx: Optional[Context] = None,
     account: str = None,
 ) -> str:
@@ -20,13 +21,16 @@ async def send_file(
         file_path: Absolute or relative path to the file under allowed roots.
             Pass a list of 2-10 paths to send them as one Telegram media group.
         caption: Optional caption for the file or media group.
+        topic_id: Optional forum topic ID (from list_topics). Sends into that topic
+            in a forum-enabled community/supergroup. Also works as reply_to for a message.
     """
     try:
         if isinstance(file_path, list):
             return await _send_album(
                 chat_id=chat_id,
                 file_paths=file_path,
                 caption=caption,
+                topic_id=topic_id,
                 ctx=ctx,
                 account=account,
             )
@@ -40,18 +44,24 @@ async def send_file(
         if path_error:
             return path_error
         entity = await resolve_entity(chat_id, cl)
-        await cl.send_file(entity, str(safe_path), caption=caption)
+        await cl.send_file(entity, str(safe_path), caption=caption, reply_to=topic_id)
         return f"File sent to chat {chat_id} from {safe_path}."
     except Exception as e:
         return log_and_format_error(
-            "send_file", e, chat_id=chat_id, file_path=file_path, caption=caption
+            "send_file",
+            e,
+            chat_id=chat_id,
+            file_path=file_path,
+            caption=caption,
+            topic_id=topic_id,
         )
 
 
 async def _send_album(
     chat_id: Union[int, str],
     file_paths: List[str],
     caption: str = None,
+    topic_id: Optional[int] = None,
     ctx: Optional[Context] = None,
     account: str = None,
 ) -> str:
@@ -71,7 +81,7 @@ async def _send_album(
         safe_paths.append(str(safe_path))
 
     entity = await resolve_entity(chat_id, cl)
-    await cl.send_file(entity, safe_paths, caption=caption)
+    await cl.send_file(entity, safe_paths, caption=caption, reply_to=topic_id)
     return f"Album sent to chat {chat_id} with {len(safe_paths)} files."
 
 
@@ -84,6 +94,7 @@ async def send_album(
     chat_id: Union[int, str],
     file_paths: List[str],
     caption: str = None,
+    topic_id: Optional[int] = None,
     ctx: Optional[Context] = None,
     account: str = None,
 ) -> str:
@@ -94,6 +105,8 @@ async def send_album(
         chat_id: The chat ID or username.
         file_paths: 2-10 absolute or relative file paths under allowed roots.
         caption: Optional caption for the album. Telegram displays it on the first item.
+        topic_id: Optional forum topic ID (from list_topics). Sends into that topic
+            in a forum-enabled community/supergroup. Also works as reply_to for a message.
     """
     try:
         if not isinstance(file_paths, list):
@@ -102,12 +115,18 @@ async def send_album(
             chat_id=chat_id,
             file_paths=file_paths,
             caption=caption,
+            topic_id=topic_id,
             ctx=ctx,
             account=account,
         )
     except Exception as e:
         return log_and_format_error(
-            "send_album", e, chat_id=chat_id, file_paths=file_paths, caption=caption
+            "send_album",
+            e,
+            chat_id=chat_id,
+            file_paths=file_paths,
+            caption=caption,
+            topic_id=topic_id,
         )
 
 
@@ -183,6 +202,7 @@ async def download_media(
 async def send_voice(
     chat_id: Union[int, str],
     file_path: str,
+    topic_id: Optional[int] = None,
     ctx: Optional[Context] = None,
     account: str = None,
 ) -> str:
@@ -192,6 +212,8 @@ async def send_voice(
     Args:
         chat_id: The chat ID or username.
         file_path: Absolute or relative path under allowed roots to the OGG/OPUS file.
+        topic_id: Optional forum topic ID (from list_topics). Sends into that topic
+            in a forum-enabled community/supergroup. Also works as reply_to for a message.
     """
     try:
         cl = get_client(account)
@@ -215,10 +237,12 @@ async def send_voice(
             return "Voice file must be .ogg or .opus format."
 
         entity = await resolve_entity(chat_id, cl)
-        await cl.send_file(entity, str(safe_path), voice_note=True)
+        await cl.send_file(entity, str(safe_path), voice_note=True, reply_to=topic_id)
         return f"Voice message sent to chat {chat_id} from {safe_path}."
     except Exception as e:
-        return log_and_format_error("send_voice", e, chat_id=chat_id, file_path=file_path)
+        return log_and_format_error(
+            "send_voice", e, chat_id=chat_id, file_path=file_path, topic_id=topic_id
+        )
 
 
 @mcp.tool(
@@ -308,6 +332,7 @@ async def get_sticker_sets(account: str = None) -> str:
 async def send_sticker(
     chat_id: Union[int, str],
     file_path: str,
+    topic_id: Optional[int] = None,
     ctx: Optional[Context] = None,
     account: str = None,
 ) -> str:
@@ -317,6 +342,8 @@ async def send_sticker(
     Args:
         chat_id: The chat ID or username.
         file_path: Absolute or relative path under allowed roots to the .webp sticker file.
+        topic_id: Optional forum topic ID (from list_topics). Sends into that topic
+            in a forum-enabled community/supergroup. Also works as reply_to for a message.
     """
     try:
         cl = get_client(account)
@@ -329,10 +356,12 @@ async def send_sticker(
             return path_error
 
         entity = await resolve_entity(chat_id, cl)
-        await cl.send_file(entity, str(safe_path), force_document=False)
+        await cl.send_file(entity, str(safe_path), force_document=False, reply_to=topic_id)
         return f"Sticker sent to chat {chat_id} from {safe_path}."
     except Exception as e:
-        return log_and_format_error("send_sticker", e, chat_id=chat_id, file_path=file_path)
+        return log_and_format_error(
+            "send_sticker", e, chat_id=chat_id, file_path=file_path, topic_id=topic_id
+        )
 
 
 @mcp.tool(
@@ -399,23 +428,32 @@ async def get_gif_search(query: str, limit: int = 10, account: str = None) -> st
 @mcp.tool(annotations=ToolAnnotations(title="Send Gif", openWorldHint=True, destructiveHint=True))
 @with_account(readonly=False)
 @validate_id("chat_id")
-async def send_gif(chat_id: Union[int, str], gif_id: int, account: str = None) -> str:
+async def send_gif(
+    chat_id: Union[int, str],
+    gif_id: int,
+    topic_id: Optional[int] = None,
+    account: str = None,
+) -> str:
     """
     Send a GIF to a chat by Telegram GIF document ID (not a file path).
 
     Args:
         chat_id: The chat ID or username.
         gif_id: Telegram document ID for the GIF (from get_gif_search).
+        topic_id: Optional forum topic ID (from list_topics). Sends into that topic
+            in a forum-enabled community/supergroup. Also works as reply_to for a message.
     """
     try:
         cl = get_client(account)
         if not isinstance(gif_id, int):
             return "gif_id must be a Telegram document ID (integer), not a file path. Use get_gif_search to find IDs."
         entity = await resolve_entity(chat_id, cl)
-        await cl.send_file(entity, gif_id)
+        await cl.send_file(entity, gif_id, reply_to=topic_id)
         return f"GIF sent to chat {chat_id}."
     except Exception as e:
-        return log_and_format_error("send_gif", e, chat_id=chat_id, gif_id=gif_id)
+        return log_and_format_error(
+            "send_gif", e, chat_id=chat_id, gif_id=gif_id, topic_id=topic_id
+        )
 
 
 __all__ = [

tests/test_media_album.py

@@ -8,11 +8,12 @@ class _DummyClient:
     def __init__(self):
         self.sent = None
 
-    async def send_file(self, entity, file_paths, caption=None):
+    async def send_file(self, entity, file_paths, caption=None, reply_to=None):
         self.sent = {
             "entity": entity,
             "file_paths": file_paths,
             "caption": caption,
+            "reply_to": reply_to,
         }
 
 
@@ -52,6 +53,67 @@ async def _resolve_entity(chat_id, cl):
         "entity": "entity:AgenticAIChat",
         "file_paths": [str(first), str(second)],
         "caption": "pick one",
+        "reply_to": None,
+    }
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tool_name", ["send_album", "send_file"])
+async def test_album_mode_passes_topic_id_as_reply_to(tmp_path, monkeypatch, tool_name):
+    root = (tmp_path / "root").resolve()
+    root.mkdir()
+    first = root / "one.png"
+    second = root / "two.png"
+    first.write_bytes(b"png-one")
+    second.write_bytes(b"png-two")
+
+    client = _DummyClient()
+    monkeypatch.setattr(runtime, "SERVER_ALLOWED_ROOTS", [root])
+    monkeypatch.setattr(media, "clients", {"default": client})
+    monkeypatch.setattr(media, "get_client", lambda account=None: client)
+
+    async def _resolve_entity(chat_id, cl):
+        return "entity:forum"
+
+    monkeypatch.setattr(media, "resolve_entity", _resolve_entity)
+
+    tool = getattr(media, tool_name)
+    result = await tool(
+        "ForumChat",
+        ["one.png", str(second)],
+        caption="topic post",
+        topic_id=777,
+    )
+
+    assert result == "Album sent to chat ForumChat with 2 files."
+    assert client.sent["reply_to"] == 777
+
+
+@pytest.mark.asyncio
+async def test_send_file_passes_topic_id_as_reply_to(tmp_path, monkeypatch):
+    root = (tmp_path / "root").resolve()
+    root.mkdir()
+    path = root / "doc.pdf"
+    path.write_bytes(b"%PDF")
+
+    client = _DummyClient()
+    monkeypatch.setattr(runtime, "SERVER_ALLOWED_ROOTS", [root])
+    monkeypatch.setattr(media, "clients", {"default": client})
+    monkeypatch.setattr(media, "get_client", lambda account=None: client)
+
+    async def _resolve_entity(chat_id, cl):
+        return "entity:forum"
+
+    monkeypatch.setattr(media, "resolve_entity", _resolve_entity)
+
+    result = await media.send_file("ForumChat", "doc.pdf", caption="hello", topic_id=42)
+
+    assert result == f"File sent to chat ForumChat from {path}."
+    assert client.sent == {
+        "entity": "entity:forum",
+        "file_paths": str(path),
+        "caption": "hello",
+        "reply_to": 42,
     }