Junê (june-mcp)

june-mcp

Beri agen Anda sebuah memori. june-mcp adalah server MCP resmi untuk Junê — server ini menghubungkan host MCP apa pun (Claude Desktop, Claude Code, dan lainnya) ke knowledge graph June, sehingga agen Anda dapat bertanya, mencari, dan mengingat terhadap memori bersama yang tersitasi dan terisolasi per penyewa.

Paket ini adalah konektor tipis tanpa logika: semua pengambilan, perakitan graf, dan penjawaban terjadi di endpoint June yang Anda arahkan. Tidak ada kode mesin di sini — itulah mengapa paket ini cukup kecil untuk dibaca sekali duduk.

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

Instalasi

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

Arahkan ke endpoint June

june-mcp berbicara ke layanan June apa pun. Ada tiga cara untuk memilikinya:

1. Aplikasi desktop Junê (lokal-pertama). Jalankan aplikasi Junê dan hubungkan ke mesin lokalnya — file, graf, dan kunci Anda tetap di perangkat Anda.
2. Layanan June Anda sendiri. Pelanggan Pro/Team yang menjalankan paket mesin june-local mengarahkan JUNE_BASE_URL ke server mereka sendiri.
3. Hosted (Team). Arahkan ke endpoint workspace June hosted Anda dengan kunci API dari konsol Anda.

Konfigurasi

Server ini gagal-tertutup: server menolak untuk memulai kecuali ia tahu ke mana harus terhubung dan sebagai siapa, dan memberi tahu Anda semua yang hilang dalam satu pesan (bukan satu kesalahan pada satu waktu).

env	wajib	arti
JUNE_BASE_URL	✅	Endpoint June Anda, mis. http://localhost:8000
JUNE_CANVAS	✅	Canvas (workspace) untuk mengikat koneksi ini — sebuah nama (work) atau id canvas. Nama diselesaikan ke id saat startup; nama ambigu gagal-tertutup
JUNE_CANVAS_CREATE	opsional	1 membuat canvas bernama pada run pertama jika belum ada (ditolak dalam mode baca-saja)
JUNE_API_KEY	✅	Kunci API June Anda (JUNE_ALLOW_ANON=1 secara eksplisit memilih keluar untuk pengaturan lokal tanpa kunci)
JUNE_LLM_KEY	opsional	Bawa kunci LLM Anda sendiri untuk jawaban tersitasi — diteruskan per-permintaan sebagai header, tidak pernah dicatat, tidak pernah disimpan di layanan
JUNE_READONLY	opsional	1 menyembunyikan + menolak semua alat tulis (memori menjadi baca-saja)
JUNE_TOOL_PROFILE	opsional	compact (default), full, atau lean. compact melipat 17 alat terkait menjadi tujuh alat keluarga yang menerima argumen op — 20 alat terdaftar alih-alih 37, 11.359 token prompt alih-alih 13.236 pada koneksi baca-tulis Pro. Setiap panggilan dikirim ke kode yang sama seperti sebelumnya, jadi gerbang, aturan canvas, tanda terima, dan konfirmasi dua fase tidak berubah. Diukur pada empat host sebelum menjadi default: Claude Code 1.000 keberhasilan tugas (baseline 0.987), GPT-5.4 langsung 0.983 (0.957), Codex 0.922 (0.763), nol penghapusan tidak aman di setiap lengan. full mencantumkan 37 anggota dengan nama mereka sendiri — kode yang sama, satu nama masing-masing. lean hanya mengekspos enam kata kerja yang digunakan agen pengkodean (june_answer / june_context / june_search / june_remember / june_learn / june_usage) dengan jabat tangan satu paragraf, ~2,5k token — untuk sesi yang hanya perlu bertanya dan mengingat
JUNE_FILES_ROOT	opsional	Direktori yang dipilih untuk agen yang dapat mengunggah file melalui june_ingest_file — tidak diatur ⇒ alat itu tidak ada
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_RETRIEVAL / JUNE_TIMEOUT_ANSWER	opsional	Anggaran waktu per kelas kata kerja (default 15 dtk / 90 dtk / 120 dtk): pembacaan cepat; june_context, yang memberi peringkat ulang setiap kandidat; jawaban, yang membawa panggilan model
JUNE_TOOL_CONCURRENCY	opsional	Maksimum panggilan alat yang berjalan sekaligus pada koneksi ini (default 8). Host mengalirkan permintaan melalui satu aliran; ini adalah batas eksplisit — panggilan berlebih mengantre, tidak pernah menyerbu
JUNE_DOCS_CANVAS	opsional	Canvas yang menyimpan dokumen agen (instruksi tetap/keterampilan — lihat Memori agen di bawah). Default agent_docs; dibuat pada june_doc_save pertama
JUNE_DOCS_REFRESH	opsional	0 menonaktifkan ringkasan standing_docs berkala (default aktif — ini adalah jaring pengaman anti-lupa)
JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES	opsional	Irama ringkasan: jatuh tempo setiap N panggilan alat (default 12) atau M menit (default 10), mana yang lebih dulu
JUNE_DOCS_DIGEST_CHARS	opsional	Batas ukuran ringkasan berseri (default 2000)
JUNE_EXPORT_ROOT	opsional	Direktori repo yang dipilih untuk agen yang dapat mengekspor halaman/dokumen June ke dalamnya sebagai file (lihat Sinkronisasi repo di bawah) — tidak diatur ⇒ tiga alat sinkronisasi repo tidak ada
JUNE_EXPORT_GIT	opsional	1 melakukan commit tepat file yang ditulis setiap ekspor (dibatasi pathspec, tidak pernah push)
JUNE_EXPORT_DIR	opsional	Subtree dokumen agen di dalam root (default docs/agent)
JUNE_LOG_LEVEL	opsional	Pencatatan hanya ke stderr secara desain — stdout adalah kabel MCP

Periksa sebelum agen Anda melakukannya

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

Dokter memverifikasi, secara berurutan: konfigurasi → layanan dapat dijangkau → resolusi canvas (canvas Anda nama → id-nya, mis. name "work" → 9147bee6-…) → jahitan pencarian sehat → manifes alat, dan mencetak PASS/FAIL per pemeriksaan dengan petunjuk yang dipetakan (mis. nama yang hilang mencantumkan canvas yang ADA dan menunjuk ke JUNE_CANVAS_CREATE=1). Dokter keluar 0 hanya ketika setiap pemeriksaan lulus (1 sebaliknya); server itu sendiri keluar 2 pada kesalahan konfigurasi alih-alih memulai setengah-terhubung. Jalankan dokter terlebih dahulu; ia menangkap setiap kesalahan konfigurasi umum sebelum agen Anda melihat server.

Hubungkan ke Claude

Claude Desktop — gabungkan ke claude_desktop_config.json (Pengaturan → Pengembang):

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

Mulai ulang host sepenuhnya (Cmd+Q di macOS), lalu periksa server menampilkan 20 alat — permukaan compact, default sejak 0.4.2. JUNE_TOOL_PROFILE=full mencantumkan kemampuan yang sama sebagai 37 alat bernama individual sebagai gantinya (38 saat Anda memilih june_ingest_file melalui JUNE_FILES_ROOT).

Alat-alat

Permukaan default adalah compact: 20 alat, tujuh di antaranya mengelompokkan operasi terkait di belakang argumen op. JUNE_TOOL_PROFILE=full mencantumkan 37 anggota dengan nama mereka sendiri sebagai gantinya — kemampuan yang sama, gerbang yang sama, perilaku yang sama.

alat keluarga	operasi	melipat
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 (+ tata bahasa blok sesuai permintaan)
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

Segala sesuatu yang lain mempertahankan namanya sendiri: 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. Kata kerja yang dapat menghapus sesuatu tidak pernah dilipat dengan yang tidak bisa — jadi june_page_write dan june_page_delete tetap terpisah dari june_page_edit, dan setiap keluarga membawa satu destructiveHint yang jujur.

Nama lama tetap berfungsi di dokumen agen tersimpan Anda: jabat tangan compact membawa peta nama-lama → nama-baru, dan panggilan ke nama yang dilipat ditolak dengan pengganti yang tepat (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

Apa yang dilakukan setiap operasi:

alat	apa yang agen Anda dapatkan
june_answer	Jawaban yang berdasar dan tersitasi dari graf — abstain daripada menebak
june_search	Bukti berperingkat untuk kueri (mendukung multi-hop)
june_context	Paket konteks yang dirakit di bawah anggaran token
june_neighborhood	Graf di sekitar satu simpul
june_subgraph	Ekspor subgraf terbatas
june_backlinks	Apa yang terhubung ke satu simpul (sisi masuknya)
june_remember	Tulis fakta/catatan ke dalam graf (menjadi dapat diambil + dapat disitasi segera). Teks panjang berjalan sebagai pekerjaan mesin: hasil {state: running, job_id} dikumpulkan dengan june_remember(job_id=…) — jangan pernah kirim ulang teks. Teks yang ditempel diberi alamat konten di mesin (v0.0.13), jadi pengiriman ulang teks identik memperbarui simpul yang sama; tidak dapat menduplikasi
june_ingest	Ingestion simpul/sisi terstruktur
june_enumerate	Simpul yang cocok dengan predikat untuk pertanyaan "daftar SEMUA X" (bukan top-k). Hanya exhaustive: true yang membuktikan daftar itu lengkap; hasil pendek atau kosong tanpa itu tidak membuktikan tidak ada yang lain yang cocok
june_ingest_file	Unggah satu file lokal (pdf/docx/xlsx/csv/html/md/gambar/audio) dari folder yang disetujui operator — hanya ada saat Anda mengatur JUNE_FILES_ROOT
june_enrich	Pro: ekstraksi ulang latar belakang canvas dengan mesin yang lebih kaya (idempoten; pekerjaan + polling; 403 pada gratis)
june_resolve	Pemeliharaan: gabungkan simpul duplikat melalui sisi same_as yang dapat dibalik (berjalan di sisi server; strong_only=false membuka kunci tingkat semantik di Pro)
june_docs_refresh / june_doc_list / june_doc_get	Baca dokumen tetap agen — ringkasan lengkap, daftar registri, isi satu dokumen
june_doc_save / june_doc_delete / june_learn	Tulis mereka — buat/ganti dokumen atau keterampilan, hapus dua fase, tambahkan satu pelajaran berstempel tanggal
june_page_insert / june_page_move	Tempatkan blok baru setelah blok bernama, atau urutkan ulang blok berdasarkan id — tanpa mengirim ulang halaman (membutuhkan mesin dengan fitur halaman positions)
june_page_rename / june_page_meta	Ubah judul halaman, atau sematkan / atur grupnya di daftar halaman Anda — bloknya tidak tersentuh
june_page_removed / june_page_restore	Lihat apa yang hilang dari halaman, dan bawa kembali blok dengan id dan posisi aslinya
june_usage	Tanda terima penggunaan — apa yang sebenarnya dilayani June, diukur oleh tokenizer bernama, tidak pernah diperkirakan. Satu tanda terima lengkap (receipt_id) atau ringkasan jendela (window); angka penghematan hanya muncul pada panggilan yang dua penggunaan yang dilaporkan penyedianya benar-benar diukur

Tanda terima pada setiap pembacaan

Saat mesin berjalan dengan JUNE_USAGE=1 (desktop: Pengaturan → Tanda terima penggunaan), setiap hasil june_answer / june_context / june_search juga membawa receipt dan satu baris 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

Konektor mengirim X-June-Source: mcp dan satu id X-June-Session per proses server, sehingga mesin dapat mencatat dokumen mana yang sudah dimiliki sesi agen ini (pembacaan ulang yang dihindarinya). Footer tidak pernah mengatakan "tersimpan": kata itu hanya ada pada tanda terima yang memegang pasangan terukur. Mesin tanpa tanda terima mengirim tanpa footer, dan jawaban june_usage dengan jelas bahwa itu mati.

Deskripsi ditulis untuk agen (apa → kapan → mengembalikan), dan setiap input yang dijepit terlihat dicatat kembali ke agen alih-alih dipotong diam-diam.

Memori agen — dokumen, keterampilan, dan ringkasan anti-lupa

Sesi panjang melupakan: instruksi yang dibaca agen di awal sesi (CLAUDE.md-nya, konvensi Anda) kehilangan kekuatan ribuan token kemudian. june-mcp memperbaiki ini secara struktural. 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.

Membuat June otomatis — agen bergantung padanya tanpa perlu diberi tahu

"Gunakan June" seharusnya tidak perlu diucapkan. Tiga mekanisme bertumpuk untuk membuat penggunaan menjadi otomatis, masing-masing menutupi titik buta mekanisme sebelumnya:

1. Host hook (menutup cold start). Server tidak dapat berbicara sampai panggilan pertama agen — jadi pasang standing instructions June ke dalam file yang dimuat host Anda secara native setiap sesi:

   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
   

   Ini ditulis sebagai bagian terkelola (konten Anda sendiri tidak pernah disentuh; eksekusi ulang memperbaruinya di tempat), dan ini menempatkan postur june-first — periksa June sebelum mengaku tidak tahu, ingat fakta tanpa diminta, pelajari pelajaran saat terjadi — ke dalam system prompt itu sendiri.

2. Deskripsi tool proaktif (tidak pernah membusuk). Deskripsi kata kerja inti memberi tahu model kapan harus menggunakannya tanpa diminta — dan deskripsi dibaca ulang di setiap giliran, di setiap host MCP, tanpa perlu kerja sama.

3. Postur june-first dalam handshake. Postur default June sendiri dibangun ke dalam instruksi koneksi (0.7.0; rilis sebelumnya menanamkannya sebagai pinned doc — seed yang tidak tersentuh kini disembunyikan, seed yang diedit adalah milik Anda dan memerlukan persetujuan Anda seperti yang lain).

Apa yang tidak dapat dilakukan server MCP mana pun — jujur — adalah memaksa host untuk bertindak: agen yang host-nya menyembunyikan SERVER_INSTRUCTIONS dan tidak memiliki file instruksi dan tidak pernah melakukan satu panggilan June pun tetap dingin. Mekanisme 1 ada justru agar kasus itu tidak pernah terjadi dalam praktik.

Sinkronisasi repo — repo tetap mutakhir dengan apa yang diketahui June

Pilih dengan JUNE_EXPORT_ROOT=<your repo> dan tiga tool lagi muncul:

tool	apa yang dilakukannya
june_docs_export	Cerminkan setiap doc agen ke docs/agent/<name>.md — repo selalu memegang standing instructions terkini
june_page_export	Ekspor halaman apa pun ke file terkelola, atau ke dalam bagian terkelola yang disisipkan di antara penanda di dalam file yang ada (path=KNOWHOW.md section=june-learnings) — hanya wilayah yang ditandai yang pernah disentuh
june_page_import	Kebalikannya: edit file yang diekspor di editor Anda dan impor kembali ke halaman June-nya — doc agen mempertahankan identitasnya, dan file basi ditolak daripada dibiarkan menimpa pengetahuan yang lebih baru

Aturan keamanan, semuanya ditegakkan dalam kode dan diuji: setiap jalur dipagari di dalam root (periksa .. leksikal dan resolusi symlink); file yang tidak ditulis oleh june-mcp tidak pernah ditimpa; tidak ada yang pernah dihapus; dan dengan JUNE_EXPORT_GIT=1 setiap ekspor melakukan commit tepat file yang ditulisnya — dibatasi pathspec, sehingga pekerjaan staged Anda tidak pernah tersapu, dan push tidak pernah terjadi. File yang diekspor membawa frontmatter dan deterministik byte, sehingga doc yang tidak berubah diekspor ulang ke file yang identik dan git tetap tenang.

Manifest (.june-export.json) membuat pemeriksaan kekinian dapat diverifikasi — dua mode CLI untuk 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 di CI mengubah "apakah docs sudah mutakhir?" dari harapan menjadi build yang gagal.

Free vs Pro — tag june-pro

june-mcp adalah satu paket untuk semua orang; tidak ada "build pro" terpisah. Pro adalah properti dari endpoint, bukan konektor: sambungkan ke June yang diaktifkan Pro (lisensi Pro di aplikasi, kunci Pro di workspace yang di-host) dan tool yang sama membawa hasil kelas Pro: setiap tulisan june_remember dan june_ingest_file menjalankan mesin entitas/edge yang lebih kaya secara otomatis (hasilnya melaporkan engine mana yang dijalankan), june_resolve meningkatkan ke pencocokan semantik, dan june_enrich mengisi kembali memori yang ditulis di lantai gratis sebelum Anda meningkatkan. Terminal menunjukkan dunia mana yang Anda tempati: --doctor mencetak baris edition dan banner startup server menandai koneksi —

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

Tag dibaca dari /v1/whoami layanan itu sendiri (status entitlement yang sama yang menggerakkan rute Pro di sisi server), sehingga tidak mungkin bertentangan dengan apa yang sebenarnya Anda dapatkan — dan ini hanya tampilan: entitlement ditegakkan di layanan apa pun yang dicetak klien. Layanan lama tanpa /v1/whoami hanya tidak menampilkan tag.

Model keamanan

Permukaan tool tidak mengekspos parameter canvas/workspace — workspace terikat di sisi server dari konteks koneksi Anda, gagal-tertutup. Pembacaan lintas-tenant bukanlah pemeriksaan izin yang bisa gagal terbuka; itu tidak dapat direpresentasikan dari klien. JUNE_READONLY=1 menambahkan pagar kedua untuk deployment hanya-baca. Kunci BYO LLM Anda mengikuti setiap permintaan jawaban sebagai header dan tidak pernah disimpan atau dicatat oleh layanan.

Kesalahan

Setiap kegagalan upstream dipetakan ke payload kesalahan yang diketik dan disunting (dibangun dari tipe pengecualian + status HTTP saja — tidak pernah dari badan respons), sehingga server bertahan dari apa pun yang dilemparkan endpoint dan agen Anda melihat pesan yang bersih dan dapat ditindaklanjuti.

Lisensi

MIT. Mesin Junê itu sendiri adalah produk terpisah dan sumber tertutup — konektor ini adalah bagian terbuka, secara desain.