Wikimate (위키메이트)

AI 에이전트에게 "정리해줘" 라고 하면, 흩어진 자료(웹 링크·PDF·대화 로그·텍스트)를 내 옵시디언 볼트에 노트로 정리하고, 원하면 노션에 색인해주는 Claude Code 플러그인. (Codex엔 "플러그인 설치(/plugin)"가 없어요 — 대신 저장소를 받아 codex mcp add로 MCP 서버로 등록해 연동합니다: adapters/codex/SETUP.md.)

English

📘 처음이세요? 그대로 따라 하는 왕초보 가이드 (PDF)를 보세요 — 용어 사전·설치·사용·문제해결·라이선스까지 전부 쉽게 설명해요.

상태: v0.7.1 — 정리·검색·볼트 건강검진·작업 로그·보관함 자동탐지(MCP 도구 5개) 동작·검증 완료. 노션 색인은 노션 도구가 연결된 환경에서 동작(아래 "현재 상태" 참고).

📱 기기 안내: Wikimate는 윈도우 PC(데스크톱·노트북) 전용이에요. 스마트폰·태블릿에는 설치되지 않습니다.

무엇을 해주나요?

• 🧹 자연어로 정리 — "이 링크 정리해줘" 한마디면 노트가 만들어져요. (가끔 자동발동이 안 되면 /wikimate <링크> 슬래시 명령으로 100% 실행.)
• 🧭 보관함 자동탐지(v0.7.1) — 옵시디언에 등록된 보관함(볼트)을 자동으로 찾아 "여기에 정리할까요?" 하고 제안해줘요(이름 안 말해도 됨, 도구 wikimate_vaults).
• 📒 내 진짜 옵시디언 볼트에 — 설치된 옵시디언 도구(MCP/CLI)를 자동 감지해 사용하고, 없으면 파일로 폴백.
• 🗂️ 노션 색인(선택) — 노션 도구가 연결돼 있으면 색인 행을 추가(옵시디언=원본, 노션=단방향 색인).
• ✋ 항상 계획 먼저 → 승인 후 실행 — 멋대로 쓰지 않아요.
• 🔁 중복 차단 — 같은 자료는 source_hash로 한 번만.
• 🛡️ 안전 설계 — 볼트 밖 경로 차단, 외부 글은 명령이 아니라 데이터로 취급(프롬프트 인젝션 방어).
• 🔎 물어보기 — "내 볼트에서 ~ 찾아줘" 하면 정리해 둔 노트에서 출처와 함께 답해요(없는 건 없다고 정직히).
• 🩺 볼트 건강검진 — 중복·깨진 [[링크]]·고아 노트·머리말 누락을 찾아 보고하고, 승인하면 삭제 없이(보관함 이동·백업) 고쳐요.
• 🧾 작업 로그 — AI가 내 볼트에서 한 일을 자동 기록("최근 작업 보여줘").

30초 용어 (왕초보용)

더 많은 용어는 왕초보 가이드 1번에 있어요.

설치 (Claude Code)

⚠️ 아래 두 명령을 한 줄씩 따로 입력하세요. (한꺼번에 붙여넣으면 URL이 깨져 실패해요.)

1) 마켓플레이스 추가 — 입력 후 Enter, "added" 확인:

/plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git

2) 플러그인 설치 — 1)이 끝난 뒤:

/plugin install wikimate@wikimate-marketplace

설치 후 Claude Code를 재시작하면 끝. (확인하고 싶으면 /mcp에 wikimate_collect·wikimate_lint·wikimate_fix·wikimate_runlog·wikimate_vaults 5개가 보이면 성공)

실행 방법

따로 "실행(켜기)"할 게 없어요. 설치만 하면 Claude Code를 켤 때마다 자동으로 함께 켜져요. "실행"은 곧 Claude Code를 켜고 대화창에 말로 시키는 것이 전부예요. (개발자가 서버를 직접 돌리려면 받은 폴더에서 npm install 후 npm start.)

설치 (Codex)

Codex엔 /plugin 마켓플레이스가 없어요. 대신 저장소를 받아 MCP 서버로 등록합니다.

1) 저장소 받기

git clone https://github.com/sodam-ai/SoDam-WikiMate.git

2) MCP 서버 등록 (볼트·저장소 경로는 본인 것으로 바꾸세요):

codex mcp add wikimate --env OBSIDIAN_VAULT_PATH=D:/내/볼트/경로 -- node D:/받은/경로/SoDam-WikiMate/mcp/server.mjs

→ codex mcp list 에 wikimate가 보이면 성공.

3) (선택) 자연어 규칙 — Codex 작업 폴더에 저장소의 AGENTS.md를 두면 "정리해줘" 같은 말도 따릅니다. 업데이트: 받은 폴더에서 git pull 하면 끝(Claude Code 같은 캐시 함정 없음).

⚠️ Codex는 "축소판"이에요. 정리(쓰기) MCP 도구까지 동작하지만, 자동 발동·물어보기·여러 노트 종합 같은 스킬은 Claude Code 전용이고, 노션 색인은 Codex에 별도 노션 MCP가 연결돼 있어야 해요. (자세히: adapters/codex/SETUP.md)

업데이트가 안 될 때 — 가장 흔한 함정 (Claude Code)

GitHub에 새 버전이 올라가도, 내 PC의 마켓플레이스 캐시는 자동으로 안 바뀌어요. 그래서 재설치만으론 옛날 버전이 그대로일 수 있어요. 최신으로 갱신하려면:

/plugin marketplace update wikimate-marketplace
/plugin install wikimate@wikimate-marketplace

그래도 안 되면 /plugin 메뉴에서 마켓플레이스를 remove → 다시 add → 설치 (캐시를 통째로 새로 받아요).

💡 "GitHub에 푸시해야 하나요?" → 아니요. 설치·업데이트는 GitHub에서 받아오는 것이라, 내가 따로 올릴(push) 필요가 없어요. (푸시는 개발자가 코드를 바꿀 때만) ⚠️ 설치 중 EBUSY: resource busy or locked 가 뜨면 → Windows 백신(Defender)이 갓 쓰인 파일을 잠깐 잠근 거예요. Claude Code를 완전히 종료했다 다시 켠 뒤 위 명령을 다시 실행하면 대개 풀립니다.

사용법

대화로 시키면 됩니다:

"이 내용을 내 'Vault' 볼트에 정리해줘"

⭐ 확실한 방법(권장) — 자연어 "정리해줘"는 AI 판단이라 가끔 자동발동을 안 하고 그냥 요약만 할 때가 있어요. 그럴 땐 슬래시 명령 /wikimate <링크/텍스트> 를 쓰면 100% 발동합니다(직접 명령이라). 예: /wikimate https://example.com

• 📎 정리할 "자료"는 무엇이든 돼요 — 한 문장 텍스트, 웹 링크(이 링크 정리해줘: https://...), 파일 경로(이 파일 정리해줘: D:\메모\오늘.md) 모두 OK. 따로 준비할 게 없어요.
• 🧭 보관함 이름은 안 말해도 돼요(v0.7.1) — Wikimate가 등록된 보관함을 찾아 "여기에 할까요?"라고 제안해줘요. 콕 집어 "내 'Vault' 볼트에" 처럼 말해도 됩니다(이름은 옵시디언 좌하단 볼트 전환 메뉴에서 확인).
• 먼저 계획(어디에·어떤 도구로·노션 색인 여부)을 보여주고, 승인하면 노트를 만듭니다.

찾을 때도 대화로 (읽기 — 정리해 둔 노트에서):

"내 볼트에서 RAG 찾아서 요약해줘"

• 색인(노션)과 원본(옵시디언)에서 찾아 출처와 함께 답해요. 답하기 전에 원본이 실제로 있는지 확인하고, 지워진 노트(끊긴 색인)면 "원본 없음"이라고 솔직히 알려줍니다(없는 걸 있다고 안 함).
• 🔗 여러 노트를 묶어서도 물어볼 수 있어요: "내 노트들로 RAG·임베딩·벡터DB 관계 정리해줘" → 관련 노트를 모아 노트별 출처와 함께 종합해 답합니다(어떤 노트로 답할지 먼저 보여줘요).

정리 상태가 궁금할 때도 대화로 (건강검진 — 읽기):

"내 'Vault' 볼트 건강검진해줘"

• 🩺 시간이 지나며 쌓인 고아 노트(아무 데도 안 이어진 노트)·깨진 [[링크]]·중복·frontmatter 누락, 그리고 노션을 쓰면 끊긴 색인(원본은 지워졌는데 노션 행만 남은 것)을 찾아 보고해요. 멋대로 고치지 않아요 — 고칠 항목을 골라 승인하면 그때만 손봅니다: 중복은 삭제가 아니라 보관함(99_Archive)으로 이동(되돌리기 쉬움), 링크 수정은 고치기 전 자동 백업(비가역은 한 번 더 확인).

환경 변수 (선택)

.env.example를 복사해 .env로 쓰세요. 실제 값(토큰 등)은 절대 git에 올리지 마세요.

폴더 구조

.claude-plugin/        플러그인·마켓플레이스 매니페스트
mcp/server.mjs         무의존 MCP 서버 (stdio) — 도구 5개(collect·lint·fix·runlog·vaults)
mcp/lib/collect.mjs    수집(이름 안전화·중복 차단)
mcp/lib/lint.mjs       건강검진(읽기전용)
mcp/lib/fix.mjs        안전 수정(삭제 없음·백업)
mcp/lib/runlog.mjs     작업 로그
skills/                자연어 자동 발동 스킬(organize·query·lint)
commands/              /wikimate · /wikimate-lint 명령
adapters/codex/        Codex용 설정 안내
templates/             노트 템플릿
scripts/               검증 스크립트(verify-*·smoke-*)
(내 볼트의) .wikimate/runlog.jsonl   작업 로그(숨김)

안전·보안

• ✅ 쓰기는 사람 승인 후 실행 (dry_run이 기본 — 계획만 먼저 보여줌). 매번 "승인"이 번거로우면 "묻지 말고 바로 정리해줘" 라고 하세요 → 신규 노트 생성은 자동(단 덮어쓰기·삭제는 항상 한 번 더 확인). 그리고 승인은 선택지(숫자/클릭) 로 떠서, "진행해줘"를 타자치지 않고 골라도 돼요.
• ✅ 노트 제목·폴더의 경로 구분자·금지문자·제어문자를 정리하고 볼트 밖 경로를 차단(경로 이탈 방지).
• ✅ 외부 자료 속 지시문은 명령이 아니라 데이터로만 취급(프롬프트 인젝션 방어).
• ✅ 옵시디언 CLI는 셸 없이 실행(명령 주입 방지). 키·토큰은 노트·배포물에 저장하지 않음.
• ✅ .obsidian/ 폴더는 건드리지 않음. 기존 노트는 승인 없이 수정·삭제하지 않음.
• ℹ️ 노션 색인은 노션 도구가 연결돼 있을 때만. 안 되면 옵시디언만 정리하고 솔직히 보고해요.
• 🧾 작업 기록(Run Log) — 실제로 만들거나·옮기거나·고친 노트는 자동으로 .wikimate/runlog.jsonl(숨김)에 한 줄씩 남아요. "최근 작업 보여줘" 라고 하면 무엇을 했는지 되짚어 드립니다(읽기 전용 안전 로그).

현재 상태 (정직하게)

• ✅ 옵시디언 정리: 실제 볼트에 노트 생성 확인(자연어 자동 발동 포함).
• ✅ 건강검진·안전수정·작업로그: 단위테스트 + 서버 프로토콜 e2e로 검증(중복·깨진링크·고아 탐지, 삭제 없는 수정, 자동 기록).
• 🟡 노션 색인: 노션 도구(MCP/CLI)가 연결·인증된 환경에서 동작. 환경에 따라 미연결이면 자동으로 건너뜁니다.
• 🟡 Codex: 같은 MCP 코어를 쓰도록 어댑터 제공(설정은 adapters/codex/SETUP.md).
• ⚠️ 라이브 세션 미검증: 실제 Claude Code /mcp 세션·실볼트 검증은 사용자 환경에서 권장(2분, 위 설치 참고).

문제 해결

• "정리해줘" 했는데 노트는 안 만들고 요약만 해요 → 자연어 자동 발동이 들쭉날쭉이에요. /wikimate <링크> 슬래시 명령으로 콕 찍으면 100% 됩니다(가장 확실).
• marketplace ... not found(마켓플레이스 못 찾음) → 등록이 안 된 거예요. update가 아니라 /plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git 부터 한 뒤 /plugin install wikimate@wikimate-marketplace.
• /mcp에 안 보여요 → Claude Code 재시작. 그래도 없으면 위 "업데이트" 방식으로 캐시 갱신.
• 노트가 옵시디언에 안 보여요 → 볼트 이름을 정확히 말했는지 확인(파일 폴백은 OBSIDIAN_VAULT_PATH 폴더에 생성됨).
• 노션에 색인이 안 돼요 → 노션 MCP/CLI가 연결·인증돼 있는지 확인. 안 되면 옵시디언 노트만 생성됩니다(정상 폴백).
• 제목의 일부 기호가 사라졌어요 → / \ : * ? " < > | 같은 파일명 금지문자는 안전을 위해 공백으로 정리돼요(의도된 동작).
• 설치가 EBUSY ... locked 로 실패해요 → 백신 파일 잠금이에요. Claude Code를 껐다 켠 뒤 다시 설치(위 "업데이트" 참고). 반복되면 잠시 뒤 재시도.
• 옛날 버전(예: 0.1.0)이 깔려요 → 마켓플레이스 캐시가 옛것이에요. 위 "업데이트"의 marketplace update(또는 remove → 다시 add)로 갱신하세요.

더 많은 증상·해결은 왕초보 가이드 15번에 표로 정리돼 있어요.

참고 도구

notesmd-cli · mcp-obsidian · notion-mcp-server · ntn CLI

라이선스 · 저작권 · 상업적 이용

⚖️ 아래는 일반 안내이며 법률 자문이 아니에요. 정확한 고지는 LICENSE·NOTICE 파일이 정본입니다.

• Wikimate 본체: Apache License 2.0 © 2026 SoDam AI Studio. 상업적 이용·수정·배포 허용, 단 저작권 고지+라이선스 사본 포함·변경 표시·NOTICE 유지 필요. 무보증(AS-IS), 상표 권리 미부여("Wikimate"·"SoDam AI Studio" 이름 임의 사용 금지).
• 외부 도구는 번들 아님 — Node.js·@modelcontextprotocol/sdk·notesmd-cli·mcp-obsidian·notion-mcp-server는 MIT, Notion API/ntn은 Notion 약관, Obsidian은 개인 무료·상업용 별도 라이선스. 각자 원문 약관을 직접 확인하세요.
• 콘텐츠 저작권은 원저작자에게 있어요. 수집·재배포 시 원저작물의 라이선스·약관을 지키세요. 노트는 내 컴퓨터(로컬) 에만 저장되고 외부로 보내지 않아요(노션 색인은 내가 켤 때만).

전체 라이선스 표·면책은 왕초보 가이드 17번 또는 NOTICE 참고. 개발·테스트·배포 방법은 DEVELOPMENT.md.