Outils MCP — Contacts

Le groupe d'outils Contacts couvre tout le cycle de vie : découverte, recherche, mutation et opérations en masse.

Outil	Annotation	Objectif
list_contacts	IsReadOnly, IsIdempotent	Recherche/liste avec pagination et filtres
get_contact	IsReadOnly, IsIdempotent	Récupère un contact avec tags + messages récents
create_contact	IsDestructive(false)	Nouveau contact (téléphone E.164)
update_contact	IsDestructive(false), IsIdempotent	Met à jour nom/email/téléphone
tag_contact	IsDestructive(false), IsIdempotent	Ajoute ou retire des tags
delete_contact	IsDestructive	Suppression définitive
import_contacts	IsDestructive(false)	Upsert en masse depuis une liste d'enregistrements

list_contacts

Search and list contacts. Supports filtering by name/phone/email, tag, and opt-in status.

Entrée	Type	Défaut	Notes
search	string	—	Correspondance par sous-chaîne sur nom/téléphone/email
tag	string	—	Nom de tag exact
opted_in_only	boolean	true	Saute les contacts opt-out
page	integer	1
per_page	integer	25	Plafonné à 100

Renvoie { data: Contact[], meta: { current_page, last_page, per_page, total } }.

get_contact

Get detailed contact info with tags and recent messages.

Entrée	Type	Notes
id	UUID	Requis si phone/email non fournis
phone	string	E.164
email	string

Renvoie le contact + la liste de tags + les N derniers messages dans les deux directions.

create_contact

Create a new contact. Phone number should be in E.164 format.

Entrée	Type	Requis
phone	string	oui
name	string	non
email	string	non
tags	string[]	non
metadata	object	non
locale	string	non
source	string	non

Upsert sur (tenant_id, phone).

update_contact

Update contact fields such as name, email, or phone.

Entrée	Type
id	UUID (requis)
name, email, phone, locale, metadata	optionnel

Seuls les champs fournis sont écrits. metadata est fusionné en surface.

tag_contact

Add or remove tags on a contact.

Entrée	Type	Notes
id	UUID	requis
add_tags	string[]	tags à attacher (créés à la volée)
remove_tags	string[]	tags à détacher (la définition du tag reste)

delete_contact

Permanently delete a contact.

IsDestructive — le client de l'agent sollicite à chaque fois.

import_contacts

Bulk import or upsert contacts from a list of records. Each record must have a phone number; matched on tenant_id + phone. Existing contacts are updated, missing ones created. Tags are added without removing existing ones. Returns counts: imported / updated / skipped, plus per-row errors.

Entrée	Type
contacts	tableau d'enregistrements {phone, name?, email?, tags?, metadata?}

Renvoie { imported, updated, skipped, errors: { row, message }[] }. Pas besoin de fichier CSV — passez les enregistrements directement. Limite pratique : quelques milliers par appel. Pour les imports très volumineux, découpez en lots côté client.