# SoDam WikiMate

> AI에게 '정리해줘'라고 하면 흩어진 자료를 옵시디언(원본)에 노트로 정리하고 선택적으로 노션에 색인하는 Claude Code 플러그인 + 이식형 MCP 코어. 보관함 자동탐지·정리·검색(가짜 인용 방지)·볼트 건강검진(중복·깨진 링크·고아 탐지, 삭제 없는 안전 수정)·작업 로그. 사람 승인 게이트·경로/프롬프트 인젝션 방어·무의존.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sodam-ai-sodam-wikimate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sodam-ai](https://agentstack.voostack.com/s/sodam-ai)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [sodam-ai](https://github.com/sodam-ai)
- **Source:** https://github.com/sodam-ai/SoDam-WikiMate

## Install

```sh
agentstack add mcp-sodam-ai-sodam-wikimate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Wikimate (위키메이트)

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

**[English](./README.en.md)**

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

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

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

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

## 30초 용어 (왕초보용)
| 낱말 | 쉬운 뜻 |
|---|---|
| **플러그인** | 프로그램에 끼워 넣는 새 기능 부품 (앱 추가 설치 같은 것) |
| **마켓플레이스** | 플러그인을 받아오는 앱 장터 |
| **MCP / MCP 도구** | AI와 도구를 잇는 통로 / 그 통로로 누르는 기능 버튼 |
| **볼트(Vault)** | 옵시디언에서 노트를 모아 두는 보관 폴더(이름이 있어요) |
| **dry-run** | 실제로 하기 전에 "계획만" 미리보기 |

> 더 많은 용어는 [왕초보 가이드 1번](./GUIDE.ko.md)에 있어요.

## 설치 (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`](./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)으로 이동**(되돌리기 쉬움), 링크 수정은 **고치기 전 자동 백업**(비가역은 한 번 더 확인).

## 환경 변수 (선택)
| 변수 | 용도 |
|---|---|
| `OBSIDIAN_VAULT_PATH` | 볼트 폴더 절대경로 (파일 폴백·중복검사용) |
| `OBSIDIAN_VAULT_NAME` | 옵시디언에 등록된 볼트 이름 (CLI용) |
| `NOTION_RESEARCH_DB_ID` | 노션 색인 DB 지정 (없으면 검색하거나 물어봐요) |

`.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번](./GUIDE.ko.md)에 표로 정리돼 있어요.

## 참고 도구
[notesmd-cli](https://github.com/Yakitrak/notesmd-cli) · [mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian) · [notion-mcp-server](https://github.com/makenotion/notion-mcp-server) · [ntn CLI](https://developers.notion.com/cli/get-started/overview)

## 라이선스 · 저작권 · 상업적 이용
> ⚖️ 아래는 일반 안내이며 **법률 자문이 아니에요.** 정확한 고지는 `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번](./GUIDE.ko.md) 또는 `NOTICE` 참고. 개발·테스트·배포 방법은 [DEVELOPMENT.md](./DEVELOPMENT.md).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sodam-ai](https://github.com/sodam-ai)
- **Source:** [sodam-ai/SoDam-WikiMate](https://github.com/sodam-ai/SoDam-WikiMate)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sodam-ai-sodam-wikimate
- Seller: https://agentstack.voostack.com/s/sodam-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.