Junê (june-mcp)

june-mcp

에이전트에게 기억을 주세요. june-mcp는 Junê의 공식 MCP 서버입니다 — 모든 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 서비스. june-local 엔진 패키지를 실행하는 Pro/Team 고객은 JUNE_BASE_URL를 자체 서버에 연결합니다.
3. 호스팅(Team). 콘솔의 API 키로 호스팅된 June 워크스페이스 엔드포인트를 지정합니다.

구성

서버는 fail-closed 방식입니다: 연결 대상과 연결 주체를 알지 못하면 시작을 거부하며, 한 번에 하나의 오류가 아닌 누락된 모든 항목을 한 메시지로 알려줍니다.

env	필수	의미
JUNE_BASE_URL	✅	June 엔드포인트, 예: http://localhost:8000
JUNE_CANVAS	✅	이 연결을 바인딩할 캔버스(워크스페이스) — 이름(work) 또는 캔버스 ID. 이름은 시작 시 ID로 확인되며, 모호한 이름은 fail-closed 처리됨
JUNE_CANVAS_CREATE	선택	1는 아직 존재하지 않는 경우 첫 실행 시 지정된 이름의 캔버스를 생성함(읽기 전용 모드에서는 거부됨)
JUNE_API_KEY	✅	June API 키(JUNE_ALLOW_ANON=1는 키 없는 로컬 설정에서 명시적으로 제외)
JUNE_LLM_KEY	선택	인용 답변을 위한 BYO LLM 키 — 요청별로 헤더로 전달되며, 로깅되거나 서비스에 저장되지 않음
JUNE_READONLY	선택	1는 모든 쓰기 도구를 숨기고 거부함(메모리가 읽기 전용이 됨)
JUNE_FILES_ROOT	선택	에이전트가 june_ingest_file를 통해 파일을 업로드할 수 있는 옵트인 디렉터리 — 설정하지 않으면 해당 도구는 존재하지 않음
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_ANSWER	선택	동사별 타임아웃(기본값 15초 / 120초)
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

호스트를 완전히 다시 시작하고(macOS에서는 Cmd+Q), 서버에 10개의 도구가 표시되는지 확인하세요(JUNE_FILES_ROOT를 통해 june_ingest_file를 옵트인하면 11개).

도구

tool	에이전트가 얻는 것
june_answer	그래프에서 근거가 있는 인용된 답변 — 추측 대신 기권
june_search	쿼리에 대한 순위가 매겨진 증거(멀티홉 지원)
june_context	토큰 예산 내에서 조립된 컨텍스트 팩
june_neighborhood	단일 노드 주변의 그래프
june_subgraph	제한된 서브그래프 내보내기
june_remember	그래프에 사실/메모 작성(즉시 검색 및 인용 가능)
june_ingest	구조화된 노드/엣지 수집
june_enumerate	조건과 일치하는 모든 노드 — 재현 완전한 "모든 X 나열"(top-k 아님)
june_ingest_file	운영자가 승인한 폴더에서 로컬 파일 하나 업로드(pdf/docx/xlsx/csv/html/md/images/audio) — JUNE_FILES_ROOT를 설정한 경우에만 존재
june_enrich	Pro: 더 풍부한 엔진으로 캔버스의 백그라운드 재추출(멱등성, 작업 + 폴링, 무료에서는 403)
june_resolve	유지 관리: 되돌릴 수 있는 same_as 엣지를 통해 중복 엔티티 병합(서버 측에서 실행, strong_only=false는 Pro에서 시맨틱 계층 잠금 해제)

설명은 에이전트를 위해 작성되었으며(무엇 → 언제 → 반환), 잘린 모든 입력은 조용히 잘리는 대신 시각적으로 에이전트에게 다시 표시됩니다.

Free vs Pro — june-pro 태그

june-mcp는 모든 사용자를 위한 단일 패키지이며, 별도의 "프로 빌드"는 없습니다. Pro는 커넥터가 아닌 엔드포인트의 속성입니다: Pro가 활성화된 June(앱의 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가 없는 이전 서비스는 태그를 표시하지 않습니다.

보안 모델

도구 표면은 캔버스/워크스페이스 매개변수를 노출하지 않습니다 — 워크스페이스는 연결 컨텍스트에서 서버 측에 바인딩되며 fail-closed 방식입니다. 교차 테넌트 읽기는 fail-open될 수 있는 권한 검사가 아니라 클라이언트에서 표현 불가능합니다. JUNE_READONLY=1는 읽기 전용 배포에 두 번째 장벽을 추가합니다. BYO LLM 키는 각 답변 요청에 헤더로 포함되며 서비스에 영구 저장되거나 로깅되지 않습니다.

오류

모든 업스트림 실패는 유형화되고 편집된 오류 페이로드로 매핑됩니다(예외 유형 + HTTP 상태만으로 구성 — 응답 본문은 절대 사용하지 않음). 따라서 서버는 엔드포인트가 던지는 모든 것을 견디고 에이전트는 깔끔하고 실행 가능한 메시지를 볼 수 있습니다.

라이선스

MIT. Junê 엔진 자체는 별도의 클로즈드 소스 제품입니다 — 이 커넥터는 설계상 오픈 부분입니다.