aiogram-mcp

Instructions

Implementation Reference

• aiogram_mcp/tools/messaging.py:35-87 (handler)

  The handler implementation for the `send_message` tool.

  async def send_message(
      chat_id: int,
      text: str,
      parse_mode: str | None = "HTML",
      disable_notification: bool = False,
      reply_to_message_id: int | None = None,
  ) -> SendMessageResult:
      """Send a text message to a Telegram chat or user."""
      if not ctx.is_chat_allowed(chat_id):
          result = SendMessageResult(
              ok=False,
              error=f"Chat {chat_id} is not in the allowed_chat_ids whitelist.",
          )
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "send_message", {"chat_id": chat_id, "text": text}, result.ok, result.error
              )
          return result
  
      try:
          if ctx.rate_limiter:
              await ctx.rate_limiter.acquire()
          msg = await ctx.bot.send_message(
              chat_id=chat_id,
              text=text,
              parse_mode=normalize_parse_mode(parse_mode),
              disable_notification=disable_notification,
              reply_parameters=(
                  ReplyParameters(message_id=reply_to_message_id)
                  if reply_to_message_id is not None
                  else None
              ),
          )
          result = SendMessageResult(
              ok=True,
              message_id=msg.message_id,
              chat_id=msg.chat.id,
              date=msg.date.isoformat(),
          )
      except ValueError as exc:
          result = SendMessageResult(ok=False, error=str(exc))
      except TelegramForbiddenError:
          result = SendMessageResult(
              ok=False, error="Bot was blocked by the user or lacks permission."
          )
      except TelegramBadRequest as exc:
          result = SendMessageResult(ok=False, error=str(exc))
  
      if ctx.audit_logger:
          ctx.audit_logger.log(
              "send_message", {"chat_id": chat_id, "text": text}, result.ok, result.error
          )
      return result

• aiogram_mcp/tools/messaging.py:14-17 (schema)

  Result schema for the `send_message` tool.

  class SendMessageResult(ToolResponse):
      message_id: int | None = None
      chat_id: int | None = None
      date: str | None = None

• aiogram_mcp/tools/messaging.py:29-32 (registration)

  Registration logic for the `send_message` tool within `register_messaging_tools`.

  def register_messaging_tools(
      mcp: FastMCP, ctx: BotContext, allowed_tools: set[str] | None = None
  ) -> None:
      if allowed_tools is None or "send_message" in allowed_tools: