aiogram-mcp

Instructions

Implementation Reference

• aiogram_mcp/tools/media.py:256-313 (handler)

  The `send_audio` MCP tool implementation within the `register_media_tools` function. It validates chat permissions, rate limits, and uses the `aiogram` bot object to send the audio message.

  @mcp.tool
  async def send_audio(
      chat_id: int,
      audio_url: str,
      caption: str | None = None,
      parse_mode: str | None = "HTML",
      performer: str | None = None,
      title: str | None = None,
      disable_notification: bool = False,
  ) -> SendMediaResult:
      """Send an audio file (music) to a Telegram chat.
  
      Args:
          chat_id: Target chat ID.
          audio_url: URL or file_id of the audio (MP3/M4A).
          caption: Optional caption.
          parse_mode: HTML, Markdown, MarkdownV2, or None.
          performer: Performer name.
          title: Track title.
          disable_notification: Send silently.
      """
      if not ctx.is_chat_allowed(chat_id):
          result = SendMediaResult(ok=False, error=f"Chat {chat_id} is not allowed.")
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "send_audio",
                  {"chat_id": chat_id, "audio_url": audio_url},
                  result.ok,
                  result.error,
              )
          return result
  
      try:
          if ctx.rate_limiter:
              await ctx.rate_limiter.acquire()
          msg = await ctx.bot.send_audio(
              chat_id=chat_id,
              audio=audio_url,
              caption=caption,
              parse_mode=normalize_parse_mode(parse_mode),
              performer=performer,
              title=title,
              disable_notification=disable_notification,
          )
          result = SendMediaResult(ok=True, message_id=msg.message_id, chat_id=msg.chat.id)
      except ValueError as exc:
          result = SendMediaResult(ok=False, error=str(exc))
      except (TelegramBadRequest, TelegramForbiddenError) as exc:
          result = SendMediaResult(ok=False, error=str(exc))
  
      if ctx.audit_logger:
          ctx.audit_logger.log(
              "send_audio",
              {"chat_id": chat_id, "audio_url": audio_url},
              result.ok,
              result.error,
          )
      return result

• aiogram_mcp/tools/media.py:254-254 (registration)

  The conditional registration check for the `send_audio` tool.

  if allowed_tools is None or "send_audio" in allowed_tools: