tool_find_contact
Search for contacts by name with fuzzy matching to locate message recipients in macOS Messages.
Instructions
Find a contact by name using fuzzy matching.
Args:
name: The name to search forInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
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