send_contact

Instructions

Implementation Reference

• aiogram_mcp/tools/media.py:415-466 (handler)

  The send_contact MCP tool handler. Registered dynamically via @mcp.tool decorator within register_media_tools(). Sends a phone contact using ctx.bot.send_contact(), with chat allowance check, rate limiting, audit logging, and error handling.

  if allowed_tools is None or "send_contact" in allowed_tools:
  
      @mcp.tool
      async def send_contact(
          chat_id: int,
          phone_number: str,
          first_name: str,
          last_name: str | None = None,
          disable_notification: bool = False,
      ) -> SendMediaResult:
          """Send a phone contact to a Telegram chat.
  
          Args:
              chat_id: Target chat ID.
              phone_number: Contact's phone number.
              first_name: Contact's first name.
              last_name: Contact's last name.
              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_contact",
                      {"chat_id": chat_id, "phone_number": phone_number},
                      result.ok,
                      result.error,
                  )
              return result
  
          try:
              if ctx.rate_limiter:
                  await ctx.rate_limiter.acquire()
              msg = await ctx.bot.send_contact(
                  chat_id=chat_id,
                  phone_number=phone_number,
                  first_name=first_name,
                  last_name=last_name,
                  disable_notification=disable_notification,
              )
              result = SendMediaResult(ok=True, message_id=msg.message_id, chat_id=msg.chat.id)
          except (TelegramBadRequest, TelegramForbiddenError) as exc:
              result = SendMediaResult(ok=False, error=str(exc))
  
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "send_contact",
                  {"chat_id": chat_id, "phone_number": phone_number},
                  result.ok,
                  result.error,
              )
          return result

• aiogram_mcp/tools/media.py:14-16 (schema)

  SendMediaResult schema: Pydantic model extending ToolResponse with message_id and chat_id fields.

  class SendMediaResult(ToolResponse):
      message_id: int | None = None
      chat_id: int | None = None

• aiogram_mcp/permissions.py:38-38 (registration)

  Permission registration: 'send_contact' is mapped to PermissionLevel.MESSAGING.

  "send_contact": PermissionLevel.MESSAGING,

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

  register_media_tools function signature: orchestrates registration of all media tools including send_contact.

  def register_media_tools(
      mcp: FastMCP, ctx: BotContext, allowed_tools: set[str] | None = None
  ) -> None:

• aiogram_mcp/server.py:24-24 (registration)

  Import of register_media_tools from aiogram_mcp/tools/media.py, called at server startup.

  from .tools.media import register_media_tools