Slipbox MCP Server

AI 어시스턴트에게 지식 관리의 능동적인 역할을 부여하세요. Slipbox는 MCP 서버로, 모든 MCP 호환 에이전트를 Zettelkasten 파트너로 만들어 줍니다. 원자적 노트 생성, 의미적 링크 형성, 떠오르는 클러스터 감지, 기존 지식에서 인사이트 종합까지 처리합니다.

아이디어가 들어가면 구조화된 지식이 나옵니다. 에이전트가 형식 지정, 링크, 통합을 처리합니다.

이 방법이 처음이신가요? Zettelkasten 방법 소개에서 원자적 노트와 연결형 사고의 이유를 확인하세요. Slipbox가 에이전트에 이 방법을 어떻게 주입하는지 보려면, 연결 시 자동으로 제공되는 서버 지침을 읽어보세요.

Claude로 구축 및 테스트되었습니다. 모든 MCP 클라이언트(Claude Desktop, Claude Code, OpenCode, Copilot 또는 MCP를 지원하는 모든 도구)에서 작동합니다.

일반 파일, 제로 락인. 노트는 YAML frontmatter가 있는 마크다운입니다. Obsidian, Foam, Logseq 또는 모든 편집기에서 읽을 수 있습니다. SQLite 데이터베이스는 인덱스일 뿐, 진실의 원천이 아닙니다. 언제든 삭제하고 파일에서 다시 구축할 수 있습니다.

• 19개의 MCP 도구 — 노트, 링크, 검색, 그래프 분석, 클러스터 관리용

• 6개의 워크플로 프롬프트(및 매칭 스킬) — Zettelkasten 방법을 인코딩하여 매 세션마다 다시 배울 필요가 없습니다

• BM25 전문 검색 — SQLite FTS5를 통한 제목 및 내용 검색

• 클러스터 감지 — 떠오르는 주제 그룹을 찾고 구조 노트를 스캐폴딩합니다

• 7가지 유형화된 링크 (reference, extends, refines, contradicts, questions, supports, related)

Python 3.10+ | macOS 또는 Linux

워크스루

Related MCP server: vault-master-mcp

빠른 시작

1. 설치

pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcp

이렇게 하면 slipbox-mcp 실행기가 PATH(~/.local/bin)에 추가됩니다. 이 단일 명령이 MCP 서버 전체입니다. 클론도, PYTHONPATH도, 하드코딩된 venv Python 경로도 필요 없습니다. 아래의 모든 내용이 이 명령을 사용합니다. 설치 없이 시도하려면 uvx slipbox-mcp가 임시 환경에서 서버를 실행합니다.

(Slipbox 자체를 개발 중이신가요? 클론 + 편집 가능 설치 설정은 개발을 참조하세요.)

2. 데이터 디렉터리 선택

SLIPBOX_BASE_DIR 하나의 변수로 모든 것이 구성됩니다. 노트는 <base>/data/notes에, SQLite 인덱스는 <base>/data/db/zettelkasten.db에 저장됩니다. 서버는 첫 실행 시 소유자 전용(0700) 권한으로 이 디렉터리들을 생성합니다.

SLIPBOX_BASE_DIR(또는 개별 SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH 경로)을 공유 위치나 시스템 위치가 아닌, 직접 제어하는 전용 데이터 디렉터리에 지정하세요. 이 경로들은 그대로 사용됩니다. 서버는 이 경로 아래에서 노트 트리와 인덱스를 관리하며, 인덱스를 재구축할 때 노트 디렉터리를 진실의 원천으로 취급합니다.

# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipbox

전체 절대 경로를 사용하세요. 앞의 ~는 MCP 클라이언트 구성 파일 내에서 확장되지 않으므로 리터럴 ~ 디렉터리가 생성됩니다.

3. MCP 클라이언트에 연결

Claude Code (파일 편집 없는 단일 명령):

claude mcp add slipbox \
  --env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
  -- slipbox-mcp

Claude Desktop (구성 파일 편집):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "slipbox": {
      "command": "slipbox-mcp",
      "env": {
        "SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
      }
    }
  }
}

Desktop PATH 주의사항: macOS Desktop 앱은 PATH에 ~/.local/bin을 항상 상속하지 않으므로, 단순한 "slipbox-mcp"가 해석되지 않을 수 있습니다. 서버 시작에 실패하면 "command": "slipbox-mcp"를 which slipbox-mcp가 출력하는 절대 경로(일반적으로 /Users/yourname/.local/bin/slipbox-mcp)로 바꾸세요.

기타 MCP 클라이언트: 환경에 SLIPBOX_BASE_DIR을 설정하고 slipbox-mcp를 서버 명령으로 등록하세요. 명령과 환경은 모든 곳에서 동일합니다.

SLIPBOX_BASE_DIR 대신 절대 경로를 개별적으로 설정하세요. 선택적 SLIPBOX_LOG_LEVEL은 DEBUG, INFO, WARNING, ERROR 중 하나입니다.

"env": {
  "SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
  "SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
  "SLIPBOX_LOG_LEVEL": "INFO"
}

4. 재시작 및 확인

클라이언트를 재시작하세요(Claude Code는 다음 실행 시 리로드되고, Claude Desktop은 종료 후 다시 열면 됩니다).

에이전트에게 물어보세요:

• "무언가에 대한 테스트 노트를 만들어 줘"

• "슬립박스에서 test를 검색해 줘"

• "고아 노트를 찾아 줘"

실제 사용 모습

위의 히어로 이미지가 핵심 루프입니다. 에이전트가 하는 나머지 작업은 다음과 같습니다.

능동적 유지보수

에이전트는 세션 시작 시 slipbox://maintenance-status 리소스를 읽고 정리가 필요한 클러스터를 표시합니다.

전문 검색

slipbox_search_notes를 통한 BM25 순위 기반 노트 검색.

지식 그래프: 중심 노트

slipbox_find_central_notes는 그래프의 구조적 앵커 — 다른 모든 것이 궤도를 도는 노트 — 를 표시합니다.

노트 분석

analyze_note 프롬프트는 원자성을 평가하고, 기존 그래프에서 실제 연결을 찾고, 태그를 제안하며, 명확성을 위해 다시 작성합니다.

소스 분해

knowledge_creation 프롬프트는 기사를 적절한 인용과 링크가 있는 원자적 문헌 노트로 분할합니다.

클러스터 감지

slipbox_get_cluster_report는 구조 노트가 없는 공동 발생 태그 그룹을 찾습니다. 크기, 고아 비율, 링크 밀도, 최신성으로 점수가 매겨집니다.

구조 노트 생성

slipbox_create_structure_from_cluster는 구조 노트를 스캐폴딩하고, 모든 구성원 노트를 링크하며, 클러스터를 해제합니다.

고아 노트

slipbox_find_orphaned_notes는 통합되지 않은 지식 — 연결 또는 삭제의 후보 — 을 표시합니다.

유사 노트

slipbox_find_similar_notes는 공유 태그, 공통 링크, 내용 중복에서 유사성을 계산합니다.

그래프 탐색

slipbox_get_linked_notes는 허브 노트에서 유형화된 링크를 링크 유형별로 그룹화하여 보여줍니다.

지식 종합

knowledge_synthesis 프롬프트는 연결되지 않은 영역 사이의 다리를 찾고 기존 지식에서 종합 노트를 제안합니다.

제로 락인: Obsidian의 일반 파일

노트는 일반 마크다운입니다. Obsidian에서 볼트를 열면 모든 것이 작동합니다 — 렌더링된 내용, 역링크, 지식 그래프.

Obsidian의 유형 없는 기본 그래프 대신 유형화된 링크를 색상으로 렌더링하는 그래프를 원한다면, 동반 플러그인 Slipbox Semantic Graph 를 설치하세요. 사람이 읽을 수 있는 제목과 색상으로 구분된 의미적 링크 유형을 갖춘 힘-방향 뷰입니다. 0.1.0 릴리스에서 수동으로 설치하세요: main.js, manifest.json, styles.css를 <vault>/.obsidian/plugins/slipbox-graph/에 복사한 다음 설정 → 커뮤니티 플러그인에서 활성화하세요. (공식 디렉터리에 승인되면 설정 → 커뮤니티 플러그인 → 찾아보기 → "Slipbox Semantic Graph" 검색으로도 설치할 수 있습니다.) 서버가 작성하는 것과 동일한 frontmatter id와 ## Links 섹션을 읽으므로 추가 구성이 필요 없습니다. Open semantic graph 명령(명령 팔레트) 또는 git-fork 리본 아이콘으로 뷰를 여세요.

상단의 범례는 각 색상을 링크 유형(extends, refines, supports, contradicts, questions, related)에 매핑합니다. 구조 노트에 초점을 맞추면 그 별자리가 나타납니다. 여기서는 Contract Testing Knowledge Map과 그 주위를 도는 구성원 노트들입니다:

선택 사항: 자동 클러스터 감지

클러스터 분석은 모든 노트를 스캔하고 유사성 점수를 계산합니다. 매일(오전 6시) 실행하면 결과가 사전 계산되어 slipbox_get_cluster_report()가 즉시 반환됩니다. 스케줄링이 없으면 클러스터 감지는 요청 시 실행되며, 대규모 컬렉션에서는 더 느립니다.

대량 가져오기, 대대적인 재구성 후 또는 즉시 결과가 필요할 때 수동으로 실행하세요.

클러스터 감지 설치 (macOS)

chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.sh

설치 프로그램이 Python/venv 경로를 감지하고 LaunchAgent plist를 생성한 후 로드합니다.

수동 테스트 (파일 감시자)

source .venv/bin/activate
python scripts/detect_clusters.py

출력은 ~/.local/share/mcp/slipbox/cluster-analysis.json에 저장됩니다.

클러스터 감지 제거

./scripts/install-cluster-detection.sh --uninstall

선택 사항: 자동 인덱싱용 macOS 파일 감시자

MCP 서버는 빠른 검색을 위해 데이터베이스 인덱스를 유지합니다. Obsidian(또는 다른 편집기)에서 노트를 편집하면 slipbox_rebuild_index를 실행할 때까지 데이터베이스가 오래된 상태가 됩니다.

파일 감시자는 백그라운드 데몬으로 실행되어 노트 디렉터리를 모니터링하고 .md 파일이 변경되면 인덱스를 자동으로 재구축합니다.

Obsidian에서 노트를 자주 편집하면서 Claude도 사용한다면 사용하세요.

파일 감시자 설치 (macOS)

chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.sh

설치 프로그램이 Python/venv 경로를 감지하고, 필요 시 watchdog을 설치하고, LaunchAgent를 로드합니다. 로그인 시 시작되고 충돌 시 재시작됩니다.

수동 테스트

source .venv/bin/activate
python scripts/watch_notes.py

노트 파일을 편집하세요. 감시자 출력에 "rebuilding index..."가 표시되어야 합니다.

상태 확인

launchctl list | grep slipbox.watcher

# View logs

tail -f ~/.local/share/mcp/slipbox/watcher.log

파일 감시자 제거

./scripts/install-file-watcher.sh --uninstall

권장 시스템 프롬프트

Slipbox는 기본값을 자동으로 제공합니다. 모든 클라이언트는 연결 시 서버 지침을 받아 도구를 잘 사용하는 방법 — 노트 유형, 링크 의미론, 품질 기준, 검색-전-생성과 같은 핵심 워크플로 — 을 다룹니다. 직접 추가할 필요가 없습니다.

docs/SYSTEM_PROMPT.md는 그 위의 옵트인 계층입니다. 서버가 스스로 주장해서는 안 되는 자율성과 주도성 지침입니다. 에이전트의 환경 설정이나 시스템 프롬프트에 추가하여 다음을 활성화하세요:

• 대화 중 자동 지식 캡처

• 대화 시작 시 클러스터 출현 감지

도구 참조

핵심 노트 작업

링크

검색 및 발견

클러스터 분석

유지보수

프롬프트 참조

MCP 프롬프트는 Zettelkasten 방법을 담은 재사용 가능한 워크플로 템플릿으로, 매 세션마다 다시 설명하지 않아도 되게 해줍니다.

호출 방법: 슬래시 명령 및 Skills

각 워크플로는 두 가지 방식으로 제공됩니다:

• MCP 프롬프트: 실행 중인 서버가 제공합니다.

• Skills: 동일한 워크플로를 실행하고 자연어 트리거를 추가하는 독립 번들(skills/<name>/)입니다.

여섯 개의 스킬 중 다섯 개는 서버가 사용하는 것과 동일한 PROMPT_* 템플릿(src/slipbox_mcp/server/descriptions.py)에서 생성되며, 커밋된 skills/가 해당 템플릿에서 벗어나면 CI가 실패합니다. 여섯 번째인 cluster-maintenance은 MCP 프롬프트가 재사용 가능한 워크플로가 아닌 런타임에 렌더링되는 상태 메시지이므로 scripts/build_skills.py에서 직접 작성됩니다.

슬래시 명령이 가장 확실한 경로입니다. Claude Code는 MCP 프롬프트를 /mcp__<server>__<prompt> 형태로 표시합니다. 선택기를 열려면 /mcp__slipbox-mcp__를 입력하세요:

/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance

(설치된 Skills는 디렉터리 이름으로 자체 슬래시 명령도 제공합니다(예: /slipbox-analyze-note).)

자연어는 해당 스킬이 설치되면 작동합니다. 원하는 것을 설명하기만 하면 됩니다:

Analyze this note for my slipbox: [paste note]

Add this to my slipbox: [paste article]

Synthesize my notes on attention and memory.

자연어 트리거는 스킬이 설치되어 있고 문구가 스킬 설명과 일치해야 동작합니다. 작동하지 않으면 슬래시 명령을 사용하세요. 모델에게 "analyze_note 프롬프트를 사용해"라고 이름으로 요청하는 것은 작동하지 않습니다. 모델은 이름으로 MCP 프롬프트를 호출할 수 없습니다. 슬래시 명령을 사용하거나 스킬이 자연어로 트리거되도록 하세요.

Skills 설치

Claude Code는 스킬을 최상위 skills/에서가 아니라 .claude/skills/(프로젝트별) 또는 ~/.claude/skills/(전역)에서 찾습니다. 원하는 스킬을 발견 경로에 심볼릭 링크하거나 복사하세요(예: 이 프로젝트의 경우):

mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all six

Claude Desktop은 각 스킬이 .skill 번들 형태로 필요합니다. 빌드한 다음 업로드하세요:

python scripts/build_skills.py     # writes dist/*.skill

설정 → Skills → 스킬 업로드로 이동하여 dist/에서 원하는 번들을 선택하세요. 각 스킬은 슬래시 명령과 자연어 트리거로 모두 설치됩니다.

descriptions.py에서 프롬프트 템플릿을 편집한 후 빌드를 다시 실행하여 스킬을 재생성하세요.

링크 유형

노트 유형

구조(Structure) vs. 허브(Hub): 구조 노트는 단일 주제를 중심으로 영구 노트 클러스터를 정리합니다. 이는 노트 자체보다 한 단계 위에 있는 큐레이션된 지도입니다. 허브 노트는 한 단계 더 위에서 작동합니다. 전체 지식 도메인에 걸쳐 구조 노트(그리고 때때로 핵심 영구 노트)로 연결됩니다. 구조 노트가 "X에 대해 내가 아는 것은 무엇인가?"에 답한다면, 허브 노트는 "이 전체 도메인에 대한 내 지식은 어떻게 구성되어 있는가?"에 답합니다. 대부분의 Zettelkasten에는 소수의 허브 노트만 있으면 됩니다.

파일 형식

노트는 YAML frontmatter가 있는 Markdown 파일로 저장됩니다:

---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
  - poetry
  - revision
  - craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---

# Poetry Revision Principles

Content here...

## Links

- reference [[20250728T125429845760000]] Member of structure

이 파일들은 텍스트 편집기나 Obsidian에서 직접 편집할 수 있습니다. 외부에서 편집한 후에는 slipbox_rebuild_index를 실행하세요.

업그레이드

새 버전을 가져온 후 Claude Desktop을 다시 시작하세요. 릴리스 노트에 데이터베이스 변경 사항이 언급된 경우 slipbox_rebuild_index를 한 번 실행하여 기존 데이터베이스를 최신 상태로 만드세요.

FTS5 검색으로 업그레이드(FTS5 릴리스 이후의 모든 버전): 전체 텍스트 검색 인덱스는 서버가 새 데이터베이스로 시작할 때 자동으로 생성됩니다. 기존 데이터베이스의 경우 FTS5 테이블은 첫 시작 시 생성되지만 다음 명령을 실행하기 전까지는 비어 있습니다:

slipbox_rebuild_index

이 명령은 기존 노트에서 BM25 인덱스를 채웁니다. 이 작업이 완료될 때까지 검색 결과는 관련성 순으로 정렬되지 않습니다.

문제 해결

Claude Desktop에서 서버가 로드되지 않음

1. 실행기가 확인되는지 확인하세요: which slipbox-mcp가 경로(일반적으로 ~/.local/bin/slipbox-mcp)를 출력해야 합니다.

2. 터미널에서는 확인되는데 Desktop에서 여전히 시작할 수 없다면 GUI 앱이 PATH에서 ~/.local/bin을 찾지 못하는 것입니다. "command": "slipbox-mcp"를 1단계에서 확인한 절대 경로로 바꾸세요.

3. Claude Desktop 로그에서 오류를 확인하세요.

slipbox-mcp: command not found

콘솔 스크립트가 설치되지 않았거나 PATH에 없습니다. pipx install --editable . --force로 다시 설치한 후 which slipbox-mcp로 확인하세요. pipx의 bin 디렉터리가 PATH에 없으면 pipx ensurepath를 실행하고 셸을 다시 시작하세요.

노트 디렉터리가 ~/...를 문자 그대로 가리키는 경우

노트 디렉터리가 CWD 기준 ./~/...로 설정된다면 JSON 구성에서 ~를 사용한 것입니다. Claude Desktop은 ~를 확장하지 않습니다. 전체 절대 경로로 바꾸세요.

검색 결과가 없음

1. FTS5 인덱스가 채워지지 않았을 수 있습니다. 기존 노트를 인덱싱하려면 slipbox_rebuild_index를 한 번 실행하세요.

2. 최근에 Claude 외부에서 노트를 편집했다면 인덱스가 최신 상태가 아닐 수 있습니다. slipbox_rebuild_index를 실행하세요.

slipbox_list_notes_by_date가 빈 결과를 반환함

start_date가 end_date보다 이후이면 일치하는 노트가 없어 빈 결과가 반환됩니다. 이는 오류가 아닌 정상적인 동작입니다.

데이터베이스 동기화 불일치

MCP 서버 외부에서 노트가 편집된 경우:

slipbox_rebuild_index

클러스터 감지가 실행되지 않음

launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection

# Check logs

cat /tmp/slipbox-clusters.log

# Reinstall if needed

./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.sh

파일 감시자가 실행되지 않음

launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher

# Check logs

cat ~/.local/share/mcp/slipbox/watcher.log

# Reinstall if needed

./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.sh

ZETTELKASTEN_* 환경 변수에서 업그레이드

이전에 ZETTELKASTEN_NOTES_DIR, ZETTELKASTEN_DATABASE_PATH 또는 기타 ZETTELKASTEN_* 변수를 사용했다면 해당 변수는 더 이상 읽히지 않습니다. 대응하는 SLIPBOX_* 변수로 이름을 바꾸세요:

서버는 이전 이름이 감지되면 경고를 기록하지만 자동으로 마이그레이션하지는 않습니다.

클러스터 보고서 경로는 구성할 수 없음

클러스터 분석 보고서는 SLIPBOX_BASE_DIR 또는 SLIPBOX_NOTES_DIR와 관계없이 항상 ~/.local/share/mcp/slipbox/cluster-analysis.json에 기록됩니다. 기본값이 아닌 경로를 사용하더라도 클러스터 보고서는 여전히 기본 위치에 저장됩니다.

설치 스크립트는 macOS 전용

scripts/install-cluster-detection.sh 및 scripts/install-file-watcher.sh 스크립트는 macOS에만 있는 launchctl과 ~/Library/LaunchAgents/를 사용합니다. Linux에서는 이에 상응하는 systemd 유닛이나 cron 작업을 수동으로 만들어야 합니다. 관련 README 섹션의 수동 테스트 명령을 참조하여 기본 Python 스크립트가 해당 플랫폼에서 작동하는지 확인하세요.

기본 경로는 작업 디렉터리를 기준으로 함

SLIPBOX_NOTES_DIR와 SLIPBOX_DATABASE_PATH가 설정되지 않으면 서버는 현재 작업 디렉터리(CWD)를 기준으로 data/notes와 data/db/zettelkasten.db를 기본값으로 사용합니다. Claude Desktop을 통해 실행할 때 CWD는 예상과 다를 수 있습니다. 이를 방지하려면 claude_desktop_config.json에 항상 절대 경로를 설정하세요.

개발

설정

git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"

테스트

프로젝트에는 세 가지 계층의 테스트가 있습니다:

# Default: runs unit + contract tests (CI runs this)

pytest

# Run everything except LLM evals

pytest tests/ evals/tool_contracts/

# Run LLM evals (requires claude CLI authenticated)

pytest evals/llm/ -v

# Run LLM evals with a specific model

EVAL_MODEL=sonnet pytest evals/llm/ -v

# Lint

ruff check src/ evals/

단위 테스트는 내부 로직(서비스, 리포지토리, 모델, 파싱)을 다룹니다.

도구 계약 테스트는 LLM이 보게 되는 MCP 도구 출력 형식(파싱 가능한 구조, 체이닝(create -> search -> get), 유용한 오류 메시지)을 검증합니다. 이 테스트는 결정적이며 LLM을 호출하지 않습니다.

LLM 평가는 MCP 서버가 연결된 상태에서 claude CLI를 통해 LLM에 프롬프트를 보낸 다음, 데이터베이스 상태(생성된 노트, 만들어진 링크, 적용된 태그)를 검사하여 결과를 평가합니다. 이는 도구 설명이 주어졌을 때 LLM이 도구를 실제로 올바르게 사용하는지 테스트합니다.

CI/CD

브랜치 보호: main에 대한 직접 푸시는 차단됩니다. 모든 변경 사항은 PR을 통해 진행됩니다.

LLM 평가 스위트는 비용이 많이 들고(~$3-5, ~10분) 자체 호스팅 방식이므로 절대 자동으로 실행되지 않습니다. 경로 기반 트리거는 실제 프롬프트 변경과 표면적인 재포맷을 구분할 수 없습니다. 프롬프트나 도구 설명의 의미를 변경할 때 의도적으로 실행하세요:

• PR에 run-llm-evals 라벨을 추가하세요. 라벨이 있는 동안 각 푸시에서 실행되고 다시 실행됩니다.

• 또는 Actions 탭에서 수동으로 트리거하세요 (workflow_dispatch).

• 또는 러너 없이 로컬에서 실행하세요: pytest evals/llm/ -v.

라벨이나 수동 디스패치가 없으면 작업은 건너뛰어집니다 (러너가 할당되지 않으므로 비용이 들지 않습니다).

평가 설정 사용자 지정

자체 호스팅 러너를 원하지 않으면: .github/workflows/llm-evals.yml을 제거하고 프롬프트 변경을 병합하기 전에 로컬에서 pytest evals/llm/ -v를 실행하세요.

모든 PR에서 LLM 평가를 자동으로 실행하려면: 관련 paths: 필터를 사용해 pull_request 트리거를 추가하고 작업의 if:에서 라벨 조건을 제거하세요. 단, 포맷팅만 변경한 편집에서도 부수적 트리거가 발생할 수 있습니다.

기본 평가 모델을 변경하려면: 환경 또는 워크플로 파일에서 EVAL_MODEL을 설정하세요. 기본값은 속도/비용을 위해 haiku입니다.

자체 호스팅 러너를 설정하려면:

# Get a registration token

gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'

# Download and configure

mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &

PyPI에 릴리스

릴리스는 자동화되어 있습니다. Release 워크플로 (.github/workflows/release.yml)는 main으로의 모든 푸시에서 release-please를 실행하고 PyPI Trusted Publishing을 통해 게시합니다 (OIDC를 사용하므로 저장소 시크릿에 API 토큰이 저장되지 않습니다).

흐름 (버전을 직접 수정하거나 태그를 푸시할 필요가 없습니다):

1. Conventional Commit 메시지로 main에 변경 사항을 반영하세요 (feat: → minor 버전 상승, fix: → patch, feat!:/BREAKING CHANGE: → major). 저장소의 커밋 훅이 이미 이 형식을 강제합니다.

2. release-please는 다음 버전 상승분(src/slipbox_mcp/__init__.py)과 해당 커밋들에서 파생된 CHANGELOG.md 항목을 축적하며 **"release PR"**을 계속 열어 둡니다.

3. 배포할 준비가 되면 release PR을 병합하세요. 그러면 릴리스 태그(v<version>)가 생성되고, 같은 워크플로 실행에서 sdist + wheel을 빌드하고 twine check를 실행한 다음 PyPI에 게시합니다.

따라서 릴리스 배포는 한 번의 클릭입니다: 봇의 PR을 병합하면 됩니다. 다른 것은 없습니다.

커밋 유형이 버전을 결정합니다. 그러니 정확하게 입력하세요. 버전 상승은 마지막 릴리스 이후의 Conventional Commit 접두사에서 기계적으로 계산되며, 변경 규모에 따라 결정되지 않습니다. feat:/fix:는 배포되는 패키지의 변경에만 사용하고, 그 외 모든 것에는 릴리스가 없는 유형을 사용하세요:

릴리스가 없는 커밋만 모인 배치는 release PR을 전혀 만들지 않습니다. squash-merge 제목이 release-please가 읽는 커밋이므로, PR 제목의 접두사가 중요합니다. 라벨은 들인 노력이 아니라 패키지가 얻는 것에 맞춰 붙이세요.

일회성 설정 (이 저장소에는 이미 완료되어 있으며, 포크를 위해 문서화되어 있습니다):

1. PyPI에서 slipbox-mcp 프로젝트에 대해 pending trusted publisher를 등록하세요: Owner: jamesfishwick · Repository: slipbox-mcp · Workflow: release.yml · Environment: release. 네 가지가 모두 정확히 일치해야 합니다.

2. GitHub에서 release라는 이름의 환경을 만드세요 (Settings → Environments). 배포 ref를 제한하는 경우 tag 규칙 v*를 추가하세요 (같은 이름의 branch 규칙은 태그와 일치하지 않습니다).

버전은 src/slipbox_mcp/__init__.py에 한 번만 정의됩니다 (release-please가 이를 올리며, # x-release-please-version 마커가 어느 줄인지 알려줍니다). pyproject.toml (dynamic = ["version"])과 서버의 server_version 모두 이 값을 읽으므로 동기화할 것이 없습니다; release-please가 만드는 태그는 항상 구조적으로 패키지 버전과 일치합니다.

게시 없이 빌드를 미리 연습하려면 직접 실행하세요: python -m build && twine check dist/* (그리고 TestPyPI 토큰으로 twine upload --repository testpypi dist/*를 실행해 업로드를 드라이런할 수 있습니다).

공유 프롬프트 상수

모든 도구 설명과 프롬프트 템플릿은 src/slipbox_mcp/server/descriptions.py에 있습니다. MCP 서버와 평가 테스트 모두 이 단일 소스에서 가져옵니다. 프롬프트를 변경하면 평가는 LLM이 새 문구에서도 여전히 올바르게 동작하는지 테스트합니다.

디버그 로깅

SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"

CLI 도구

slipbox 명령은 기계적인 작업을 위한 터미널 액세스를 제공합니다:

slipbox status          # Overview of notes, tags, orphans, pending clusters
slipbox search <query>  # Find notes by text
slipbox clusters        # Show pending structure note candidates
slipbox orphans         # List unconnected notes
slipbox rebuild         # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id>     # Export note markdown to stdout
slipbox tags            # List all tags with usage counts

설치: pipx install --editable . (slipbox를 PATH에 추가합니다)

실험적: 에이전트 메모리로서의 Slipbox

검증되지 않은 가설이며 권장 설정이 아닙니다. 위의 모든 내용은 에이전트가 당신의 지식을 관리하도록 돕습니다. 이것은 그 반대입니다: 에이전트가 네이티브 메모리나 규칙 파일 대신 세션 간 자신의 영구 메모리로 slipbox를 사용합니다.

모델은 세션 간 메모리가 없으므로 slipbox는 한 세션이 다음 세션을 위해 남기는 유일한 채널입니다. 이전 컨텍스트 없이 시작하는 후임자를 위한 브리핑(실패와 그 이유, 반복되는 제약, 수정 사항, 힘들게 얻은 사실)을 작성하고 agent-memory 태그를 붙인 다음, 행동하기 전에 해당 태그를 검색합니다. 핵심은 연결된 메모리가 평평한 규칙 파일보다 낫다는 것인데, 탐색을 통해 검색할 수 있기 때문입니다.

먼저 알아야 할 세 가지: 네임스페이스 격리는 태그 규칙일 뿐 강제되지 않으므로 별도의 slipbox 인스턴스에서 실행하세요; "메모리"라는 표현은 부적절한데, 노트 자체 외에는 아무것도 지속되지 않기 때문입니다; 그리고 성장 규율이 검증되지 않은 부분이므로 첫 실행에서는 무분별하게 늘어날 것으로 예상하세요. 전체 설명과 주의사항: 에이전트 자기 메모리로서의 Slipbox.

문서

기여

설정 지침, 코딩 표준, 변경 사항 제출 방법은 CONTRIBUTING.md를 참조하세요.

로드맵

계획된 기능과 향후 방향은 ROADMAP.md를 참조하세요.

스폰서

slipbox-mcp가 유용하다면 프로젝트 후원을 고려해 주세요.

라이선스

MIT