aiogram-mcp

Instructions

Implementation Reference

• aiogram_mcp/tools/chats.py:104-151 (handler)

  The ban_user tool handler, which bans a user from a chat using the Telegram bot API.

  async def ban_user(
      chat_id: int,
      user_id: int,
      ban_duration_hours: int | None = None,
      revoke_messages: bool = False,
  ) -> BanUserResult:
      """Ban a user from a chat."""
      if not ctx.is_chat_allowed(chat_id):
          result = BanUserResult(ok=False, error=f"Chat {chat_id} is not allowed.")
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "ban_user",
                  {"chat_id": chat_id, "user_id": user_id},
                  result.ok,
                  result.error,
              )
          return result
  
      until_date = None
      if ban_duration_hours:
          until_date = datetime.now(timezone.utc) + timedelta(hours=ban_duration_hours)
  
      try:
          if ctx.rate_limiter:
              await ctx.rate_limiter.acquire()
          await ctx.bot.ban_chat_member(
              chat_id=chat_id,
              user_id=user_id,
              until_date=until_date,
              revoke_messages=revoke_messages,
          )
          result = BanUserResult(
              ok=True,
              user_id=user_id,
              permanent=until_date is None,
              until=until_date.isoformat() if until_date else None,
          )
      except (TelegramBadRequest, TelegramForbiddenError) as exc:
          result = BanUserResult(ok=False, error=str(exc))
  
      if ctx.audit_logger:
          ctx.audit_logger.log(
              "ban_user",
              {"chat_id": chat_id, "user_id": user_id},
              result.ok,
              result.error,
          )
      return result

• aiogram_mcp/tools/chats.py:28-31 (schema)

  The result model for the ban_user tool.

  class BanUserResult(ToolResponse):
      user_id: int | None = None
      permanent: bool | None = None
      until: str | None = None

• aiogram_mcp/tools/chats.py:101-101 (registration)

  Conditional registration check for the ban_user tool within register_chat_tools.

  if allowed_tools is None or "ban_user" in allowed_tools: