Aller au contenu principal

Intégration du serveur MCP

docStatic intègre un serveur MCP (Model Context Protocol) qui permet aux assistants IA d’accéder à votre documentation et de la comprendre. Cela offre une assistance intelligente pour l’édition, la recherche et l’analyse de contenu.

Présentation​

Le serveur MCP connecte les assistants IA directement à votre documentation docStatic via le point de terminaison GraphQL de TinaCMS, ce qui leur permet de :

  • Rechercher du contenu dans la documentation à l’aide de requêtes en langage naturel
  • Récupérer des documents spécifiques par chemin d’accès ou selon des critères
  • Analyser les modèles d’utilisation des composants MDX
  • Comprendre la structure des documents et les métadonnées
  • Fournir une assistance contextuelle basée sur votre contenu réel

Prérequis​

  • Node.js 22.0 ou version ultérieure, soit la même version que celle requise par docStatic lui-même
  • Un serveur de développement docStatic en cours d’exécution (npm run dev)
  • Point de terminaison GraphQL de TinaCMS accessible à l’adresse [localhost](http://localhost:4001/graphql)

Configuration​

1. Installer les dépendances du serveur MCP​

Depuis le répertoire principal de docStatic :

npm run mcp:install

Cela installe les dépendances nécessaires au serveur MCP dans le sous-répertoire mcp-server.

2. Compiler le serveur MCP​

npm run mcp:build

Cela compile le code TypeScript du serveur MCP en JavaScript.

3. Démarrer le serveur de développement docStatic​

Le serveur MCP nécessite que votre site docStatic soit en cours d’exécution :

npm run dev

Cela démarre :

  • Docusaurus à l’adresse [http://localhost:3000](http://localhost:3000`)
  • L'interface d'administration de TinaCMS à l'adresse [localhost](http://localhost:3000/admin)
  • Le point de terminaison GraphQL à l'adresse [localhost](http://localhost:4001/graphql)

4. Exécuter le serveur MCP​

Dans un terminal séparé :

npm run mcp:start

Pour le développement avec redémarrage automatique en cas de modifications :

npm run mcp:dev

Outils disponibles​

Le serveur MCP fournit plusieurs outils que les assistants IA peuvent utiliser :

Recherche de documents​

  • `search_documents` : rechercher des documents à l’aide de mots-clés
  • `get_document` : récupérer un document spécifique par chemin d’accès
  • `list_all_documents` : obtenir les métadonnées de tous les documents

Analyse de contenu​

  • `get_documents_by_tag` : filtrer les documents par balises de taxonomie
  • `analyze_mdx_components` : identifier les composants MDX utilisés dans les documents
  • `check_server_status` : vérifier la connectivité GraphQL

Configuration avec Claude Desktop​

Pour utiliser le serveur MCP avec Claude Desktop, ajoutez cette configuration à vos paramètres MCP dans Claude Desktop :

{
  "mcpServers": {
    "docstatic": {
      "command": "node",
      "args": ["/absolute/path/to/docstatic/mcp-server/dist/server.js"],
      "cwd": "/absolute/path/to/docstatic"
    }
  }
}
Path Requirements

Replace /absolute/path/to/docstatic with the full path to your docStatic project directory. Both the args path and cwd path must be absolute paths.

Commandes de développement​

CommandeDescriptionnpm run mcp:installInstaller les dépendances du serveur MCPnpm run mcp:buildCompiler TypeScript en JavaScriptnpm run mcp:startDémarrer le serveur MCP compilénpm run mcp:devCompiler et démarrer en mode développement

Dépannage​

Problèmes courants​

« Le serveur GraphQL ne fonctionne pas »

  • Assurez-vous que la commande npm run dev est en cours d’exécution dans le répertoire principal
  • Vérifiez que [localhost](http://localhost:4001/graphql) est accessible
  • Vérifiez que TinaCMS a bien démarré

« Connexion refusée »

  • Vérifiez que le serveur de développement est en cours d’exécution
  • Vérifiez si le port 4001 est disponible
  • Vérifiez que les paramètres du pare-feu ne bloquent pas la connexion

« Document introuvable »

  • Utilisez des chemins relatifs tels que installation.mdx, et non /docs/installation.mdx
  • Assurez-vous que le document existe bien dans le répertoire docs/
  • Vérifiez que le fichier comporte un frontmatter MDX correct

Test de la connectivité​

Testez directement le point de terminaison GraphQL :

curl -X POST http://localhost:4001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

Réponse attendue :

{"data":{"__typename":"Query"}}

Vérification des journaux du serveur MCP​

Le serveur MCP envoie ses journaux vers stderr. Si vous utilisez Claude Desktop, consultez les journaux de Claude Desktop pour repérer les messages d’erreur provenant du serveur MCP.

Avantages pour le workflow de documentation​

Grâce à l’intégration MCP, les assistants IA peuvent :

  1. Comprendre la structure de votre contenu - Accéder à la taxonomie complète et à la hiérarchie des documents
  2. Fournir des suggestions précises - Fonder leurs recommandations sur vos modèles de documentation réels
  3. Contribuer à la cohérence - Identifier les endroits où du contenu ou des composants similaires devraient être utilisés
  4. Accélérer l’édition - Trouver rapidement du contenu associé et suggérer des améliorations
  5. Analyser les schémas - Identifier les composants fréquemment utilisés et les lacunes de contenu

Architecture​

docStatic Project
├── docs/               # Your MDX documentation files
├── mcp-server/         # MCP server implementation
│   ├── src/server.ts   # Main server logic
│   ├── package.json    # MCP-specific dependencies
│   └── dist/           # Compiled JavaScript
└── tina/               # TinaCMS configuration
    └── config.jsx      # GraphQL schema definition

Le serveur MCP fait office de passerelle entre les assistants IA et votre contenu docStatic, offrant un accès structuré à la documentation via l’API GraphQL existante de TinaCMS.

Prochaines étapes​

Une fois le serveur MCP configuré :

  1. Testez l’intégration avec votre assistant IA
  2. Explorez les fonctionnalités de recherche dans la documentation
  3. Utilisez des outils d’analyse de contenu pour comprendre les schémas de votre documentation
  4. Tirez parti de l’assistance IA pour les workflows de création et d’édition de contenu

Pour plus de détails sur la mise en œuvre du serveur MCP, consultez la page Détails de mise en œuvre du serveur MCP.