Wikimate (위키메이트)

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

English

상태: 초기 단계(Phase 1a). 옵시디언 정리는 동작 확인됨, 노션 색인은 노션 도구가 연결된 환경에서 동작(아래 "현재 상태" 참고).

무엇을 해주나요?

• 🧹 자연어로 정리 — "이 링크 정리해줘" 한마디면 노트가 만들어져요(도구를 따로 안 불러도 됨).
• 📒 내 진짜 옵시디언 볼트에 — 설치된 옵시디언 도구(MCP/CLI)를 자동 감지해 사용하고, 없으면 파일로 폴백.
• 🗂️ 노션 색인(선택) — 노션 도구가 연결돼 있으면 색인 행을 추가(옵시디언=원본, 노션=단방향 색인).
• ✋ 항상 계획 먼저 → 승인 후 실행 — 멋대로 쓰지 않아요.
• 🔁 중복 차단 — 같은 자료는 source_hash로 한 번만.
• 🛡️ 안전 설계 — 볼트 밖 경로 차단, 외부 글은 명령이 아니라 데이터로 취급(프롬프트 인젝션 방어).

설치 (Claude Code)

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

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

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

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

/plugin install wikimate@wikimate-marketplace

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

설치 (Codex)

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

1) 저장소 받기

git clone https://github.com/sodam-ai/wikimate.git

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

codex mcp add wikimate --env OBSIDIAN_VAULT_PATH=D:/내/볼트/경로 -- node D:/받은/경로/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' 볼트에 정리해줘"

• 📎 정리할 "자료"는 무엇이든 돼요 — 한 문장 텍스트, 웹 링크(이 링크 정리해줘: https://...), 파일 경로(이 파일 정리해줘: D:\메모\오늘.md) 모두 OK. 따로 준비할 게 없어요.
• 🏷️ 옵시디언 CLI(예: notesmd-cli)를 쓰려면 볼트 이름을 함께 말해주세요(예: "내 'Vault' 볼트에"). 볼트 이름을 모르면 옵시디언 좌하단 볼트 전환 메뉴에서 볼 수 있어요. 안 그러면 파일 경로로 동작해요.
• 먼저 계획(어디에·어떤 도구로·노션 색인 여부)을 보여주고, 승인하면 노트를 만듭니다.

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

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

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

환경 변수 (선택)

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

폴더 구조

.claude-plugin/      플러그인·마켓플레이스 매니페스트
mcp/server.mjs       무의존 MCP 서버 (stdio)
mcp/lib/collect.mjs  수집 로직 (이름 안전화·중복 차단)
skills/              자연어로 자동 발동하는 스킬
commands/            /wikimate 명령
adapters/codex/      Codex용 설정 안내
templates/           노트 템플릿

안전·보안

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

현재 상태 (정직하게)

• ✅ 옵시디언 정리: 실제 볼트에 노트 생성 확인(자연어 자동 발동 포함).
• 🟡 노션 색인: 노션 도구(MCP/CLI)가 연결·인증된 환경에서 동작. 환경에 따라 미연결이면 자동으로 건너뜁니다.
• 🟡 Codex: 같은 MCP 코어를 쓰도록 어댑터 제공(설정은 adapters/codex/SETUP.md).

문제 해결

• /mcp에 안 보여요 → Claude Code 재시작. 그래도 없으면 위 "업데이트" 방식으로 캐시 갱신.
• 노트가 옵시디언에 안 보여요 → 볼트 이름을 정확히 말했는지 확인(파일 폴백은 OBSIDIAN_VAULT_PATH 폴더에 생성됨).
• 노션에 색인이 안 돼요 → 노션 MCP/CLI가 연결·인증돼 있는지 확인. 안 되면 옵시디언 노트만 생성됩니다(정상 폴백).
• 제목의 일부 기호가 사라졌어요 → / \ : * ? " < > | 같은 파일명 금지문자는 안전을 위해 공백으로 정리돼요(의도된 동작).
• 설치가 EBUSY ... locked 로 실패해요 → 백신 파일 잠금이에요. Claude Code를 껐다 켠 뒤 다시 설치(위 "업데이트" 참고). 반복되면 잠시 뒤 재시도.
• 옛날 버전(예: 0.1.0)이 깔려요 → 마켓플레이스 캐시가 옛것이에요. 위 "업데이트"의 marketplace update(또는 remove → 다시 add)로 갱신하세요.

참고 도구

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

라이선스

Apache License 2.0 © 2026 SoDam AI Studio

개발·테스트·배포 방법은 DEVELOPMENT.md 참고.