mistral-mcp: Instructions file for Claude Code

CLAUDE.md — mistral-mcp

Instructions de travail pour Claude (Opus 4.7) sur ce repo. Objectif : un serveur MCP centré sur les documents, avec un profil core de six outils et une couverture avancée explicite. La compatibilité est testée ; la disponibilité de l'API Mistral n'est pas garantie par ce dépôt.

Voir CONTRIBUTING.md pour les validations et MIGRATION.md pour la version candidate 1.0.0-rc.1.

1. Identité du projet

• Nom : mistral-mcp (npm + github.com/Swih/mistral-mcp)
• Rôle : serveur MCP stdio + Streamable HTTP wrappant l'API Mistral pour clients MCP (Claude Code, Cursor, Zed, Windsurf, Claude Desktop, ChatGPT Apps).
• Versions en vigueur :
  • MCP spec : 2026-07-28, plus le handshake 2025 servi depuis les mêmes enregistrements. Le second n'est pas de la dette : c'est ce que parlent quasiment tous les clients diffusés. Toute évolution doit rester servable aux deux ères — test/stdio/protocol-eras.test.ts le vérifie.
  • SDK MCP : @modelcontextprotocol/server@^2.0.0 — toujours via la high-level API McpServer + registerTool/Resource/Prompt. Ne jamais descendre au low-level Server.
    • stdio et HTTP prennent une factory, jamais une instance : serveStdio(factory, { legacy: "serve" }) et createMcpHandler(factory, { legacy: "stateless" }). C'est le SDK qui décide de l'ère.
    • @modelcontextprotocol/sdk@^1.30.0 reste en devDependency : c'est le client de l'ère 2025 utilisé pour tester la compat, rien d'autre ne doit l'importer.
  • SDK Mistral : @mistralai/mistralai@^2.6.4 (Speakeasy-generated). Retry config obligatoire.
  • zod : ^4.2.0 (plancher imposé par le SDK v2). Attention : .default() porte sur le type de sortie en zod 4 — pour un objet dont les champs ont leurs propres defaults, c'est .prefault({}).
  • Node : >=20, TypeScript strict.

2. Règles dures (ne pas transgresser)

1. Zéro claim non-vérifiable. Si une feature n'est pas shippée dans ce repo et testée, elle n'existe pas dans le README, la doc, le CHANGELOG. Pas de "coming soon", pas de roadmap aspirationnelle vendue comme acquise.
2. Langues : FR + EN uniquement. Prompts, docs, commentaires, messages d'erreur. Aucune autre langue. Si on trouve de l'espagnol/allemand/etc. dans le code, on strippe.
3. Spec-compliance >>> ergonomie. Si la spec MCP dit "include outputSchema" ou "annotations are REQUIRED for read/write hints", on fait. Toujours.
4. Chaque tool renvoie content[] ET structuredContent. content[] = fallback lisible pour clients pré-2025-06-18. structuredContent = payload JSON strict conforme à outputSchema. Jamais l'un sans l'autre.
5. Chaque tool déclare annotations : title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Pour un wrapper API externe, openWorldHint=true quasi toujours.
6. Erreurs API → { content: [text], isError: true }, jamais throw. Le LLM appelant doit pouvoir self-correct.
7. Les inputs zod sont la source de vérité. Jamais de cast as any, jamais de z.any(). Si un type Mistral n'est pas exporté, on le reconstruit avec zod, on ne "fait confiance".
8. Le retry config est non-négociable : backoff strategy, initialInterval: 500, maxInterval: 5000, exponent: 2, maxElapsedTime: 30000, retryConnectionErrors: true, timeoutMs: 60000.
9. Pas d'env var autre que MISTRAL_API_KEY sans justification. L'API key est lue UNE fois dans src/index.ts.
10. Pas de dépendance runtime ajoutée sans approbation explicite. Les seules deps runtime acceptées : @modelcontextprotocol/server, @mistralai/mistralai, zod. Point final. C'est pourquoi l'adaptateur node:http ↔ web-standard est écrit à la main dans transport.ts plutôt que pris chez @modelcontextprotocol/node, qui traîne @hono/node-server pour quarante lignes.