Junê (june-mcp)

june-mcp

Dale memoria a tu agente. june-mcp es el servidor MCP oficial para Junê — conecta cualquier host MCP (Claude Desktop, Claude Code y amigos) 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, de lógica cero: toda la recuperación, el ensamblado 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 leerse 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. Hay tres formas de tener uno:

1. App de escritorio Junê (local-first). Ejecuta la app 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 del motor june-local apuntan JUNE_BASE_URL a su propio servidor.
3. Alojado (Team). Apunta al endpoint de tu workspace de June alojado con la clave API de tu consola.

Configuración

El servidor es fail-closed: se niega a arrancar a menos que sepa a 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 canvas (workspace) al que vincular esta conexión — un nombre (work) o un id de canvas. Los nombres se resuelven al id al arrancar; los nombres ambiguos fallan en modo cerrado
JUNE_CANVAS_CREATE	opcional	1 crea el canvas nombrado en el primer arranque si aún no existe (rechazado en modo 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	Trae tu propia clave de LLM para respuestas citadas — se reenvía por solicitud como cabecera, nunca se registra, nunca se almacena en el servicio
JUNE_READONLY	opcional	1 oculta y rechaza todas las herramientas de escritura (la memoria pasa a ser solo lectura)
JUNE_FILES_ROOT	opcional	Carpeta desde la que los agentes de directorio opt-in pueden subir archivos vía june_ingest_file — sin definir ⇒ esa herramienta no existe
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_ANSWER	opcional	Tiempos de espera por verbo (por defecto 15 s / 120 s)
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 canvas (el nombre de tu canvas → 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 ausente lista los canvas que SÍ existen y apunta a 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 en un error de configuración en lugar de arrancar a medio cablear. Ejecuta primero el doctor; detecta todas las configuraciones erróneas comunes antes de que tu agente vea jamás 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 10 herramientas (11 cuando optas por june_ingest_file vía JUNE_FILES_ROOT).

Las herramientas

herramienta	qué obtiene tu agente
june_answer	Una respuesta citada y fundamentada del grafo — se abstiene en lugar de adivinar
june_search	Evidencia clasificada para una consulta (admite multi-salto)
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 y citable de inmediato)
june_ingest	Ingestión estructurada de nodos/aristas
june_enumerate	CADA nodo que coincida con un predicado — "lista TODOS los X" con cobertura completa de recuperación (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 estableces JUNE_FILES_ROOT
june_enrich	Pro: re-extracción en segundo plano del canvas con el motor más rico (idempotente; trabajo + sondeo; 403 en free)
june_resolve	Mantenimiento: fusiona entidades duplicadas mediante aristas reversibles same_as (se ejecuta en el servidor; strong_only=false desbloquea el nivel semántico en Pro)

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

Free vs Pro — la etiqueta june-pro

june-mcp es un solo paquete para todos; no existe una "build 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 june_remember y june_ingest_file ejecuta automáticamente los motores de entidades/aristas más ricos (el resultado informa qué engine se ejecutó), june_resolve se actualiza a coincidencia semántica, y june_enrich rellena memorias que se escribieron en el nivel free antes de que actualizaras. La terminal muestra en qué mundo estás: --doctor imprime una línea edition y el banner de arranque 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 derechos que limita las rutas Pro en el servidor), por lo que no puede discrepar de 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 canvas/workspace — el workspace está vinculado en el servidor desde el contexto de tu conexión, fail-closed. Una lectura entre inquilinos no es una comprobación de permisos que pudiera fallar en abierto; es irrepresentable desde el cliente. JUNE_READONLY=1 añade una segunda valla para despliegues de solo lectura. Tu clave de LLM propia viaja en cada solicitud de respuesta como cabecera y nunca la persiste ni registra el servicio.

Errores

Cada fallo ascendente se mapea 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), por lo que el servidor sobrevive a cualquier cosa que lance el endpoint y tu agente ve un mensaje limpio y accionable.

Licencia

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