Junê (june-mcp)

june-mcp

Dê memória ao seu agente. june-mcp é o servidor oficial MCP para Junê — ele conecta qualquer host MCP (Claude Desktop, Claude Code, e outros) a um grafo de conhecimento June, para que seu agente possa perguntar, buscar e lembrar contra uma memória compartilhada, citada e isolada por tenant.

Este pacote é um conector fino, sem lógica: toda recuperação, montagem de grafo e resposta acontecem no endpoint June para o qual você o aponta. Nenhum código de motor vive aqui — por isso é pequeno o suficiente para ser lido de uma só vez.

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

Instalar

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

Aponte para um endpoint June

june-mcp fala com qualquer serviço June. Três maneiras de ter um:

1. Aplicativo de desktop Junê (local-first). Execute o aplicativo Junê e conecte-se ao seu motor local — seus arquivos, grafo e chaves permanecem na sua máquina.
2. Seu próprio serviço June. Clientes Pro/Team que executam o pacote de motor june-local apontam JUNE_BASE_URL para o próprio servidor.
3. Hospedado (Team). Aponte para o endpoint do seu workspace June hospedado com a chave de API do seu console.

Configure

O servidor é fail-closed: ele se recusa a iniciar a menos que saiba para onde conectar e como quem, e informa tudo o que está faltando em uma única mensagem (não um erro por vez).

env	obrigatório	significado
JUNE_BASE_URL	✅	Seu endpoint June, ex.: http://localhost:8000
JUNE_CANVAS	✅	O canvas (workspace) ao qual vincular esta conexão — um nome (work) ou um id de canvas. Nomes são resolvidos para o id na inicialização; nomes ambíguos falham fechados
JUNE_CANVAS_CREATE	opcional	1 cria o canvas nomeado na primeira execução se ele ainda não existir (recusado em modo somente leitura)
JUNE_API_KEY	✅	Sua chave de API June (JUNE_ALLOW_ANON=1 opta explicitamente por setups locais sem chave)
JUNE_LLM_KEY	opcional	Chave LLM própria para respostas citadas — encaminhada por requisição como cabeçalho, nunca registrada, nunca armazenada no serviço
JUNE_READONLY	opcional	1 oculta e recusa todas as ferramentas de escrita (a memória se torna somente leitura)
JUNE_FILES_ROOT	opcional	Diretório opt-in do qual os agentes podem enviar arquivos via june_ingest_file — não definido ⇒ essa ferramenta não existe
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_ANSWER	opcional	Timeouts por verbo (padrões 15 s / 120 s)
JUNE_LOG_LEVEL	opcional	O registro é somente em stderr por design — stdout é o fio MCP

Verifique antes do seu agente

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

O doutor verifica, em ordem: config → serviço acessível → resolução do canvas (seu nome do canvas → seu id, ex.: name "work" → 9147bee6-…) → seam de busca saudável → manifesto de ferramentas, e imprime PASS/FAIL para cada verificação com uma dica mapeada (ex.: um nome ausente lista os canvases que EXISTEM e aponta para JUNE_CANVAS_CREATE=1). O doutor sai com código 0 apenas quando todas as verificações passam (1 caso contrário); o servidor em si sai com 2 em um erro de configuração em vez de iniciar pela metade. Execute o doutor primeiro; ele detecta toda configuração incorreta comum antes que seu agente veja o servidor.

Conecte-se ao Claude

Claude Desktop — mescle em claude_desktop_config.json (Settings → Developer):

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

Reinicie completamente o host (Cmd+Q no macOS) e verifique se o servidor mostra 10 ferramentas (11 quando você opta por june_ingest_file via JUNE_FILES_ROOT).

As ferramentas

ferramenta	o que seu agente obtém
june_answer	Uma resposta fundamentada e citada do grafo — abstém-se em vez de adivinhar
june_search	Evidências classificadas para uma consulta (suporta multi-hop)
june_context	Um pacote de contexto montado sob um orçamento de tokens
june_neighborhood	O grafo ao redor de um nó
june_subgraph	Uma exportação de subgrafo limitada
june_remember	Escreve um fato/nota no grafo (torna-se recuperável e citável imediatamente)
june_ingest	Ingestão estruturada de nós/arestas
june_enumerate	TODOS os nós que correspondem a um predicado — recall-completo "liste TODOS X" (não top-k)
june_ingest_file	Envia um arquivo local (pdf/docx/xlsx/csv/html/md/imagens/áudio) da pasta aprovada pelo operador — só existe quando você define JUNE_FILES_ROOT
june_enrich	Pro: reextração em segundo plano do canvas com o motor mais rico (idempotente; trabalho + poll; 403 no free)
june_resolve	Manutenção: mescla entidades duplicadas via arestas reversíveis same_as (executa no lado do servidor; strong_only=false desbloqueia o nível semântico no Pro)

As descrições são escritas para o agente (o quê → quando → retorna), e cada entrada limitada é visivelmente anotada de volta ao agente em vez de ser truncada silenciosamente.

Free vs Pro — a tag june-pro

june-mcp é um pacote para todos; não há "build pro" separado. Pro é uma propriedade do endpoint, não do conector: conecte-se a um June ativado para Pro (uma licença Pro no aplicativo, uma chave Pro em um workspace hospedado) e as mesmas ferramentas trazem resultados de nível Pro: toda escrita june_remember e june_ingest_file executa os motores de entidade/arestas mais ricos automaticamente (o resultado informa qual engine foi executado), june_resolve atualiza para correspondência semântica, e june_enrich preenche memórias que foram escritas no nível free antes de você atualizar. O terminal mostra em qual mundo você está: --doctor imprime uma linha edition e o banner de inicialização do servidor marca a conexão —

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

A etiqueta é lida do próprio /v1/whoami do serviço (o mesmo estado de permissões que controla as rotas Pro no lado do servidor), então não pode divergir do que você realmente recebe — e é apenas de exibição: as permissões são aplicadas no serviço independentemente do que qualquer cliente imprimir. Serviços mais antigos sem /v1/whoami simplesmente não mostram etiqueta.

Modelo de segurança

A superfície de ferramentas não expõe nenhum parâmetro de canvas/workspace — o workspace é vinculado no lado do servidor a partir do contexto da sua conexão, fail-closed. Uma leitura entre tenants não é uma verificação de permissão que possa falhar aberta; é irrepresentável a partir do cliente. JUNE_READONLY=1 adiciona uma segunda cerca para implantações somente leitura. Sua chave LLM própria viaja em cada requisição de resposta como cabeçalho e nunca é persistida ou registrada pelo serviço.

Erros

Cada falha upstream é mapeada para um payload de erro tipado e redigido (construído apenas a partir do tipo de exceção + status HTTP — nunca de corpos de resposta), para que o servidor sobreviva a qualquer coisa que o endpoint lance e seu agente veja uma mensagem limpa e acionável.

Licença

MIT. O motor Junê em si é um produto separado e de código fechado — este conector é a parte aberta, por design.