Serveur MCP Cue

Expose le backlog Cue à Claude : lecture, écriture, jamais de suppression.

Le serveur tourne en local, parle à Claude par stdio et n'ouvre aucun port. Supprimer un projet ou un item reste un geste humain dans l'app — n'ajoutez pas d'outil de suppression ici. Les écritures sont unitaires, une entité à la fois, et chaque outil renvoie l'objet touché pour que Claude puisse confirmer ce qu'il vient de faire.

Installation (utilisateurs)

Rien à cloner, rien à compiler, rien à copier depuis l'app. Deux lignes, les mêmes pour tout le monde — npx télécharge le serveur au premier lancement :

claude mcp add cue --scope user -- npx -y cue-backlog-mcp

npx -y cue-backlog-mcp login

login ouvre une page Google dans votre navigateur, puis range votre clé dans ~/.cue/credentials.json. Elle n'ouvre que vos données : le serveur s'authentifie comme vous, et firestore.rules n'autorise que users/{votre uid}.

| Commande | Effet | | --- | --- | | login | Connecte un compte par le navigateur | | status | Dit quel compte est connecté | | logout | Efface la clé de cet appareil |

Sans terminal, sur Claude Desktop notamment : déclarer le serveur dans claude_desktop_config.json (Réglages → Developer → Edit Config) avec le même bloc mcpServers, puis demander « connecte mon compte Cue ». L'outil cue_login ouvre la page Google depuis la conversation.

La configuration MCP ne contient aucun secret — c'est voulu. La clé vit dans votre dossier personnel, jamais dans un fichier qu'on committe.

Aucune clé de service Firebase Admin n'intervient — et il ne faut pas en réintroduire. Une telle clé contourne les règles et donnerait accès aux backlogs de tous les comptes, ce qui rend l'outil indistribuable.

Développement du serveur

cd cue-mcp
npm install
npm run build

Le .mcp.json à la racine pointe déjà sur la version compilée localement. La configuration publique est embarquée dans src/config.ts — c'est là que l'ID client OAuth de bureau doit être reporté avant publication.

Tout est surchargeable par variable d'environnement, sans republier : CUE_FIREBASE_API_KEY, CUE_FIREBASE_PROJECT_ID, CUE_GOOGLE_CLIENT_ID, CUE_GOOGLE_CLIENT_SECRET, et CUE_HOME pour ranger la clé ailleurs que dans ~/.cue — pratique pour tester sans toucher à sa vraie session. CUE_TOKEN est encore lu en dernier recours, pour ne pas casser les installations faites en 1.2.

Le serveur démarre même sans configuration : il annonce ses outils et renvoie un message d'erreur explicite au premier appel, plutôt que de mourir au lancement.

Pour vérifier à la main :

node dist/cue-mcp/src/index.js

Le serveur écrit sa ligne de démarrage sur stderr et attend du JSON-RPC sur stdin. stdout est réservé au protocole : toute trace ajoutée au code doit passer par console.error, sinon la connexion casse.

Outils

Connexion

| Outil | Effet | | --- | --- | | cue_login | Ouvre la page Google et enregistre la clé — sans terminal |

Sans effet si un compte est déjà connecté, sauf force. L'appel bloque le temps de la connexion : un serveur stdio n'a pas de minuterie par requête, et rendre la main tout de suite obligerait à un second outil pour savoir si c'est fait. Aucun outil de déconnexion ici — logout reste en ligne de commande, comme la suppression reste un geste humain dans l'app.

Lecture

| Outil | Effet | | --- | --- | | cue_list_projects | Projets avec compteurs ouverts / chauds | | cue_get_project | Projet, items, dernière roadmap, cadrage | | cue_get_guidance | Le cadrage seul | | cue_get_roadmaps | Roadmaps d'un projet avec leur avancement | | cue_get_roadmap | Une roadmap complète |

Écriture

| Outil | Effet | | --- | --- | | cue_mark_done | Coche un item, renvoie l'avancement des roadmaps qui le citent | | cue_set_status | Coche ou rouvre — réversible | | cue_add_project | Crée un projet vide | | cue_add_item | Ajoute un item, notamment pour découper une grosse tâche | | cue_update_item | Titre, description, importance, type (pas le statut) | | cue_save_roadmap | Enregistre une roadmap de session | | cue_update_roadmap | Modifie son titre ou ses étapes |

completionPct n'est jamais fourni : il est calculé à partir des items liés, avec la même fonction que l'app.

Créer, oui ; supprimer, non. La règle « aucun outil de suppression » vise ce qu'on ne peut pas reprendre. Ajouter un projet n'entre pas dans ce cadre : c'est un contenant vide, visible aussitôt dans l'app, et l'utilisateur peut l'y supprimer d'un geste. Refuser cela obligeait à interrompre quelqu'un au milieu d'une phrase — « crée un projet pour mon TP et mets-y ces cinq tâches » — pour lui faire ouvrir l'app.

Le cadrage

roadmap-guidance.md est le prompt système remis à Claude à chaque ouverture de projet. Il est invisible dans l'app : c'est notre méthode de travail, pas une consigne demandée à l'utilisateur. Éditez-le librement, il est rechargé au redémarrage du serveur.

Logique partagée avec l'app

Le calcul d'avancement et les compteurs sont importés depuis src/data/ de l'app plutôt que recopiés : les deux côtés doivent donner exactement le même chiffre. Ces modules n'ont que des imports de types, donc rien à résoudre à l'exécution.