Développer avec l'IA

Pour le développement quotidien assisté par l'IA avec les Skills Mastra et la CLI, consultez Développer. Cette page présente d'autres moyens de donner aux Agents de programmation accès à la documentation de Mastra.

Documentation intégrée aux packages

Les packages Mastra incluent une documentation intégrée dans dist/docs. Lorsque vous installez un package Mastra, votre Agent IA peut lire ces fichiers directement depuis node_modules afin de comprendre les API et les modèles du package.

Chaque répertoire dist/docs comprend :

• SKILL.md : un fichier de Skill conforme au standard des Skills
• references/ : un dossier contenant les fichiers de documentation relatifs au package
• assets/SOURCE_MAP.json : un fichier source map qui relie les exports publics à leur emplacement dans node_modules

Fichiers de contexte

Mastra fournit à la racine un fichier llms.txt qui présente toutes les pages de documentation disponibles. Il ne fournit pas de fichier llms-full.txt, car regrouper toute la documentation dans un seul fichier n'est pas utile.

À la place, chaque page de documentation possède son propre fichier llms.txt. Ces fichiers Markdown sont simplifiés. À la fin de chaque page de documentation, vous trouverez un lien vers le fichier llms.txt correspondant.

Ajoutez /llms.txt à n'importe quelle URL de la documentation Mastra pour y accéder. Vous pouvez également le demander en ajoutant l'extension .md à la fin de l'URL.

Exemples pour la page d'introduction :

• /docs/llms.txt
• /docs.md

Serveur de documentation MCP

attention

Le serveur de documentation MCP n'est pas recommandé pour le développement quotidien. Utilisez plutôt le Skill Mastra, car il est plus à jour et plus performant.

Le package @mastra/mcp-docs-server fournit un accès local direct à l'intégralité de la documentation Mastra au moyen du Model Context Protocol (MCP). Il fonctionne avec Cursor, Windsurf, Cline, Claude Code, VS Code, Codex ou tout autre outil prenant en charge MCP.

Ces Tools sont conçus pour aider les Agents à récupérer des informations précises et propres à une tâche, que vous ajoutiez une fonctionnalité à un Agent, créiez la structure d'un nouveau projet ou cherchiez à comprendre le fonctionnement d'un élément.

Si vous ne pouvez pas utiliser de serveur MCP local et devez vous connecter à un serveur distant, utilisez cette URL : https://mastra.mcp.kapa.ai. Vous devez vous authentifier avec votre compte Google (seul un identifiant anonyme est transmis) afin de permettre la limitation du débit. Dans la mesure du possible, Mastra recommande d'utiliser un serveur MCP local pour bénéficier de meilleures performances et d'une plus grande fiabilité.

Installation

La commande create-mastra ne configure pas le serveur de documentation MCP. Ajoutez le serveur manuellement lorsque vous avez besoin de Tools propres à MCP, tels que le Tool de migration.

Si aucune instruction propre à votre outil ne figure ci-dessous, vous pouvez éventuellement ajouter le serveur MCP à l'aide de cette configuration JSON courante.

mcp.json

{
  "mcpServers": {
    "mastra": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

Claude Code CLI

Installez-le à l'aide de la commande de terminal suivante :

claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest

Cette commande crée un fichier .mcp.json limité au projet s'il n'existe pas encore. Vous pouvez utiliser la même commande lorsque vous employez Claude Code comme extension Visual Studio Code.

En savoir plus sur l'utilisation de serveurs MCP avec Claude Code

OpenAI Codex CLI

1. Enregistrez-le depuis le terminal :

   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest

2. Exécutez codex mcp list pour confirmer que le serveur apparaît avec l'état enabled.

En savoir plus sur l'utilisation de serveurs MCP avec OpenAI Codex

Cursor

Installez-le en sélectionnant le bouton ci-dessous :

Si vous avez suivi l'installation automatique, une fenêtre contextuelle s'affiche dans le coin inférieur gauche lorsque vous ouvrez Cursor et vous invite à activer Mastra Docs MCP Server.

En savoir plus sur l'utilisation de serveurs MCP avec Cursor

Antigravity

Google Antigravity est une plateforme de développement centrée sur les Agents qui prend en charge les serveurs MCP pour accéder à la documentation externe, aux API et au contexte du projet.

1. Ouvrez votre fichier de configuration MCP Antigravity :

   • Cliquez sur Agent session, puis sélectionnez le menu déroulant « … » en haut du panneau latéral de l'éditeur. Sélectionnez ensuite MCP Servers pour accéder au MCP Store.
   • Vous pouvez y accéder depuis l'interface MCP Store d'Antigravity

   

2. Pour ajouter un serveur MCP personnalisé, sélectionnez Manage MCP Servers en haut du MCP Store, puis View raw config dans l'onglet principal.

   

3. Ajoutez la configuration du serveur MCP Mastra :

   {
     "mcpServers": {
       "mastra-docs": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server"]
       }
     }
   }

4. Enregistrez la configuration et redémarrez Antigravity

   

Une fois configuré, le serveur MCP Mastra met les éléments suivants à la disposition des Agents Antigravity :

• Documentation indexée et schémas d'API de Mastra, permettant la récupération par programmation du contexte pertinent lors de la génération de code
• Accès aux exemples de code et aux modèles d'utilisation stockés dans la documentation Mastra
• Données structurées pour la gestion des erreurs et références de débogage dans l'éditeur
• Métadonnées sur les modèles actuels des projets Mastra afin de faciliter la suggestion et la complétion de code

Le serveur MCP apparaît dans le MCP Store d'Antigravity, où vous pouvez gérer son état de connexion et son authentification si nécessaire.

En savoir plus sur l'utilisation de serveurs MCP avec Antigravity

Visual Studio Code

1. Créez un fichier .vscode/mcp.json dans votre Workspace

2. Insérez la configuration suivante :

   .vscode/mcp.json

   {
     "servers": {
       "mastra": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

Une fois le serveur MCP installé, vous pouvez l'utiliser comme suit :

1. Ouvrez les paramètres de VSCode.

2. Accédez aux paramètres MCP.

3. Cliquez sur « enable » pour l'option Chat > MCP.

   

MCP fonctionne uniquement en mode Agent dans VSCode. Une fois dans ce mode, ouvrez le fichier mcp.json et sélectionnez le bouton « start ». Notez que ce bouton n'apparaît que si le dossier .vscode contenant mcp.json se trouve à la racine de votre Workspace, ou au niveau le plus élevé de l'explorateur de fichiers de l'éditeur.

Après avoir démarré le serveur MCP, sélectionnez le bouton Tools dans le volet Copilot pour afficher les Tools disponibles.

En savoir plus sur l'utilisation de serveurs MCP avec Visual Studio Code

Windsurf

1. Ouvrez ~/.codeium/windsurf/mcp_config.json dans votre éditeur

2. Insérez la configuration suivante :

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "mastra": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

3. Enregistrez la configuration et redémarrez Windsurf

En savoir plus sur l'utilisation de serveurs MCP avec Windsurf

OpenCode

Vous pouvez définir des serveurs MCP dans votre configuration OpenCode sous mcp. Créez un fichier opencode.jsonc à la racine de votre projet avec le contenu suivant :

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mastra": {
      "type": "local",
      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
      "enabled": true
    }
  }
}

En savoir plus sur l'utilisation de serveurs MCP avec OpenCode

Zed

1. Ouvrez ~/.config/zed/settings.json dans votre éditeur
2. Insérez la configuration suivante :

~/.config/zed/settings.json

{
  "context_servers": {
    "Mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

Utilisation

Une fois la configuration terminée, vous pouvez poser à votre Tool IA des questions sur Mastra ou lui demander d'effectuer des actions. Pour ces étapes, il utilise les informations à jour provenant du serveur MCP de Mastra.

Ajouter des fonctionnalités :

• « Ajoute des Evals à mon Agent et écris des tests »
• « Écris-moi un Workflow qui effectue la tâche suivante : [task] »
• « Crée un nouveau Tool permettant à mon Agent d'accéder à [3rd party API] »

Poser des questions sur les intégrations :

• « Mastra fonctionne-t-il avec AI SDK ? Comment puis-je l'utiliser dans mon projet [React/Svelte/etc] ? »
• « Mastra prend-il en charge les API de parole et de voix de [provider] ? Montre-moi dans mon code un exemple de leur utilisation. »

Déboguer ou mettre à jour le code existant :

• « Je rencontre un bug avec la Memory de l'Agent. Des modifications ou des corrections de bugs associées ont-elles été apportées récemment ? »
• « Comment la mémoire de travail se comporte-t-elle dans Mastra et comment puis-je l'utiliser pour effectuer [task] ? Elle ne semble pas fonctionner comme prévu. »
• « J'ai vu qu'il existe de nouvelles fonctionnalités de Workflow. Explique-les-moi, puis mets à jour [workflow] pour les utiliser. »

Résolution des problèmes

1. Le serveur ne démarre pas

   • Vérifiez que npx est installé et fonctionne.
   • Recherchez d'éventuels conflits avec d'autres serveurs MCP.
   • Vérifiez la syntaxe de votre fichier de configuration.

2. Échec des appels de Tools

   • Redémarrez le serveur MCP ou votre IDE, ou les deux.
   • Mettez votre IDE à jour vers la dernière version.