Merge pull request chigwell#251 from YorickLane/readonly-hint-side-effects

Mark export_unread_messages and the invite-link tools as not read-only; print hidden tools at startup

Author: chigwell

README.md

@@ -261,6 +261,9 @@ TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message,send_file
 An unknown name in the allowlist aborts startup, so a typo cannot silently
 degrade into a narrower surface that looks like it worked.
 
+At startup the server prints the names of the tools the mode hides to stderr;
+those are the names the `+` list accepts.
+
 This is an MCP tool-surface restriction, not a Telegram session sandbox or
 reduced Telegram account permission. The Telegram session string still has its
 normal authority inside the server process; read-only mode only prevents

telegram_mcp/runner.py

@@ -275,7 +275,15 @@ def main() -> None:
     # send_file is not exposed is a valid configuration, so the name check
     # has to see the full tool set.
     _runtime._apply_file_extension_overrides()
-    _runtime._apply_exposed_tools_mode()
+    hidden = _runtime._apply_exposed_tools_mode()
+    if hidden:
+        # These names are the menu for the "+" allowlist; without this line the
+        # only way to find them is reading the tool annotations in the source.
+        print(
+            f"TELEGRAM_EXPOSED_TOOLS hides {len(hidden)} tool(s); list any of them "
+            f"after '+' to expose it: {', '.join(sorted(hidden))}",
+            file=sys.stderr,
+        )
     _transcription.validate_transcription_config()
     _session_lock_shared()  # fail loudly at startup on a bad toggle
     asyncio.run(_main())

telegram_mcp/tools/groups.py

@@ -1125,7 +1125,7 @@ async def get_banned_users(chat_id: Union[int, str], account: str = None) -> str
 
 
 @mcp.tool(
-    annotations=ToolAnnotations(title="Get Invite Link", openWorldHint=True, readOnlyHint=True)
+    annotations=ToolAnnotations(title="Get Invite Link", openWorldHint=True, readOnlyHint=False)
 )
 @with_account(readonly=True)
 @validate_id("chat_id")
@@ -1222,7 +1222,7 @@ async def join_chat_by_link(link: str, account: str = None) -> str:
 
 
 @mcp.tool(
-    annotations=ToolAnnotations(title="Export Chat Invite", openWorldHint=True, readOnlyHint=True)
+    annotations=ToolAnnotations(title="Export Chat Invite", openWorldHint=True, readOnlyHint=False)
 )
 @with_account(readonly=True)
 @validate_id("chat_id")

telegram_mcp/tools/messages.py

@@ -2654,7 +2654,7 @@ async def clear_draft(chat_id: Union[int, str], account: str = None) -> str:
     annotations=ToolAnnotations(
         title="Export Unread Messages",
         openWorldHint=True,
-        readOnlyHint=True,
+        readOnlyHint=False,
         destructiveHint=False,
     )
 )

tests/test_runner.py

@@ -434,3 +434,23 @@ def test_cli_host_and_port_flags(monkeypatch):
     runtime._configure_allowed_roots_from_cli(["--host", "0.0.0.0", "--port", "9000"])
     assert runtime._CLI_HOST == "0.0.0.0"
     assert runtime._CLI_PORT == 9000
+
+
+def test_main_prints_the_tools_exposure_hides(monkeypatch, capsys):
+    """The hidden names are what a user copies into read-only+<tool>."""
+    monkeypatch.setattr(runner, "_configure_allowed_roots_from_cli", lambda *a, **k: None)
+    monkeypatch.setattr(runner._runtime, "_apply_file_extension_overrides", lambda: None)
+    monkeypatch.setattr(
+        runner._runtime,
+        "_apply_exposed_tools_mode",
+        lambda: ["send_message", "export_chat_invite"],
+    )
+    monkeypatch.setattr(runner._transcription, "validate_transcription_config", lambda: None)
+    monkeypatch.setattr(runner, "_session_lock_shared", lambda: None)
+    monkeypatch.setattr(runner.asyncio, "run", lambda coro: coro.close())
+
+    runner.main()
+
+    err = capsys.readouterr().err
+    assert "hides 2 tool(s)" in err
+    assert "export_chat_invite, send_message" in err

tests/test_side_effect_annotations.py

@@ -0,0 +1,17 @@
+import pytest
+
+from telegram_mcp import runtime
+from telegram_mcp.tools import groups, messages  # noqa: F401  (registers the tools)
+
+# These tools change state, so TELEGRAM_EXPOSED_TOOLS=read-only must drop them:
+# export_unread_messages writes a JSON file to a caller-chosen path, and
+# export_chat_invite / get_invite_link call messages.exportChatInvite, which
+# creates a new invite link. They can still be exposed by name
+# (read-only+export_chat_invite).
+SIDE_EFFECT_TOOLS = ["export_unread_messages", "export_chat_invite", "get_invite_link"]
+
+
+@pytest.mark.parametrize("tool_name", SIDE_EFFECT_TOOLS)
+def test_side_effect_tools_are_not_read_only(tool_name):
+    registered = {tool.name: tool for tool in runtime.mcp._tool_manager.list_tools()}
+    assert registered[tool_name].annotations.readOnlyHint is False