MCP — connecter Tesserae à Claude Code, Codex, Cursor

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Deutsch

<!-- translations:end -->

Tesserae fournit un serveur stdio Model Context Protocol qui expose le graphe typé compilé à tout client compatible MCP : Claude Code, Codex CLI, Cursor, Claude Desktop, et d'autres. Le serveur annonce trois surfaces MCP complètes — tools, resources et prompts — afin que les clients puissent à la fois interroger le graphe à la demande et amorcer le contexte à moindre coût depuis des URI canoniques.

Prérequis

Le serveur lit depuis .tesserae/graph.json, donc une compilation initiale est requise :

cd /path/to/your-project
tesserae init    # interactive; or --yes for non-interactive
tesserae compile  # deterministic, no LLM calls, no API keys

Recompilez chaque fois que vos sources changent. Le serveur prendra en compte le nouveau graphe au prochain appel d'outil, sans nécessiter de redémarrage.

1) Générer la configuration client

tesserae projects mcp-config

Affiche un fragment JSON ressemblant à :

{
  "mcpServers": {
    "tesserae": {
      "command": "python3",
      "args": [
        "-m", "tesserae.mcp_server",
        "--graph", "/path/to/your-project/.tesserae/graph.json"
      ]
    }
  }
}

Le chemin exact est rempli à partir du projet courant. Passez --name <alias> si vous souhaitez un nom d'entrée de serveur différent de tesserae.

2) Coller la configuration dans votre client MCP

Redémarrez le client après modification. La session suivante se connectera et découvrira la surface Tesserae.

3) Ce que voit le client

Tools — invoqués par le modèle

Chaque outil accepte un graph_path ou un project (alias du registre) optionnel, de sorte qu'un seul serveur peut résoudre n'importe quel vault enregistré à chaque appel. À défaut, repli sur le projet actif.

Requêtes sur le graphe et récupération

Compilateur de contexte à la demande (Phase 7)

Mémoire de session (voir sessions.md)

Questions-réponses et registre

Configuration guidée

Resources — chargées automatiquement dans le contexte du modèle

URI que le client peut tirer via son sélecteur de ressources sans consommer un tour d'outil :

• tesserae://graph/schema — même charge utile que l'outil schema, prête à servir de contexte statique
• tesserae://graph/summary — résumé du projet actif
• tesserae://lint-report — le dernier lint report au format markdown

Plus des templates d'URI que le client peut construire à la demande :

• tesserae://wiki/{kind}/{slug} — le corps de n'importe quelle page wiki compilée
• tesserae://raw/{source_path} — n'importe quel markdown source brut

Prompts — modèles de recherche en un clic

Ils apparaissent dans le menu slash du client (par ex. la palette / de Claude Code) :

Chaque prompt se matérialise par un unique message utilisateur qui indique au modèle exactement quels outils Tesserae enchaîner, afin que le modèle n'ait pas à redécouvrir la surface à chaque fois.

Multi-projet : enregistrer plusieurs vaults sous un même serveur

Un registre persistant à ~/.tesserae/registry.json permet au même serveur MCP de résoudre n'importe quel projet enregistré par son nom :

tesserae register-project /path/to/research --name research
tesserae register-project /path/to/notes    --name notes

Après cela, tout outil acceptant project ou graph_path résoudra project: "research" via le registre au lieu d'exiger un chemin complet. Le serveur vérifie même que le graph_path enregistré existe toujours et renvoie une erreur claire si une recompilation est nécessaire.

Fan-out sur chaque vault enregistré

L'outil ask accepte scope: "all-registered" pour interroger en parallèle chaque projet enregistré et renvoyer les résultats agrégés :

{
  "name": "ask",
  "arguments": {
    "question": "Where is splatting used?",
    "scope": "all-registered"
  }
}

Restreignez à un sous-ensemble avec scope_aliases: ["research", "notes"].

CLI Claude multi-comptes

Si votre outil ask passe par la CLI Claude et que vous avez plusieurs comptes (par ex. ~/.claude et ~/.claude-personal2), passez claude_config_dir à chaque appel :

{
  "name": "ask",
  "arguments": {
    "question": "...",
    "claude_config_dir": "/Users/you/.claude-personal2"
  }
}

Le serveur exporte CLAUDE_CONFIG_DIR pour la durée de cet appel uniquement et restaure la valeur précédente ensuite. Aucune fuite entre les appels.

Vérification

Après le redémarrage de votre client MCP, confirmez la connexion :

• Claude Code : /mcp devrait lister tesserae avec le nombre d'outils.
• Cursor : l'icône MCP dans la barre de chat devrait afficher tesserae: connected avec les compteurs de tools/resources/prompts.
• Codex / Hermes : invoquez n'importe quel outil par son nom (par ex. schema) et vérifiez la réponse.

Si rien n'apparaît, vérifiez à deux fois que --graph pointe vers un .tesserae/graph.json existant — le serveur valide désormais cela au démarrage et à chaque appel d'outil, vous verrez donc un message d'erreur clair plutôt qu'une 500 silencieuse.

Où cela s'inscrit

Le serveur MCP est l'interface de lecture du graphe typé. Pour le chemin d'écriture (ingestion des sources, recompilation, rafraîchissement d'outils compagnons comme RAG-Anything ou Understand-Anything), utilisez la CLI directement. Les deux sont découplés : la CLI met à jour .tesserae/, le serveur MCP lit ce qui s'y trouve au prochain appel d'outil.