Serveur MCP

Mindwtr fournit un serveur MCP (Model Context Protocol) facultatif. Il permet de connecter des agents d’IA (comme Claude Desktop, Claude Code, OpenAI Codex ou Gemini CLI) à votre base de données Mindwtr locale, à l’API locale de l’application de bureau ou à un point de terminaison Mindwtr Cloud auto-hébergé.

L’utilitaire autonome utilise stdio par défaut.

Référence d’implémentation : apps/mcp-server/README.md. Si ce README diffère du code actuel du serveur ou des schémas d’outils MCP générés, le code et les schémas font foi.

Binaires de l’application et utilitaire MCP

L’utilitaire MCP autonome reste disponible sous le nom mindwtr-mcp et figure dans le registre MCP public.

Vous n’avez pas besoin d’exécuter toute l’application depuis les sources pour utiliser MCP. Utilisez le binaire normal de l’application de bureau pour vos tâches, puis laissez votre client MCP lancer mindwtr-mcp avec npx, ou installez-le globalement avec npm. Indiquez à l’utilitaire la base locale mindwtr.db de l’application de bureau, ou utilisez le backend API locale décrit ci-dessous.

Sur ordinateur, les chemins par défaut de la base de données figurent plus bas, dans Emplacements par défaut de la base de données. Les binaires mobiles n’exposent pas de serveur MCP local.

MCP intégré sur ordinateur

L’application de bureau comprend un serveur MCP dans Réglages → Intégrations → Serveur MCP local (avancé). Il s’exécute dans l’application et partage les opérations internes avec l’API locale. Ni Node, npm, Bun, ni utilitaire séparé ne sont nécessaires, et l’API locale peut rester désactivée. MCP est désactivé et en lecture seule par défaut.

Activez le serveur et gardez Mindwtr ouvert. La réduction dans la zone de notification le laisse disponible ; désactiver MCP ou quitter l’application l’arrête. Les clients doivent prendre en charge Streamable HTTP authentifié. Le point de terminaison par défaut est :

text

http://127.0.0.1:8722/mcp

Disponible à partir de v1.3.7 : les commandes ci-dessous ajoutent la copie de la configuration Codex, un port configurable et des autorisations d’écriture distinctes. Les versions précédentes utilisent un port fixe et une seule option Autoriser les modifications.

Connecter Codex

Choisissez Copier pour Codex et ajoutez le TOML copié à ~/.codex/config.toml. Si ce fichier contient déjà mcp_servers.mindwtr, remplacez cette entrée au lieu d’en ajouter une seconde. Conservez le reste de votre configuration. Mindwtr copie le texte ; il ne modifie pas les fichiers de Codex.

La configuration copiée a cette forme, avec votre point de terminaison et votre jeton actuels :

toml

[mcp_servers.mindwtr]
url = "http://127.0.0.1:8722/mcp"

[mcp_servers.mindwtr.http_headers]
Authorization = "Bearer <token from Mindwtr>"

Redémarrez ou reconnectez votre client Codex après avoir modifié sa configuration. Copier les informations de connexion fournit du JSON aux clients utilisant mcpServers ; les clients limités à stdio nécessitent toujours l’utilitaire autonome.

Autorisations et port

Autoriser la modification des tâches et des projets permet de créer, modifier, terminer et restaurer des tâches, ainsi que de créer ou modifier des projets. Dans Avancé, activez séparément Autoriser l’archivage et Autoriser la suppression si nécessaire. Chaque autorisation est indépendante et toutes sont désactivées lors d’une nouvelle installation. Les installations existantes qui avaient activé Autoriser les modifications conservent leur autorisation de suppression précédente ; vous pouvez la désactiver sans désactiver les modifications. L’archivage nécessite une nouvelle autorisation explicite.

L’outil intégré mindwtr_archive_task archive à l’aide de l’opération existante de l’application. Il ne termine pas une tâche et ne génère pas sa prochaine récurrence. Une mise à jour combinant des modifications ordinaires et des changements d’archivage ou d’annulation nécessite les deux autorisations. La suppression est logique. Ces réglages s’appliquent au serveur intégré, et non à l’utilitaire autonome ou à l’API locale séparée.

Avancé permet aussi de choisir un port entre 1024 et 65535. Enregistrez-le et copiez les informations de connexion actualisées pour votre client. Si un autre processus occupe le port, choisissez un port libre ou résolvez le conflit et utilisez Réessayer. Le serveur se lie toujours à 127.0.0.1.

Les clients d’IA connectés peuvent lire les données exposées par ces outils et les envoyer à leur fournisseur. Gardez le jeton copié confidentiel. Sa régénération déconnecte les clients existants, qui ont besoin du nouveau jeton.

Ce point de terminaison sert les clients du même ordinateur. Il ne fournit ni accès distant depuis ChatGPT, ni tunnel, ni service hébergé. Les applications mobiles ne l’hébergent pas.

Prérequis

Ces prérequis concernent l’utilitaire autonome.

Node.js 22+ pour les installations sans compilation : la dépendance SQLite fournit des binaires précompilés pour Node 22 et versions ultérieures. Node 20 exécute toujours le serveur, mais l’installation nécessite des outils de compilation C++
Les installations utilisant uniquement l’API peuvent omettre le module SQLite facultatif avec --omit=optional.
npm ou un autre exécuteur de paquets Node pour le paquet mindwtr-mcp publié
Une base de données Mindwtr locale (mindwtr.db) pour le mode SQLite, une API locale de l’application de bureau en cours d’exécution et son jeton porteur pour le mode API, ou une URL Mindwtr Cloud auto-hébergée et un jeton porteur pour le mode Cloud
Bun uniquement si vous exécutez l’utilitaire depuis l’arborescence des sources

Pour le mode SQLite avec npm 12, autorisez le script d’installation de la dépendance SQLite : sinon, une installation réussie peut échouer au démarrage faute de module natif. Pour npx ou une installation globale, autorisez uniquement better-sqlite3 :

bash

npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"
npm install -g --allow-scripts=better-sqlite3 mindwtr-mcp

Dans les configurations MCP utilisant npx, ajoutez "--allow-scripts=better-sqlite3" avant "mindwtr-mcp" dans args. Pour une installation locale existante, exécutez npm install-scripts approve better-sqlite3, puis npm rebuild better-sqlite3 depuis ce projet. Vérifiez la dépendance avant de l’autoriser ; n’activez pas tous les scripts.

Emplacements par défaut de la base de données

Linux : ~/.local/share/mindwtr/mindwtr.db
Linux (Snap) : ~/snap/mindwtr/current/.local/share/mindwtr/mindwtr.db
macOS : ~/Library/Application Support/mindwtr/data/mindwtr.db
Windows : %APPDATA%\mindwtr\data\mindwtr.db

Chemin macOS supplémentaire pour les versions isolées :

~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db

Les chemins macOS et Windows ci-dessus valent pour la v1.3.2 et les versions suivantes. Avant la v1.3.2, la base se trouvait directement dans le dossier mindwtr, par exemple %APPDATA%\mindwtr\mindwtr.db. Sous Linux, rien n’a changé.

Vous pouvez remplacer l’emplacement de la base locale avec :

--db /path/to/mindwtr.db
Variable d’environnement : MINDWTR_DB_PATH ou MINDWTR_DB

Pour le mode Cloud auto-hébergé, utilisez :

--cloud-url https://mindwtr.example.com ou MINDWTR_MCP_CLOUD_URL
--cloud-token <token> ou MINDWTR_MCP_CLOUD_TOKEN
éventuellement --cloud-allow-insecure-http=true pour les déploiements HTTP privés de confiance

Installation et configuration

Avec l’utilitaire autonome, les clients MCP exécutent le serveur comme sous-processus. Vous leur indiquez la commande et transmettez les arguments.

Commande recommandée sans installation pour les clients MCP :

json

{
  "command": "npx",
  "args": [
    "-y",
    "mindwtr-mcp",
    "--db",
    "/path/to/mindwtr.db"
  ]
}

Le paquet est en lecture seule par défaut. Ajoutez --write uniquement lorsque vous souhaitez explicitement qu’un client d’IA ajoute, mette à jour, termine ou supprime des données Mindwtr.

Mode API locale de l’application de bureau

Nécessite mindwtr-mcp 1.1.11 ou une version ultérieure.

Activez l’API locale de l’application de bureau dans les Réglages et copiez son jeton porteur. Laissez l’application et l’API en cours d’exécution. Ce backend utilise les points de terminaison REST de l’application et n’ouvre jamais de base de données ni ne se rabat sur SQLite.

Pour une installation utilisant uniquement l’API, omettez le module SQLite natif facultatif :

bash

npm install -g --omit=optional mindwtr-mcp

Configurez votre client MCP pour transmettre le jeton via son environnement, plutôt que dans les arguments de la ligne de commande :

json

{
  "command": "mindwtr-mcp",
  "args": ["--api-url", "http://127.0.0.1:3456"],
  "env": {
    "MINDWTR_MCP_API_TOKEN": "<token from desktop settings>"
  }
}

Utilisez le port affiché dans les Réglages. MINDWTR_MCP_API_URL peut remplacer --api-url. Les URL doivent utiliser littéralement 127.0.0.1 ou [::1], sans identifiants, chemin, paramètres de requête ni fragment ; les redirections sont refusées. Ne combinez pas les options API et Cloud/--db. Les variables d’environnement existantes indiquant le chemin de la base de données sont ignorées en mode API.

Les écritures restent désactivées tant qu’elles ne sont pas explicitement activées avec --write. Si l’application est fermée ou le jeton invalide, l’utilitaire renvoie une erreur. Une écriture ayant dépassé le délai d’attente peut avoir atteint l’application : vérifiez la tâche avant de réessayer, car l’utilitaire ne relance pas automatiquement les écritures.

Fonctionnalité MCP	Prise en charge par l’API locale de l’application de bureau
Lister/obtenir des tâches	Pris en charge, y compris les opérateurs de recherche avancés, les filtres de date, le tri et la pagination
Créer des tâches	Titre et champs explicites ; `quickAdd` n’est pas disponible
Mettre à jour/terminer/supprimer/restaurer des tâches	Pris en charge via les points de terminaison correspondants de l’API ; les changements vers un état final ne peuvent pas être soumis comme de simples modifications
Lister/obtenir/créer/mettre à jour/supprimer des projets	Pris en charge pour les champs de projet de base de l’API : titre, couleur, état, domaine et comportement séquentiel
Lister les domaines	Pris en charge
Sections, personnes gérées, écritures sur les domaines	Indisponibles ; ces outils sont masqués en mode API
Disponibilité GTD `view`	Indisponible car l’API n’expose pas l’instantané des sections requis
Remplacer les liens de pièces jointes	Indisponible car l’API ne fournit pas de mises à jour conditionnelles des pièces jointes

Les autres champs non pris en charge sont rejetés avant toute écriture. Les limites de récurrence de l’API de bureau s’appliquent également ; certaines tâches récurrentes doivent être terminées dans l’application. Ce backend ne garantit pas une parité complète avec les outils SQLite/Cloud.

--api-url sélectionne la source de données de l’utilitaire. --http sélectionne plutôt la façon dont un client MCP se connecte à l’utilitaire ; il peut être utilisé avec n’importe quel backend et dispose d’un jeton d’authentification distinct.

Mode Cloud auto-hébergé

Utilisez le mode Cloud lorsque vous exécutez votre propre serveur Mindwtr Cloud et souhaitez disposer des outils MCP sans exposer un fichier SQLite local :

bash

npx -y mindwtr-mcp \
  --cloud-url "https://mindwtr.example.com" \
  --cloud-token "$MINDWTR_TOKEN"

Vous pouvez aussi utiliser des variables d’environnement dans la configuration d’un client MCP :

json

{
  "command": "npx",
  "args": ["-y", "mindwtr-mcp"],
  "env": {
    "MINDWTR_MCP_CLOUD_URL": "https://mindwtr.example.com",
    "MINDWTR_MCP_CLOUD_TOKEN": "your-token"
  }
}

Le mode Cloud lit l’instantané /v1/data actuel depuis votre serveur Cloud auto-hébergé et expose des outils de lecture pour les tâches, projets, sections, domaines et personnes. Avec --write, les écritures de tâches, projets, sections et domaines passent par les points de terminaison REST propres à chaque ressource du serveur Cloud (POST /v1/tasks, PATCH /v1/tasks/:id, etc.) : chaque modification bénéficie ainsi de la même validation et du même suivi des révisions que celles effectuées depuis vos applications. Sans --write, les outils d’écriture renvoient read_only. La modification des personnes et la restauration des tâches supprimées ne sont pas encore disponibles en mode Cloud. Utilisez le système local de base de données pour ces opérations.

La modification des liens joints via MCP en mode Cloud nécessite Mindwtr Cloud 1.2.8 ou une version ultérieure. L’outil utilise des écritures conditionnelles pour conserver les fichiers joints modifiés par un autre client et effectue jusqu’à trois tentatives en cas de modifications simultanées. Si votre serveur ne fournit pas de ETag pour l’élément, mettez-le à jour avant de modifier les liens ; l’outil refuse la modification sans écrire. La modification des autres champs et la création de tâches ou de projets conservent leur comportement précédent.

Il ne s’agit pas du connecteur mutualisé hébergé qui est bloqué. Vous exécutez toujours vous-même le serveur Cloud et l’utilitaire MCP ; Mindwtr n’exploite pas de service stockant les données de tâches de tout le monde.

Pour une installation globale :

bash

npm install -g mindwtr-mcp
mindwtr-mcp --db "/path/to/mindwtr.db"

Arguments principaux

--db "/path/to/mindwtr.db" : chemin de votre base de données SQLite en mode local.
--write : active les opérations d’écriture (ajout, mise à jour, achèvement, suppression) en mode local ou Cloud. Sans cette option, le serveur est en lecture seule.
--cloud-url "https://mindwtr.example.com" : utilise un point de terminaison Mindwtr Cloud auto-hébergé à la place d’une base locale.
--cloud-token "<token>" : jeton porteur du point de terminaison Cloud auto-hébergé.
--cloud-allow-insecure-http=true : autorise les URL Cloud HTTP privées de confiance lorsque vous utilisez volontairement une connexion sans HTTPS.

1. Claude Desktop

Ajoutez une entrée de serveur au fichier de configuration de Claude Desktop.

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db",
        "--write"
      ]
    }
  }
}

Remarque : remplacez le chemin de la base de données par celui de votre base Mindwtr locale.

2. Claude Code (CLI)

Vous pouvez ajouter le serveur via la CLI :

bash

claude mcp add mindwtr -- \
  npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

3. OpenAI Codex (CLI / extension IDE)

Codex lit la configuration des serveurs MCP depuis ~/.codex/config.toml. Vous pouvez aussi utiliser un fichier .codex/config.toml propre à un projet de confiance. La CLI Codex et l’extension IDE partagent cette configuration.

Ligne de commande :

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db"

Ajoutez --write uniquement si vous souhaitez que Codex modifie les données Mindwtr locales :

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

Dans le TUI de Codex, exécutez /mcp pour vérifier que le serveur est actif.

Configuration manuelle :

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db"
]

Avec l’accès en écriture :

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db",
  "--write"
]

4. Gemini CLI

Gemini CLI utilise settings.json (utilisateur : ~/.gemini/settings.json ou projet : .gemini/settings.json).

Ligne de commande :

bash

gemini mcp add mindwtr \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

Configuration manuelle :

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "/path/to/mindwtr.db",
        "--write"
      ]
    }
  }
}

5. Application Gemini (apps personnalisées)

Les applications web et mobiles Gemini peuvent se connecter à un serveur MCP distant via une URL (« apps personnalisées » sur gemini.google.com). Cela fonctionne avec mindwtr-mcp en mode HTTP : hébergez le serveur à un endroit accessible aux serveurs de Google (une URL HTTPS publique derrière un reverse proxy ; Gemini se connecte depuis les serveurs de Google, donc localhost ne fonctionne pas), puis ajoutez cette URL comme app personnalisée avec votre jeton bearer.

6. Google Antigravity

Antigravity (l'IDE agentique de Google) lit les serveurs MCP locaux dans un fichier de configuration JSON ; il n'existe pas de commande CLI pour en ajouter. Ouvrez le fichier depuis le panneau latéral de l'agent via MCP Servers -> Manage MCP Servers -> View raw config, ou modifiez-le directement :

Versions récentes : ~/.gemini/config/mcp_config.json (par espace de travail : .agents/mcp_config.json)
Versions plus anciennes : ~/.gemini/antigravity/mcp_config.json (Windows : %USERPROFILE%\.gemini\antigravity\mcp_config.json)

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\mindwtr\\data\\mindwtr.db",
        "--write"
      ]
    }
  }
}

Remplacez le chemin par celui de votre base de données locale (les chemins Windows exigent des antislashs doublés en JSON). Omettez --write pour un accès en lecture seule. Redémarrez Antigravity et vérifiez que mindwtr apparaît dans ses paramètres de serveurs MCP. La configuration MCP locale d'Antigravity est indépendante du settings.json de Gemini CLI et des apps personnalisées de l'application Gemini.

Accès distant (HTTP)

Nécessite une version de mindwtr-mcp plus récente que 1.1.1 (ou une exécution depuis les sources).

Par défaut, le serveur parle stdio. Passez --http pour servir à la place un point de terminaison MCP HTTP en streaming, afin que les clients MCP distants puissent se connecter par URL. Le mode HTTP fonctionne avec les trois backends (SQLite local, API locale de l’application de bureau ou Cloud auto-hébergé).

bash

mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"

Options (toutes ont des variables d'environnement MINDWTR_MCP_HTTP* équivalentes) :

Option	Variable d'environnement	Signification
`--http`	`MINDWTR_MCP_HTTP`	Active le mode HTTP. Également impliqué par n'importe laquelle des options ci-dessous.
`--http-token <token>`	`MINDWTR_MCP_HTTP_TOKEN`	Obligatoire dès que le mode HTTP est actif ; au moins 16 caractères. Générez-en un avec `openssl rand -hex 32`. Sans jeton, le serveur refuse de démarrer.
`--http-host <host>`	`MINDWTR_MCP_HTTP_HOST`	Adresse d'écoute, par défaut `127.0.0.1`.
`--http-port <port>`	`MINDWTR_MCP_HTTP_PORT`	Port d'écoute, par défaut `8722`.

Le serveur MCP intégré de l’application de bureau utilise lui aussi le port 8722. S’il est activé, indiquez un autre port avec --http-port, par exemple --http-port 8723.

Le point de terminaison MCP est POST /mcp et exige Authorization: Bearer <token> à chaque requête. GET /healthz renvoie 200 ok sans authentification pour les contrôles de santé du reverse proxy. Les requêtes sans jeton valide reçoivent 401 ; les échecs répétés d’authentification entraînent une réponse 429 avec un en-tête Retry-After. Les corps de plus de 1 MiB reçoivent 413. En mode HTTP, le serveur reste actif tant qu'il écoute (stdio n'est pas connecté), et le comportement --write/lecture seule est inchangé.

Le serveur n’intègre ni TLS ni limitation de débit pour les requêtes authentifiées. Pour exposer le serveur au-delà de localhost, placez un reverse proxy (Caddy, nginx) devant pour le HTTPS et fournissez l'URL https:// obtenue avec votre jeton au client MCP distant.

Exécution manuelle

Il n’est généralement pas nécessaire de l’exécuter manuellement (le client MCP s’en charge), mais cela peut être utile pour les tests.

Depuis npm

bash

# Read-only
npx -y mindwtr-mcp --db "/path/to/mindwtr.db"

# With write access
npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

Depuis les sources (Bun)

bash

# Read-only
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

# With write access
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --write

Construction et exécution (Node)

bash

# Build
bun run --filter mindwtr-mcp build

# Run
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

Migration : renommage des outils (`mindwtr.` → `mindwtr_`)

Les noms d’outils utilisent désormais la notation avec trait de soulignement, comme mindwtr_list_tasks ; les anciens noms avec notation pointée ne sont plus documentés.

Outils disponibles

Une fois connecté, l’agent d’IA a accès aux outils suivants. Par défaut, le serveur est en lecture seule ; transmettez --write pour activer les outils d’écriture. Seul --write permet l’accès en écriture (aucun autre alias).

Outil	Opération	Exige `--write`
`mindwtr_list_tasks`	Répertorier les tâches	Non
`mindwtr_list_projects`	Répertorier les projets	Non
`mindwtr_get_project`	Récupérer un projet	Non
`mindwtr_list_sections`	Répertorier les sections	Non
`mindwtr_get_section`	Récupérer une section	Non
`mindwtr_list_areas`	Répertorier les domaines	Non
`mindwtr_list_people`	Répertorier les personnes	Non
`mindwtr_get_person`	Récupérer une personne	Non
`mindwtr_get_task`	Récupérer une tâche par ID	Non
`mindwtr_add_task`	Créer une tâche	Oui
`mindwtr_update_task`	Mettre à jour une tâche	Oui
`mindwtr_complete_task`	Marquer comme terminée	Oui
`mindwtr_delete_task`	Supprimer logiquement une tâche	Oui
`mindwtr_restore_task`	Restaurer une tâche	Oui
`mindwtr_add_project`	Créer un projet	Oui
`mindwtr_update_project`	Mettre à jour un projet	Oui
`mindwtr_delete_project`	Supprimer logiquement un projet	Oui
`mindwtr_add_section`	Créer une section	Oui
`mindwtr_update_section`	Mettre à jour une section	Oui
`mindwtr_delete_section`	Supprimer logiquement une section	Oui
`mindwtr_add_area`	Créer un domaine	Oui
`mindwtr_update_area`	Mettre à jour un domaine	Oui
`mindwtr_delete_area`	Supprimer logiquement un domaine	Oui
`mindwtr_add_person`	Créer une personne	Oui
`mindwtr_update_person`	Mettre à jour une personne	Oui
`mindwtr_rename_person`	Renommer une personne	Oui
`mindwtr_delete_person`	Supprimer logiquement une personne	Oui

Outils de lecture

mindwtr_list_tasks : répertorier les tâches avec des filtres (statut, projet, plage de dates, recherche, isFocusedToday pour le focus du jour, view pour la disponibilité GTD).
mindwtr_list_projects : répertorier tous les projets.
mindwtr_get_project : obtenir les détails d’un projet précis par son ID.
mindwtr_list_sections : répertorier les sections des projets, avec filtrage facultatif par projet.
mindwtr_get_section : obtenir les détails d’une section précise par son ID.
mindwtr_list_areas : répertorier tous les domaines.
mindwtr_list_people : répertorier les fiches de personnes gérées.
mindwtr_get_person : obtenir les détails d’une personne précise par son ID.
mindwtr_get_task : obtenir les détails d’une tâche précise par son ID.

Outils d’écriture (exigent `--write`)

Les outils d’écriture fonctionnent avec la base locale comme avec un système Cloud auto-hébergé, à deux exceptions près en mode Cloud : les outils d’écriture des personnes et mindwtr_restore_task renvoient une erreur explicite, car l’API Cloud ne possède pas encore de points de terminaison pour ces opérations.

mindwtr-mcp permet de conserver ou de renommer un lien existant vers un partage réseau lors de la mise à jour d’une tâche ou d’un projet. Gardez son URI strictement identique et réutilisez son identifiant de pièce jointe, ou omettez l’identifiant pour retrouver le lien par son URI. Le lien doit encore être actif sur le même élément. MCP continuera de refuser les nouveaux liens vers des partages réseau, les changements d’URI réseau et la restauration de liens réseau supprimés.

mindwtr_add_task : créer une tâche. Prend en charge quickAdd en langage naturel (par exemple « Buy milk @errands /due:tomorrow »). Prend aussi en charge les pièces jointes de type lien via attachments.
mindwtr_update_task : mettre à jour une tâche existante, notamment des champs de planification comme dueDate, startTime, reviewAt et isFocusedToday (les champs peuvent être effacés avec null). attachments définit les pièces jointes de type lien : la liste transmise est la liste complète des liens, les liens omis sont supprimés, les pièces jointes de type fichier ne sont jamais modifiées, et null supprime tous les liens.
mindwtr_complete_task : marquer une tâche comme terminée.
mindwtr_delete_task : supprimer logiquement une tâche.
mindwtr_restore_task : restaurer une tâche supprimée logiquement.
mindwtr_add_project : créer un projet, notamment avec les champs facultatifs startDate, dueDate et reviewAt. Accepte aussi les pièces jointes de type lien via attachments.
mindwtr_update_project : mettre à jour un projet, notamment avec les champs facultatifs startDate, dueDate et reviewAt. Les pièces jointes de type lien dans attachments suivent la même règle de liste complète que lors de la mise à jour d’une tâche.
mindwtr_delete_project : supprimer logiquement un projet.
mindwtr_add_section : créer une section dans un projet.
mindwtr_update_section : mettre à jour une section de projet.
mindwtr_delete_section : supprimer logiquement une section de projet. Les tâches de cette section sont conservées et déplacées hors de toute section par le cœur.
mindwtr_add_area : créer un domaine.
mindwtr_update_area : mettre à jour un domaine.
mindwtr_delete_area : supprimer logiquement un domaine.
mindwtr_add_person : créer une personne gérée pour les responsables et les tâches en attente.
mindwtr_update_person : mettre à jour les métadonnées d’une personne gérée.
mindwtr_rename_person : renommer une personne gérée et, éventuellement, mettre à jour les affectations de tâches exactes.
mindwtr_delete_person : supprimer logiquement une personne gérée sans effacer les affectations de tâches.

Remarque sur le schéma :

Les outils d’écriture de tâches couvrent dueDate, startTime et reviewAt (lors d’une mise à jour).
Les outils d’écriture de projets couvrent dueDate et reviewAt.
Les outils d’écriture de personnes couvrent name, note, referenceLink et la mise à jour facultative des affectations lors d’un renommage.
Pour connaître les entrées canoniques exactes, consultez apps/mcp-server/README.md.

Matrice des autorisations

Utilisez cette matrice pour décider d’exécuter le serveur en lecture seule ou avec --write.

Outil	Accès aux données	Type de modification	Mode lecture seule	Mode `--write`
`mindwtr_list_tasks`	Lignes de tâches (filtrées)	Aucune	Autorisé	Autorisé
`mindwtr_list_projects`	Lignes de projets	Aucune	Autorisé	Autorisé
`mindwtr_get_project`	Un projet par ID	Aucune	Autorisé	Autorisé
`mindwtr_list_sections`	Lignes de sections	Aucune	Autorisé	Autorisé
`mindwtr_get_section`	Une section par ID	Aucune	Autorisé	Autorisé
`mindwtr_list_areas`	Lignes de domaines	Aucune	Autorisé	Autorisé
`mindwtr_list_people`	Lignes de personnes	Aucune	Autorisé	Autorisé
`mindwtr_get_person`	Une personne par ID	Aucune	Autorisé	Autorisé
`mindwtr_get_task`	Une tâche par ID	Aucune	Autorisé	Autorisé
`mindwtr_add_task`	Table des tâches	Insertion	Refusé	Autorisé
`mindwtr_update_task`	Table des tâches	Mise à jour	Refusé	Autorisé
`mindwtr_complete_task`	Table des tâches	Mise à jour du statut	Refusé	Autorisé
`mindwtr_delete_task`	Table des tâches	Suppression logique	Refusé	Autorisé
`mindwtr_restore_task`	Table des tâches	Restauration après suppression logique	Refusé	Autorisé
`mindwtr_add_project`	Table des projets	Insertion	Refusé	Autorisé
`mindwtr_update_project`	Table des projets	Mise à jour	Refusé	Autorisé
`mindwtr_delete_project`	Table des projets	Suppression logique	Refusé	Autorisé
`mindwtr_add_section`	Table des sections	Insertion	Refusé	Autorisé
`mindwtr_update_section`	Table des sections	Mise à jour	Refusé	Autorisé
`mindwtr_delete_section`	Table des sections	Suppression logique	Refusé	Autorisé
`mindwtr_add_area`	Table des domaines	Insertion	Refusé	Autorisé
`mindwtr_update_area`	Table des domaines	Mise à jour	Refusé	Autorisé
`mindwtr_delete_area`	Table des domaines	Suppression logique	Refusé	Autorisé
`mindwtr_add_person`	Table des personnes	Insertion	Refusé	Autorisé
`mindwtr_update_person`	Table des personnes	Mise à jour	Refusé	Autorisé
`mindwtr_rename_person`	Table des personnes/tâches	Renommage/mise à jour des références	Refusé	Autorisé
`mindwtr_delete_person`	Table des personnes	Suppression logique	Refusé	Autorisé

Conseils pratiques :

Utilisez par défaut le mode lecture seule pour l’exploration et les rapports.
Activez --write uniquement pour les systèmes dont vous autorisez la modification par le client d’IA : une base locale ou votre propre serveur Cloud.
Pour les workflows d’agents, privilégiez une confirmation explicite avant les opérations de suppression ou d’achèvement.

Exemples d’utilisation avancée

1) Revue hebdomadaire guidée

Appelez mindwtr_list_tasks avec status: "waiting" et status: "someday".
Résumez les éléments bloqués par projet.
Pour les éléments sélectionnés, appelez mindwtr_update_task afin de définir reviewAt.

2) Session de traitement de la boîte de réception

Appelez mindwtr_list_tasks avec status: "inbox" et sortBy: "createdAt".
Pour chaque tâche, effectuez le classement avec mindwtr_update_task (next, waiting, reference, etc.).
Ajoutez les métadonnées manquantes (projet, contextes, étiquettes) lors d’un second passage.

3) Procédure sûre de clôture en masse

Pour une automatisation potentiellement destructive :

Exécutez la phase de lecture : répertoriez uniquement les ID candidats.
Présentez un résumé de confirmation (nombre + titres).
Exécutez les écritures (complete_task / delete_task) uniquement après l’approbation explicite de l’utilisateur.
Conservez les ID pour permettre un retour arrière avec restore_task.

4) Capture rapide en langage naturel

Utilisez mindwtr_add_task + quickAdd :

json

{
  "quickAdd": "Follow up with Alex +Hiring @work #ops /due:tomorrow 10am"
}

Utilisez cette méthode pour les flux de capture rapide où l’analyse des commandes est plus efficace que la définition manuelle de chaque champ.

Référence des outils

Tous les outils renvoient du JSON dans le champ content.text. Analysez ce JSON pour obtenir la charge utile réelle.

Limites opérationnelles

Ces limites sont utiles lorsque vous intégrez Mindwtr à des workflows d’agents :

mindwtr_list_tasks utilise par défaut limit: 200 et plafonne limit à 500.
Les titres des tâches sont limités à 500 caractères par la validation de création/mise à jour des tâches MCP.
Les entrées d’ajout rapide sont limitées à 2000 caractères pour la création de tâches MCP, comme dans l’API Cloud d’ajout rapide de tâches.
La couche SQLite utilise un busy_timeout de 5 secondes : une base verrouillée doit donc échouer au lieu de rester bloquée indéfiniment.

Si vous avez besoin de plus de 500 tâches, utilisez une pagination avec limit + offset au lieu d’attendre une réponse unique sans limite.

`mindwtr_list_tasks`

Champs d’entrée

status : inbox | next | waiting | someday | reference | done | archived | all
projectId : chaîne
includeDeleted : booléen
limit : nombre
offset : nombre
search : chaîne
dueDateFrom : chaîne de date ou date-heure ISO (comparée par date calendaire)
dueDateTo : chaîne de date ou date-heure ISO (comparée par date calendaire)
isFocusedToday : booléen
view : available | deferred | blocked — Disponibilité GTD. available = réalisable dès maintenant (une action suivante, ou une tâche dont la date de revue est arrivée, dans un projet actif, après toute date de début et sans attendre derrière une étape antérieure d’un projet séquentiel). deferred = la date de début est encore dans le futur. blocked = une étape antérieure d’un projet séquentiel occupe la place.
sortBy : updatedAt | createdAt | dueDate | title | priority
sortOrder : asc | desc

Exemple

json

{
  "status": "next",
  "limit": 20,
  "offset": 0,
  "sortBy": "updatedAt",
  "sortOrder": "desc"
}

Réponse

json

{
  "tasks": [
    {
      "id": "task-uuid",
      "title": "Follow up with design",
      "status": "next",
      "updatedAt": "2026-01-25T03:45:57.246Z"
    }
  ]
}

`mindwtr_list_projects`

Champs d’entrée

aucun

Réponse

json

{
  "projects": [
    {
      "id": "project-uuid",
      "title": "Mindwtr",
      "status": "active"
    }
  ]
}

`mindwtr_get_project`

Champs d’entrée

id : chaîne (UUID du projet)
includeDeleted : booléen (facultatif)

Exemple

json

{ "id": "project-uuid" }

`mindwtr_list_sections`

Champs d’entrée

projectId : chaîne (facultatif)
includeDeleted : booléen (facultatif)

Réponse

json

{
  "sections": [
    {
      "id": "section-uuid",
      "projectId": "project-uuid",
      "title": "Planning"
    }
  ]
}

`mindwtr_get_section`

Champs d’entrée

id : chaîne (UUID de la section)
includeDeleted : booléen (facultatif)

Exemple

json

{ "id": "section-uuid" }

`mindwtr_list_areas`

Champs d’entrée

aucun

Réponse

json

{
  "areas": [
    {
      "id": "area-uuid",
      "name": "Work"
    }
  ]
}

`mindwtr_list_people`

Champs d’entrée

includeDeleted : booléen (facultatif)

Réponse

json

{
  "people": [
    {
      "id": "person-uuid",
      "name": "Alex"
    }
  ]
}

`mindwtr_get_person`

Champs d’entrée

id : chaîne (UUID de la personne)
includeDeleted : booléen (facultatif)

Exemple

json

{ "id": "person-uuid" }

`mindwtr_get_task`

Champs d’entrée

id : chaîne (UUID de la tâche)
includeDeleted : booléen (facultatif)

Exemple

json

{ "id": "task-uuid" }

`mindwtr_add_task` (écriture)

Champs d’entrée

title : chaîne (obligatoire si quickAdd est omis)
quickAdd : chaîne (obligatoire si title est omis)
status : inbox | next | waiting | someday | reference | done | archived
projectId : chaîne
sectionId : chaîne
dueDate : chaîne ISO
startTime : chaîne ISO
recurrence : objet de récurrence ou chaîne RRULE RFC 5545
contexts : chaîne[]
tags : chaîne[]
description : chaîne
priority : low | medium | high | urgent
energyLevel : low | medium | high
assignedTo : chaîne
timeEstimate : 5min | 10min | 15min | 30min | 1hr | 2hr | 3hr | 4hr | 4hr+
Autres champs modifiables : areaId, reviewAt, taskMode, relativeStartOffset, showFutureRecurrence, pushCount, checklist, textDirection, location, isFocusedToday, timeSpentMinutes, suppressMindwtrReminders, repeatReminderMinutes, attachments

Exemple

json

{
  "quickAdd": "Send invoice +Acme /due:tomorrow 9am #finance"
}

`mindwtr_update_task` (écriture)

Champs d’entrée

id : chaîne (UUID de la tâche)
title, status, projectId, sectionId, areaId, dueDate, startTime, contexts, tags, description, priority, energyLevel, assignedTo, timeEstimate, reviewAt, taskMode, relativeStartOffset, showFutureRecurrence, pushCount, checklist, textDirection, location, isFocusedToday, timeSpentMinutes, suppressMindwtrReminders, repeatReminderMinutes, order, boardOrder, focusOrder, attachments
recurrence : objet de récurrence, chaîne RRULE RFC 5545 ou null pour l’effacer

Remarques

Utilisez null pour effacer les champs acceptant une valeur nulle. Cela s’applique aux champs de tâche comme projectId, dueDate, startTime, contexts et tags ; aux champs de projet comme areaId, startDate, dueDate, reviewAt et supportNotes ; à description pour les sections ; à color et icon pour les domaines ; ainsi qu’à note et referenceLink pour les personnes.

Exemple

json

{
  "id": "task-uuid",
  "status": "waiting",
  "reviewAt": "2026-01-27T09:00:00.000Z"
}

`mindwtr_complete_task` (écriture)

Champs d’entrée

id : chaîne (UUID de la tâche)

`mindwtr_delete_task` (écriture)

Champs d’entrée

id : chaîne (UUID de la tâche)

`mindwtr_restore_task` (écriture)

Champs d’entrée

id : chaîne (UUID de la tâche)

`mindwtr_add_project` (écriture)

Champs d’entrée

title : chaîne
color : chaîne (facultatif)
status : active | someday | waiting | archived (facultatif)
areaId : chaîne ou null
isSequential : booléen (facultatif)
isFocused : booléen (facultatif)
startDate : chaîne ISO ou null
dueDate : chaîne ISO ou null
reviewAt : chaîne ISO ou null
supportNotes : chaîne ou null

`mindwtr_update_project` (écriture)

Champs d’entrée

id : chaîne (UUID du projet)
title, color, status, areaId, isSequential, isFocused, startDate, dueDate, reviewAt, supportNotes, attachments

`mindwtr_delete_project` (écriture)

Champs d’entrée

id : chaîne (UUID du projet)

`mindwtr_add_section` (écriture)

Champs d’entrée

projectId : chaîne
title : chaîne
description : chaîne ou null (facultatif)
order : nombre (facultatif)
isCollapsed : booléen (facultatif)

`mindwtr_update_section` (écriture)

Champs d’entrée

id : chaîne (UUID de la section)
title, description, order, isCollapsed

`mindwtr_delete_section` (écriture)

Champs d’entrée

id : chaîne (UUID de la section)

`mindwtr_add_area` (écriture)

Champs d’entrée

name : chaîne
color : chaîne (facultatif)
icon : chaîne (facultatif)

`mindwtr_update_area` (écriture)

Champs d’entrée

id : chaîne (UUID du domaine)
name, color, icon

`mindwtr_delete_area` (écriture)

Champs d’entrée

id : chaîne (UUID du domaine)

`mindwtr_add_person` (écriture)

Champs d’entrée

name : chaîne
note : chaîne ou null (facultatif)
referenceLink : chaîne ou null (facultatif)

`mindwtr_update_person` (écriture)

Champs d’entrée

id : chaîne (UUID de la personne)
name, note, referenceLink

`mindwtr_rename_person` (écriture)

Champs d’entrée

id : chaîne (UUID de la personne)
name : chaîne
updateTasks : booléen (facultatif)

`mindwtr_delete_person` (écriture)

Champs d’entrée

id : chaîne (UUID de la personne)

Remarques sur le format de sortie

Les sorties des outils sont des chaînes JSON et non des valeurs MCP structurées. Votre client doit analyser content[0].text.
Les ID de tâches/projets sont des UUID issus de la base SQLite locale.
Les dates sont des chaînes ISO 8601 (UTC).

Sécurité et remarques

Accès concurrent (mode SQLite local) : le serveur utilise le mode WAL de SQLite et relance l’écriture avec les données actuelles après un conflit de verrouillage temporaire. Le client ne doit réessayer que si ces tentatives échouent.
Logique partagée : les opérations d’écriture utilisent la bibliothèque partagée @mindwtr/core afin de garantir l’application des règles métier.
Maintien en fonctionnement : en mode stdio, le serveur reste actif tant que stdin est ouvert. En mode HTTP, il reste actif tant que le listener fonctionne.

`cancelledAt`

Task et Project acceptent cancelledAt, un horodatage ISO facultatif avec fuseau horaire. Il archive l'engagement comme annulé. La tâche n'a pas de completedAt et ne génère pas d'occurrence suivante. Pour un projet, les étapes terminées sont conservées et les actions restantes sont annulées. Mettez à jour tous les clients qui écrivent les données avant la synchronisation. Voir le flux GTD.

cancelledAt: null seul efface le marqueur sans réactiver l'élément. Pour le réactiver, définissez explicitement un status non archivé.

Résolution des problèmes

« Command not found » : utilisez npx -y mindwtr-mcp dans les configurations des clients MCP, ou installez le paquet globalement avec npm install -g mindwtr-mcp.
Problèmes de connexion du client : vérifiez que vous n’utilisez PAS bun run comme commande dans la configuration de votre client MCP, car il peut produire du texte supplémentaire. Préférez npx -y mindwtr-mcp ; pour les copies de travail des sources, exécutez directement bun sur le fichier source ou node sur le fichier construit.

Serveur MCP ​

Binaires de l’application et utilitaire MCP ​

MCP intégré sur ordinateur ​

Connecter Codex ​

Autorisations et port ​

Prérequis ​

Emplacements par défaut de la base de données ​

Installation et configuration ​

Mode API locale de l’application de bureau ​

Mode Cloud auto-hébergé ​

Arguments principaux ​

1. Claude Desktop ​

2. Claude Code (CLI) ​

3. OpenAI Codex (CLI / extension IDE) ​

4. Gemini CLI ​

5. Application Gemini (apps personnalisées) ​

6. Google Antigravity ​

Accès distant (HTTP) ​

Exécution manuelle ​

Depuis npm ​

Depuis les sources (Bun) ​

Construction et exécution (Node) ​

Migration : renommage des outils (mindwtr.* → mindwtr_*) ​

Outils disponibles ​

Outils de lecture ​

Outils d’écriture (exigent --write) ​

Matrice des autorisations ​

Exemples d’utilisation avancée ​

1) Revue hebdomadaire guidée ​

2) Session de traitement de la boîte de réception ​

3) Procédure sûre de clôture en masse ​

4) Capture rapide en langage naturel ​

Référence des outils ​

Limites opérationnelles ​

mindwtr_list_tasks ​

mindwtr_list_projects ​

mindwtr_get_project ​

mindwtr_list_sections ​

mindwtr_get_section ​

mindwtr_list_areas ​

mindwtr_list_people ​

mindwtr_get_person ​

mindwtr_get_task ​

mindwtr_add_task (écriture) ​

mindwtr_update_task (écriture) ​

mindwtr_complete_task (écriture) ​

mindwtr_delete_task (écriture) ​

mindwtr_restore_task (écriture) ​

mindwtr_add_project (écriture) ​

mindwtr_update_project (écriture) ​

mindwtr_delete_project (écriture) ​

mindwtr_add_section (écriture) ​

mindwtr_update_section (écriture) ​

mindwtr_delete_section (écriture) ​

mindwtr_add_area (écriture) ​

mindwtr_update_area (écriture) ​

mindwtr_delete_area (écriture) ​

mindwtr_add_person (écriture) ​

mindwtr_update_person (écriture) ​

mindwtr_rename_person (écriture) ​

mindwtr_delete_person (écriture) ​

Remarques sur le format de sortie ​

Sécurité et remarques ​

cancelledAt ​

Résolution des problèmes ​

Serveur MCP

Binaires de l’application et utilitaire MCP

MCP intégré sur ordinateur

Connecter Codex

Autorisations et port

Prérequis

Emplacements par défaut de la base de données

Installation et configuration

Mode API locale de l’application de bureau

Mode Cloud auto-hébergé

Arguments principaux

1. Claude Desktop

2. Claude Code (CLI)

3. OpenAI Codex (CLI / extension IDE)

4. Gemini CLI

5. Application Gemini (apps personnalisées)

6. Google Antigravity

Accès distant (HTTP)

Exécution manuelle

Depuis npm

Depuis les sources (Bun)

Construction et exécution (Node)

Migration : renommage des outils (`mindwtr.` → `mindwtr_`)

Outils disponibles

Outils de lecture

Outils d’écriture (exigent `--write`)

Matrice des autorisations

Exemples d’utilisation avancée

1) Revue hebdomadaire guidée

2) Session de traitement de la boîte de réception

3) Procédure sûre de clôture en masse

4) Capture rapide en langage naturel

Référence des outils

Limites opérationnelles

`mindwtr_list_tasks`

`mindwtr_list_projects`

`mindwtr_get_project`

`mindwtr_list_sections`

`mindwtr_get_section`

`mindwtr_list_areas`

`mindwtr_list_people`

`mindwtr_get_person`

`mindwtr_get_task`

`mindwtr_add_task` (écriture)

`mindwtr_update_task` (écriture)

`mindwtr_complete_task` (écriture)

`mindwtr_delete_task` (écriture)

`mindwtr_restore_task` (écriture)

`mindwtr_add_project` (écriture)

`mindwtr_update_project` (écriture)

`mindwtr_delete_project` (écriture)

`mindwtr_add_section` (écriture)

`mindwtr_update_section` (écriture)

`mindwtr_delete_section` (écriture)

`mindwtr_add_area` (écriture)

`mindwtr_update_area` (écriture)

`mindwtr_delete_area` (écriture)

`mindwtr_add_person` (écriture)

`mindwtr_update_person` (écriture)

`mindwtr_rename_person` (écriture)

`mindwtr_delete_person` (écriture)

Remarques sur le format de sortie

Sécurité et remarques

`cancelledAt`

Résolution des problèmes