MCP Server — Configuration Claude Code

Ce chapitre couvre la configuration de Claude Code pour utiliser le serveur MCP WakaStart hébergé sur ce site de documentation.

---

Configuration .mcp.json

Créez un fichier .mcp.json à la racine de votre projet WakaApp :

jsonCopier
{
  "mcpServers": {
    "wakastart-docs": {
      "url": "http://localhost:3020/api/mcp",
      "transport": "http"
    }
  }
}

Pour pointer vers la staging ou la production :

jsonCopier
{
  "mcpServers": {
    "wakastart-docs": {
      "url": "https://docs.wakastart-dev.app/api/mcp",
      "transport": "http"
    }
  }
}

URLs par environnement :

---

Questions que vous pouvez poser à Claude

Une fois configuré, interrogez directement depuis Claude Code :

Via list_endpoints

• "Montre-moi tous les endpoints d'authentification"
• "Quels endpoints acceptent des POST ?"
• "Liste tous les endpoints d'invitations avec leurs droits requis"

Via get_endpoint_spec

• "Quel est le body attendu pour POST /api/invitations ?"
• "Quels codes d'erreur peut retourner DELETE /api/invitations/:id ?"
• "Génère un exemple curl pour POST /api/auth/enrich"

Via search_docs

• "Comment fonctionne le PKCE dans Wakastart ?"
• "Qu'est-ce qu'un AppRight ?"
• "Comment configurer le rate limiting côté Wakapp ?"

Via get_auth_flow

• "Explique-moi le flow d'auth Wakastart pour une app frontend"
• "Comment fonctionne l'auth M2M avec une API key ?"

Via get_error_code

• "Pourquoi est-ce que j'obtiens un 401 ?"
• "Qu'est-ce que BOLA ?"
• "Quand est-ce que l'API retourne un 409 ?"

---

Vérification du serveur

Testez que le serveur répond :

bashCopier
# Handshake
curl -X POST http://localhost:3020/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"}}}'

# Lister les tools disponibles
curl -X POST http://localhost:3020/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Appeler un tool
curl -X POST http://localhost:3020/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_endpoints","arguments":{"tag":"Auth"}}}'

---

Exemple de session Claude Code

Une fois .mcp.json configuré :

textCopier
Vous : "Génère le code TypeScript pour appeler POST /api/invitations"

Claude : [Appelle list_endpoints avec tag="Invitations"]
         [Appelle get_endpoint_spec avec path="/api/invitations", method="POST"]
         → Génère le code avec les types corrects, les headers requis et la gestion d'erreurs

---

Utilisation avec resources/read

Pour lire un chapitre complet de documentation dans Claude :

bashCopier
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "resources/list",
    "params": {}
  }'

Puis lire une resource :

bashCopier
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "resources/read",
    "params": { "uri": "wakastart://openapi/v1" }
  }'

---

Bonnes pratiques

• Utilisez list_endpoints + get_endpoint_spec en début de sprint.
• Le MCP est read-only — aucun risque de modifier la plateforme.
• En CI/CD, ne pas inclure .mcp.json dans le container de production — documentation locale uniquement.
• Si l'instance docs est down, la spec OpenAPI statique reste accessible via public/openapi.json.

Aller plus loin

• Vue d'ensemble du MCP : tools, resources, caractéristiques techniques
• Référence des endpoints : tableau statique de toutes les routes