Junê (june-mcp)

june-mcp

Ajanınıza bir hafıza kazandırın. june-mcp, Junê için resmi MCP sunucusudur — herhangi bir MCP ana bilgisayarını (Claude Desktop, Claude Code ve benzerleri) bir June bilgi grafiğine bağlar; böylece ajanınız paylaşılan, alıntılanan ve kiracı izoleli bir hafızaya karşı sorabilir, arayabilir ve hatırlayabilir.

Bu paket ince, mantıksız bir bağlayıcıdır: tüm alma, grafik oluşturma ve yanıtlama, işaret ettiğiniz June uç noktasında gerçekleşir. Burada motor kodu yoktur — bu yüzden tek oturuşta okunabilecek kadar küçüktür.

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

Kurulum

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

Bir June uç noktasına yönlendirin

june-mcp, herhangi bir June hizmetiyle konuşur. Bir tane edinmenin üç yolu vardır:

1. Junê masaüstü uygulaması (yerel öncelikli). Junê uygulamasını çalıştırın ve yerel motoruna bağlanın — dosyalarınız, grafiğiniz ve anahtarlarınız makinenizde kalır.
2. Kendi June hizmetiniz. june-local motor paketini çalıştıran Pro/Takım müşterileri, JUNE_BASE_URL'i kendi sunucularına yönlendirir.
3. Barındırılan (Takım). Konsolunuzdaki API anahtarıyla barındırılan June çalışma alanı uç noktanıza yönlendirin.

Yapılandırma

Sunucu başarısız-kapalıdır: nereye bağlanacağını ve kim olarak bağlanacağını bilmedikçe başlamayı reddeder ve eksik olan her şeyi tek mesajda söyler (her seferinde bir hata değil).

env	gerekli	anlam
JUNE_BASE_URL	✅	June uç noktanız, örn. http://localhost:8000
JUNE_CANVAS	✅	Bu bağlantının bağlanacağı tuval (çalışma alanı) — bir ad (work) veya bir tuval kimliği. Adlar başlangıçta kimliğe çözümlenir; belirsiz adlar başarısız-kapalı olur
JUNE_CANVAS_CREATE	isteğe bağlı	1, adlandırılmış tuvali ilk çalıştırmada yoksa oluşturur (salt okunur modda reddedilir)
JUNE_API_KEY	✅	June API anahtarınız (JUNE_ALLOW_ANON=1, anahtarsız yerel kurulumlar için açıkça devre dışı bırakır)
JUNE_LLM_KEY	isteğe bağlı	Alıntılanan yanıtlar için kendi LLM anahtarınızı getirin — istek başına bir başlık olarak iletilir, asla günlüğe kaydedilmez, hizmette asla saklanmaz
JUNE_READONLY	isteğe bağlı	1, tüm yazma araçlarını gizler ve reddeder (hafıza salt okunur olur)
JUNE_TOOL_PROFILE	isteğe bağlı	compact (varsayılan), full veya lean. compact, 17 ilgili aracı bir op alan yedi aile aracına katlar — 37 yerine 20 araç listelenir, Pro okuma-yazma bağlantısında 13.236 yerine 11.359 istem belirteci. Varsayılan olmadan önce dört ana bilgisayarda ölçüldü: Claude Code 1.000 görev başarısı (taban 0.987), GPT-5.4 doğrudan 0.983 (0.957), Codex 0.922 (0.763), her kolda sıfır güvenli olmayan silme. full, 37 üyeyi kendi adları altında listeler — aynı kod, her biri bir ad. lean, yalnızca bir kodlama ajanının kullandığı altı fiili (june_answer / june_context / june_search / june_remember / june_learn / june_usage) tek paragraflık bir el sıkışma ile açığa çıkarır, ~2,5k belirteç — yalnızca sorması ve hatırlaması gereken oturumlar için
JUNE_FILES_ROOT	isteğe bağlı	Dizin ajanlarının june_ingest_file aracılığıyla dosya yükleyebileceği katılım klasörü — ayarlanmamışsa bu araç mevcut değildir
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_RETRIEVAL / JUNE_TIMEOUT_ANSWER	isteğe bağlı	Fiil sınıfı başına zaman bütçesi (varsayılanlar 15 sn / 90 sn / 120 sn): hızlı okumalar; her adayı yeniden sıralayan june_context; bir model çağrısı taşıyan yanıtlar
JUNE_TOOL_CONCURRENCY	isteğe bağlı	Bu bağlantıda aynı anda yürütülen maksimum araç çağrısı (varsayılan 8). Ana bilgisayarlar istekleri tek akış üzerinden boru hattına alır; bu açık tavandır — fazla çağrılar kuyruğa alınır, asla izdiham olmaz
JUNE_DOCS_CANVAS	isteğe bağlı	Ajan belgelerini tutan tuval (kalıcı talimatlar/beceriler — aşağıdaki Ajan hafızası bölümüne bakın). Varsayılan agent_docs; ilk june_doc_save üzerinde oluşturulur
JUNE_DOCS_REFRESH	isteğe bağlı	0, periyodik standing_docs özetini devre dışı bırakır (varsayılan açık — unutmayı önleyen güvenlik ağıdır)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	isteğe bağlı	Özet ritmi: her N araç çağrısında (varsayılan 12) veya M dakikada (varsayılan 10) vadesi gelir, hangisi önce gelirse
JUNE_DOCS_DIGEST_CHARS	isteğe bağlı	Serileştirilmiş özet boyut sınırı (varsayılan 2000)
JUNE_EXPORT_ROOT	isteğe bağlı	Ajanın June sayfalarını/belgelerini dosya olarak dışa aktarabileceği katılım deposu dizini (aşağıdaki Depo senkronizasyonu bölümüne bakın) — ayarlanmamışsa üç depo-senkronizasyon aracı mevcut değildir
JUNE_EXPORT_GIT	isteğe bağlı	1, her dışa aktarmanın yazdığı dosyaları tam olarak işler (yol-sınırlı, asla itmez)
JUNE_EXPORT_DIR	isteğe bağlı	Kök içindeki ajan-belgeleri alt ağacı (varsayılan docs/agent)
JUNE_LOG_LEVEL	isteğe bağlı	Günlüğe kaydetme tasarım gereği yalnızca stderr'dir — stdout MCP telidir

Ajanınızdan önce kontrol edin

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

Doktor sırayla doğrular: yapılandırma → hizmet erişilebilirliği → tuval çözümlemesi (tuval adınız → kimliği, örn. name "work" → 9147bee6-…) → arama dikişi sağlıklı → araç manifestosu ve her kontrol için eşlenmiş bir ipucuyla (örn. eksik bir ad, VAR olan tuvalleri listeler ve JUNE_CANVAS_CREATE=1'i işaret eder) PASS/FAIL yazdırır. Doktor, yalnızca her kontrol geçtiğinde 0 ile çıkar (aksi halde 1); sunucunun kendisi, yarı bağlı başlamak yerine bir yapılandırma hatasında 2 ile çıkar. Önce doktoru çalıştırın; ajanınız sunucuyu görmeden önce her yaygın yanlış yapılandırmayı yakalar.

Claude'a bağlayın

Claude Desktop — claude_desktop_config.json içine birleştirin (Ayarlar → Geliştirici):

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

Ana bilgisayarı tamamen yeniden başlatın (macOS'te Cmd+Q), ardından sunucunun 20 araç gösterdiğini kontrol edin — 0.4.2'den beri varsayılan olan kompakt yüzey. JUNE_TOOL_PROFILE=full, aynı yetenekleri 37 ayrı adlandırılmış araç olarak listeler (JUNE_FILES_ROOT aracılığıyla june_ingest_file'yi tercih ettiğinizde 38).

Araçlar

Varsayılan yüzey kompakttır: 20 araç, bunlardan yedisi ilgili işlemleri bir op bağımsız değişkeninin arkasında gruplar. JUNE_TOOL_PROFILE=full, 37 üyeyi kendi adları altında listeler — aynı yetenekler, aynı kapılar, aynı davranış.

aile aracı	işlemler	katlar
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 (+ isteğe bağlı blok dilbilgisi)
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

Diğer her şey kendi adını korur: 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. Bir şeyi kaldırabilen bir fiil, kaldıramayanla asla katlanmaz — bu yüzden june_page_write ve june_page_delete, june_page_edit'den ayrı kalır ve her aile bir dürüst destructiveHint taşır.

Eski adlar, kayıtlı ajan belgelerinizde çalışmaya devam eder: kompakt el sıkışma, eski ad → yeni ad haritasını taşır ve katlanmış bir ada yapılan çağrı, tam değiştirme ile reddedilir (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

Her işlemin ne yaptığı:

araç	ajanınızın aldığı
june_answer	Grafikten temellendirilmiş, alıntılanmış bir yanıt — tahmin etmek yerine çekimser kalır
june_search	Bir sorgu için sıralanmış kanıt (çok atlamalı destekler)
june_context	Bir belirteç bütçesi altında birleştirilmiş bir bağlam paketi
june_neighborhood	Tek bir düğümün etrafındaki grafik
june_subgraph	Sınırlı bir alt grafik dışa aktarımı
june_backlinks	Bir düğüme giden bağlantılar (gelen kenarları)
june_remember	Grafiğe bir gerçek/not yazın (hemen alınabilir + alıntılanabilir olur). Uzun metinler bir motor işi olarak çalışır: {state: running, job_id} sonucu june_remember(job_id=…) ile toplanır — metni asla yeniden göndermeyin. Yapıştırılan metin, motor üzerinde içerik adreslidir (v0.0.13), bu nedenle aynı metnin yeniden gönderilmesi aynı düğümleri günceller; çoğaltamaz
june_ingest	Yapılandırılmış düğüm/kenar alımı
june_enumerate	"Tüm X'i listele" soruları için bir yüklemle eşleşen düğümler (üst-k değil). Yalnızca exhaustive: true, listenin eksiksiz olduğunu kanıtlar; onsuz kısa veya boş bir sonuç, başka hiçbir şeyin eşleşmediğini kanıtlamaz
june_ingest_file	Operatör onaylı klasörden bir yerel dosya yükleyin (pdf/docx/xlsx/csv/html/md/görseller/ses) — yalnızca JUNE_FILES_ROOT ayarladığınızda mevcuttur
june_enrich	Pro: daha zengin motorla tuvalin arka plan yeniden çıkarımı (idempotent; iş + yoklama; ücretsizde 403)
june_resolve	Bakım: yinelenen varlıkları geri dönüşümlü same_as kenarlarıyla birleştirin (sunucu tarafında çalışır; strong_only=false, Pro'da anlamsal katmanı açar)
june_docs_refresh / june_doc_list / june_doc_get	Ajanın kalıcı belgelerini okuyun — tam özet, kayıt listesi, bir belgenin gövdesi
june_doc_save / june_doc_delete / june_learn	Bunları yazın — bir belge veya beceri oluşturun/değiştirin, iki aşamalı silme, tarihli bir ders ekleyin
june_page_insert / june_page_move	Adlandırılmış bir bloktan sonra yeni bloklar yerleştirin veya blokları kimliğe göre yeniden sıralayın — sayfayı yeniden göndermeden (positions sayfa özelliğine sahip bir motor gerektirir)
june_page_rename / june_page_meta	Bir sayfayı yeniden adlandırın veya sayfalar listenizde sabitleyin / grubunu ayarlayın — bloklarına dokunulmaz
june_page_removed / june_page_restore	Bir sayfanın ne kaybettiğini görün ve blokları orijinal kimlikleri ve konumlarıyla geri getirin
june_usage	Kullanım makbuzları — June'un gerçekte ne sunduğu, adlandırılmış bir belirteçleyiciyle ölçülür, asla tahmin edilmez. Tam bir makbuz (receipt_id) veya pencere özeti (window); bir tasarruf rakamı yalnızca iki sağlayıcı bildirimli kullanımı gerçekten ölçülen çağrılar üzerinde görünür

Her okumada makbuzlar

Motor JUNE_USAGE=1 ile çalıştığında (masaüstü: Ayarlar → Kullanım makbuzları), her june_answer / june_context / june_search sonucu ayrıca receipt ve tek satırlık bir receipt_footer taşır:

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

Bağlayıcı, sunucu işlemi başına X-June-Source: mcp ve bir X-June-Session kimliği gönderir; böylece motor, bu ajan oturumunun hangi belgeleri zaten aldığını kaydedebilir (kaçındığı yeniden okumalar). Alt bilgi asla "kaydedildi" demez: bu kelime yalnızca ölçülen bir çift taşıyan bir makbuzda bulunur. Makbuzları olmayan bir motor alt bilgi göndermez ve june_usage, kapalı olduklarını açıkça yanıtlar.

Açıklamalar ajan için yazılmıştır (ne → ne zaman → ne döndürür) ve her sıkıştırılmış girdi, sessizce kesilmek yerine ajana görünür şekilde geri bildirilir.

Ajan hafızası — belgeler, beceriler ve unutmayı önleyen özet

Uzun oturumlar unutur: bir ajanın oturum başında okuduğu talimatlar (CLAUDE.md'si, sözleşmeleriniz) binlerce belirteç sonra gücünü kaybeder. june-mcp bunu yapısal olarak düzeltir. Agents save standing docs into June — kind='doc' for durable instructions (pinned=true asks for an always-on rule), kind='skill' for named procedures with a one-line when_to_use trigger (bodies load lazily, like skills should), kind='learnings' for an append-only dated log written via june_learn. Each doc is an ordinary June page in the docs canvas (JUNE_DOCS_CANVAS, default agent_docs), marked by a small metadata block — so you can open your agent's memory in the Junê app, read it, and edit it.

You approve what agents obey (0.7.0). A pinned doc or a skill is a request until you approve it in the Junê app (the doc's banner, or Settings → Connection → Standing instructions). The engine seals the exact text you approved; if anything other than you edits the page afterwards, it stops counting until you look again. Agents can't approve — their connection key doesn't hold that power — so text an agent read somewhere ("save this as a pinned rule…") can never become a standing instruction on its own. An engine too old to record approvals gives agents no standing instructions at all, and says so.

Where approved text travels: in full in the connection handshake (up to 4,000 characters — a doc that doesn't fit is named, never cut mid-rule) and from june_docs_refresh. On the first tool call of every session, and then every 12 calls or 10 minutes (tunable), the connector attaches a compact standing_docs digest to an ordinary tool result — the names of the approved instructions, approved skill triggers, a version stamp that changes when you approve, revoke or edit one, and the requested-but-unapproved docs labelled as notes. The digest carries none of an unapproved doc's words. A digest that can't be built (service busy, canvas missing) is skipped — it never costs the carrying call anything. Set JUNE_DOCS_REFRESH=0 to turn the digest off; the doc tools keep working.

June teaches agents how to use it — from inside itself. The first save creates the docs canvas and seeds agent-memory-guide: the operating manual (what belongs in the system canvas vs a workstream canvas, the three kinds and when to use each, naming, what to pin, revision discipline, repo sync). It's listed in every registry and digest, agents read it with june_doc_get('agent-memory-guide') whenever unsure — and it's an ordinary page you can edit. Before anything is saved, empty states return a setup walkthrough instead of a shrug, and the june_memory_setup prompt has the agent interview you and save your conventions as the first docs.

June'yu otomatik hale getirmek — ajan, söylenmeden ona bağımlı olur

"June'yu kullan" demek asla gerekli olmamalı. Kullanımı otomatik hale getirmek için üç mekanizma üst üste biner ve her biri bir öncekinin kör noktasını kapatır:

1. Ana bilgisayar kancası (soğuk başlangıcı kapatır). Bir sunucu, ajanın ilk çağrısına kadar konuşamaz — bu yüzden June'nun kalıcı talimatlarını, ana bilgisayarınızın her oturumda yerel olarak yüklediği dosyaya kurun:

   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
   

   Yönetilen bir bölüm olarak yazılmıştır (kendi içeriğinize asla dokunulmaz; yeniden çalıştırmalar onu yerinde günceller) ve june-first duruşunu — June'yu kontrol etmeden önce bilgisizlik iddia etme, gerçekleri istenmeden hatırla, dersleri oldukları gibi öğren — sistem isteminin kendisine koyar.

2. Proaktif araç açıklamaları (asla bozulmaz). Çekirdek fiillerin açıklamaları modele istenmeden ne zaman onlara ulaşması gerektiğini söyler — ve açıklamalar her turda, her MCP ana bilgisayarında, hiçbir iş birliği gerektirmeden yeniden okunur.

3. El sıkışmadaki june-first duruşu. June'nun kendi varsayılan duruşu, bağlantının talimatlarına yerleşiktir (0.7.0; önceki sürümler onu sabitlenmiş bir belge olarak tohumladı — dokunulmamış bir tohum artık gizlidir, düzenlenmiş bir tohum sizindir ve diğerleri gibi onayınıza ihtiyaç duyar).

Hiçbir MCP sunucusunun yapamayacağı şey — dürüstçe — bir ana bilgisayarı harekete geçmeye zorlamaktır: ana bilgisayarı SERVER_INSTRUCTIONS'yi gizleyen ve talimat dosyası olmayan ve asla tek bir June çağrısı yapmayan bir ajan soğuk kalır. Mekanizma 1, tam olarak bu durumun pratikte asla oluşmaması için vardır.

Repo senkronizasyonu — repo, June'nun bildikleriyle güncel kalır

JUNE_EXPORT_ROOT=<your repo> ile devreye alın ve üç araç daha görünür:

araç	ne yapar
june_docs_export	Her ajan belgesini docs/agent/<name>.md'ye yansıtır — repo her zaman güncel kalıcı talimatları tutar
june_page_export	Herhangi bir sayfayı yönetilen bir dosyaya veya mevcut bir dosyanın içindeki işaretçiler arasına eklenmiş yönetilen bir bölüme dışa aktarır (path=KNOWHOW.md section=june-learnings) — yalnızca işaretli bölgeye asla dokunulmaz
june_page_import	Tersi: dışa aktarılan bir dosyayı düzenleyicinizde düzenleyin ve June sayfasına geri içe aktarın — ajan belgeleri kimliklerini korur ve bayat bir dosya, daha yeni bilgilerin üzerine yazılmasına izin vermek yerine reddedilir

Tümü kodda uygulanan ve testlerle sabitlenen güvenlik kuralları: her yol, kökün içinde çitle çevrilidir (sözcüksel .. kontrolü ve sembolik bağlantı çözümlemesi); june-mcp tarafından yazılmamış bir dosya asla üzerine yazılmaz; hiçbir şey asla silinmez; ve JUNE_EXPORT_GIT=1 ile her dışa aktarım, yazdığı dosyaları tam olarak işler — pathspec ile sınırlıdır, böylece aşamalı çalışmanız asla süpürülmez ve push asla gerçekleşmez. Dışa aktarılan dosyalar frontmatter taşır ve bayt-deterministikdir, böylece değişmeyen bir belge aynı dosyaya yeniden dışa aktarılır ve git sessiz kalır.

Manifest (.june-export.json) güncelliği kontrol edilebilir kılar — CI için iki CLI modu:

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

CI'daki --export-check, "belgeler güncel mi?" sorusunu bir umuttan başarısız bir derlemeye dönüştürür.

Ücretsiz vs Pro — june-pro etiketi

june-mcp herkes için tek bir pakettir; ayrı bir "pro derleme" yoktur. Pro, bağlantı noktasının bir özelliğidir, bağlayıcının değil: Pro etkinleştirilmiş bir June'ya bağlanın (uygulamada bir Pro lisansı, barındırılan bir çalışma alanında bir Pro anahtarı) ve aynı araçlar Pro düzeyinde sonuçlar taşır: her june_remember ve june_ingest_file yazımı, daha zengin varlık/kenar motorlarını otomatik olarak çalıştırır (sonuç, hangi engine'nin çalıştığını bildirir), june_resolve anlamsal eşleştirmeye yükseltir ve june_enrich, yükseltmeden önce ücretsiz katta yazılmış anıları geri doldurur. Terminal hangi dünyada olduğunuzu gösterir: --doctor bir edition satırı yazdırır ve sunucunun başlangıç afişi bağlantıyı etiketler —

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

Etiket, hizmetin kendi /v1/whoami'ünden okunur (Pro rotalarını sunucu tarafında kapatan aynı yetki durumu), bu yüzden gerçekte aldığınızla çelişemez — ve yalnızca görüntüleme amaçlıdır: yetkiler, istemci ne yazdırırsa yazdırsın hizmette uygulanır. /v1/whoami olmayan eski hizmetler basitçe etiket göstermez.

Güvenlik modeli

Araç yüzeyi canvas/çalışma alanı parametresi sunmaz — çalışma alanı, bağlantınızın bağlamından sunucu tarafında bağlanır, başarısız-kapalıdır. Kiracılar arası bir okuma, açık başarısız olabilecek bir izin kontrolü değildir; istemciden temsil edilemez. JUNE_READONLY=1, salt okunur dağıtımlar için ikinci bir çit ekler. Kendi BYO LLM anahtarınız, her yanıt isteğinde bir başlık olarak gider ve hizmet tarafından asla kalıcı hale getirilmez veya günlüğe kaydedilmez.

Hatalar

Her üst akış hatası, yazılan, redakte edilmiş bir hata yüküne eşlenir (yalnızca istisna türü + HTTP durumundan oluşturulur — asla yanıt gövdelerinden değil), böylece sunucu, uç noktanın attığı her şeye dayanır ve ajanınız temiz, uygulanabilir bir mesaj görür.

Lisans

MIT. Junê motorunun kendisi ayrı, kapalı kaynaklı bir üründür — bu bağlayıcı, tasarım gereği açık kısımdır.