Piloter Knowledge avec le serveur MCP

Objectif : lire et écrire dans Knowledge depuis un client MCP (Model Context Protocol) — par exemple un assistant IA — sans écrire d'appels HTTP.

Prérequis : une clé API Knowledge (scope write pour créer/modifier), Node installé.

1. Installer / déclarer le serveur¶

Le paquet @puwapi/knowledge-mcp expose un binaire MCP en stdio. Avec Claude Code par exemple :

claude mcp add puwapi-knowledge \
  -e PUWAPI_KNOWLEDGE_API_KEY=pkk_live_xxx \
  -e PUWAPI_KNOWLEDGE_API_URL=https://knowledge.api.puwapi.com \
  -- npx -y @puwapi/knowledge-mcp

Variables d'environnement :

• PUWAPI_KNOWLEDGE_API_KEY — obligatoire (votre clé).
• PUWAPI_KNOWLEDGE_API_URL — défaut : la production ; en dev local http://localhost:6300.

2. Les outils disponibles¶

Une vingtaine d'outils, miroir de la surface d'intégration :

• Lecture : list_spaces, list_collections, list_articles, get_article, search, list_article_versions, get_article_version.
• Écriture : create_article, update_article, create/update/delete_space, create/update/delete_collection, reorder_articles, set_article_status, publish_article, archive_article, restore_article_version.

Le scope de la clé est appliqué côté serveur : une clé read ne peut pas écrire (les outils d'écriture échouent en erreur, sans planter le serveur).

3. Exemple d'usage¶

Une fois le serveur déclaré, votre assistant peut enchaîner : « liste mes espaces » → list_spaces, « crée un article Markdown dans la collection X et publie-le » → create_article puis publish_article.

Pièges¶

• stdout est réservé au protocole MCP : les logs du serveur vont sur stderr.
• Une erreur d'API remonte comme résultat d'erreur de l'outil, jamais comme exception — votre client la voit proprement.
• Pour un pilotage scripté (non-MCP), utilisez directement l'API : voir Publier de la documentation par l'API.