MCP Server — Vue d'ensemble

Le serveur MCP (Model Context Protocol) WakaStart est hébergé par ce site de documentation à https://docs.wakastart-dev.app/api/mcp. Il permet à Claude Code d'accéder à la documentation de l'API publique et aux specs OpenAPI directement depuis votre éditeur.

Pourquoi cette intégration

Plutôt que de jongler entre cette documentation et votre IDE, vous pouvez configurer Claude Code pour qu'il interroge directement le MCP et obtienne : la liste des endpoints disponibles, le détail des DTOs, des exemples curl générés, et des explications du flow auth — le tout en contexte, pendant que vous codez.

---

5 Tools disponibles

1. list_endpoints

Liste tous les endpoints /api/* avec méthode HTTP, route, droit requis et description.

bashCopier
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_endpoints",
      "arguments": { "tag": "Auth" }
    }
  }'

Paramètres optionnels :

• tag : filtrer par tag Swagger (Auth, Config, Discovery, Invitations…)
• method : filtrer par méthode HTTP (GET, POST, PUT, DELETE, PATCH)

---

2. get_endpoint_spec

Détail complet d'un endpoint : DTO request/response, codes HTTP, droit requis, exemples.

bashCopier
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_endpoint_spec",
      "arguments": { "path": "/api/auth/enrich", "method": "POST" }
    }
  }'

---

3. search_docs

Recherche full-text dans les chapitres de documentation Markdown du site.

bashCopier
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_docs",
      "arguments": { "query": "PKCE flow organizations" }
    }
  }'

---

4. get_auth_flow

Résumé structuré du flow d'authentification.

Paramètres :

• format : summary | full (défaut: full)
• context : frontend | backend | mobile

---

5. get_error_code

Détail d'un code d'erreur HTTP ou métier Wakastart.

Codes reconnus : 401, 403, 404, 409, 429, 5xx, BOLA, TOKEN_EXPIRED, VULN-002…

---

Resources disponibles

bashCopier
# Handshake MCP (obligatoire avant toute interaction)
curl -X POST https://docs.wakastart-dev.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": { "name": "claude-code", "version": "1.0" }
    }
  }'

Resources disponibles :

---

Caractéristiques techniques

---

URLs par environnement

---

Swagger UI

La spec OpenAPI est également disponible via l'interface interactive de ce site :

https://docs.wakastart-dev.app/v1.0/dev/api-reference

JSON brut (pour import dans Postman, Insomnia, etc.) : Si votre instance locale de la public-api tourne : http://localhost:3005/api/docs-json

---

Bonnes pratiques

• Utilisez list_endpoints + get_endpoint_spec en début de sprint pour découvrir les nouvelles routes.
• Le MCP est read-only — il ne peut pas modifier la plateforme.
• En CI/CD, ne pas inclure .mcp.json dans le container de production.
• Si l'instance docs est down, la spec OpenAPI statique reste accessible via public/openapi.json dans ce repo.

Aller plus loin

• Configuration Claude Code : .mcp.json, exemples et utilisation avancée
• Référence des endpoints : tableau statique de toutes les routes