Migadu MCP Server

Instructions

Implementation Reference

• migadu_mcp/tools/rewrite_tools.py:31-58 (handler)

  The primary handler function for the 'list_rewrites' tool, decorated with @mcp.tool(). It handles optional domain parameter (defaults from config), logging, service factory retrieval, API call via service, result processing with count, and comprehensive error handling.

  @mcp.tool(
      annotations={
          "readOnlyHint": True,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  @with_context_protection(max_tokens=2000)
  async def list_rewrites(ctx: Context, domain: str | None = None) -> Dict[str, Any]:
      """List pattern-based rewrite rules for domain. Returns summary with statistics and samples."""
      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 rewrite rules", domain)
      try:
          service = get_service_factory().rewrite_service()
          result = await service.list_rewrites(domain)
          count = len(result.get("rewrites", []))
          await log_operation_success(ctx, "Listed rewrite rules", domain, count)
          return result
      except Exception as e:
          await log_operation_error(ctx, "List rewrites", domain, str(e))
          raise

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

  Registration call to register_rewrite_tools(mcp), which defines and registers the list_rewrites tool using FastMCP's @mcp.tool decorator.

  register_rewrite_tools(mcp)

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

  Core service helper method that performs the actual API request to list rewrites for the given domain via MigaduClient.

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

• migadu_mcp/tools/resource_tools.py:166-178 (helper)

  MCP resource 'rewrites://{domain}' that provides list_rewrites functionality as a resource endpoint, directly calling the service.list_rewrites method.

  @mcp.resource("rewrites://{domain}")
  async def domain_rewrites(domain: str) -> Dict[str, Any]:
      """Resource providing all pattern-based rewrite rules configured for a domain. Shows wildcard
      patterns, destination addresses, processing order, and rule configuration for dynamic email
      routing. Use this resource to audit pattern-based forwarding systems, verify rule precedence,
      and manage complex email routing scenarios that require wildcard matching.
  
      URI Format: rewrites://example.org
      """
      factory = get_service_factory()
      service = factory.rewrite_service()
      return await service.list_rewrites(domain)

• migadu_mcp/tools/rewrite_tools.py:28-29 (registration)

  The register_rewrite_tools function that contains the @mcp.tool decorator for list_rewrites and other rewrite tools, invoked from main.py.

  def register_rewrite_tools(mcp: FastMCP):
      """Register rewrite tools using List[Dict] + iterator pattern"""