Eines
El servidor exposa 17 eines agrupades per àrea funcional.Organització
get_user_organization_info
Retorna el context de l’organització activa (NIF, règim fiscal i valors per defecte) perquè l’agent pugui operar amb context fiscal correcte quan necessiti context d’empresa o valors fiscals.
get_mcp_workflows_guidance
Retorna una guia resumida de workflows MCP (nom del flux, descripció i passos d’arrencada) per ajudar l’agent a planificar o executar fluxos de diversos passos.
Contactes
list_contacts
Cerca contactes de l’organització amb filtres opcionals.
resolve_contact
Resol de manera determinista un únic contacte. Retorna status (unique / ambiguous / none) i fins a 5 candidats. Utilitza-ho abans de qualsevol operació d’escriptura que necessiti un contact_id.
Cal almenys un dels quatre camps.
create_contact
Crea un nou contacte a l’organització. Idempotent per document_number: si ja existeix un contacte amb aquell NIF/CIF, retorna l’existent en lloc de crear un duplicat.
update_contact
Actualitza els camps d’un contacte existent. Només es modifiquen els camps que es passin (semàntica PATCH).
Productes
resolve_product
Resol de manera determinista un únic producte. Retorna status (unique / ambiguous / none) i candidats. Utilitza-ho abans de crear un esborrany de factura.
Cal almenys un dels dos camps.
create_product
Afegeix un nou producte al catàleg de l’organització.
update_product
Actualitza els camps d’un producte existent. Només es modifiquen els camps que es passin (semàntica PATCH).
Factures
resolve_invoice
Localitza una factura emesa existent.
create_invoice_draft
Crea un esborrany de factura ordinària (F1). L’esborrany no s’emet; utilitza issue_invoice_draft per fer-lo fiscalment vinculant.
Retorna el draft_id, un confirmation_token i una vista prèvia per mostrar a l’usuari abans d’emetre.
create_simplified_invoice_draft
Crea un esborrany de factura simplificada (F2), sense contacte associat. Útil per a tiquets o vendes al públic en general.
Retorna draft_id, confirmation_token i vista prèvia.
issue_invoice_draft
Emet un esborrany (F1 o F2), fent-lo fiscalment vinculant. La factura s’envia automàticament a VeriFactu.
send_invoice_email
Envia o reenvía una factura emesa per correu electrònic al contacte associat.
Factures rebudes
create_received_invoice
Registra una factura rebuda d’un proveïdor. Abans de cridar-la, utilitza resolve_contact i mostra a l’usuari només les dades de la factura: proveïdor, número, data, línies, totals, estat de pagament i classificació comptable. Requereix confirmació explícita i un UUID nou a idempotency_key. El registre no adjunta cap document: si s’envia upload_session_id, l’eina retorna l’error attach_after_registration i no crea la factura.
El servidor calcula els totals autoritatius, detecta duplicats i rebutja períodes tancats. control_totals permet comparar els totals del document amb els calculats pel servidor; la resposta inclou les discrepàncies.
La resposta retorna l’id desat, els totals autoritatius, les discrepàncies, l’estat de l’adjunt (sempre sense document) i la URL d’edició. Després del registre, l’agent pot oferir adjuntar el document original.
create_received_invoice_upload_session
Crea una sessió temporal per adjuntar el PDF o la imatge d’una factura rebuda ja registrada. Crida-la només després que create_received_invoice hagi funcionat i l’usuari hagi acceptat adjuntar el document. La sessió queda vinculada a la factura indicada i només s’hi pot adjuntar a ella.
La resposta inclou
upload_session_id, expires_at, upload_url i received_invoice (id, full_number i supplier_name). Utilitza la upload_url retornada o renderitza el recurs MCP App de ui.resourceUri; totes dues interfícies mostren el proveïdor i el número de factura. Accepta un únic document validat; no enviïs bytes, claus d’emmagatzematge ni credencials com a arguments. Quan la pujada estigui preparada, crida update_received_invoice amb el mateix received_invoice_id, attachment_action replace i upload_session_id.
update_received_invoice
Corregeix una factura rebuda existent després de mostrar i confirmar l’estat complet corregit. Utilitza received_invoice_id i un UUID nou a idempotency_key; si canvia el proveïdor, resol-lo primer amb resolve_contact. Els camps escalars omesos es conserven i lines, si s’envia, substitueix totes les línies. attachment_action pot ser preserve, replace o remove; en reemplaçar, upload_session_id és obligatori i ha de ser una sessió creada per a la mateixa factura. Per adjuntar el document a una factura acabada de registrar, envia només received_invoice_id, idempotency_key, attachment_action i upload_session_id. La resposta inclou changed_fields, totals recalculats i l’estat final de l’adjunt.

