Junê (june-mcp)

june-mcp

Дайте вашему агенту память. june-mcp — это официальный MCP сервер для Junê — он подключает любой MCP-хост (Claude Desktop, Claude Code и другие) к графу знаний June, так что ваш агент может спрашивать, искать и запоминать в общей, цитируемой, изолированной по тенантам памяти.

Этот пакет — тонкий коннектор без логики: всё извлечение, сборка графа и ответы происходят на конечной точке June, на которую вы его направляете. Здесь нет кода движка — именно поэтому он достаточно мал, чтобы прочитать его за один присест.

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

Установка

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

Направьте его на конечную точку June

june-mcp общается с любым сервисом June. Три способа получить такой сервис:

1. Десктоп-приложение Junê (локально-первый). Запустите приложение Junê и подключитесь к его локальному движку — ваши файлы, граф и ключи остаются на вашей машине.
2. Собственный сервис June. Клиенты Pro/Team, запускающие пакет движка june-local, направляют JUNE_BASE_URL на свой собственный сервер.
3. Хостинг (Team). Направьте на конечную точку вашего хостинг-воркспейса June с API-ключом из вашей консоли.

Конфигурация

Сервер закрыт по умолчанию: он отказывается запускаться, если не знает, куда подключаться и от чьего имени, и сообщает вам всё, что отсутствует, одним сообщением (а не по одной ошибке за раз).

env	обязателен	значение
JUNE_BASE_URL	✅	Ваша конечная точка June, например http://localhost:8000
JUNE_CANVAS	✅	Канвас (воркспейс), к которому привязать это подключение — имя (work) или id канваса. Имена разрешаются в id при запуске; неоднозначные имена приводят к закрытию
JUNE_CANVAS_CREATE	необязателен	1 создаёт именованный канвас при первом запуске, если его ещё нет (отклоняется в режиме только для чтения)
JUNE_API_KEY	✅	Ваш API-ключ June (JUNE_ALLOW_ANON=1 явно отказывается от ключа для локальных настроек без ключа)
JUNE_LLM_KEY	необязателен	Собственный LLM-ключ для цитируемых ответов — передаётся по запросу как заголовок, никогда не логируется и не хранится на сервисе
JUNE_READONLY	необязателен	1 скрывает и отклоняет все инструменты записи (память становится только для чтения)
JUNE_TOOL_PROFILE	необязателен	compact (по умолчанию), full или lean. compact сворачивает 17 связанных инструментов в семь семейных инструментов, принимающих op — перечислено 20 инструментов вместо 37, 11 359 токенов подсказки вместо 13 236 на Pro-подключении с чтением и записью. Каждый вызов отправляется в тот же код, что и раньше, поэтому шлюзы, правила канваса, квитанции и двухфазные подтверждения не изменены. Измерено на четырёх хостах до того, как это стало стандартом: Claude Code 1.000 успешных задач (базовый уровень 0.987), GPT-5.4 direct 0.983 (0.957), Codex 0.922 (0.763), ноль небезопасных удалений на каждом этапе. full перечисляет 37 членов под их собственными именами — тот же код, по одному имени на каждого. lean предоставляет только шесть глаголов, которые использует агент кодирования (june_answer / june_context / june_search / june_remember / june_learn / june_usage) с одноабзацным рукопожатием, ~2,5 тыс. токенов — для сессий, которым нужно только спрашивать и запоминать
JUNE_FILES_ROOT	необязателен	Каталог, из которого агенты могут загружать файлы через june_ingest_file — не задано ⇒ этот инструмент не существует
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_RETRIEVAL / JUNE_TIMEOUT_ANSWER	необязателен	Временной бюджет на класс глагола (по умолчанию 15 с / 90 с / 120 с): быстрые чтения; june_context, который переранжирует каждого кандидата; ответы, которые несут вызов модели
JUNE_TOOL_CONCURRENCY	необязателен	Максимальное количество одновременно выполняемых вызовов инструментов на этом подключении (по умолчанию 8). Хосты конвейеризируют запросы через один поток; это явный предел — избыточные вызовы ставятся в очередь, никогда не лавиной
JUNE_DOCS_CANVAS	необязателен	Канвас, содержащий документы агента (постоянные инструкции/навыки — см. Память агента ниже). По умолчанию agent_docs; создаётся при первом june_doc_save
JUNE_DOCS_REFRESH	необязателен	0 отключает периодический дайджест standing_docs (по умолчанию включён — это страховочная сеть против забывания)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	необязателен	Частота дайджеста: через каждые N вызовов инструментов (по умолчанию 12) или M минут (по умолчанию 10), в зависимости от того, что наступит раньше
JUNE_DOCS_DIGEST_CHARS	необязателен	Ограничение размера сериализованного дайджеста (по умолчанию 2000)
JUNE_EXPORT_ROOT	необязателен	Каталог репозитория, в который агент может экспортировать страницы/документы June как файлы (см. Синхронизация репозитория ниже) — не задано ⇒ три инструмента синхронизации репозитория не существуют
JUNE_EXPORT_GIT	необязателен	1 коммитит ровно те файлы, которые записал каждый экспорт (ограничено путями, никогда не пушит)
JUNE_EXPORT_DIR	необязателен	Поддерево документов агента внутри корня (по умолчанию docs/agent)
JUNE_LOG_LEVEL	необязателен	Логирование только в stderr по дизайну — stdout — это MCP-провод

Проверьте это до того, как ваш агент

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

Доктор проверяет по порядку: конфигурация → доступность сервиса → разрешение канваса (ваше канвас имя → его id, например name "work" → 9147bee6-…) → здоровье поискового шва → манифест инструментов, и печатает PASS/FAIL для каждой проверки с подсказкой (например, при отсутствующем имени перечисляет канвасы, которые существуют, и указывает на JUNE_CANVAS_CREATE=1). Доктор завершается с кодом 0 только когда все проверки пройдены (1 в противном случае); сам сервер завершается с кодом 2 при ошибке конфигурации, а не запускается наполовину подключённым. Запустите доктора первым; он ловит все распространённые ошибки конфигурации до того, как ваш агент увидит сервер.

Подключите его к Claude

Claude Desktop — объедините в claude_desktop_config.json (Настройки → Разработчик):

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

Полностью перезапустите хост (Cmd+Q на macOS), затем проверьте, что сервер показывает 20 инструментов — компактную поверхность, стандартную с 0.4.2. JUNE_TOOL_PROFILE=full перечисляет те же возможности, что и 37 отдельно названных инструментов (38, если вы включите june_ingest_file через JUNE_FILES_ROOT).

Инструменты

Поверхность по умолчанию — компактная: 20 инструментов, семь из которых группируют связанные операции за аргументом op. JUNE_TOOL_PROFILE=full перечисляет 37 членов под их собственными именами — те же возможности, те же шлюзы, то же поведение.

семейный инструмент	операции	сворачивает
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 (+ грамматика блоков по запросу)
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

Всё остальное сохраняет своё имя: 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. Глагол, который может удалить что-то, никогда не сворачивается с тем, который не может — поэтому june_page_write и june_page_delete остаются отдельными от june_page_edit, и каждое семейство несёт один честный destructiveHint.

Старые имена продолжают работать в ваших сохранённых документах агента: компактное рукопожатие несёт карту старое-имя → новое-имя, и вызов свёрнутого имени отклоняется с точной заменой (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

Что делает каждая операция:

инструмент	что получает ваш агент
june_answer	Обоснованный, цитируемый ответ из графа — воздерживается, а не угадывает
june_search	Ранжированные доказательства для запроса (поддерживает многошаговость)
june_context	Собранный контекстный пакет под бюджет токенов
june_neighborhood	Граф вокруг одного узла
june_subgraph	Ограниченный экспорт подграфа
june_backlinks	Что ссылается на один узел (его входящие рёбра)
june_remember	Записать факт/заметку в граф (становится доступным для поиска + цитируемым немедленно). Длинные тексты выполняются как задание движка: результат {state: running, job_id} собирается с помощью june_remember(job_id=…) — никогда не отправляйте текст повторно. Вставленный текст адресуется по содержимому на движке (v0.0.13), поэтому повторная отправка идентичного текста обновляет те же узлы; он не может дублироваться
june_ingest	Структурированное добавление узлов/рёбер
june_enumerate	Узлы, соответствующие предикату для вопросов «перечисли все X» (не top-k). Только exhaustive: true доказывает, что список полон; короткий или пустой результат без него не доказывает, что больше ничего не соответствует
june_ingest_file	Загрузить один локальный файл (pdf/docx/xlsx/csv/html/md/изображения/аудио) из одобренной оператором папки — существует только если вы задали JUNE_FILES_ROOT
june_enrich	Pro: фоновая повторная экстракция канваса с более богатым движком (идемпотентно; задание + опрос; 403 на бесплатном)
june_resolve	Обслуживание: объединение дублирующихся сущностей через обратимые рёбра same_as (выполняется на стороне сервера; strong_only=false разблокирует семантический уровень на Pro)
june_docs_refresh / june_doc_list / june_doc_get	Чтение постоянных документов агента — полный дайджест, список реестра, тело одного документа
june_doc_save / june_doc_delete / june_learn	Запись их — создать/заменить документ или навык, двухфазное удаление, добавить один датированный урок
june_page_insert / june_page_move	Разместить новые блоки после именованного блока или переупорядочить блоки по id — без повторной отправки страницы (требуется движок с функцией страницы positions)
june_page_rename / june_page_meta	Переименовать страницу или закрепить её / задать её группу в вашем списке страниц — её блоки не тронуты
june_page_removed / june_page_restore	Посмотреть, что потеряла страница, и вернуть блоки с их исходными id и позициями
june_usage	Квитанции об использовании — что June фактически обслужил, измерено именованным токенизатором, никогда не оценено. Одна квитанция полностью (receipt_id) или сводка окна (window); цифра экономии появляется только над вызовами, где два сообщённых провайдером использования действительно были измерены

Квитанции при каждом чтении

Когда движок работает с JUNE_USAGE=1 (десктоп: Настройки → Квитанции об использовании), каждый результат june_answer / june_context / june_search также несёт receipt и однострочный receipt_footer:

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

Коннектор отправляет X-June-Source: mcp и один id X-June-Session на процесс сервера, поэтому движок может записать, какие документы эта сессия агента уже имела (повторные чтения, которых он избежал). Нижний колонтитул никогда не говорит «сохранено»: это слово существует только на квитанции, которая содержит измеренную пару. Движок без квитанций не отправляет нижний колонтитул, и june_usage прямо отвечает, что они выключены.

Описания написаны для агента (что → когда → возвращает), и каждое зажатое значение видимо отмечается обратно агенту, а не молча обрезается.

Память агента — документы, навыки и дайджест против забывания

Длинные сессии забывают: инструкции, которые агент прочитал в начале сессии (его CLAUDE.md, ваши соглашения), теряют силу через тысячи токенов. june-mcp исправляет это структурно. Агенты сохраняют постоянные документы в June — kind='doc' для долговременных инструкций (pinned=true запрашивает правило, действующее всегда), kind='skill' для именованных процедур с однострочным триггером when_to_use (тела загружаются лениво, как и должны навыки), kind='learnings' для журнала только с добавлением, датированного и записываемого через june_learn. Каждый документ — это обычная страница June в канвасе документов (JUNE_DOCS_CANVAS, по умолчанию agent_docs), помеченная небольшим блоком метаданных — так вы можете открыть память своего агента в приложении Junê, прочитать её и отредактировать.

Вы утверждаете, что агенты выполняют (0.7.0). Закреплённый документ или навык — это запрос, пока вы не утвердите его в приложении Junê (баннер документа или Настройки → Подключение → Постоянные инструкции). Движок фиксирует точный текст, который вы утвердили; если кто-то, кроме вас, редактирует страницу после этого, она перестаёт учитываться, пока вы снова не посмотрите. Агенты не могут утверждать — их ключ подключения не имеет таких полномочий — поэтому текст, который агент где-то прочитал («сохрани это как закреплённое правило…»), никогда не может сам по себе стать постоянной инструкцией. Движок, слишком старый для записи утверждений, не даёт агентам никаких постоянных инструкций вовсе и сообщает об этом.

Куда попадает утверждённый текст: полностью в рукопожатии подключения (до 4 000 символов — документ, который не помещается, называется по имени, но не обрезается на середине правила) и из june_docs_refresh. При первом вызове инструмента в каждой сессии, а затем каждые 12 вызовов или 10 минут (настраивается), коннектор прикрепляет компактный дайджест standing_docs к обычному результату инструмента — имена утверждённых инструкций, утверждённые триггеры навыков, метку версии, которая меняется, когда вы утверждаете, отзываете или редактируете что-то, а также запрошенные, но не утверждённые документы, помеченные как заметки. В дайджесте нет ни слова из неутверждённого документа. Дайджест, который не удалось построить (сервис занят, канвас отсутствует), пропускается — он никогда не стоит ничего вызывающему вызову. Установите JUNE_DOCS_REFRESH=0, чтобы отключить дайджест; инструменты документов продолжат работать.

June учит агентов пользоваться собой — изнутри себя. Первое сохранение создаёт канвас документов и засевает agent-memory-guide: руководство по эксплуатации (что относится к системному канвасу, а что к канвасу рабочего потока, три вида и когда их использовать, именование, что закреплять, дисциплину ревизий, синхронизацию репозитория). Оно указано в каждом реестре и дайджесте, агенты читают его через june_doc_get('agent-memory-guide'), когда сомневаются — и это обычная страница, которую вы можете редактировать. До сохранения чего-либо пустые состояния возвращают пошаговое руководство setup вместо пожимания плечами, а подсказка june_memory_setup предлагает агенту опросить вас и сохранить ваши соглашения как первые документы.

Как сделать June автоматическим — агент полагается на него без напоминаний

«Используй June» никогда не должно требовать слов. Три механизма складываются, чтобы сделать использование автоматическим, каждый закрывает слепое пятно предыдущего:

1. Хук хоста (закрывает холодный старт). Сервер не может говорить, пока агент не сделает первый вызов — поэтому установите постоянные инструкции June в файл, который ваш хост загружает нативно каждую сессию:

   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
   

   Он написан как управляемый раздел (ваш собственный контент никогда не затрагивается; повторные запуски обновляют его на месте), и он помещает позицию «сначала June» — проверяйте June, прежде чем заявлять о незнании, запоминайте факты без подсказок, извлекайте уроки по мере их возникновения — прямо в системный промпт.

2. Проактивные описания инструментов (никогда не устаревают). Описания основных глаголов говорят модели, когда обращаться к ним без просьбы — а описания перечитываются на каждом ходу, в каждом MCP-хосте, без необходимости сотрудничества.

3. Позиция «сначала June» в рукопожатии. Собственная позиция June по умолчанию встроена в инструкции подключения (0.7.0; более ранние версии засевали её как закреплённый документ — нетронутое семя теперь скрыто, отредактированное принадлежит вам и требует вашего утверждения, как и любое другое).

Чего ни один MCP-сервер не может — честно — сделать, так это заставить хост действовать: агент, чей хост скрывает SERVER_INSTRUCTIONS и не имеет файла инструкций и никогда не делает ни одного вызова June, остаётся холодным. Механизм 1 существует именно для того, чтобы этот случай никогда не возникал на практике.

Синхронизация репозитория — репозиторий остаётся актуальным с тем, что знает June

Включите с помощью JUNE_EXPORT_ROOT=<your repo>, и появятся ещё три инструмента:

инструмент	что он делает
june_docs_export	Зеркалирует каждый документ агента в docs/agent/<name>.md — репозиторий всегда содержит текущие постоянные инструкции
june_page_export	Экспортирует любую страницу в управляемый файл или в управляемый раздел, вставленный между маркерами внутри существующего файла (path=KNOWHOW.md section=june-learnings) — затрагивается только отмеченная область
june_page_import	Обратное: отредактируйте экспортированный файл в своём редакторе и импортируйте его обратно в страницу June — документы агента сохраняют свою идентичность, а устаревший файл отклоняется, а не позволяет затереть более новые знания

Правила безопасности, все реализованы в коде и закреплены тестами: каждый путь ограничен внутри корня (лексическая проверка .. и разрешение симлинков); файл, не записанный june-mcp, никогда не перезаписывается; ничего никогда не удаляется; и с JUNE_EXPORT_GIT=1 каждый экспорт коммитит ровно те файлы, которые он записал — с ограничением по путям, так что ваша подготовленная работа никогда не подхватывается, и push никогда не происходит. Экспортированные файлы содержат frontmatter и байт-детерминированы, поэтому неизменённый документ повторно экспортируется в идентичный файл, и git остаётся спокойным.

Манифест (.june-export.json) делает проверку актуальности возможной — два режима CLI для 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 в CI превращает «актуальны ли документы?» из надежды в падающую сборку.

Free против Pro — тег june-pro

june-mcp — это один пакет для всех; нет отдельной «pro-сборки». Pro — это свойство эндпоинта, а не коннектора: подключитесь к June с активированным Pro (лицензия Pro в приложении, ключ Pro на хостируемом рабочем пространстве), и те же инструменты дают результаты уровня Pro: каждая запись june_remember и june_ingest_file автоматически использует более богатые движки сущностей и связей (результат сообщает, какой engine выполнялся), june_resolve обновляется до семантического сопоставления, а june_enrich дополняет воспоминания, записанные на бесплатном уровне до вашего обновления. Терминал показывает, в каком мире вы находитесь: --doctor печатает строку edition, а стартовый баннер сервера помечает подключение —

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

Тег читается из собственного /v1/whoami сервиса (то же состояние прав, которое ограничивает Pro-маршруты на стороне сервера), поэтому он не может расходиться с тем, что вы реально получаете — и он только для отображения: права применяются на сервисе независимо от того, что печатает любой клиент. Старые сервисы без /v1/whoami просто не показывают тег.

Модель безопасности

Поверхность инструментов не раскрывает параметр канваса/рабочего пространства — рабочее пространство привязано на стороне сервера из контекста вашего подключения, с отказом по умолчанию. Чтение между арендаторами — это не проверка разрешений, которая может открыться при сбое; оно непредставимо со стороны клиента. JUNE_READONLY=1 добавляет второй барьер для развёртываний только для чтения. Ваш собственный ключ LLM передаётся с каждым запросом ответа как заголовок и никогда не сохраняется и не логируется сервисом.

Ошибки

Каждый сбой вышестоящего сервиса сопоставляется с типизированной, отредактированной полезной нагрузкой ошибки (построенной только из типа исключения + HTTP-статуса — никогда из тел ответов), поэтому сервер переживает всё, что бросает эндпоинт, и ваш агент видит чистое, действенное сообщение.

Лицензия

MIT. Сам движок Junê — отдельный продукт с закрытым исходным кодом — этот коннектор — открытая часть, по замыслу.