mac-messages-mcp

Instructions

Find a contact by name using fuzzy matching.

Args:
    name: The name to search for

Implementation Reference

• mac_messages_mcp/server.py:78-108 (handler)

  The primary handler for the 'tool_find_contact' tool. Decorated with @mcp.tool() for registration. Performs fuzzy contact search by calling the helper function, handles errors, and formats single or multiple match results.

  @mcp.tool()
  def tool_find_contact(ctx: Context, name: str) -> str:
      """
      Find a contact by name using fuzzy matching.
      
      Args:
          name: The name to search for
      """
      logger.info(f"Finding contact: {name}")
      try:
          matches = find_contact_by_name(name)
          
          if not matches:
              return f"No contacts found matching '{name}'."
          
          if len(matches) == 1:
              contact = matches[0]
              return f"Found contact: {contact['name']} ({contact['phone']}) with confidence {contact['score']:.2f}"
          else:
              # Format multiple matches
              result = [f"Found {len(matches)} contacts matching '{name}':"]
              for i, contact in enumerate(matches[:10]):  # Limit to top 10
                  result.append(f"{i+1}. {contact['name']} ({contact['phone']}) - confidence {contact['score']:.2f}")
              
              if len(matches) > 10:
                  result.append(f"...and {len(matches) - 10} more.")
              
              return "\n".join(result)
      except Exception as e:
          logger.error(f"Error in find_contact: {str(e)}")
          return f"Error finding contact: {str(e)}"

• mac_messages_mcp/messages.py:386-414 (helper)

  Key helper function implementing the fuzzy contact matching logic. Uses cached contacts from AddressBook, applies fuzzy_match utility, and returns scored contact matches used by the tool handler.

  def find_contact_by_name(name: str) -> List[Dict[str, Any]]:
      """
      Find contacts by name using fuzzy matching.
      
      Args:
          name: The name to search for
      
      Returns:
          List of matching contacts (may be multiple if ambiguous)
      """
      contacts = get_cached_contacts()
      
      # Build a list of (name, phone) pairs to search through
      candidates = [(contact_name, phone) for phone, contact_name in contacts.items()]
      
      # Perform fuzzy matching
      matches = fuzzy_match(name, candidates)
      
      # Convert to a list of contact dictionaries
      results = []
      for contact_name, phone, score in matches:
          results.append({
              "name": contact_name,
              "phone": phone,
              "score": score
          })
      
      return results