# Brancher Claude Desktop (stdio)

Les serveurs que déclare `claude_desktop_config.json` sont des processus que Claude Desktop
lance lui-même et auxquels il parle par leur entrée et leur sortie standard (stdio). PalmaPlan
sert ce mode depuis toujours, à côté de la porte HTTP + OAuth de [Claude Code](claude-code.md).
(Les connecteurs distants que Claude Desktop ajoute par ses réglages parleraient à `/mcp` comme
Claude Code ; ce chemin-là n'a pas été essayé avec PalmaPlan.)

## La configuration

Ouvrez `claude_desktop_config.json` et ajoutez :

```json
{
  "mcpServers": {
    "palmaplan": {
      "command": "node",
      "args": ["/chemin/vers/palmaplan/packages/mcp/dist/main.js"],
      "env": {
        "PALMAPLAN_TOKEN": "pp_le-jeton-nommé",
        "PALMAPLAN_URL": "http://127.0.0.1:4785"
      }
    }
  }
}
```

*Réglages › Connexions et agents › Accès avancés* (`/settings?onglet=avance`) donne cet
extrait déjà rempli, au moment où l'on crée un jeton nommé — il n'y a en principe que le chemin
de `main.js` à adapter.

- **`command` / `args`** : le chemin vers `packages/mcp/dist/main.js` sur la machine où
  Claude Desktop tourne — le binaire du paquet MCP construit (`pnpm build`), pas celui de
  l'API.
- **`PALMAPLAN_TOKEN`** : un **jeton nommé**, créé depuis *Réglages › Connexions et agents ›
  Accès avancés*. **Jamais
  le jeton de l'écran** (la variable `PALMAPLAN_TOKEN` que le *serveur* lit au démarrage) —
  ce jeton-là n'est pas nominatif, n'apparaît dans aucun journal attribuable, et ne se
  révoque pas individuellement.
- **`PALMAPLAN_URL`** : l'adresse à laquelle ce processus MCP joint l'API — celle de votre
  instance (`http://127.0.0.1:4785` sur votre machine), ou `https://palmaplan.com` pour la
  bêta, avec un jeton créé **sur** la bêta. Le processus MCP tourne toujours sur votre poste
  (il faut une copie du dépôt construite, `pnpm build`) ; c'est lui qui joint l'instance, par
  HTTPS et par le canal temps réel (`wss://`).

## Le piège documenté : quelle adresse pour `PALMAPLAN_URL`

**`PALMAPLAN_URL` doit être l'adresse du processus complet** (`serveur.js`, ce que `pnpm
start` lance — l'API, l'écran construit et la vue embarquée, dans le même processus),
**jamais celle de l'API seule** (`packages/api/dist/main.js`).

La raison : pour un client qui n'affiche pas les MCP Apps, [`show_schedule`](vue-embarquee.md)
construit l'adresse de la vue `/embed` à partir de cette même origine (ou de
`PALMAPLAN_PUBLIC_URL` en HTTP). Si `PALMAPLAN_URL` pointe vers une API qui ne sert pas
`/embed/:id`, ce lien ne mène nulle part, alors que tous les autres tools continuent de
fonctionner, puisqu'ils ne parlent qu'à l'API. Le symptôme est donc trompeur : tout semble
marcher, jusqu'au jour où l'on ouvre le lien d'un planning. Claude Desktop, lui, affiche la
vue native dans la conversation : elle est servie par le serveur MCP lui-même (la ressource
`ui://palmaplan/planning`) et lit tout par lui, sans passer par `/embed`.

## L'essai de la vue dans Claude Desktop

La vue dans la conversation est prouvée contre l'hôte de recette du dépôt, **pas encore
dans Claude Desktop**. Voici la marche à suivre pour l'essayer. Elle demande de quitter et
de relancer Claude Desktop : ne la jouez pas pendant une session d'agent en cours dans
Claude Desktop.

1. **PalmaPlan tourne**, dans une version qui contient la vue native (0.25.0 ou plus — elle
   y est arrivée avec le sprint 24, MCP Apps ; la version servie aujourd'hui est 0.27.0) :
   `http://127.0.0.1:4785/api/v1/health` répond, et sa `version` le dit (l'adresse est celle
   de votre instance). Le processus MCP lancé par Claude Desktop doit venir **de la même
   version** : c'est lui qui porte la vue.
2. **Un jeton nommé** : *Réglages › Connexions et agents › Accès avancés*, « Créer un jeton »,
   nommé « Claude Desktop — essai de la vue », case *Écriture* cochée (lecture et écriture).
   Copiez le secret `pp_…` : il ne sera plus montré. Ne le collez dans aucune conversation.
3. **Déclarer le serveur** : Claude Desktop › Réglages › Développeur › Modifier la
   configuration, puis ajouter l'entrée `palmaplan` de la configuration
   ci-dessus, avec ce jeton et l'adresse du processus complet. Un Node 24 convient
   (`"command"` peut être son chemin absolu).
4. **Quitter Claude Desktop (Cmd+Q) et le relancer.** Claude Desktop › Réglages › Développeur
   doit montrer « palmaplan » en marche. Sinon, le journal du serveur (`mcp-server-palmaplan.log`, dans
   le dossier des journaux de Claude) dit « serveur MCP PalmaPlan prêt — API : <adresse> »,
   puis « connexion établie — N planning(s) accessible(s) ». S'il dit que le serveur a refusé
   le jeton, le jeton est révoqué ou n'est pas un jeton nommé de cette instance.
5. **Les demandes à taper**, dans une nouvelle conversation :
   - « Montre-moi le planning <nom> dans la conversation. » Claude doit appeler
     `show_schedule`.
   - « Passe-le en plein écran », puis « Montre le kanban de ce planning », puis « et
     l'agenda ».
   - Choisir un bloc dans la vue, puis : « Décale ce bloc d'une semaine. »
   - « Que se passerait-il si je décalais <un bloc> d'une semaine ? » (`what_if`), puis
     « Accepter » dans la vue.
6. **Ce qu'il faut voir** :
   - le Gantt dans la conversation, aux couleurs du thème de Claude Desktop, en ligne puis
     en plein écran ;
   - un bloc déplacé dans la vue l'est aussi dans l'écran web ouvert à côté, et
     inversement (après quelques secondes) ;
   - Claude décale le bloc choisi, sans demander lequel ;
   - l'avant/après de `what_if`, et « Accepter » qui l'applique.
7. **À rapporter** : la version de Claude Desktop, ce qui s'affiche (une capture, sans
   secret), ce que dit la console du cadre si le mode développeur est actif, et la réponse
   de Claude à chaque demande. Un cadre vide, ou des tools en double, sont des constats
   aussi précieux qu'une réussite.
8. **Défaire** : retirer l'entrée `palmaplan` de la configuration, relancer Claude Desktop,
   puis révoquer le jeton dans *Réglages › Connexions et agents › Applications connectées*.

## À confirmer

**L'essai réel de Claude Desktop contre cette configuration n'a jamais été joué.** Le
sprint 14 (21/09/2026) a préparé un planning d'essai dédié et la configuration ci-dessus,
et le sprint 24 la marche à suivre de la vue. Mais l'essai lui-même (ouvrir Claude Desktop,
coller ce bloc, vérifier que la conversation voit les tools et que `show_schedule` affiche
la vue) demande la main sur le poste où Claude Desktop est installé, et n'a pas eu lieu. Ce
qui est vérifié, en revanche : le stdio lui-même (le protocole MCP par entrée/sortie
standard) est éprouvé en continu par les recettes du dépôt et par la vidéo de démonstration
du sprint 14, où un vrai client MCP en stdio construit un planning geste par geste pendant
qu'un navigateur suit l'écran par le canal temps réel. Ce qui manque, précisément, c'est
l'essai **dans Claude Desktop lui-même**.