NOUZ — Obsidian용 MCP 서버

Obsidian 내 의미론적 지식 관리를 위한 통합 MCP 서버입니다. 로컬 임베딩 모델과 함께 작동하며 클라우드가 필요하지 않습니다.

MIT License Python 3.10+ MCP

빠른 시작

git clone https://github.com/KVANTRA-dev/NOUZ-MCP
cd NOUZ-MCP
pip install -r requirements.txt

export OBSIDIAN_ROOT=./vault
export EMBED_API_URL=http://127.0.0.1:1234/v1  # LM Studio or Ollama

python server.py

stdio 전송을 사용하여 MCP 호환 클라이언트(Claude Desktop 등)를 통해 연결하세요.

Related MCP server: Semantic Mesh Memory (SEM) MCP Server

모드

NOUZ는 세 가지 작동 모드를 지원합니다. MODE 환경 변수나 config.yaml을 통해 설정할 수 있습니다.

모드	설명	임베딩 필요 여부
luca	순수 그래프 — YAML + 링크, 의미론적 분류 없음	아니오
prizma	그래프 + 의미론 — 기호 분류, core_mix, 의미론적 브리지	예
sloi	엄격한 5단계 계층 구조 — 순환 감지, 위반 경고	예

그래프 탐색만 원하신다면 LUCA로 시작하세요. 의미론적 코어를 정의할 준비가 되면 PRIZMA/SLOI를 추가하세요.

노트 형식

각 노트는 YAML 프런트매터를 사용합니다:

---
type: module
level: 3
sign: T
status: active
tags:
  - research
parents:
  - Parent Note Name
parents_meta:
  - entity: Parent Note Name
    link_type: hierarchy
---

Your note content here.

5단계 계층

단계	유형	설명
1	core	최상위 도메인 (예: "수학")
2	pattern	도메인 내 지식 영역
3	module	분야 내 그룹화
4	quant	구체적인 원자 단위 노트
5	artifact	말단 노트, 참조, 로그

parents 필드는 노트 이름의 목록입니다(Obsidian/ExcaliBrain의 위키링크에서 사용). parents_meta 필드는 NOUZ 그래프 로직을 위한 구조화된 링크 메타데이터를 담고 있습니다. 이 둘을 동기화 상태로 유지하세요. NOUZ는 쓰기 작업 시 이를 자동으로 처리합니다.

의미론적 에탈론(Semantic Etalons) (Prizma / Sloi)

에탈론은 지식 공간의 "축"을 정의하며, 각 지식 도메인을 나타내는 참조 텍스트입니다. NOUZ는 이 벡터들과의 코사인 유사도를 통해 노트를 분류합니다.

config.template.yaml을 config.yaml로 복사하세요:

mode: prizma

etalons:
  - sign: T
    name: Technology
    text: "programming software architecture infrastructure machine learning neural networks algorithms"
  - sign: S
    name: Science
    text: "physics chemistry biology mathematics formal logic theorems cosmology quantum mechanics"
  - sign: H
    name: Humanities
    text: "philosophy psychology sociology history literature art culture ethics cognitive science"

모범 사례:

3~5개의 도메인을 사용하세요. 너무 많으면 분류가 부정확해집니다.
각 에탈론은 문장이 아닌 밀도 높은 키워드 목록이어야 합니다.
에탈론 변경 후 calibrate_cores를 실행하고 쌍별 코사인 유사도를 확인하세요.
깔끔한 분리를 위해 에탈론 간 유사도를 0.55 미만으로 유지하는 것을 목표로 하세요.

도구

모든 모드

도구	설명
`read_file(path)`	파싱된 YAML 메타데이터와 함께 노트 읽기
`write_file(path, content, metadata)`	YAML 프런트매터와 함께 노트 쓰기
`list_files(level, sign, tags)`	볼트에서 노트를 필터링하고 나열
`index_all(with_embeddings)`	볼트를 SQLite DB로 인덱싱
`embed(text)`	구성된 제공자로부터 임베딩 벡터 가져오기
`get_parents(path)`	부모 노드 가져오기 (이 노드를 참조하는 파일들)
`get_children(path)`	자식 노드 가져오기 (이 노드가 참조하는 파일들)
`format_entity_compact(path)`	엔티티 공식 반환: `(children)[entity]{parents}`

Prizma / Sloi 전용

도구	설명
`calibrate_cores()`	설정에서 에탈론 임베딩 재계산
`recalc_signs()`	인덱싱된 모든 노트에 기호 자동 할당
`recalc_core_mix()`	DAG를 통해 상향식으로 core_mix 집계
`suggest_metadata(path)`	노트에 대한 기호, 단계, core_mix 제안
`suggest_parents(path)`	벡터 유사도를 기반으로 부모 링크 제안

환경 변수

변수	기본값	설명
`OBSIDIAN_ROOT`	`./obsidian`	Obsidian 볼트 경로
`MODE`	`luca`	`luca` / `prizma` / `sloi` — config.yaml에 의해 재정의됨
`EMBED_PROVIDER`	`openai`	`openai` / `gigachat` / `ollama`
`EMBED_API_URL`	`http://127.0.0.1:1234/v1`	임베딩 API 엔드포인트
`EMBED_MODEL`	—	모델 이름 (선택 사항, 제공자 기본값 사용)
`EMBED_API_KEY`	—	API 키 (로컬 모델의 경우 비워둠)
`EMBED_ENABLED`	`true`	임베딩을 완전히 비활성화하려면 `false`로 설정

예시 워크플로우

# 1. Start server
python server.py

# 2. Index your vault
index_all(with_embeddings=true)

# 3. Calibrate etalons (Prizma/Sloi)
calibrate_cores()

# 4. Classify all notes
recalc_signs()

# 5. Query
suggest_parents("path/to/note.md")
list_files(sign="T", level=4)

NOUZ MCP Server

NOUZ — Obsidian용 MCP 서버

빠른 시작

모드

노트 형식

5단계 계층

의미론적 에탈론(Semantic Etalons) (Prizma / Sloi)

도구

모든 모드

Prizma / Sloi 전용

환경 변수

예시 워크플로우

링크

변경 로그

v2.1.1

v2.1.0

Resources

Tools

Latest Blog Posts

MCP directory API