Junê (june-mcp)

june-mcp

Dale a tu agente una memoria. june-mcp es el servidor oficial MCP para Junê — conecta cualquier host MCP (Claude Desktop, Claude Code y otros) a un grafo de conocimiento de June, para que tu agente pueda preguntar, buscar y recordar contra una memoria compartida, citada y aislada por inquilino.

Este paquete es un conector delgado, sin lógica propia: toda la recuperación, el ensamblaje del grafo y las respuestas ocurren en el endpoint de June al que lo apuntes. Aquí no vive ningún código de motor — por eso es lo bastante pequeño como para leerlo de una sentada.

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

Instalación

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

Apúntalo a un endpoint de June

june-mcp habla con cualquier servicio de June. Tres formas de tener uno:

1. Aplicación de escritorio Junê (local-primero). Ejecuta la aplicación Junê y conéctate a su motor local — tus archivos, grafo y claves permanecen en tu máquina.
2. Tu propio servicio de June. Los clientes Pro/Team que ejecutan el paquete de motor june-local apuntan JUNE_BASE_URL a su propio servidor.
3. Alojado (Team). Apunta al endpoint de tu espacio de trabajo June alojado con la clave API de tu consola.

Configuración

El servidor es de cierre ante fallo: se niega a arrancar a menos que sepa dónde conectarse y como quién, y te dice todo lo que falta en un solo mensaje (no un error a la vez).

env	requerido	significado
JUNE_BASE_URL	✅	Tu endpoint de June, p. ej. http://localhost:8000
JUNE_CANVAS	✅	El lienzo (espacio de trabajo) al que vincular esta conexión — un nombre (work) o un id de lienzo. Los nombres se resuelven al id al arrancar; los nombres ambiguos fallan de forma cerrada
JUNE_CANVAS_CREATE	opcional	1 crea el lienzo nombrado en la primera ejecución si aún no existe (rechazado en modo de solo lectura)
JUNE_API_KEY	✅	Tu clave API de June (JUNE_ALLOW_ANON=1 opta explícitamente por no usarla en configuraciones locales sin clave)
JUNE_LLM_KEY	opcional	Clave LLM propia para respuestas citadas — reenviada por solicitud como cabecera, nunca registrada, nunca almacenada en el servicio
JUNE_READONLY	opcional	1 oculta y rechaza todas las herramientas de escritura (la memoria se vuelve de solo lectura)
JUNE_TOOL_PROFILE	opcional	compact (predeterminado), full o lean. compact pliega 17 herramientas relacionadas en siete herramientas familiares que toman un op — 20 herramientas listadas en lugar de 30, 11 359 tokens de prompt en lugar de 13 236 en una conexión Pro de lectura-escritura. Cada llamada se envía al mismo código de antes, por lo que las compuertas, las reglas del lienzo, los recibos y las confirmaciones en dos fases no cambian. Medido en cuatro hosts antes de convertirse en el predeterminado: Claude Code 1.000 de éxito de tarea (base 0.987), GPT-5.4 directo 0.983 (0.957), Codex 0.922 (0.763), cero borrados inseguros en cada brazo. full lista los 30 miembros bajo sus propios nombres — el mismo código 0.4.2, un nombre cada uno. lean expone solo los seis verbos que usa un agente de codificación (june_answer / june_context / june_search / june_remember / june_learn / june_usage) con un apretón de manos de un párrafo, ~2.5k tokens — para sesiones que solo necesitan preguntar y recordar
JUNE_FILES_ROOT	opcional	Directorio de inclusión voluntaria desde el que los agentes pueden subir archivos mediante june_ingest_file — sin definir ⇒ esa herramienta no existe
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_ANSWER	opcional	Tiempos de espera por verbo (predeterminados 15 s / 120 s)
JUNE_TOOL_CONCURRENCY	opcional	Máximo de llamadas a herramientas ejecutándose a la vez en esta conexión (predeterminado 8). Los hosts canalizan solicitudes por un flujo; este es el techo explícito — el exceso de llamadas se pone en cola, nunca se abalanza
JUNE_DOCS_CANVAS	opcional	Lienzo que contiene los documentos del agente (instrucciones permanentes/habilidades — ver Memoria del agente abajo). Predeterminado agent_docs; creado en el primer june_doc_save
JUNE_DOCS_REFRESH	opcional	0 desactiva el resumen periódico standing_docs (predeterminado activado — es la red de seguridad contra el olvido)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	opcional	Cadencia del resumen: vence cada N llamadas a herramientas (predeterminado 12) o M minutos (predeterminado 10), lo que ocurra primero
JUNE_DOCS_DIGEST_CHARS	opcional	Límite de tamaño del resumen serializado (predeterminado 2000)
JUNE_EXPORT_ROOT	opcional	Directorio de repositorio de inclusión voluntaria al que el agente puede exportar páginas/documentos de June como archivos (ver Sincronización de repositorio abajo) — sin definir ⇒ las tres herramientas de sincronización de repositorio no existen
JUNE_EXPORT_GIT	opcional	1 confirma exactamente los archivos que escribió cada exportación (limitado por pathspec, nunca hace push)
JUNE_EXPORT_DIR	opcional	Subárbol de documentos del agente dentro de la raíz (predeterminado docs/agent)
JUNE_LOG_LEVEL	opcional	El registro es solo a stderr por diseño — stdout es el cable MCP

Compruébalo antes que tu agente

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

El doctor verifica, en orden: configuración → servicio alcanzable → resolución del lienzo (tu nombre de lienzo → su id, p. ej. name "work" → 9147bee6-…) → costura de búsqueda saludable → manifiesto de herramientas, e imprime PASS/FAIL por comprobación con una pista mapeada (p. ej. un nombre faltante lista los lienzos que SÍ existen y señala JUNE_CANVAS_CREATE=1). El doctor sale con 0 solo cuando todas las comprobaciones pasan (1 en caso contrario); el propio servidor sale con 2 ante un error de configuración en lugar de arrancar a medio cablear. Ejecuta el doctor primero; detecta todas las configuraciones erróneas comunes antes de que tu agente vea el servidor.

Conéctalo a Claude

Claude Desktop — fusiona en claude_desktop_config.json (Configuración → Desarrollador):

{
  "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

Reinicia completamente el host (Cmd+Q en macOS) y luego comprueba que el servidor muestra 20 herramientas — la superficie compacta, la predeterminada desde 0.4.2. JUNE_TOOL_PROFILE=full lista las mismas capacidades como 30 herramientas con nombre individual en su lugar (31 cuando optas por june_ingest_file mediante JUNE_FILES_ROOT).

Las herramientas

La superficie predeterminada es compacta: 20 herramientas, siete de las cuales agrupan operaciones relacionadas detrás de un argumento op. JUNE_TOOL_PROFILE=full lista los 30 miembros bajo sus propios nombres en su lugar — mismas capacidades, mismas compuertas, mismo comportamiento.

herramienta familiar	operaciones	pliegues
june_graph	neighborhood, subgraph	june_neighborhood, june_subgraph
june_maintain	enrich, resolve	june_enrich, june_resolve
june_page_read	list, get, grammar	june_page_list, june_page_get (+ la gramática de bloques bajo demanda)
june_page_edit	create, append, update	june_page_create, june_page_append, june_page_update
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

Todo lo demás conserva su propio nombre: 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 verbo que puede eliminar algo nunca se pliega con uno que no puede — por lo que june_page_write y june_page_delete permanecen separados de june_page_edit, y cada familia lleva un destructiveHint honesto.

Los nombres antiguos siguen funcionando en tus documentos de agente guardados: el resumen de documentos permanentes lleva el mapa nombre-antiguo → nombre-nuevo, y una llamada a un nombre plegado se rechaza con el reemplazo exacto (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

Qué hace cada operación:

herramienta	qué obtiene tu agente
june_answer	Una respuesta fundamentada y citada del grafo — se abstiene antes que adivinar
june_search	Evidencia clasificada para una consulta (admite múltiples saltos)
june_context	Un paquete de contexto ensamblado bajo un presupuesto de tokens
june_neighborhood	El grafo alrededor de un nodo
june_subgraph	Una exportación de subgrafo acotada
june_remember	Escribe un hecho/nota en el grafo (se vuelve recuperable + citable de inmediato). Los textos largos se ejecutan como un trabajo del motor: un resultado de {state: running, job_id} se recoge con june_remember(job_id=…) — nunca reenvíes el texto. El texto pegado se direcciona por contenido en el motor (v0.0.13), por lo que un reenvío de texto idéntico actualiza los mismos nodos; no puede duplicar
june_ingest	Ingestión estructurada de nodos/bordes
june_enumerate	TODOS los nodos que coinciden con un predicado — recuperación completa de "lista TODOS los X" (no top-k)
june_ingest_file	Sube un archivo local (pdf/docx/xlsx/csv/html/md/imágenes/audio) desde la carpeta aprobada por el operador — solo existe cuando configuras JUNE_FILES_ROOT
june_enrich	Pro: reextracción en segundo plano del lienzo con el motor más rico (idempotente; trabajo + sondeo; 403 en gratis)
june_resolve	Mantenimiento: fusiona entidades duplicadas mediante bordes same_as reversibles (se ejecuta en el servidor; strong_only=false desbloquea el nivel semántico en Pro)
june_docs_refresh / june_doc_list / june_doc_get	Lee los documentos permanentes del agente — resumen completo, listado del registro, cuerpo de un documento
june_doc_save / june_doc_delete / june_learn	Escríbelos — crea/reemplaza un documento o habilidad, eliminación en dos fases, añade una lección fechada
june_usage	Recibos de uso — lo que June realmente sirvió, medido por un tokenizador nombrado, nunca estimado. Un recibo completo (receipt_id) o el resumen de la ventana (window); una cifra de ahorro aparece solo sobre llamadas cuyos dos usos reportados por el proveedor se midieron realmente

Recibos en cada lectura

Cuando el motor se ejecuta con JUNE_USAGE=1 (escritorio: Configuración → Recibos de uso), cada resultado de june_answer / june_context / june_search también lleva receipt y un receipt_footer de una línea:

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

El conector envía X-June-Source: mcp y un id de X-June-Session por proceso de servidor, para que el motor pueda registrar qué documentos esta sesión de agente ya tenía (relecturas que evitó). El pie de página nunca dice "guardado": esa palabra existe solo en un recibo que contiene un par medido. Un motor sin recibos no envía pie de página, y june_usage responde claramente que están desactivados.

Las descripciones están escritas para el agente (qué → cuándo → devuelve), y cada entrada limitada se nota visiblemente de vuelta al agente en lugar de truncarse en silencio.

Memoria del agente — documentos, habilidades y el resumen contra el olvido

Las sesiones largas olvidan: las instrucciones que un agente leyó al inicio de la sesión (su CLAUDE.md, tus convenciones) pierden fuerza miles de tokens después. june-mcp lo arregla estructuralmente.

Los agentes guardan documentos permanentes en June — kind='doc' para instrucciones duraderas (pinned=true = siempre en vigor), kind='skill' para procedimientos nombrados con un disparador when_to_use de una línea (los cuerpos se cargan de forma perezosa, como deberían las habilidades), kind='learnings' para un registro fechado de solo añadido escrito mediante june_learn. Cada documento es una página ordinaria de June en el lienzo de documentos (JUNE_DOCS_CANVAS, predeterminado agent_docs), marcada por un pequeño bloque de metadatos — para que puedas abrir la memoria de tu agente en la aplicación Junê, leerla y editarla; el agente recoge tus ediciones en su siguiente actualización.

La mitad contra el olvido: en la primera llamada a herramienta de cada sesión, y luego cada 12 llamadas o 10 minutos (ajustable), el conector adjunta un resumen compacto standing_docs a un resultado de herramienta ordinario — cuerpos fijados completos, líneas de disparo de habilidades, resúmenes de una línea de documentos. Los resultados de herramientas siempre reingresan al contexto fresco del modelo, por lo que las instrucciones no pueden decaer como lo hace un prompt de sistema, en cualquier host MCP, sin cooperación del host. Un resumen que no se puede construir (servicio ocupado, lienzo faltante) se omite en silencio — nunca le cuesta nada a la llamada que lo lleva. Configura JUNE_DOCS_REFRESH=0 para desactivar el resumen; las herramientas de documentos siguen funcionando. June le enseña a los agentes cómo usarlo — desde su propio interior. El primer guardado crea el lienzo de documentación y siembra agent-memory-guide: el manual operativo (qué pertenece al lienzo del sistema vs. un lienzo de workstream, los tres tipos y cuándo usar cada uno, nombres, qué fijar, disciplina de revisión, sincronización de repositorio). Está listado en todos los registros y resúmenes, los agentes lo leen con june_doc_get('agent-memory-guide') cada vez que tienen dudas — y es una página ordinaria, así que edítalo y tus agentes seguirán tu versión. Antes de que se guarde nada, los estados vacíos devuelven un recorrido de setup en lugar de un encogimiento de hombros, y el prompt de june_memory_setup hace que el agente te entreviste y guarde tus convenciones como la primera documentación.

Haciendo June automático — el agente depende de él sin que se le diga

"Usa June" nunca debería necesitar decirse. Tres mecanismos se apilan para hacer el uso automático, cada uno cubriendo el punto ciego del anterior:

1. El hook del host (cierra el arranque en frío). Un servidor no puede hablar hasta la primera llamada del agente — así que instala las instrucciones permanentes de June en el archivo que tu host carga de forma nativa en cada sesión:

   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
   

   Está escrito como una sección gestionada (tu propio contenido nunca se toca; las re-ejecuciones lo actualizan en su lugar), y pone la postura de june-primero — consulta June antes de afirmar ignorancia, recuerda hechos sin que te lo pidan, aprende lecciones a medida que ocurren — directamente en el prompt del sistema.

2. Descripciones de herramientas proactivas (nunca decaen). Las descripciones de los verbos principales le dicen al modelo cuándo recurrir a ellos sin que se lo pidan — y las descripciones se releen en cada turno, en cada host MCP, sin necesidad de cooperación.

3. El documento june-first fijado (reafirma toda la sesión). Sembrado junto a la guía, viaja en cada resumen de standing_docs, de modo que la postura se repite a mitad de sesión exactamente donde la deriva de contexto largo la erosionaría. Como todo lo sembrado, es una página ordinaria — edítalo y tus agentes seguirán tu versión.

Lo que ningún servidor MCP puede hacer — honestamente — es forzar a un host a actuar: un agente cuyo host oculta SERVER_INSTRUCTIONS y no tiene archivo de instrucciones y nunca hace una llamada a June permanece en frío. El mecanismo 1 existe precisamente para que ese caso nunca ocurra en la práctica.

Sincronización de repositorio — el repo se mantiene actualizado con lo que June sabe

Actívalo con JUNE_EXPORT_ROOT=<your repo> y aparecen tres herramientas más:

herramienta	qué hace
june_docs_export	Refleja cada documento de agente a docs/agent/<name>.md — el repo siempre contiene las instrucciones permanentes actuales
june_page_export	Exporta cualquier página a un archivo gestionado, o a una sección gestionada insertada entre marcadores dentro de un archivo existente (path=KNOWHOW.md section=june-learnings) — solo se toca la región marcada
june_page_import	Lo inverso: edita un archivo exportado en tu editor e impórtalo de vuelta a su página de June — los documentos de agente mantienen su identidad, y un archivo obsoleto es rechazado en lugar de permitir que sobrescriba conocimiento más nuevo

Reglas de seguridad, todas aplicadas en código y fijadas por pruebas: cada ruta está cercada dentro de la raíz (verificación léxica de .. y resolución de enlaces simbólicos); un archivo no escrito por june-mcp nunca se sobrescribe; nada se elimina jamás; y con JUNE_EXPORT_GIT=1 cada exportación confirma exactamente los archivos que escribió — limitada por pathspec, de modo que tu trabajo preparado nunca se barre, y el push nunca ocurre. Los archivos exportados llevan frontmatter y son deterministas en bytes, de modo que un documento sin cambios se re-exporta a un archivo idéntico y git permanece en silencio.

El manifiesto (.june-export.json) hace comprobable la actualidad — dos modos CLI para 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 en CI convierte "¿está la documentación al día?" de una esperanza a una compilación fallida.

Gratis vs Pro — la etiqueta june-pro

june-mcp es un solo paquete para todos; no existe una "compilación Pro" separada. Pro es una propiedad del endpoint, no del conector: conéctate a un June activado con Pro (una licencia Pro en la app, una clave Pro en un workspace alojado) y las mismas herramientas llevan resultados de nivel Pro: cada escritura de june_remember y june_ingest_file ejecuta automáticamente los motores de entidad/edge más ricos (el resultado informa qué engine se ejecutó), june_resolve se actualiza a coincidencia semántica, y june_enrich rellena recuerdos que se escribieron en el nivel gratuito antes de que actualizaras. La terminal muestra en qué mundo estás: --doctor imprime una línea de edition y el banner de inicio del servidor etiqueta la conexión —

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

La etiqueta se lee del propio /v1/whoami del servicio (el mismo estado de derecho que controla las rutas Pro en el servidor), de modo que no puede discrepar con lo que realmente obtienes — y es solo de visualización: los derechos se aplican en el servicio sin importar lo que imprima cualquier cliente. Los servicios más antiguos sin /v1/whoami simplemente no muestran etiqueta.

Modelo de seguridad

La superficie de herramientas no expone ningún parámetro de lienzo/workspace — el workspace está vinculado en el servidor desde el contexto de tu conexión, con cierre ante fallos. Una lectura entre inquilinos no es una verificación de permisos que podría fallar abiertamente; es irrepresentable desde el cliente. JUNE_READONLY=1 añade una segunda cerca para implementaciones de solo lectura. Tu clave BYO LLM viaja en cada solicitud de respuesta como un encabezado y nunca se persiste ni se registra por el servicio.

Errores

Cada fallo ascendente se asigna a un payload de error tipado y redactado (construido solo a partir del tipo de excepción + estado HTTP — nunca de los cuerpos de respuesta), de modo que el servidor sobrevive a cualquier cosa que el endpoint lance y tu agente ve un mensaje limpio y accionable.

Licencia

MIT. El motor de Junê en sí es un producto separado de código cerrado — este conector es la parte abierta, por diseño.