Migadu MCP Server

Instructions

Implementation Reference

• migadu_mcp/tools/alias_tools.py:32-66 (handler)

  The primary handler for the 'list_aliases' MCP tool. Includes decorators for registration and protection, input handling, logging, service delegation, and result processing.

  @mcp.tool(
      annotations={
          "readOnlyHint": True,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  @with_context_protection(max_tokens=2000)
  async def list_aliases(ctx: Context, domain: str | None = None) -> Dict[str, Any]:
      """List email aliases for domain. Returns summary with statistics and samples.
  
      Args:
          domain: Domain name. Uses MIGADU_DOMAIN if not provided.
  
      Returns:
          JSON object with alias summary and statistics
      """
      if domain is None:
          from migadu_mcp.config import get_config
  
          config = get_config()
          domain = config.get_default_domain()
          if not domain:
              raise ValueError("No domain provided and MIGADU_DOMAIN not configured")
  
      await log_operation_start(ctx, "Listing aliases", domain)
      try:
          service = get_service_factory().alias_service()
          result = await service.list_aliases(domain)
          count = len(result.get("aliases", []))
          await log_operation_success(ctx, "Listed aliases", domain, count)
          return result
      except Exception as e:
          await log_operation_error(ctx, "List aliases", domain, str(e))
          raise

• migadu_mcp/main.py:23-23 (registration)

  The call to register_alias_tools which defines and registers the list_aliases tool (and other alias tools) with the FastMCP instance.

  register_alias_tools(mcp)

• migadu_mcp/services/alias_service.py:16-18 (helper)

  Supporting service method that performs the actual API request to retrieve aliases from Migadu.

  async def list_aliases(self, domain: str) -> Dict[str, Any]:
      """List all aliases for a domain"""
      return await self.client.request("GET", f"/domains/{domain}/aliases")

• migadu_mcp/tools/alias_tools.py:29-66 (helper)

  The registration function that contains the tool definitions and @mcp.tool decorators for alias tools including list_aliases.

  def register_alias_tools(mcp: FastMCP):
      """Register alias tools using List[Dict] + iterator pattern"""
  
      @mcp.tool(
          annotations={
              "readOnlyHint": True,
              "idempotentHint": True,
              "openWorldHint": True,
          },
      )
      @with_context_protection(max_tokens=2000)
      async def list_aliases(ctx: Context, domain: str | None = None) -> Dict[str, Any]:
          """List email aliases for domain. Returns summary with statistics and samples.
  
          Args:
              domain: Domain name. Uses MIGADU_DOMAIN if not provided.
  
          Returns:
              JSON object with alias summary and statistics
          """
          if domain is None:
              from migadu_mcp.config import get_config
  
              config = get_config()
              domain = config.get_default_domain()
              if not domain:
                  raise ValueError("No domain provided and MIGADU_DOMAIN not configured")
  
          await log_operation_start(ctx, "Listing aliases", domain)
          try:
              service = get_service_factory().alias_service()
              result = await service.list_aliases(domain)
              count = len(result.get("aliases", []))
              await log_operation_success(ctx, "Listed aliases", domain, count)
              return result
          except Exception as e:
              await log_operation_error(ctx, "List aliases", domain, str(e))
              raise