---
title: "Outils"
description: "Les outils du serveur MCP, par rôle et par niveau d’accès."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.puncto.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Outils

Le serveur n’expose que les outils qui correspondent aux rôles de la personne connectée. Les outils
administrateur apparaissent si elle administre une entreprise, les outils collaborateur si elle a un
contrat. Les outils de saisie demandent en plus l’accès **Lecture et modification** (scope
`mcp:write`).

Les outils qui agissent dans un espace Puncto acceptent un `companyId` facultatif, qui devient
obligatoire quand la personne appartient à plusieurs entreprises. S’il manque, l’outil renvoie une
erreur qui liste les entreprises possibles. Les outils de documentation n’ont pas besoin d’un
identifiant d’entreprise.

## Tous les rôles

| Outil | Contenu |
| --- | --- |
| `list_my_companies` | La personne connectée et, pour chaque entreprise, ses rôles (`COMPANY_ADMIN`, `COLLABORATOR`) et les établissements de celles qu’elle administre |
| `search_guides` | Catalogue des guides d’utilisation, avec titre, description, public, lien et identifiant. Filtres facultatifs `query` (mots-clés en français), `audience` (`admin` ou `collaborator`), `page` et `perPage` |
| `get_guide` | Texte Markdown d’un guide et lien vers la documentation. Utilisez l’`id` renvoyé par `search_guides` |

## Administrateur, lecture

| Outil | Paramètres | Contenu |
| --- | --- | --- |
| `find_collaborators` | `search`, `contractStatus` | Une ligne par contrat : statut, dates, poste, équipe, salaire, manager et lien. Sans recherche, renvoie les contrats actifs du jour |
| `get_collaborator` | `collaboratorId`, `year`, `month` | Identité, contrats, absences en attente ou à venir, variables de paie d’un mois (par défaut le mois en cours). Renvoie le `contractId` attendu par les outils de saisie |
| `list_absences` | `status`, `type`, `search` | Les absences de l’entreprise, les plus récentes d’abord. `status: "pending"` pour les demandes à traiter |
| `get_payroll_month` | `year`, `month` | L’état d’un mois de paie par établissement : statut, étapes de clôture, erreurs de génération, date de clôture, suivi DSN |
| `list_tasks` | `collaboratorId` | Les tâches ouvertes ou reportées, par échéance. `canMarkDone` indique celles que `complete_task` peut fermer |

## Administrateur, saisie

Ces outils demandent l’accès **Lecture et modification**, ainsi que l’accès administrateur
**Lecture & Edition** dans Puncto.

### Absences et tâches

| Outil | Paramètres | Effet |
| --- | --- | --- |
| `create_absence` | `contractId`, `type`, `startDate`, `endDate`, demi-journées, événement familial | Pose une absence **validée**. Un congé payé est réparti sur les compteurs, et refusé si le solde est insuffisant |
| `decide_absence` | `absenceId`, `decision` | Valide ou refuse une demande en attente ; les bulletins des mois couverts sont recalculés |
| `complete_task` | `taskId` | Marque une tâche comme faite. Les tâches qui se ferment seules une fois l’obligation remplie ne peuvent pas être cochées : l’outil renvoie alors `done: false` et le lien de la page |

Types d’absence acceptés : congés payés (`PTO_N`), `RTT`, `JNT`, repos compensateurs (`COR`,
`RCR`), repos (`REST`), sans solde (`UNPAID`), ancienneté (`SENIORITY`), congés de stagiaire
(`INTERN_CP`) et événements familiaux (`FAMILY`).

### Variables de paie

Sans `year` ni `month`, la variable est ajoutée au premier mois de paie encore ouvert.

| Outil | Paramètres | Effet |
| --- | --- | --- |
| `add_prime` | `primeType`, `amount`, `name`, `isAbsenceSensitive` | Prime brute ponctuelle, validée |
| `add_overtime` | `date`, `hours` | Heures supplémentaires d’une journée, payées aux taux de l’entreprise. Refusé sur un contrat sans heures supplémentaires (forfait jours, cadres…) |
| `add_transport_costs` | `titleType`, `monthlyPrice`, `name` | Abonnement de transport mensuel. La part employeur est calculée selon les paramètres de l’entreprise |
| `add_expense_note` | `expenseType`, `amount`, `date`, `vatAmounts`, `mealParticipantContractIds` | Note de frais remboursée au mois de la dépense. Le justificatif est à joindre ensuite dans Puncto |
| `add_in_kind_benefit` | `benefitType`, `amount`, `name` | Avantage en nature ponctuel |
| `add_salary_deduction` | `deductionType`, `amount`, `name` | Retenue sur le net (`NET_REDUCTION`) ou sur le brut (`BRUT_REDUCTION`) |
| `add_salary_advance` | `amount`, `paymentDate` | Acompte déjà versé, déduit du virement de fin de mois |
| `remove_variable` | `variableId` | Supprime une variable. Refusé sur un mois clôturé ou pour une variable issue d’un autre module (feuille de temps, intéressement, fin de contrat…) |

`remove_variable` est annoté `destructiveHint: true`.

### Contrats et collaborateurs

| Outil | Paramètres | Effet |
| --- | --- | --- |
| `update_contract` | `contractId`, `effectiveFrom` ou `effectiveDate`, `grossAnnualSalary`, `roleName`, `teamName`, `establishmentId` | Change le salaire, le poste, l’équipe ou l’établissement au 1er de ce mois ou du suivant. Seuls le salaire, le poste et l’équipe peuvent changer à une autre date. Refusé sur un mois dont le bulletin est validé |
| `update_trial_period` | `contractId`, `action` (`validate`, `renew`), `date` | Valide une période d’essai à une date, ou la renouvelle jusqu’à une date, dans les limites légales |
| `create_collaborator` | `firstName`, `lastName`, `email`, `startDate`, `workerType`, `establishmentId` | Crée le collaborateur avec un contrat à venir et lui envoie son invitation. Le collaborateur renseigne lui-même son identité, son adresse, sa sécurité sociale et son RIB. L’administrateur complète ensuite le contrat dans Puncto, qui déclare la DPAE |

## Collaborateur

| Outil | Accès | Contenu ou effet |
| --- | --- | --- |
| `get_my_leave_balance` | Lecture | Ses compteurs de congés à une date : acquis, pris, restants |
| `list_my_absences` | Lecture | Ses absences et demandes, avec leur statut |
| `list_my_payslips` | Lecture | Ses bulletins validés : brut, net avant impôt, impôt prélevé, net versé |
| `get_my_payslip` | Lecture | Les lignes d’un bulletin, telles qu’imprimées |
| `request_absence` | Modification | Demande une absence, en attente de validation par un administrateur |
| `cancel_my_absence` | Modification | Annule une de ses absences pas encore commencée, en attente ou validée |

Le téléchargement des bulletins en PDF et la déclaration des arrêts maladie, avec leur justificatif,
se font dans Puncto.

Source: https://docs.puncto.fr/developpeurs/mcp/outils/index.mdx
