# 온톨로지 서버 — 맥미니 + Neo4j 설계

> 2026-07-19. 상태: 설계 확정(사용자 승인), 구현 계획 대기.
> 배경 문서: `docs/ontology/kit.md`(진단 온톨로지 키트 v0.1), `docs/ontology/jobslab.md`(첫 사본), `docs/handoff-business-model.md`

## 1. 배경 / 목표

진단 온톨로지 키트(개체 6유형·관계 어휘 12개)의 데이터를 **에이전트들이 실시간으로 읽고 쓰는 살아있는 그래프**로 만든다. 마크다운 사본은 사람용 산출물로 유지하고, 그래프가 에이전트용 원본이 된다.

**소비자**: ① 로컬 에이전트(Claude Code·jedit, 맥) ② EC2 서버 에이전트(jurin 개인 비서, 카톡봇) ③ (미래) 고객사 자동화 시스템.

### 확정 결정

| 결정 | 내용 | 근거 |
|---|---|---|
| 저장소 | **Neo4j Community Edition** (그래프 DB) | 온톨로지의 정석 저장소. 사용자 선택 |
| 실행 위치 | **맥미니** (EC2 아님) | EC2 메모리/비용 부담 회피. 사용자 선택 |
| 연결층 | **Neo4j 공식 MCP 서버** (`mcp-neo4j-cypher`), HTTP 전송 | 커스텀 서버 불필요 — 공식 도구가 HTTP·읽기전용·CORS/신뢰호스트 지원 (find-docs 실측) |
| 외부 노출 | **Cloudflare Tunnel** → `ontology.jobslab.dev` | 집 공유기 포트 개방 없이 HTTPS. jobslab.dev가 이미 Cloudflare |
| 인증 | Cloudflare Access **서비스 토큰** | EC2 에이전트만 통과. MCP 서버 자체엔 인증 없으므로 터널 앞단에서 강제 |
| 테넌트 격리 | 노드 `tenant` 속성 (속성 기반) | Community는 다중 DB 미지원(유료판 기능). 현 접속자 전원이 본인 에이전트라 규약 수준으로 충분 |
| 데이터 흐름 | 마크다운(사람용) → 시드 스크립트 → 그래프(에이전트용) | 진단 산출물 워크플로우 유지 |

### 범위 밖

- 고객사 에이전트의 **직접 접속** (격리 강제 층은 그 시점에 추가 — 본 설계는 경계만 명시)
- 그래프 시각화 UI (Neo4j 내장 브라우저로 충분)
- 마크다운 자동 동기화 (초기 적재는 1회성 시드, 이후 그래프가 원본)
- EC2 이전 (트리거: 고객사 시스템이 실시간 의존하게 될 때 — 백업 덤프로 이전)

## 2. 아키텍처

```
[맥미니 — 상시 가동 전제]
  Neo4j Community  ──(bolt, 로컬만)──  mcp-neo4j-cypher (HTTP, 127.0.0.1:8080, /mcp/)
                                          │
                              cloudflared (터널, 아웃바운드만)
                                          │
                              ontology.jobslab.dev (Cloudflare Access 게이트)

[접속]
  맥 로컬 에이전트  → http://127.0.0.1:8080/mcp/ (직결)
  EC2 에이전트(jurin·카톡봇) → https://ontology.jobslab.dev/mcp/ + 서비스 토큰 헤더
```

- Neo4j 설치: Homebrew (macOS 네이티브, VM 오버헤드 없음, `brew services` 자동 시작)
- MCP 서버: 공식 패키지를 uvx로 실행, `--transport http --server-host 127.0.0.1 --server-port 8080 --server-path /mcp/ --allowed-hosts "ontology.jobslab.dev,localhost,127.0.0.1"`
- 자동 기동 3종: Neo4j(brew services) · MCP 서버(LaunchAgent) · cloudflared(LaunchAgent). 절전 방지 설정 포함

## 3. 데이터 모델 (키트 1층 = 스키마)

**노드 라벨 6개** (모든 노드 공통 속성: `tenant`, `id`, `name`, `desc`, `status`[확인됨|미확인], `evidence`)

| 라벨 | 키트 유형 | ID 접두어 |
|---|---|---|
| `Actor` | 행위자 | A- |
| `Object` | 대상 | O- |
| `Event` | 이벤트 | E- |
| `Record` | 기록 | R- |
| `Rule` | 규칙 | RU- |
| `Bottleneck` | 병목 | B- |

**관계 12개** (키트 고정 어휘의 영문 매핑 — 이 외 관계 생성 금지)

`CREATES`(만든다) `APPROVES`(승인한다) `CHECKS`(확인한다) `HANDS_OFF`(전달한다) `WRITES_TO`(적는다) `REFERENCES`(참조한다) `WAITS_ON`(기다린다) `JUDGES_BY`(판단한다) `OWNS`(소유한다) `REQUESTS`(요청한다) `NOTIFIES`(알린다) `RECONCILES`(대사한다)

**병목 노드 추가 속성**: `pattern`(P01~P12 카탈로그 매핑), `pain`(1~3)

**제약**: `(tenant, id)` 복합 유니크. 테넌트 값: `jobslab`, 이후 고객사 슬러그.

**에이전트 사용 규약** (연결하는 모든 에이전트의 지침에 포함할 것): 모든 질의는 `tenant` 필터를 반드시 포함한다. 관계는 12개 어휘만 쓴다.

## 4. 초기 데이터 (시드)

`docs/ontology/jobslab.md`의 개체·관계를 적재하는 1회성 시드 파일(Cypher). 파서 만들지 않음 — 개체 30개 미만이라 수기 변환이 최소 구현. 시드 파일은 `docs/ontology/seed/` 아래 보관해 재현 가능하게.

## 5. 운영

| 항목 | 방식 |
|---|---|
| 백업 | launchd 일일 스케줄 — 그래프 전체 덤프 → 로컬 백업 폴더, 14일 보존 |
| 복구/이전 | 덤프 파일 = EC2·Aura 이전 경로 (탈출 경로 상시 확보) |
| 절전 | 시스템 절전 해제 설정 (상시 가동) |
| 모니터링 | 1단계에선 없음. jurin이 온톨로지 조회 실패 시 알리는 것으로 갈음 (범위 밖) |

## 6. 완료 기준 (Sprint Contract)

1. 맥 로컬에서 Claude Code가 MCP 경유로 잡스랩 병목 목록(B-01~06) 조회 성공
2. EC2에서 `ontology.jobslab.dev` 경유 동일 조회 성공 **+ 토큰 없는 요청은 거부** 확인
3. `jobslab.md`의 개체·관계 전량이 그래프에 적재 (개체 수·관계 수 대조)
4. 맥미니 재부팅 후 Neo4j·MCP 서버·터널 3종 자동 복구 확인

## 7. 리스크와 경계

- **맥미니 = 집 인프라.** 정전·인터넷 장애·macOS 업데이트가 곧 다운타임. 본인 에이전트용으로는 허용. **고객사 시스템이 실시간 의존하는 순간 EC2/관리형으로 이전** — 이 경계를 넘는 계약 전에 이전 완료할 것.
- **속성 기반 격리의 한계.** 접속자가 전부 본인 에이전트인 동안만 유효. 고객사 직접 접속 시 격리 강제 층(별도 게이트웨이 또는 유료판) 필요 — 그 전까지 고객 데이터는 "내 에이전트가 대신 조회"만.
- **원시 Cypher 노출.** 공식 MCP는 쓰기 포함 자유 질의라 에이전트 실수로 스키마 오염 가능. 어휘·테넌트 규약을 에이전트 지침에 박고, 백업으로 복구선 확보. 오염 반복 시 읽기전용 서버 분리(공식 지원 옵션) 검토.

## 8. 미해결

- **맥미니 상시 가동 여부** — 사용자 확인 필요. 간헐 가동이면 EC2 에이전트(카톡봇 등)가 조회 실패하는 시간대 발생 → 용도 재조정 필요.

## 9. 의사결정 로그

| 일자 | 결정 | 대안 | 이유 |
|---|---|---|---|
| 07-18 | 접속 범위 = EC2 서버 에이전트 포함 | 로컬 전용 | jurin·카톡봇도 소비자 |
| 07-18 | 멀티테넌트 처음부터 | 잡스랩 단독 | A 산출물이 C 인프라가 되는 구조 |
| 07-19 | Neo4j + 맥미니 | MCP+Atlas(권장안), 파일 기반 | 정석 선택 + 비용을 하드웨어로 해결 (사용자) |
| 07-19 | 공식 MCP 서버 사용 | 커스텀 Node 서버 | HTTP·보안 미들웨어 공식 지원 확인 — 최소 구현 |