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 afins) a um grafo de conhecimento June, para que seu agente possa perguntar, buscar e lembrar contra uma memória compartilhada, citada e isolada por locatário.

Este pacote é um conector fino, sem lógica própria: 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 vez só.

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

Instalação

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 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.

Configuração

O servidor é fail-closed: ele se recusa a iniciar a menos que saiba 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 de forma fechada
JUNE_CANVAS_CREATE	opcional	1 cria o canvas nomeado na primeira execução se ele ainda não existir (recusado no modo somente leitura)
JUNE_API_KEY	✅	Sua chave de API June (JUNE_ALLOW_ANON=1 opta explicitamente por não usar chave em configurações locais sem chave)
JUNE_LLM_KEY	opcional	Traga sua própria chave de LLM 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 fica somente leitura)
JUNE_TOOL_PROFILE	opcional	compact (padrão), full ou lean. compact dobra 17 ferramentas relacionadas em sete ferramentas de família que recebem um op — 20 ferramentas listadas em vez de 30, 11.359 tokens de prompt em vez de 13.236 em uma conexão Pro de leitura/escrita. Cada chamada é despachada para o mesmo código de antes, então portões, regras de canvas, recibos e confirmações em duas fases permanecem inalterados. Medido em quatro hosts antes de se tornar o padrão: Claude Code 1.000 de sucesso de tarefa (linha de base 0.987), GPT-5.4 direto 0.983 (0.957), Codex 0.922 (0.763), zero apagamentos inseguros em todos os braços. full lista os 30 membros sob seus próprios nomes — o mesmo código 0.4.2, um nome cada. lean expõe apenas os seis verbos que um agente de codificação usa (june_answer / june_context / june_search / june_remember / june_learn / june_usage) com um handshake de um parágrafo, ~2,5 mil tokens — para sessões que só precisam perguntar e lembrar
JUNE_FILES_ROOT	opcional	Diretório do qual agentes opt-in 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_TOOL_CONCURRENCY	opcional	Máximo de chamadas de ferramenta executando simultaneamente nesta conexão (padrão 8). Hosts fazem pipeline de requisições em um único stream; este é o teto explícito — chamadas excedentes entram na fila, nunca em debandada
JUNE_DOCS_CANVAS	opcional	Canvas que contém os documentos do agente (instruções permanentes/habilidades — veja Memória do agente abaixo). Padrão agent_docs; criado no primeiro june_doc_save
JUNE_DOCS_REFRESH	opcional	0 desativa o resumo periódico standing_docs (padrão ligado — é a rede de segurança contra esquecimento)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	opcional	Cadência do resumo: devido a cada N chamadas de ferramenta (padrão 12) ou M minutos (padrão 10), o que vier primeiro
JUNE_DOCS_DIGEST_CHARS	opcional	Limite de tamanho do resumo serializado (padrão 2000)
JUNE_EXPORT_ROOT	opcional	Diretório de repositório opt-in para o qual o agente pode exportar páginas/documentos June como arquivos (veja Sincronização de repositório abaixo) — não definido ⇒ as três ferramentas de sincronização de repositório não existem
JUNE_EXPORT_GIT	opcional	1 confirma exatamente os arquivos que cada exportação escreveu (limitado por pathspec, nunca faz push)
JUNE_EXPORT_DIR	opcional	Subárvore de documentos do agente dentro da raiz (padrão docs/agent)
JUNE_LOG_LEVEL	opcional	O registro é somente 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 doctor verifica, em ordem: configuração → serviço acessível → resolução de canvas (seu nome de canvas → seu id, ex.: name "work" → 9147bee6-…) → costura de busca saudável → manifesto de ferramentas, e imprime PASS/FAIL por verificação com uma dica mapeada (ex.: um nome ausente lista os canvases que EXISTEM e aponta para JUNE_CANVAS_CREATE=1). O doctor sai com 0 apenas quando todas as verificações passam (1 caso contrário); o próprio servidor sai com 2 em erro de configuração em vez de iniciar meio conectado. Execute o doctor primeiro; ele captura toda configuração incorreta comum antes que seu agente veja o servidor.

Conecte ao Claude

Claude Desktop — mescle em claude_desktop_config.json (Configurações → Desenvolvedor):

{
  "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 20 ferramentas — a superfície compacta, o padrão desde 0.4.2. JUNE_TOOL_PROFILE=full lista as mesmas capacidades como 30 ferramentas nomeadas individualmente (31 quando você opta por june_ingest_file via JUNE_FILES_ROOT).

As ferramentas

A superfície padrão é compacta: 20 ferramentas, sete das quais agrupam operações relacionadas atrás de um argumento op. JUNE_TOOL_PROFILE=full lista os 30 membros sob seus próprios nomes — mesmas capacidades, mesmos portões, mesmo comportamento.

ferramenta de família	operações	dobra
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 (+ a gramática de blocos sob 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 o resto mantém seu próprio nome: 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. Um verbo que pode remover algo nunca é dobrado com um que não pode — então june_page_write e june_page_delete permanecem separados de june_page_edit, e cada família carrega um destructiveHint honesto.

Nomes antigos continuam funcionando em seus documentos de agente salvos: o resumo de documentos permanentes carrega o mapa nome-antigo → nome-novo, e uma chamada a um nome dobrado é recusada com a substituição exata (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

O que cada operação faz:

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ência classificada 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). Textos longos rodam como um job do motor: um resultado de {state: running, job_id} é coletado com june_remember(job_id=…) — nunca reenvie o texto. Texto colado é endereçado por conteúdo no motor (v0.0.13), então um reenvio de texto idêntico faz upsert dos mesmos nós; não pode duplicar
june_ingest	Ingestão estruturada de nós/arestas
june_enumerate	TODOS os nós que correspondem a um predicado — recall completo de "liste TODOS os 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; job + 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)
june_docs_refresh / june_doc_list / june_doc_get	Lê os documentos permanentes do agente — resumo completo, listagem de registro, corpo de um documento
june_doc_save / june_doc_delete / june_learn	Escreve-os — cria/substitui um documento ou habilidade, exclusão em duas fases, anexa uma lição datada
june_usage	Recibos de uso — o que June realmente serviu, medido por um tokenizador nomeado, nunca estimado. Um recibo completo (receipt_id) ou o resumo da janela (window); um número de economia aparece apenas sobre chamadas cujos dois usos relatados pelo provedor foram realmente medidos

Recibos em cada leitura

Quando o motor roda com JUNE_USAGE=1 (desktop: Configurações → Recibos de uso), cada resultado de june_answer / june_context / june_search também carrega receipt e um receipt_footer de uma linha:

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

O conector envia X-June-Source: mcp e um id X-June-Session por processo de servidor, para que o motor possa registrar quais documentos esta sessão de agente já tinha (releituras que evitou). O rodapé nunca diz "salvo": essa palavra existe apenas em um recibo que contém um par medido. Um motor sem recibos não envia rodapé, e june_usage responde claramente que estão desligados.

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

Memória do agente — documentos, habilidades e o resumo anti-esquecimento

Sessões longas esquecem: instruções que um agente leu no início da sessão (seu CLAUDE.md, suas convenções) perdem força milhares de tokens depois. june-mcp corrige isso estruturalmente.

Agentes salvam documentos permanentes no June — kind='doc' para instruções duráveis (pinned=true = sempre em vigor), kind='skill' para procedimentos nomeados com um gatilho when_to_use de uma linha (corpos carregam preguiçosamente, como habilidades devem), kind='learnings' para um registro datado somente de anexação escrito via june_learn. Cada documento é uma página June comum no canvas de documentos (JUNE_DOCS_CANVAS, padrão agent_docs), marcada por um pequeno bloco de metadados — para que você possa abrir a memória do seu agente no aplicativo Junê, lê-la e editá-la; o agente capta suas edições na próxima atualização.

A metade anti-esquecimento: na primeira chamada de ferramenta de cada sessão, e depois a cada 12 chamadas ou 10 minutos (ajustável), o conector anexa um resumo compacto standing_docs a um resultado de ferramenta comum — corpos fixados na íntegra, linhas de gatilho de habilidades, resumos de uma linha de documentos. Resultados de ferramentas sempre reentram no contexto fresco do modelo, então as instruções não podem decair da mesma forma que um prompt de sistema, em qualquer host MCP, sem cooperação do host. Um resumo que não pode ser construído (serviço ocupado, canvas ausente) é silenciosamente ignorado — nunca custa nada à chamada que o carrega. Defina JUNE_DOCS_REFRESH=0 para desligar o resumo; as ferramentas de documento continuam funcionando. June ensina os agentes a usá-lo — a partir de si mesmo. O primeiro salvamento cria o canvas de documentação e semeia agent-memory-guide: o manual de operação (o que pertence ao canvas do sistema vs um canvas de workstream, os três tipos e quando usar cada um, nomenclatura, o que fixar, disciplina de revisão, sincronização de repositório). Ele está listado em todos os registros e resumos, os agentes o leem com june_doc_get('agent-memory-guide') sempre que estiverem em dúvida — e é uma página comum, então edite-o e seus agentes seguirão sua versão. Antes de qualquer coisa ser salva, estados vazios retornam um passo a passo de setup em vez de um encolher de ombros, e o prompt de june_memory_setup faz o agente entrevistar você e salvar suas convenções como a primeira documentação.

Tornando June automático — o agente depende dele sem precisar ser instruído

"Use June" nunca deve precisar ser dito. Três mecanismos se combinam para tornar o uso automático, cada um cobrindo o ponto cego do anterior:

1. O hook do host (fecha o início a frio). Um servidor não pode falar até a primeira chamada do agente — então instale as instruções permanentes do June no arquivo que seu host carrega nativamente a cada sessão:

   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
   

   Ele é escrito como uma seção gerenciada (seu próprio conteúdo nunca é tocado; re-execuções o atualizam no lugar), e coloca a postura june-primeiro — verifique June antes de alegar ignorância, lembre-se de fatos sem ser solicitado, aprenda lições conforme elas acontecem — no próprio prompt do sistema.

2. Descrições proativas de ferramentas (nunca decaem). As descrições dos verbos principais dizem ao modelo quando usá-los sem ser pedido — e as descrições são relidas a cada turno, em todo host MCP, sem necessidade de cooperação.

3. O documento june-first fixado (reafirma toda a sessão). Semeado junto com o guia, ele acompanha cada resumo de standing_docs, então a postura é repetida no meio da sessão exatamente onde a deriva de contexto longo a erodiria. Como tudo que é semeado, é uma página comum — edite-o e seus agentes seguirão sua versão.

O que nenhum servidor MCP pode fazer — honestamente — é forçar um host a agir: um agente cujo host esconde SERVER_INSTRUCTIONS e não tem arquivo de instruções e nunca faz uma chamada ao June permanece frio. O mecanismo 1 existe precisamente para que esse caso nunca ocorra na prática.

Sincronização de repositório — o repositório permanece atualizado com o que June sabe

Ative com JUNE_EXPORT_ROOT=<your repo> e mais três ferramentas aparecem:

ferramenta	o que faz
june_docs_export	Espelha cada documento de agente para docs/agent/<name>.md — o repositório sempre contém as instruções permanentes atuais
june_page_export	Exporta qualquer página para um arquivo gerenciado, ou para uma seção gerenciada inserida entre marcadores dentro de um arquivo existente (path=KNOWHOW.md section=june-learnings) — apenas a região marcada é tocada
june_page_import	O inverso: edite um arquivo exportado no seu editor e importe-o de volta para sua página do June — os documentos de agente mantêm sua identidade, e um arquivo desatualizado é recusado em vez de permitir sobrescrever conhecimento mais recente

Regras de segurança, todas aplicadas em código e fixadas por testes: cada caminho é cercado dentro da raiz (verificação lexical de .. e resolução de symlink); um arquivo não escrito por june-mcp nunca é sobrescrito; nada é excluído; e com JUNE_EXPORT_GIT=1 cada exportação confirma exatamente os arquivos que escreveu — limitado por pathspec, então seu trabalho em staging nunca é varrido, e push nunca acontece. Arquivos exportados carregam frontmatter e são deterministicamente em bytes, então um documento inalterado re-exporta para um arquivo idêntico e o git permanece silencioso.

O manifesto (.june-export.json) torna a verificação de atualização possível — dois modos de 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 no CI transforma "os documentos estão atualizados?" de uma esperança em uma build com falha.

Free vs Pro — a tag june-pro

june-mcp é um pacote para todos; não há "build Pro" separada. Pro é uma propriedade do endpoint, não do conector: conecte-se a um June ativado com Pro (uma licença Pro no aplicativo, uma chave Pro em um workspace hospedado) e as mesmas ferramentas carregam resultados de nível Pro: cada escrita de june_remember e june_ingest_file executa automaticamente os mecanismos de entidade/edge mais ricos (o resultado relata qual engine foi executado), june_resolve atualiza para correspondência semântica, e june_enrich preenche memórias que foram escritas no nível gratuito antes de você atualizar. O terminal mostra em qual mundo você está: --doctor imprime uma linha de 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 tag é lida do próprio /v1/whoami do serviço (o mesmo estado de direito que controla as rotas Pro no lado do servidor), então ela não pode discordar do que você realmente recebe — e é apenas exibição: os direitos são aplicados no serviço, não importa o que qualquer cliente imprima. Serviços mais antigos sem /v1/whoami simplesmente não mostram tag.

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, com falha fechada. Uma leitura entre tenants não é uma verificação de permissão que poderia falhar aberta; é irrepresentável a partir do cliente. JUNE_READONLY=1 adiciona uma segunda cerca para implantações somente leitura. Sua chave BYO LLM acompanha cada solicitação de resposta como um cabeçalho e nunca é persistida ou registrada pelo serviço.

Erros

Cada falha upstream mapeia 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), então o servidor sobrevive a qualquer coisa que o endpoint lance e seu agente vê uma mensagem limpa e acionável.

Licença

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