Junê (june-mcp)

june-mcp

Donnez une mémoire à votre agent. june-mcp est le serveur MCP officiel pour Junê — il connecte tout hôte MCP (Claude Desktop, Claude Code, et autres) à un graphe de connaissances June, afin que votre agent puisse demander, rechercher et se souvenir via une mémoire partagée, citée et isolée par locataire.

Ce paquet est un connecteur fin, sans logique propre : toute la récupération, l'assemblage du graphe et les réponses se font sur le point de terminaison June vers lequel vous le pointez. Aucun code moteur ne vit ici — c'est pourquoi il est assez petit pour être lu d'une traite.

Claude Desktop / Claude Code  ──stdio──▶  june-mcp  ──HTTPS──▶  your June endpoint
                                                                 (graph · retrieval · answers)

Installation

pip install june-mcp          # just the connector   (or: pipx install june-mcp)
pip install june-ai           # umbrella: june-mcp + june-bench (the benchmark suite)
pip install "june-bench[mcp]" # the bench, with the connector as an extra

Pointez-le vers un point de terminaison June

june-mcp parle à tout service June. Trois façons d'en avoir un :

1. Application de bureau Junê (locale d'abord). Lancez l'application Junê et connectez-vous à son moteur local — vos fichiers, graphe et clés restent sur votre machine.
2. Votre propre service June. Les clients Pro/Team exécutant le paquet moteur june-local pointent JUNE_BASE_URL vers leur propre serveur.
3. Hébergé (Team). Pointez vers le point de terminaison de votre espace de travail June hébergé avec la clé API de votre console.

Configuration

Le serveur est fermé par défaut : il refuse de démarrer s'il ne sait pas où se connecter et en tant que qui, et vous dit tout ce qui manque en un seul message (pas une erreur à la fois).

env	requis	signification
JUNE_BASE_URL	✅	Votre point de terminaison June, p. ex. http://localhost:8000
JUNE_CANVAS	✅	Le canvas (espace de travail) auquel lier cette connexion — un nom (work) ou un identifiant de canvas. Les noms sont résolus en identifiants au démarrage ; les noms ambigus échouent en mode fermé
JUNE_CANVAS_CREATE	facultatif	1 crée le canvas nommé au premier lancement s'il n'existe pas encore (refusé en mode lecture seule)
JUNE_API_KEY	✅	Votre clé API June (JUNE_ALLOW_ANON=1 se désinscrit explicitement pour les configurations locales sans clé)
JUNE_LLM_KEY	facultatif	Apportez votre propre clé LLM pour les réponses citées — transmise par requête sous forme d'en-tête, jamais journalisée, jamais stockée sur le service
JUNE_READONLY	facultatif	1 masque et refuse tous les outils d'écriture (la mémoire devient en lecture seule)
JUNE_TOOL_PROFILE	facultatif	compact (défaut), full ou lean. compact regroupe 17 outils liés en sept outils familiaux qui prennent un argument op — 20 outils listés au lieu de 37, 11 359 jetons d'invite au lieu de 13 236 sur une connexion Pro en lecture-écriture. Chaque appel est acheminé vers le même code qu'avant, donc les portes, règles de canvas, reçus et confirmations en deux phases sont inchangés. Mesuré sur quatre hôtes avant de devenir le défaut : Claude Code 1 000 réussites de tâches (base 0,987), GPT-5.4 direct 0,983 (0,957), Codex 0,922 (0,763), zéro effacement dangereux sur chaque bras. full liste les 37 membres sous leurs propres noms — le même code, un nom chacun. lean n'expose que les six verbes qu'un agent de codage utilise (june_answer / june_context / june_search / june_remember / june_learn / june_usage) avec une poignée de main d'un paragraphe, ~2,5 k jetons — pour les sessions qui n'ont besoin que de demander et de se souvenir
JUNE_FILES_ROOT	facultatif	Répertoire opt-in à partir duquel les agents peuvent téléverser des fichiers via june_ingest_file — non défini ⇒ cet outil n'existe pas
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_RETRIEVAL / JUNE_TIMEOUT_ANSWER	facultatif	Budget de temps par classe de verbe (défauts 15 s / 90 s / 120 s) : lectures rapides ; june_context, qui réordonne chaque candidat ; réponses, qui portent un appel de modèle
JUNE_TOOL_CONCURRENCY	facultatif	Nombre maximal d'appels d'outils s'exécutant simultanément sur cette connexion (défaut 8). Les hôtes pipeline les requêtes sur un flux ; c'est le plafond explicite — les appels excédentaires font la file, jamais de ruée
JUNE_DOCS_CANVAS	facultatif	Canvas contenant les documents d'agent (instructions/compétences permanentes — voir Mémoire d'agent ci-dessous). Défaut agent_docs ; créé au premier june_doc_save
JUNE_DOCS_REFRESH	facultatif	0 désactive le digest périodique standing_docs (défaut activé — c'est le filet de sécurité anti-oubli)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	facultatif	Cadence du digest : dû tous les N appels d'outils (défaut 12) ou M minutes (défaut 10), selon la première échéance
JUNE_DOCS_DIGEST_CHARS	facultatif	Plafond de taille du digest sérialisé (défaut 2000)
JUNE_EXPORT_ROOT	facultatif	Répertoire de dépôt opt-in dans lequel l'agent peut exporter des pages/documents June sous forme de fichiers (voir Synchronisation de dépôt ci-dessous) — non défini ⇒ les trois outils de synchronisation de dépôt n'existent pas
JUNE_EXPORT_GIT	facultatif	1 valide exactement les fichiers que chaque export a écrits (limité par pathspec, ne pousse jamais)
JUNE_EXPORT_DIR	facultatif	Sous-arbre des documents d'agent dans la racine (défaut docs/agent)
JUNE_LOG_LEVEL	facultatif	La journalisation est uniquement sur stderr par conception — stdout est le fil MCP

Vérifiez-le avant votre agent

JUNE_BASE_URL=http://localhost:8000 JUNE_API_KEY=... JUNE_CANVAS=work june-mcp --doctor

Le docteur vérifie, dans l'ordre : configuration → service joignable → résolution du canvas (votre nom de canvas → son identifiant, p. ex. name "work" → 9147bee6-…) → couture de recherche saine → manifeste d'outils, et imprime RÉUSSI/ÉCHEC par vérification avec un indice mappé (p. ex. un nom manquant liste les canvas qui existent et pointe vers JUNE_CANVAS_CREATE=1). Le docteur sort avec 0 uniquement lorsque chaque vérification réussit (1 sinon) ; le serveur lui-même sort avec 2 sur une erreur de configuration au lieu de démarrer à moitié câblé. Exécutez le docteur d'abord ; il attrape chaque erreur de configuration courante avant que votre agent ne voie le serveur.

Branchez-le dans Claude

Claude Desktop — fusionnez dans claude_desktop_config.json (Paramètres → Développeur) :

{
  "mcpServers": {
    "june": {
      "command": "june-mcp",
      "env": {
        "JUNE_BASE_URL": "http://localhost:8000",
        "JUNE_API_KEY": "your-key",
        "JUNE_CANVAS": "work",
        "JUNE_LLM_KEY": "your-llm-provider-key"
      }
    }
  }
}

Claude Code :

claude mcp add june -e JUNE_BASE_URL=http://localhost:8000 \
  -e JUNE_API_KEY=your-key -e JUNE_CANVAS=work \
  -e JUNE_LLM_KEY=your-llm-provider-key -- june-mcp

Redémarrez complètement l'hôte (Cmd+Q sur macOS), puis vérifiez que le serveur affiche 20 outils — la surface compacte, le défaut depuis 0.4.2. JUNE_TOOL_PROFILE=full liste les mêmes capacités que 37 outils nommés individuellement à la place (38 lorsque vous optez pour june_ingest_file via JUNE_FILES_ROOT).

Les outils

La surface par défaut est compacte : 20 outils, dont sept regroupent des opérations liées derrière un argument op. JUNE_TOOL_PROFILE=full liste les 37 membres sous leurs propres noms à la place — mêmes capacités, mêmes portes, même comportement.

outil familial	opérations	regroupe
june_graph	neighborhood, subgraph, backlinks	june_neighborhood, june_subgraph, june_backlinks
june_maintain	enrich, resolve	june_enrich, june_resolve
june_page_read	list, get, removed, grammar	june_page_list, june_page_get, june_page_removed (+ la grammaire de blocs à la demande)
june_page_edit	create, append, update, insert, move, rename, meta, restore	june_page_create, june_page_append, june_page_update, june_page_insert, june_page_move, june_page_rename, june_page_meta, june_page_restore
june_canvas_read	list, current, use	june_canvas_list, june_canvas_current, june_canvas_use
june_canvas_erase	clear, delete	june_canvas_clear, june_canvas_delete
june_docs_read	refresh, list, get	june_docs_refresh, june_doc_list, june_doc_get

Tout le reste garde son propre nom : june_answer, june_search, june_enumerate, june_context, june_usage, june_remember, june_ingest, june_page_write, june_page_delete, june_canvas_create, june_doc_save, june_doc_delete, june_learn. Un verbe qui peut supprimer quelque chose n'est jamais regroupé avec un qui ne le peut pas — donc june_page_write et june_page_delete restent séparés de june_page_edit, et chaque famille porte un destructiveHint honnête.

Les anciens noms continuent de fonctionner dans vos documents d'agent enregistrés : la poignée de main compacte porte la carte ancien-nom → nouveau-nom, et un appel à un nom regroupé est refusé avec le remplacement exact (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

Ce que fait chaque opération :

outil	ce que votre agent obtient
june_answer	Une réponse citée et fondée du graphe — s'abstient plutôt que de deviner
june_search	Preuves classées pour une requête (prend en charge le multi-saut)
june_context	Un paquet de contexte assemblé sous un budget de jetons
june_neighborhood	Le graphe autour d'un nœud
june_subgraph	Une exportation de sous-graphe bornée
june_backlinks	Ce qui pointe vers un nœud (ses arêtes entrantes)
june_remember	Écrire un fait/une note dans le graphe (devient récupérable + citable immédiatement). Les textes longs s'exécutent comme un travail moteur : un résultat de {state: running, job_id} est collecté avec june_remember(job_id=…) — ne renvoyez jamais le texte. Le texte collé est adressé par contenu sur le moteur (v0.0.13), donc un renvoi de texte identique met à jour les mêmes nœuds ; il ne peut pas dupliquer
june_ingest	Ingestion structurée de nœuds/arêtes
june_enumerate	Nœuds correspondant à un prédicat pour les questions « liste TOUS les X » (pas top-k). Seul exhaustive: true prouve que la liste est complète ; un résultat court ou vide sans lui ne prouve pas que rien d'autre ne correspond
june_ingest_file	Téléverser un fichier local (pdf/docx/xlsx/csv/html/md/images/audio) depuis le dossier approuvé par l'opérateur — n'existe que lorsque vous définissez JUNE_FILES_ROOT
june_enrich	Pro : ré-extraction en arrière-plan du canvas avec le moteur plus riche (idempotent ; travail + sondage ; 403 sur gratuit)
june_resolve	Maintenance : fusionner les entités en double via des arêtes same_as réversibles (s'exécute côté serveur ; strong_only=false déverrouille le niveau sémantique sur Pro)
june_docs_refresh / june_doc_list / june_doc_get	Lire les documents permanents de l'agent — digest complet, liste du registre, corps d'un document
june_doc_save / june_doc_delete / june_learn	Les écrire — créer/remplacer un document ou une compétence, suppression en deux phases, ajouter une leçon datée
june_page_insert / june_page_move	Placer de nouveaux blocs après un bloc nommé, ou réordonner les blocs par identifiant — sans renvoyer la page (nécessite un moteur avec la fonctionnalité de page positions)
june_page_rename / june_page_meta	Renommer une page, ou l'épingler / définir son groupe dans votre liste de pages — ses blocs intacts
june_page_removed / june_page_restore	Voir ce qu'une page a perdu, et ramener les blocs avec leurs identifiants et positions d'origine
june_usage	Reçus d'utilisation — ce que June a réellement servi, mesuré par un tokeniseur nommé, jamais estimé. Un reçu complet (receipt_id) ou le résumé de fenêtre (window) ; un chiffre d'économie n'apparaît que sur les appels dont les deux utilisations rapportées par le fournisseur ont été réellement mesurées

Reçus sur chaque lecture

Lorsque le moteur s'exécute avec JUNE_USAGE=1 (bureau : Paramètres → Reçus d'utilisation), chaque résultat june_answer / june_context / june_search porte également receipt et un receipt_footer d'une ligne :

receipt r_7f…: served 812 tokens (exact, tiktoken:cl100k_base) from 3 blocks across 2 docs
· 1 doc this session already had — june_usage(receipt_id="r_7f…") shows it in full

Le connecteur envoie X-June-Source: mcp et un identifiant X-June-Session par processus serveur, donc le moteur peut enregistrer quels documents cette session d'agent avait déjà (les relectures qu'elle a évitées). Le pied de page ne dit jamais « économisé » : ce mot n'existe que sur un reçu qui contient une paire mesurée. Un moteur sans reçus n'envoie aucun pied de page, et june_usage répond simplement qu'ils sont désactivés.

Les descriptions sont écrites pour l'agent (quoi → quand → retours), et chaque entrée limitée est visiblement notifiée à l'agent au lieu d'être tronquée silencieusement.

Mémoire d'agent — documents, compétences et le digest anti-oubli

Les longues sessions oublient : les instructions qu'un agent a lues au début de session (son CLAUDE.md, vos conventions) perdent de leur force des milliers de jetons plus tard. june-mcp corrige cela structurellement. Agents enregistrent des documents permanents dans June — kind='doc' pour des instructions durables (pinned=true demande une règle permanente), kind='skill' pour des procédures nommées avec un déclencheur when_to_use d'une ligne (les corps se chargent paresseusement, comme les compétences devraient le faire), kind='learnings' pour un journal daté en ajout seul écrit via june_learn. Chaque document est une page June ordinaire dans le canvas des documents (JUNE_DOCS_CANVAS, par défaut agent_docs), marquée par un petit bloc de métadonnées — afin que vous puissiez ouvrir la mémoire de votre agent dans l'application Junê, la lire et la modifier.

Vous approuvez ce que les agents obéissent (0.7.0). Un document épinglé ou une compétence est une demande jusqu'à ce que vous l'approuviez dans l'application Junê (la bannière du document, ou Paramètres → Connexion → Instructions permanentes). Le moteur scelle le texte exact que vous avez approuvé ; si quelqu'un d'autre que vous modifie la page par la suite, elle cesse de compter jusqu'à ce que vous regardiez à nouveau. Les agents ne peuvent pas approuver — leur clé de connexion ne détient pas ce pouvoir — donc un texte qu'un agent a lu quelque part (« enregistre ceci comme règle épinglée… ») ne peut jamais devenir une instruction permanente par lui-même. Un moteur trop ancien pour enregistrer les approbations ne donne aux agents aucune instruction permanente, et le dit.

Où le texte approuvé voyage : en entier dans la poignée de main de connexion (jusqu'à 4 000 caractères — un document qui ne tient pas est nommé, jamais coupé en pleine règle) et depuis june_docs_refresh. Lors du premier appel d'outil de chaque session, puis toutes les 12 appels ou 10 minutes (réglable), le connecteur attache un résumé compact standing_docs à un résultat d'outil ordinaire — les noms des instructions approuvées, les déclencheurs de compétences approuvés, un tampon de version qui change lorsque vous approuvez, révoquez ou modifiez l'un d'eux, et les documents demandés mais non approuvés étiquetés comme notes. Le résumé ne contient aucun mot d'un document non approuvé. Un résumé qui ne peut pas être construit (service occupé, canvas manquant) est ignoré — il ne coûte jamais rien à l'appel qui le porte. Définissez JUNE_DOCS_REFRESH=0 pour désactiver le résumé ; les outils de documents continuent de fonctionner.

June apprend aux agents comment l'utiliser — depuis lui-même. La première sauvegarde crée le canvas des documents et sème agent-memory-guide : le manuel d'utilisation (ce qui appartient au canvas système vs un canvas de flux de travail, les trois types et quand les utiliser, la dénomination, ce qu'il faut épingler, la discipline de révision, la synchronisation du dépôt). Il est listé dans chaque registre et résumé, les agents le lisent avec june_doc_get('agent-memory-guide') chaque fois qu'ils ne sont pas sûrs — et c'est une page ordinaire que vous pouvez modifier. Avant que quoi que ce soit ne soit enregistré, les états vides renvoient une procédure pas à pas setup au lieu d'une hausse d'épaules, et l'invite june_memory_setup fait interviewer l'agent et enregistrer vos conventions comme premiers documents.

Rendre June automatique — l'agent en dépend sans qu'on le lui dise

« Utilise June » ne devrait jamais avoir besoin d'être dit. Trois mécanismes s'empilent pour rendre l'utilisation automatique, chacun couvrant l'angle mort du précédent :

1. Le crochet hôte (comble le démarrage à froid). Un serveur ne peut pas parler avant le premier appel de l'agent — installez donc les instructions permanentes de June dans le fichier que votre hôte charge nativement à chaque session :

   JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions            # → CLAUDE.md
   JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions AGENTS.md  # other agents
   

   Il est écrit comme une section gérée (votre propre contenu n'est jamais touché ; les ré-exécutions le mettent à jour en place), et il place la posture june-first — vérifier June avant de prétendre l'ignorance, se souvenir des faits sans qu'on le demande, apprendre les leçons au fur et à mesure — dans l'invite système elle-même.

2. Descriptions d'outils proactives (ne se dégradent jamais). Les descriptions des verbes de base indiquent au modèle quand les utiliser sans qu'on le demande — et les descriptions sont relues à chaque tour, dans chaque hôte MCP, sans coopération nécessaire.

3. La posture june-first dans la poignée de main. La posture par défaut de June est intégrée dans les instructions de la connexion (0.7.0 ; les versions antérieures l'ont semée comme document épinglé — une graine non touchée est maintenant cachée, une modifiée est à vous et nécessite votre approbation comme toute autre).

Ce qu'aucun serveur MCP ne peut faire — honnêtement — c'est forcer un hôte à agir : un agent dont l'hôte cache SERVER_INSTRUCTIONS et n'a pas de fichier d'instructions et ne fait jamais un appel June reste froid. Le mécanisme 1 existe précisément pour que ce cas ne se produise jamais en pratique.

Synchronisation du dépôt — le dépôt reste à jour avec ce que June sait

Optez avec JUNE_EXPORT_ROOT=<your repo> et trois autres outils apparaissent :

outil	ce qu'il fait
june_docs_export	Miroir chaque document d'agent vers docs/agent/<name>.md — le dépôt contient toujours les instructions permanentes actuelles
june_page_export	Exporter n'importe quelle page vers un fichier géré, ou dans une section gérée insérée entre des marqueurs dans un fichier existant (path=KNOWHOW.md section=june-learnings) — seule la région marquée est jamais touchée
june_page_import	L'inverse : modifier un fichier exporté dans votre éditeur et l'importer de nouveau dans sa page June — les documents d'agent conservent leur identité, et un fichier obsolète est refusé plutôt que de permettre d'écraser des connaissances plus récentes

Règles de sécurité, toutes appliquées dans le code et verrouillées par des tests : chaque chemin est clôturé à l'intérieur de la racine (vérification lexicale .. et résolution de liens symboliques) ; un fichier non écrit par june-mcp n'est jamais écrasé ; rien n'est jamais supprimé ; et avec JUNE_EXPORT_GIT=1 chaque export valide exactement les fichiers qu'il a écrits — limité par pathspec, donc votre travail en attente n'est jamais balayé, et le push ne se produit jamais. Les fichiers exportés portent un frontmatter et sont déterministes en octets, donc un document inchangé se ré-exporte en un fichier identique et git reste silencieux.

Le manifeste (.june-export.json) rend la vérification de fraîcheur possible — deux modes CLI pour CI :

june-mcp --export         # sync agent docs + every managed page/section, commit if enabled
june-mcp --export-check   # write NOTHING; exit 1 if the repo has drifted from June

--export-check dans CI transforme « les documents sont-ils à jour ? » d'un espoir en une construction qui échoue.

Gratuit vs Pro — la balise june-pro

june-mcp est un seul paquet pour tout le monde ; il n'y a pas de « build Pro » séparé. Pro est une propriété de l'endpoint, pas du connecteur : connectez-vous à un June activé Pro (une licence Pro dans l'application, une clé Pro sur un espace de travail hébergé) et les mêmes outils portent des résultats de niveau Pro : chaque écriture june_remember et june_ingest_file exécute automatiquement les moteurs d'entités/relations plus riches (le résultat rapporte quel engine a été exécuté), june_resolve passe à la correspondance sémantique, et june_enrich remplit les souvenirs qui ont été écrits sur le plan gratuit avant votre mise à niveau. Le terminal montre dans quel monde vous êtes : --doctor imprime une ligne edition et la bannière de démarrage du serveur étiquette la connexion —

june-mcp: connected http://localhost:8000 canvas name "work" → 11d2… [june-pro]

La balise est lue depuis le /v1/whoami du service lui-même (le même état de droit qui verrouille les routes Pro côté serveur), donc elle ne peut pas être en désaccord avec ce que vous obtenez réellement — et c'est affichage uniquement : les droits sont appliqués sur le service peu importe ce que n'importe quel client imprime. Les services plus anciens sans /v1/whoami n'affichent simplement aucune balise.

Modèle de sécurité

La surface d'outils n'expose aucun paramètre de canvas/espace de travail — l'espace de travail est lié côté serveur depuis le contexte de votre connexion, en échec-fermé. Une lecture inter-tenant n'est pas une vérification de permission qui pourrait échouer en ouvert ; elle est non représentable depuis le client. JUNE_READONLY=1 ajoute une deuxième clôture pour les déploiements en lecture seule. Votre clé LLM BYO voyage dans chaque demande de réponse comme un en-tête et n'est jamais persistée ni journalisée par le service.

Erreurs

Chaque échec en amont est mappé à un payload d'erreur typé et expurgé (construit uniquement à partir du type d'exception + du statut HTTP — jamais à partir des corps de réponse), donc le serveur survit à tout ce que l'endpoint lance et votre agent voit un message propre et actionnable.

Licence

MIT. Le moteur Junê lui-même est un produit séparé et à code source fermé — ce connecteur est la partie ouverte, par conception.